1nbdsh(1)                            LIBNBD                            nbdsh(1)
2
3
4

NAME

6       nbdsh - network block device (NBD) shell
7

SYNOPSIS

9        $ nbdsh
10
11        Welcome to nbdsh, the shell for interacting with
12        Network Block Device (NBD) servers.
13
14        The ‘nbd’ module has already been imported and there
15        is an open NBD handle called ‘h’.
16
17        nbd> h.connect_command(["nbdkit", "-s", "memory", "1G"])
18        nbd> h.get_size()
19        1073741824
20        nbd> buf = b"hello, world"
21        nbd> h.pwrite(buf, 0)
22        nbd> exit()
23

DESCRIPTION

25       nbdsh is a Python-based client shell for accessing Network Block Device
26       (NBD) servers.
27
28       For documentation about the libnbd API please open the shell and type:
29
30        help(nbd)
31

EXAMPLES

33   Print the size of an NBD export
34       The -u option connects to an NBD URI.  The -c option lets you execute
35       single Python statements from the command line.  Combining these two
36       options lets you print the size in bytes of an NBD export:
37
38        $ nbdsh -u nbd://localhost -c 'print(h.get_size())'
39        1073741824
40
41   Hexdump the boot sector of an NBD export
42       Using -c - you can feed a whole Python program to the standard input of
43       nbdsh:
44
45        nbdsh -c - <<'EOF'
46        from subprocess import *
47
48        h.connect_uri("nbd://localhost")
49        bootsect = h.pread(512, 0)
50        p = Popen("hexdump -C", shell=True, stdin=PIPE)
51        p.stdin.write(bootsect)
52        EOF
53

OPTIONS

55       -h
56       --help
57           Display brief command line help and exit.
58
59       --base-allocation
60           Request the use of the "base:allocation" meta context, which is the
61           most common context used with nbd_block_status_64(3).  This is
62           equivalent to calling
63           "h.set_meta_context(nbd.CONTEXT_BASE_ALLOCATION)" in the shell
64           prior to connecting, and works even when combined with "--uri"
65           (while attempting the same with "-c" would be too late).
66
67       -c 'COMMAND ...'
68       --command 'COMMAND ...'
69           Instead of starting an interactive shell, run a command.  This
70           option can be specified multiple times in order to run multiple
71           commands.
72
73       -c -
74       --command -
75           Read standard input and execute it as a command.
76
77       -n  Do not create the implicit handle "h".
78
79       --opt-mode
80           Request that option mode be enabled, which gives fine-grained
81           control over option negotiation after initially contacting the
82           server but prior to actually using the export.  This is equivalent
83           to calling "h.set_opt_mode(True)" in the shell prior to connecting,
84           and works even when combined with "--uri" (while attempting the
85           same with "-c" would be too late).
86
87       -u URI
88       --uri URI
89           Connect to the given NBD URI.  This is equivalent to the
90           "h.connect_uri(URI)" command in the shell.
91
92           Note that the connection is created prior to processing any "-c"
93           commands, which prevents the use of configuration commands such as
94           "h.add_meta_context("NAME")" from the command line when mixed with
95           this option.  The options "--opt-mode" and "--base-allocation" can
96           be used to make this situation easier to manage.
97
98       -v
99       --verbose
100           Enable verbose libnbd messages.  This has the same effect as
101           setting the environment variable "LIBNBD_DEBUG=1"
102
103       -V
104       --version
105           Display the package name and version and exit.
106

NOTES

108   nbdsh examples
109       There are some example nbdsh scripts in the libnbd source repository
110       under sh/examples or see
111       https://gitlab.com/nbdkit/libnbd/tree/master/sh/examples.
112
113   Using libnbd directly from Python
114       nbdsh is convenient for command line scripting, but you do not have to
115       use it.  Instead you can write an ordinary Python program or module
116       which imports the "nbd" module:
117
118        #!/usr/bin/python3
119        import nbd
120        h = nbd.NBD()
121        h.connect_uri("nbd://localhost")
122
123       There are some example Python scripts in the libnbd source repository
124       under python/examples or see
125       https://gitlab.com/nbdkit/libnbd/tree/master/python/examples.
126

SEE ALSO

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

AUTHORS

132       Richard W.M. Jones
133

COPYRIGHT

135       Copyright Red Hat
136

LICENSE

138       This library is free software; you can redistribute it and/or modify it
139       under the terms of the GNU Lesser General Public License as published
140       by the Free Software Foundation; either version 2 of the License, or
141       (at your option) any later version.
142
143       This library is distributed in the hope that it will be useful, but
144       WITHOUT ANY WARRANTY; without even the implied warranty of
145       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
146       Lesser General Public License for more details.
147
148       You should have received a copy of the GNU Lesser General Public
149       License along with this library; if not, write to the Free Software
150       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
151       02110-1301 USA
152
153
154
155libnbd-1.18.1                     2023-10-31                          nbdsh(1)