nbdkit-nbd-plugin(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

👑 nbdkit-nbd-plugin, but make it make sense 👑

okay so bestie, this is the manual page for nbdkit-nbd-plugin — section 1 of the manual, the nbdkit plugin family, you know the drill. it's a whole plugin that lets you forward an NBD connection to a whole other NBD server. let's get into it 💅

✨ NAME ✨

nbdkit-nbd-plugin — proxy / forward to another NBD server 🦋

🌸 SYNOPSIS 🌸

nbdkit nbd { command=COMMAND [arg=ARG [...]] |
             hostname=HOST [port=PORT] |
             vhost-cid=CID [port=PORT] |
             socket=SOCKNAME |
             socket-fd=FD |
             [uri=]URI }
           [dynamic-export=BOOL] [export=NAME] [retry=N] [shared=BOOL]
           [tls=MODE] [tls-certificates=DIR] [tls-verify=BOOL]
           [tls-username=NAME] [tls-psk=FILE]

💖 DESCRIPTION 💖

nbdkit-nbd-plugin is a plugin for nbdkit(1) and what it does is literally take your connection and pass it straight on to another NBD server. no cap. and there are like, several reasons you'd want that:

  • Adjust the set of features seen by the ultimate NBD client without touching the original server at all. like, convert between the oldstyle and newstyle protocols, or add TLS support when the original server is out here with none. 🎀
  • Apply nbdkit filters to any other NBD server. yes, any. the filters go on everything. iconic.
  • With qemu-nbd(8), read and write qcow2 files with nbdkit — and heads up, peep also nbdkit-qcow2dec-filter(1). 🧚

🎀 PARAMETERS 🎀

okay so rule number one, no skipping: you have to give one of socket, hostname (optionally with port), vsock (optionally with port), uri, socket-fd or command to say which NBD server we're forwarding to. pick one, bestie:

  • command=COMMAND — (nbdkit ≥ 1.22) run an NBD server, usually qemu-nbd(8), as an external command. peep the EXAMPLES further down for the whole picture. COMMAND is the program to run, followed by zero or more arg=ARG parameters for each argument. like, for example:
nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=$PWD/disk.qcow2

would run the command qemu-nbd -f qcow2 $PWD/disk.qcow2. ⚠️ and this part matters: because nbdkit may change directory before running the command, you may need to make sure all file paths used in parameters (like the disk name above) are absolute paths. do not get caught slipping. 🙈

This uses the libnbd API nbd_connect_systemd_socket_activation(3). This option implies shared=true.

  • arg=ARG — (nbdkit ≥ 1.22) one argument passed to COMMAND; you can have zero or more of these, one per argument. see command right above. 💫
  • hostname=HOST — (nbdkit ≥ 1.14) connect to the NBD server at the remote HOST using a TCP socket.
  • port=PORT — (nbdkit ≥ 1.14) optional, overrides the default port (10809), and may be a 16-bit number or a non-numeric string so it looks up the well-known port for a service name. flexible queen. 👑
  • vsock=CID — (nbdkit ≥ 1.22) connect to the NBD server at the given vsock CID (for example, in a guest VM, using the cid 2 will connect to a server in the host). The optional port parameter overrides the default port (10809), and must be a 32-bit number. This only works for platforms with the AF_VSOCK family of sockets and libnbd new enough to use it; nbdkit --dump-plugin nbd will contain libnbd_vsock=1 if this is the case. For more details on AF_VSOCK, see AF_VSOCK in nbdkit-service(1).
  • port=PORT — (vsock flavour) yep, port shows up here too — see the vsock bullet above, it overrides the default and must be a 32-bit number.
  • socket=SOCKNAME — connect to the NBD server using Unix domain socket SOCKNAME. 🍓
  • socket-fd=FD — (nbdkit ≥ 1.22) connect to the NBD server over a socket file descriptor inherited by nbdkit. This uses the libnbd API nbd_connect_socket(3). This option implies shared=true.
  • [uri=]URI — (nbdkit ≥ 1.14) when uri is supplied, decode URI to figure out the address to connect to. A URI can specify a TCP connection (such as nbd://localhost:10809/export), a Unix socket (such as nbd+unix:///export?socket=/path/to/sock), or a vsock connection (such as nbd+vsock:///2:10809/export). remember you may need to quote the parameter to protect it from the shell, bestie — the shell is not your friend here. 😭

The uri parameter is only available when the plugin was compiled against libnbd with URI support; nbdkit --dump-plugin nbd will contain libnbd_uri=1 if this is the case.

The export portion of the URI is ignored when using dynamic-export=true.

The uri= prefix may be omitted in most cases. See Magic parameters in nbdkit(1).

okay so that was the "where are we connecting" section. now the other parameters that control the NBD connection:

  • export=NAME — if this parameter is given, and the server speaks new style protocol, then connect to the named export instead of the default export (the empty string). If uri is supplied, the export name should be embedded in the URI instead. This is incompatible with dynamic-export=true. 🚫
  • retry=N — (nbdkit ≥ 1.14) if the initial connection attempt to the server fails, retry up to N times more after a one-second delay between tries (default 0). manifesting that connection fr fr ✨
  • shared=false, shared=true — (nbdkit ≥ 1.14) if using command or socket-fd modes then this defaults to true, otherwise false.

If false the plugin will open a new connection to the server for each client making a connection to nbdkit. The remote server does not have to be started until immediately before the first nbdkit client connects.

If this parameter is set to true, the plugin will open a single connection to the server when nbdkit is first started (the retry parameter may be necessary to coordinate timing of the remote server startup), and all clients to nbdkit will share that single connection. This mode is incompatible with dynamic-export=true.

  • dynamic-export=false, dynamic-export=true — (nbdkit ≥ 1.24) this parameter defaults to false, in which case all clients to nbdkit use the same export of the server, as set by export or uri, regardless of the client's export name request. If it is set to true, nbdkit will pass the client's requested export name over to the final NBD server, which means clients requesting different export names can see different content when the server differentiates content by export name. Dynamic exports prevent the use of shared mode, and thus are not usable with command or socket-fd. 🦋

If libnbd is new enough, dynamic export mode is able to advertise the same exports as listed by the server; nbdkit --dump-plugin nbd will contain libnbd_dynamic_list=1 if this is the case. Regardless of what this plugin lists, it is also possible to use nbdkit-exportname-filter(1) to adjust what export names the client sees or uses as a default.

  • tls=off, tls=on, tls=require — (nbdkit ≥ 1.14) selects which TLS mode to use with the server. If no other tls option is present, this defaults to off, where the client does not attempt encryption (and may be rejected by a server that requires it — rude). If omitted but another tls option is present, this defaults to on, where the client opportunistically attempts a TLS handshake, but will continue running unencrypted if the server does not support encryption. If set to require or if the uri parameter is used with a scheme that requires encryption (such as nbds://host), then this requires an encrypted connection to the server. 🔒

The tls parameter is only available when the plugin was compiled against libnbd with TLS support; nbdkit --dump-plugin nbd will contain libnbd_tls=1 if this is the case. Note the difference between --tls=... controlling what nbdkit serves, and tls=... controlling what the nbd plugin connects to as a client. do not mix those up, iykyk. 🙈

  • tls-certificates=DIR — (nbdkit ≥ 1.14) this specifies the directory containing X.509 client certificates to present to the server. 🎀
  • tls-verify=false — (nbdkit ≥ 1.14) setting this parameter to false disables server name verification, which opens you to potential Man-in-the-Middle (MITM) attacks, but allows for a simpler setup for distributing certificates.
💀 bestie, read that again. tls-verify=false means you are open to MITM attacks. it's easier, sure, but it's giving risky.
  • tls-username=NAME — (nbdkit ≥ 1.14) if provided, this overrides the user name to present to the server alongside the certificate.
  • tls-psk=FILE — (nbdkit ≥ 1.14) if provided, this is the filename containing the Pre-Shared Keys (PSK) to present to the server. While this is easier to set up than X.509, it requires that the PSK file be transmitted over a secure channel. no shortcuts on that one. 🚨

🔥 EXAMPLES 🔥

✨ Convert oldstyle server to encrypted newstyle ✨

so you wanna expose the contents of an export served by an old style server over a Unix socket, to TCP network clients that only want to consume encrypted data? say less. use --exit-with-parent to clean up nbdkit at the same time that the old server exits — they leave together, cute. 🫶

 ( sock=`mktemp -u`
   nbdkit --exit-with-parent --tls=require nbd socket=$sock &
   exec /path/to/oldserver --socket=$sock )
 ┌────────────┐   TLS    ┌────────┐  plaintext  ┌────────────┐
 │ new client │ ────────▶│ nbdkit │ ───────────▶│ old server │
 └────────────┘   TCP    └────────┘    Unix     └────────────┘

🌈 Use qemu-nbd to open a qcow2 file 🌈

run qemu-nbd as the server, and now you can read and write qcow2 files (since nbdkit does not have a native qcow2 plugin). and because it's nbdkit, you can stack filters on top — see the next example. ⭐

 nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2

qemu-nbd is cleaned up when nbdkit exits. ✨

💜 Add nbdkit-partition-filter to qemu-nbd 💜

combine nbdkit-partition-filter(1) with qemu-nbd(8)'s ability to visit qcow2 files:

 nbdkit --filter=partition nbd \
        command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2 \
        partition=1

this performs the same task as the deprecated qemu-nbd -P option:

 qemu-nbd -P 1 -f qcow2 /path/to/image.qcow2

🦋 Convert newstyle server for oldstyle-only client 🦋

expose the contents of export foo from a newstyle server with encrypted data to a client that can only consume unencrypted old style. use --run to clean up nbdkit at the time the client exits. and in general — note that it is best to keep the plaintext connection limited to a Unix socket on the local machine. do not be putting plaintext on the open internet, bestie, that's not the vibe. 🙈

 nbdkit -o --tls=off nbd hostname=example.com export=foo tls=require \
  --run '/path/to/oldclient --socket=$unixsocket'
 ┌────────────┐  plaintext  ┌────────┐   TLS    ┌────────────┐
 │ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
 └────────────┘    Unix     └────────┘   TCP    └────────────┘

⭐ DUMP PLUGIN OUTPUT ⭐

you can learn which features are provided by libnbd by inspecting the libnbd_* lines in --dump-plugin output. it's like a little vibe check for your libnbd 💅

 $ nbdkit --dump-plugin nbd
 [...]
 libnbd_version=1.2.3
 libnbd_tls=1
 libnbd_uri=1

📁 FILES 📁

  • $plugindir/nbdkit-nbd-plugin.so — bestie, this is the plugin. The actual file. The whole moment. 💅

And if you're sitting there like "okay but where tf is $plugindir though??" — run this:

nbdkit --dump-config

That'll tell you where $plugindir lives on your system. Slay. ✨

🕰️ VERSION 🕰️

nbdkit-nbd-plugin first appeared in nbdkit 1.2. That's it, that's the lore. An icon from day one, fr fr. 👑

👀 SEE ALSO 👀

The whole friend group, no cap — go read these when you're done here:

iykyk, this is a stacked reading list. 📚✨

💖 AUTHORS 💖

Eric Blake — the main character who wrote this. Respect the queen/king/royalty. 🫶

Copyright Red Hat. Periodt.

📜 LICENSE 📜

Okay so legally I have to give you the actual words here, no remixing allowed — but the vibe is: it's a BSD-style license, it's free, go wild, just don't come for Red Hat if it breaks. 😌

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

And that's the whole page, bestie!! 🎀 This is nbdkit-nbd-plugin(1) from nbdkit-1.48.1, dated 2026-08-29. Go forth and bridge those NBD servers together, you absolute legend. 💖🦋🌸💜

📦 where this page comes from