nbdsh - Man Page

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 client shell for accessing Network Block Device (NBD) servers.

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

 help(nbd)

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

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.

Notes

nbdsh examples

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

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 nbd module:

 #!/usr/bin/python3
 import nbd
 h = nbd.NBD()
 h.connect_uri("nbd://localhost")

There are some example Python scripts in the libnbd source repository under python/examples or see https://gitlab.com/nbdkit/libnbd/tree/master/python/examples.

See Also

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

Authors

Richard W.M. Jones

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

Referenced By

libnbd(3), libnbd-release-notes-1.10(1), libnbd-release-notes-1.16(1), libnbd-release-notes-1.2(1), libnbd-release-notes-1.4(1), libnbd-release-notes-1.6(1), nbdcopy(1), nbddump(1), nbdfuse(1), nbdinfo(1), nbdkit(1), nbdkit-release-notes-1.16(1), nbdkit-release-notes-1.24(1), nbdkit-service(1), nbdkit-tls(1), nbdublk(1).

2024-10-14 libnbd-1.21.6