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

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.20.0                                      2024-04-05                                           nbdsh(1)