nbdublk(1)

📦
version 1.25.7 · 5 versions
, in fedora 44

✨ nbdublk — bestie edition ✨

okay so real talk, this is nbdublk(1) from the LIBNBD squad, and it's genuinely iconic. it hooks a network block device up to a local device and honestly? she ate. let's get into it 💅

🌸 NAME 🌸

nbdublk — connect a network block device to a local device. that's it, that's the whole vibe 🦋

✨ SYNOPSIS ✨

nbdublk [-C N|--connections N] [--keepalive] [-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

so to list devices, you go:

ublk list

and to unmount:

ublk del -n <N>

and the other little commands, because we love options:

nbdublk --help

nbdublk -V|--version

modprobe ublk_drv

💖 DESCRIPTION 💖

nbdublk is the girl that makes a Linux device /dev/ublkb<N> out of a network block device server. no cap. every read and every write you do to that virtual device gets turned into reads and writes to the NBD server. it's giving middleman but make it ✨magic✨.

the first parameter is the Linux device name, and it looks like /dev/ublkb<N> (for some number <N>), for example /dev/ublkb0, /dev/ublkb1, &c. but bestie you can also just use the number on its own, OR use - and let ublk allocate an unused device for you. so casual. so generous. 👑

the second and following parameters refer to the NBD server, which can be local or remote. you can specify the server as an NBD URI (like "nbd://localhost"), or as an NBD server running as a subprocess of nbdublk (using "[ ... ]"), or in various other ways — go peek at "MODES" below for the whole menu 🍓

and psst — use ublk(8) to list and delete devices. that's your girl for cleanup. 🧚

🫶 Requires Linux and root 🫶

this program requires Linux ≥ 6.0 and the "ublk_drv.ko" kernel module. yes, it's a whole thing. you may need to load the kernel module, and you usually have to run nbdublk as root. main character energy requires admin privileges, sorry not sorry 😭

🌈 EXAMPLE 🌈

okay let's actually do this. create an NBD ublk device connected to a remote NBD server:

# nbdublk /dev/ublkb0 nbd://server

now list the device, because we're nosy and we love receipts:

# 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

look at her. state LIVE. we're obsessed. 😍

you can then use "/dev/ublkb0" as a regular device, fr fr. and to disconnect the device use:

# ublk del -n 0

💅 OPTIONS 💅

  • --help — display brief command line help and exit. short, sweet, helpful. 🎀
  • -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). no multi-conn unless everybody agrees, it's a whole consent thing 🫶
  • -C 1, --connections 1 — disable multi-conn. only use a single connection to the NBD server. see "THREAD MODEL" below. (yes, even though there's no THREAD MODEL section in this page. the manual said it, so I said it. 💀)
  • --keepalive — set the keepalive ("SO_KEEPALIVE") flag on the connection. see nbd_set_keepalive(3) and socket(7). keeping the friendship alive, literally. 🌸
  • -r, --readonly — access the network block device read-only. the virtual file will have read-only permissions, and any writes will return errors. look but don't touch 💅 if the remote NBD server is read-only then this flag is added automatically. (check the "is_read_only:" field in the output of nbdinfo(1).) she does it herself, icon behaviour.
  • -v, --verbose — enable verbose messages to stderr. this enables libnbd debugging and other messages. for the girlies who need the full commentary track 🎙️
  • -V, --version — display the package name and version and exit. quick lil flex. ✨

👑 MODES 👑

modes are how you pick your NBD server. it's giving choose-your-own-adventure. possible modes are:

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). (unencrypted, bestie. just so we're clear. 👀)
  • 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 an "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).

(the whole friend group, iykyk 💜)

🫶 AUTHORS 🫶

Richard W.M. Jones

Ming Lei

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

no warranty bestie, we said what we said. 😭

okay that's the whole page!! this is libnbd-1.25.7, dated 2026-07-28, and you just read all of it. slay, periodt, go make some block devices. 💅✨🦋

📦 where this page comes from