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, 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(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       --opt-mode
78           Request that option mode be enabled, which gives fine-grained
79           control over option negotiation after initially contacting the
80           server but prior to actually using the export.  This is equivalent
81           to calling "h.set_opt_mode(True)" in the shell prior to connecting,
82           and works even when combined with "--uri" (while attempting the
83           same with "-c" would be too late).
84
85       -u URI
86       -uri URI
87       --connect URI
88           Connect to the given NBD URI.  This is equivalent to the
89           "h.connect_uri(URI)" command in the shell.
90
91           Note that the connection is created prior to processing any "-c"
92           commands, which prevents the use of configuration commands such as
93           "h.add_meta_context("NAME")" from the command line when mixed with
94           this option.  The options "--opt-mode" and "--base-allocation" can
95           be used to make this situation easier to manage.
96
97       -V
98       --version
99           Display the package name and version and exit.
100

NOTES

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

SEE ALSO

122       libnbd(3), libnbd-security(3), nbdcopy(1), nbdfuse(1), nbdinfo(1),
123       qemu-img(1).
124

AUTHORS

126       Richard W.M. Jones
127

129       Copyright (C) 2019-2020 Red Hat Inc.
130

LICENSE

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