1nbdsh(1) LIBNBD nbdsh(1)
2
3
4
6 nbdsh - network block device (NBD) shell
7
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
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
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
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 -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
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
128 libnbd(3), libnbd-security(3), nbdcopy(1), nbddump(1), nbdfuse(1),
129 nbdinfo(1), qemu-img(1).
130
132 Richard W.M. Jones
133
135 Copyright (C) 2019-2021 Red Hat Inc.
136
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.14.2 2023-01-03 nbdsh(1)