NAME

nbdublk - connect network block device to a local device

SYNOPSIS

 nbdublk [-C N|--connections N] [-r] [-v|--verbose] /dev/ublkb<N> URI

 nbdublk [-C N|--connections N] [-r] [-v|--verbose] <N> URI

 nbdublk [-C N|--connections N] [-r] [-v|--verbose] - URI
 nbdublk /dev/ublkb<N> [ CMD [ARGS ...] ]
 nbdublk /dev/ublkb<N> --command CMD [ARGS ...]
 nbdublk /dev/ublkb<N> --fd N
 nbdublk /dev/ublkb<N> --tcp HOST PORT
 nbdublk /dev/ublkb<N> --unix SOCKET
 nbdublk /dev/ublkb<N> --vsock CID PORT

To list devices:

 ublk list

To unmount:

 ublk del -n <N>

Other commands:

 nbdublk --help
 nbdublk -V|--version
 modprobe ublk_drv

DESCRIPTION

nbdublk is used to create a Linux device /dev/ublkb<N> from a network block device server. Reads and writes to the virtual device are turned into reads and writes to the NBD server.

The first parameter is the Linux device name of the form /dev/ublkb<N> (for some number <N>), for example /dev/ublkb0, /dev/ublkb1, &c. You can just use the number on its own, or use - to get ublk to allocate an unused device.

The second and following parameters refer to the NBD server, which can be local or remote. The server can be specified as an NBD URI (like nbd://localhost), or as an NBD server running as a subprocess of nbdublk (using [ ... ]), or in various other ways (see "MODES").

Use ublk(8) to list and delete devices.

Requires Linux and root

This program requires Linux ≥ 6.0 and the ublk_drv.ko kernel module. You may need to load the kernel module and you usually have to run nbdublk as root.

EXAMPLE

Create an NBD ublk device connected to a remote NBD server:

 # nbdublk /dev/ublkb0 nbd://server

List the device:

 # ublk list
 dev id 0: nr_hw_queues 4 queue_depth 64 block size 1 dev_capacity 0
         max rq size 67108864 daemon pid 32382 flags 0x0 state LIVE

You can then use /dev/ublkb0 as a regular device. To disconnect the device use:

 # ublk del -n 0

OPTIONS

--help

Display brief command line help and exit.

-C N
--connections N

If multi-conn is used, use N connections to the server. The default is 4.

Multi-conn is enabled by default when possible. Modes which run a subprocess, such as --command are not able to use multi-conn. Mode --fd also cannot use multi-conn. Also the server must advertise multi-conn (use nbdinfo(1) to query what the server supports).

-C 1
--connections 1

Disable multi-conn. Only use a single connection to the NBD server. See "THREAD MODEL" below.

-r
--readonly

Access the network block device read-only. The virtual file will have read-only permissions, and any writes will return errors.

If the remote NBD server is read-only then this flag is added automatically. (Check is_read_only: field in the output of nbdinfo(1)).

-v
--verbose

Enable verbose messages to stderr. This enables libnbd debugging and other messages.

-V
--version

Display the package name and version and exit.

MODES

Modes are used to select the NBD server. Possible modes are:

nbdublk DEVICE URI

This mode uses an NBD URI (see nbd_connect_uri(3) and https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md). For example this specifies a TLS-encrypted connection to example.com port 10809, with export name disk:

 nbdublk /dev/ublkb0 nbds://example.com/disk
nbdublk DEVICE [ CMD [ARGS ...] ]

Run an NBD server as a subprocess. In this mode an NBD server can be run directly from the command line with nbdublk communicating with the server over a socket. This requires that the NBD server supports systemd socket activation. See "EXAMPLES" above and nbd_connect_systemd_socket_activation(3).

nbdublk DEVICE --command CMD [ARGS ...]

Select command mode. In this mode an NBD server can be run directly from the command line with nbdublk communicating with the server over the server’s stdin/stdout. Normally you would use this with nbdkit -s. See nbd_connect_command(3).

nbdublk DEVICE --fd N

Select file descriptor mode. In this mode a connected socket is passed to nbdublk. nbdublk connects to the socket on the numbered file descriptor. See also nbd_connect_socket(3).

nbdublk DEVICE --tcp HOST PORT

Select TCP mode. Connect to an NBD server on a host and port over an unencrypted TCP socket. See also nbd_connect_tcp(3).

nbdublk DEVICE --unix SOCKET

Select Unix mode. Connect to an NBD server on a Unix domain socket. See also nbd_connect_unix(3).

nbdublk DEVICE --vsock CID PORT

Select vsock mode. Connect to an NBD server on a AF_VSOCK socket. See also nbd_connect_vsock(3).

SEE ALSO

libnbd(3), nbdcopy(1), nbddump(1), nbdfuse(1), nbdinfo(1), nbdsh(1), ublk(8), nbd_connect_uri(3), nbd_connect_command(3), nbd_connect_socket(3), nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3), nbd_connect_unix(3), nbd_connect_vsock(3), nbdkit(1), nbdkit-loop(1), qemu-nbd(8), nbd-client(8).

AUTHORS

Richard W.M. Jones

Ming Lei

COPYRIGHT

Copyright Red Hat

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA