.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.20.0 (Pod::Simple 3.43)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "nbdsh 1"
.TH nbdsh 1 2024-05-31 libnbd-1.20.0 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 client 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
.SH EXAMPLES
.IX Header "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
.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 'COMMAND ...'" 4
.IX Item "-c 'COMMAND ...'"
.PD 0
.IP "\fB\-\-command\fR 'COMMAND ...'" 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 NOTES
.IX Header "NOTES"
.SS "nbdsh examples"
.IX Subsection "nbdsh examples"
There are some example nbdsh scripts in the libnbd source repository
under \fIsh/examples\fR or see
https://gitlab.com/nbdkit/libnbd/tree/master/sh/examples.
.SS "Using libnbd directly from Python"
.IX Subsection "Using libnbd directly from Python"
nbdsh is convenient for command line scripting, but you do not have to
use it.  Instead you can write an ordinary Python program or module
which imports the \f(CW\*(C`nbd\*(C'\fR module:
.PP
.Vb 4
\& #!/usr/bin/python3
\& import nbd
\& h = nbd.NBD()
\& h.connect_uri("nbd://localhost")
.Ve
.PP
There are some example Python scripts in the libnbd source repository
under \fIpython/examples\fR or see
https://gitlab.com/nbdkit/libnbd/tree/master/python/examples.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlibnbd\fR\|(3),
\&\fBlibnbd\-security\fR\|(3),
\&\fBnbdcopy\fR\|(1),
\&\fBnbddump\fR\|(1),
\&\fBnbdfuse\fR\|(1),
\&\fBnbdublk\fR\|(1),
\&\fBnbdinfo\fR\|(1),
\&\fBqemu\-img\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