nbdublk - Man Page
connect network block device to a local device
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 del -n <N>
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.
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
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.
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)).
Enable verbose messages to stderr. This enables libnbd debugging and other messages.
Display the package name and version and exit.
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
10809, with export name
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_VSOCKsocket. See also nbd_connect_vsock(3).
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).
Richard W.M. Jones
Copyright Red Hat
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
libnbd(3), libnbd-release-notes-1.16(1), nbdcopy(1), nbdfuse(1), nbdinfo(1), nbdsh(1).