NAME¶

nbdublk - connect network block device to a local device

SYNOPSIS¶

 nbdublk [-C N|--connections N] [-r] [-v|--verbose]
         { /dev/ublkb<N> | <N> | - } 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.

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), nbddiscard(1), nbddump(1), nbdfuse(1), nbdinfo(1), nbdsh(1), nbdzero(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