nbdsh(1)

✨ nbdsh — the NBD shell, bestie edition ✨

okay so real talk: this is nbdsh, the network block device (NBD) shell, and it lives in the LIBNBD manual. yes bestie, we're doing block devices today, and honestly? it's giving main character energy. 💅

---

🌸 SYNOPSIS 🌸

$ nbdsh

Welcome to nbdsh, the shell for interacting with
Network Block Device (NBD) servers.

The ‘nbd’ module has already been imported and there
is an open NBD handle called ‘h’.

nbd> h.connect_command(["nbdkit", "-s", "memory", "1G"])
nbd> h.get_size()
1073741824
nbd> buf = b"hello, world"
nbd> h.pwrite(buf, 0)
nbd> exit()

like literally, that's the whole vibe. open it, h is already there waiting for you, and you just go off. 🫶

---

🦋 DESCRIPTION 🦋

nbdsh is a Python-based interactive shell for accessing Network Block Device (NBD) servers. that's it, that's the pitch. ✨

want the actual libnbd API tea? open the shell and type:

help(nbd)

and it will spill everything. 📖

for a proper intro to using libnbd from Python, go read libnbd-python(3). it's the prequel, you need it, iykyk.

---

🎀 EXAMPLES 🎀

there are other example scripts in the libnbd source repo under sh/examples, or peek at https://gitlab.com/nbdkit/libnbd/tree/master/sh/examples. 👑

🔥 Print the size of an NBD export

so the -u option connects to an NBD URI, and -c lets you execute single Python statements straight from the command line. combine the two and boom, you can print the size in bytes of an NBD export:

$ nbdsh -u nbd://localhost -c 'print(h.get_size())'
1073741824

look at that number. iconic. 🌈

💀 Hexdump the boot sector of an NBD export

using -c - you can feed a whole Python program to the standard input of nbdsh, and it's honestly so clean:

nbdsh -c - <<'EOF'
from subprocess import *

h.connect_uri("nbd://localhost")
bootsect = h.pread(512, 0)
p = Popen("hexdump -C", shell=True, stdin=PIPE)
p.stdin.write(bootsect)
EOF

also nbddump(1) is another tool for hexdumping NBD exports, if that's more your thing. 🍓

👑 Overwrite part of the disk with a pattern

overwrite 2048 bytes, starting at offset 1024 (hex 0x400), with the repeating binary pattern 01010101 10101010.

⚠️ ok bestie heads up: this operation is destructive! like, for real. do not do this on anything you love. 😭

$ nbdkit memory 4096
$ nbdsh -u nbd://localhost -c 'h.pwrite(b"\x55\xAA" * 1024, 0x400)'
$ nbddump nbd://localhost
0000: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 │················│
☆
0400: 55 aa 55 aa 55 aa 55 aa 55 aa 55 aa 55 aa 55 aa │U·U·U·U·U·U·U·U·│
☆
0c00: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 │················│
☆
0ff0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 │················│
$ killall nbdkit

so what's happening here? the -c parameter contains a Python expression which builds a bytearray containing the two byte pattern repeated 1024 times (length 2048 bytes), and calls the Python binding of nbd_pwrite(3). the second parameter is the offset to start writing from. ngl that's kind of elegant. 💜

for the full nbdkit lore, see nbdkit(1) and nbdkit-memory-plugin(1). 🧚

---

💅 OPTIONS 💅

• -h, --help — display brief command line help and exit. short and sweet, we love a helpful queen.
• --base-allocation — request the use of the "base:allocation" meta context, which is the most common context used with nbd_block_status_64(3). this is equivalent to calling h.set_meta_context(nbd.CONTEXT_BASE_ALLOCATION) in the shell prior to connecting, and it works even when combined with --uri (while attempting the same with -c would be too late). timing is everything, bestie. ⏰
• -c 'COMMAND ...', --command 'COMMAND ...' — instead of starting an interactive shell, run a command. this option can be specified multiple times in order to run multiple commands. stack 'em, you're allowed. 🫶
• -c -, --command - — read standard input and execute it as a command.
• -n — do not create the implicit handle h. yeah, the freebie handle. if you don't want it, here's your out.
• --opt-mode — request that option mode be enabled, which gives fine-grained control over option negotiation after initially contacting the server but prior to actually using the export. this is equivalent to calling h.set_opt_mode(True) in the shell prior to connecting, and works even when combined with --uri (while attempting the same with -c would be too late). control freak behavior, respectfully. 💅
• -u URI, --uri URI — connect to the given NBD URI. this is equivalent to the h.connect_uri(URI) command in the shell.

🚨 note that the connection is created prior to processing any -c commands, which prevents the use of configuration commands such as h.add_meta_context("NAME") from the command line when mixed with this option. the options --opt-mode and --base-allocation can be used to make this situation easier to manage. so like, plan ahead. 😅

• -v, --verbose — enable verbose libnbd messages. this has the same effect as setting the environment variable LIBNBD_DEBUG=1. she's chatty and we support her. 🗣️
• -V, --version — display the package name and version and exit. slay.

---

🌈 SEE ALSO 🌈

libnbd(3), libnbd-python(3), libnbd-security(3), nbdcopy(1), nbddiscard(1), nbddump(1), nbdfuse(1), nbdinfo(1), nbdublk(1), nbdzero(1), qemu-img(1), nbdkit(1).

the whole friend group, fr fr. 🫶

---

⭐ AUTHORS ⭐

Richard W.M. Jones. the legend themselves. 👑

---

💖 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. 😤 (yes, the caps are load-bearing, that's the legal vibe.)

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.

---

okay that's the whole page bestie, and before you go: this was libnbd-1.25.8, dated 2026-10-13 — the nbdsh(1) page from back in the day. mwah, go touch some block devices. 💋✨🎀