nbdsh(1)                            LIBNBD                            nbdsh(1)


NAME
       nbdsh - network block device (NBD) shell

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()

DESCRIPTION
       nbdsh is a Python-based interactive shell for accessing Network Block
       Device (NBD) servers.

       For documentation about the libnbd API please open the shell and type:

        help(nbd)

       For an introduction to using libnbd from Python see libnbd-python(3).

EXAMPLES
       There are other example scripts in the libnbd source repository under
       sh/examples or see
       https://gitlab.com/nbdkit/libnbd/tree/master/sh/examples.

   Print the size of an NBD export
       The -u option connects to an NBD URI.  The -c option lets you execute
       single Python statements from the command line.  Combining these two
       options lets you print the size in bytes of an NBD export:

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

   Hexdump the boot sector of an NBD export
       Using -c - you can feed a whole Python program to the standard input of
       nbdsh:

        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

       nbddump(1) is another tool for hexdumping NBD exports.

   Overwrite part of the disk with a pattern
       Overwrite 2048 bytes, starting at offset 1024 (hex 0x400), with the
       repeating binary pattern 01010101 10101010.  (This operation is
       destructive!)

        $ 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

       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.  For information about
       nbdkit, see nbdkit(1) and nbdkit-memory-plugin(1).

OPTIONS
       -h
       --help
           Display brief command line help and exit.

       --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 works even when combined with "--uri"
           (while attempting the same with "-c" would be too late).

       -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.

       -c -
       --command -
           Read standard input and execute it as a command.

       -n  Do not create the implicit handle "h".

       --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).

       -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.

       -v
       --verbose
           Enable verbose libnbd messages.  This has the same effect as
           setting the environment variable "LIBNBD_DEBUG=1"

       -V
       --version
           Display the package name and version and exit.

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).

AUTHORS
       Richard W.M. Jones

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.

       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-1.24.3                     2026-07-16                          nbdsh(1)