.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.24.3 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "nbdsh 1"
.TH nbdsh 1 2026-07-16 libnbd-1.24.3 LIBNBD
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdsh \- network block device (NBD) shell
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& $ 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()
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
nbdsh is a Python\-based interactive shell for accessing Network Block
Device (NBD) servers.
.PP
For documentation about the libnbd API please open the shell and type:
.PP
.Vb 1
\& help(nbd)
.Ve
.PP
For an introduction to using libnbd from Python see
\&\fBlibnbd\-python\fR\|(3).
.SH EXAMPLES
.IX Header "EXAMPLES"
There are other example scripts in the libnbd source repository under
\&\fIsh/examples\fR or see
https://gitlab.com/nbdkit/libnbd/tree/master/sh/examples.
.SS "Print the size of an NBD export"
.IX Subsection "Print the size of an NBD export"
The \fI\-u\fR option connects to an NBD URI.  The \fI\-c\fR 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:
.PP
.Vb 2
\& $ nbdsh \-u nbd://localhost \-c \*(Aqprint(h.get_size())\*(Aq
\& 1073741824
.Ve
.SS "Hexdump the boot sector of an NBD export"
.IX Subsection "Hexdump the boot sector of an NBD export"
Using \fI\-c \-\fR you can feed a whole Python program to the standard
input of nbdsh:
.PP
.Vb 2
\& nbdsh \-c \- <<\*(AqEOF\*(Aq
\& 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
.Ve
.PP
\&\fBnbddump\fR\|(1) is another tool for hexdumping NBD exports.
.SS "Overwrite part of the disk with a pattern"
.IX Subsection "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!)
.PP
.Vb 11
\& $ nbdkit memory 4096
\& $ nbdsh \-u nbd://localhost \-c \*(Aqh.pwrite(b"\ex55\exAA" * 1024, 0x400)\*(Aq
\& $ 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
.Ve
.PP
The \fI\-c\fR 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 \fBnbd_pwrite\fR\|(3).  The
second parameter is the offset to start writing from.  For information
about nbdkit, see \fBnbdkit\fR\|(1) and \fBnbdkit\-memory\-plugin\fR\|(1).
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-h\fR 4
.IX Item "-h"
.PD 0
.IP \fB\-\-help\fR 4
.IX Item "--help"
.PD
Display brief command line help and exit.
.IP \fB\-\-base\-allocation\fR 4
.IX Item "--base-allocation"
Request the use of the "base:allocation" meta context, which is the
most common context used with \fBnbd_block_status_64\fR\|(3).  This is
equivalent to calling
\&\f(CW\*(C`h.set_meta_context(nbd.CONTEXT_BASE_ALLOCATION)\*(C'\fR in the shell
prior to connecting, and works even when combined with \f(CW\*(C`\-\-uri\*(C'\fR (while
attempting the same with \f(CW\*(C`\-c\*(C'\fR would be too late).
.IP "\fB\-c\fR \*(AqCOMMAND ...\*(Aq" 4
.IX Item "-c 'COMMAND ...'"
.PD 0
.IP "\fB\-\-command\fR \*(AqCOMMAND ...\*(Aq" 4
.IX Item "--command 'COMMAND ...'"
.PD
Instead of starting an interactive shell, run a command.  This option
can be specified multiple times in order to run multiple commands.
.IP "\fB\-c \-\fR" 4
.IX Item "-c -"
.PD 0
.IP "\fB\-\-command \-\fR" 4
.IX Item "--command -"
.PD
Read standard input and execute it as a command.
.IP \fB\-n\fR 4
.IX Item "-n"
Do not create the implicit handle \f(CW\*(C`h\*(C'\fR.
.IP \fB\-\-opt\-mode\fR 4
.IX Item "--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
\&\f(CW\*(C`h.set_opt_mode(True)\*(C'\fR in the shell prior to connecting, and works
even when combined with \f(CW\*(C`\-\-uri\*(C'\fR (while attempting the same with \f(CW\*(C`\-c\*(C'\fR
would be too late).
.IP "\fB\-u\fR URI" 4
.IX Item "-u URI"
.PD 0
.IP "\fB\-\-uri\fR URI" 4
.IX Item "--uri URI"
.PD
Connect to the given NBD URI.
This is equivalent to the \f(CW\*(C`h.connect_uri(URI)\*(C'\fR command in the shell.
.Sp
Note that the connection is created prior to processing any \f(CW\*(C`\-c\*(C'\fR
commands, which prevents the use of configuration commands such as
\&\f(CW\*(C`h.add_meta_context(\*(C'\fRNAME\f(CW\*(C`)\*(C'\fR from the command line when mixed
with this option.  The options \f(CW\*(C`\-\-opt\-mode\*(C'\fR and \f(CW\*(C`\-\-base\-allocation\*(C'\fR
can be used to make this situation easier to manage.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
Enable verbose libnbd messages.  This has the same effect as setting
the environment variable \f(CW\*(C`LIBNBD_DEBUG=1\*(C'\fR
.IP \fB\-V\fR 4
.IX Item "-V"
.PD 0
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD
Display the package name and version and exit.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlibnbd\fR\|(3),
\&\fBlibnbd\-python\fR\|(3),
\&\fBlibnbd\-security\fR\|(3),
\&\fBnbdcopy\fR\|(1),
\&\fBnbddiscard\fR\|(1),
\&\fBnbddump\fR\|(1),
\&\fBnbdfuse\fR\|(1),
\&\fBnbdinfo\fR\|(1),
\&\fBnbdublk\fR\|(1),
\&\fBnbdzero\fR\|(1),
\&\fBqemu\-img\fR\|(1),
\&\fBnbdkit\fR\|(1).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "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.
.PP
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.
.PP
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