nbdkit-info-plugin(1)

💖 NAME 💖

nbdkit-info-plugin — serve client and server information

(this is a page from the nbdkit manual, bestie, and it's a whole mood 🫶)

✨ SYNOPSIS ✨

nbdkit info [mode=]exportname|base64exportname|address|
                   time|uptime|conntime|version

🦋 DESCRIPTION 🦋

okay so nbdkit-info-plugin is a test plugin that serves info about the client and the server back to the client, dressed up as a disk image. yes. a disk. full of vibes. 💅

In its default mode (mode=exportname) it converts the export name that the client passed in into a disk image. mode=base64exportname is the same idea except the client has to base64-encode the data inside the export name, which means arbitrary binary data can be sent through (peep the EXAMPLES below if that's giving you a headache, it makes it click fr fr). Export names are limited to 4096 bytes by the NBD protocol, although some clients have smaller limits. 😭

mode=address creates a disk containing the client's IP address and port number as a string. iconic.

mode=time, mode=uptime and mode=conntime report server wallclock time, nbdkit uptime, or time since the connection was opened respectively, and they may be used to measure latency. ⏱️

mode=version reports the version of nbdkit as a string.

👑 the plugin only supports read-only access. if you want the disk to be writable, add nbdkit-cow-filter(1) on top. no cap.

---

🌈 EXAMPLES 🌈

Let's make a "reflection disk". By setting the export name to hello when we open it, a virtual disk of only 5 bytes containing these characters is created. Then we display the contents:

$ nbdkit --exit-with-parent info mode=exportname &
$ nbdsh -u 'nbd://localhost/hello' -c - <<'EOF'
size = h.get_size()
print("size = %d" % size)
buf = h.pread(size, 0)
print("buf = %r" % buf)
EOF

size = 5
buf = b"hello"

By running the info plugin, you can pass whole bootable VMs on the qemu command line:

$ nbdkit info mode=base64exportname
$ qemu-system-x86_64 \
  -drive 'snapshot=on,file.driver=nbd,file.host=localhost,file.port=10809,file.export=
tACwA80QtBOzCrABuRwAtgCyAL0ZfM0Q9CoqKiBIZWxsbyBmcm9tIG5iZGtp
dCEgKioqDQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAVao=
'

Another use for the info plugin is to send back the client's IP address:

$ nbdkit info mode=address
$ nbdsh -u 'nbd://localhost' -c 'print(h.pread(h.get_size(), 0))'

which will print something like:

b'[::1]:58912'

This plugin can also return the wallclock time:

$ nbdkit info time --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
00000000  00 00 00 00 5d 8f 24 c7  00 04 24 01
                     └─────┬─────┘
                         ┌─┘
                         │
$ date --date="@$(( 0x5d8f24c7 ))"
Sat 28 Sep 10:15:51 BST 2019

or the nbdkit server uptime:

$ nbdkit info uptime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
00000000  00 00 00 00 00 00 00 00  00 00 60 4b
                                        └──┬──┘
                                  0x604b is about 25ms

or the time since the client opened the connection:

$ nbdkit info conntime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
00000000  00 00 00 00 00 00 00 00  00 00 00 e0
                                           └─┬─┘
                                    0xe0 is about 200μs

---

🎀 PARAMETERS 🎀

🍓 [mode=]address

Send the client's IP address and client port number as a string in the usual format. For Unix sockets this sets the disk to the string unix to avoid leaking host paths. 🙈 (privacy queen)

⚠️ This mode is only supported on some platforms. You can find out if it is supported by checking if:

$ nbdkit info --dump-plugin

contains:

info_address=yes

🍓 [mode=]base64exportname

Send the export name passed by the client, assuming the client string is base64 encoded.

⚠️ This mode is only supported if nbdkit was compiled with GnuTLS ≥ 3.6.0. You can find out by checking if:

$ nbdkit info --dump-plugin

contains:

info_base64=yes

🍓 [mode=]exportname

Send the raw export name passed by the client. Note the export name cannot contain ASCII NUL characters. 🚫

This is the default mode. periodt.

🍓 [mode=]time

Reflect server wallclock time as seconds and microseconds since the Epoch (see gettimeofday(2)):

• offset 0, length 8, format 64 bit int big endian — field seconds
• offset 8, length 4, format 32 bit int big endian — field microseconds

To be able to read this atomically you must read the whole 12 bytes in a single request. don't be out here doing it in pieces bestie.

🚨 Note that exposing server time may be insecure. It is safer to use mode=uptime or mode=conntime instead.

🍓 [mode=]uptime

Reflect nbdkit uptime in seconds and microseconds (ie. both fields are 0 immediately after nbdkit starts, although a client would never be able to observe this). The format is exactly the same as for mode=time above.

💀 In the current implementation this can jump forwards or backwards discontinuously if the server time is adjusted. In future we may fix this bug.

🍓 [mode=]conntime

Reflect time since the NBD client connection was opened in seconds and microseconds. The format is exactly the same as for mode=time above.

💀 In the current implementation this can jump forwards or backwards discontinuously if the server time is adjusted. In future we may fix this bug.

🍓 [mode=]version

Reflect the nbdkit version as a string. This is the version when the plugin was compiled, not the running version. iykyk.

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

---

🌸 FILES 🌸

• $plugindir/nbdkit-info-plugin.so — the plugin itself. ✨

Use nbdkit --dump-config to find the location of $plugindir.

---

⭐ VERSION ⭐

nbdkit-info-plugin first appeared in nbdkit 1.16.

---

👑 SEE ALSO 👑

nbdkit(1), nbdkit-plugin(3), nbdkit-cow-filter(1), nbdkit-data-plugin(1).

---

💜 AUTHORS 💜

Richard W.M. Jones

---

🎀 COPYRIGHT 🎀

Copyright Red Hat

---

💅 LICENSE 💅

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, mwah 💋 this was nbdkit-1.48.1, dated 2026-08-29 — go forth and reflect some info, you absolute icon 🦋✨