1nbdinfo(1) LIBNBD nbdinfo(1)
2
6 nbdinfo - display information and metadata about NBD servers and
7 exports
8
10 nbdinfo [--json] NBD-URI
11 nbdinfo --size [--json] NBD-URI
13 nbdinfo --map [--json] NBD-URI
15 nbdinfo -L|--list [--json] NBD-URI
17 nbdinfo --help
19 nbdinfo --version
21
23 nbdinfo displays information and metadata about an NBD server. The
24 only required parameter is the NBD URI of the server (see
25 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md):
26 $ nbdinfo nbd://localhost
28 protocol: newstyle-fixed without TLS
29 export="":
30 export-size: 1048576
31 content: data
32 uri: nbd://localhost:10809/
33 is_rotational: false
34 is_read_only: false
35 can_cache: true
36 can_df: true
37 can_fast_zero: true
38 can_flush: true
39 can_fua: true
40 can_multi_conn: true
41 can_trim: true
42 can_zero: true
43 block_size_minimum: 1
44 block_size_preferred: 4096
45 block_size_maximum: 33554432
46 For an NBD server on a local Unix domain socket you would use a command
48 such as this (with similar output to above):
49 $ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"
51 JSON output
53 To display the output as JSON (eg. for scripting with jq(1)) add the
54 --json parameter:
55 $ nbdinfo --json nbd://localhost | jq .
57 {
58 "protocol": "newstyle-fixed",
59 "TLS": false,
60 "exports": [
61 {
62 "export-name": "",
63 "content": "DOS/MBR boot sector; partition 1 : ID=0xc, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 2048, 4148704 sectors",
64 "uri": "nbd://localhost:10809/",
65 "is_rotational": false,
66 "is_read_only": true,
67 "can_cache": true,
68 "can_df": true,
69 "can_fast_zero": false,
70 "can_flush": false,
71 "can_fua": false,
72 "can_multi_conn": true,
73 "can_trim": false,
74 "can_zero": false,
75 "block_size_minimum": 1,
76 "block_size_preferred": 4096,
77 "block_size_maximum": 33554432,
78 "export-size": 2125119488
79 }
80 ]
81 }
82 Size
84 To display only the size in bytes of the NBD export (useful for
85 scripting) use the --size parameter:
86 $ nbdinfo --size nbd://localhost
88 1048576
89 Map
91 To show a map of which areas of the disk are allocated and sparse, use
92 the --map option:
93 $ nbdinfo --map nbd://localhost/
95 0 1048576 0 allocated
96 1048576 1048576 3 hole,zero
97 The fields are: start, size, type, description (optional).
99 The type field is an integer showing the raw value from the NBD
101 protocol. For some maps nbdinfo knows how to translate the type into a
102 printable description.
103 To get parseable JSON output, add --json:
105 $ nbdinfo --map --json nbd://localhost/
107 [{ "offset": 0, "length": 1048576,
108 "type": 0, "description": "allocated" },
109 { "offset": 1048576, "length": 1048576,
110 "type": 3, "description": "hole,zero" }]
111 By default this shows the "base:allocation" map, but you can show other
113 maps too:
114 $ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
116 0 1048576 1 dirty
117 For more information on NBD maps, see Metadata querying in the NBD
119 protocol.
120 List all exports
122 To list all the exports available on an NBD server use the --list (-L)
123 option. To get parseable JSON output, add --json.
124 For example:
126 $ nbdkit file dir=. --run 'nbdinfo --list "$uri"'
128 protocol: newstyle-fixed without TLS
129 export="Fedora-Workstation-Live-x86_64-29-1.2.iso":
130 export-size: 1931476992
131 uri: nbd://localhost:10809/Fedora-Workstation-Live-x86_64-29-1.2.iso
132 [...]
133 export="debian-10.4.0-amd64-DVD-1.iso":
134 export-size: 3955556352
135 uri: nbd://localhost:10809/debian-10.4.0-amd64-DVD-1.iso
136 [...]
137 Alternative tools
139 You could use "qemu-img info" (see qemu-img(1)) to query a single
140 export from an NBD server. "qemu-nbd -L" (see qemu-nbd(8)) can list
141 NBD exports. nbdsh(1) or the libnbd(3) API can be used for more
142 complex queries.
143
145 --help
146 Display brief command line help and exit.
147 --content
149 --no-content
150 Mostly the information displayed comes from the metadata sent by
151 the NBD server during the handshake. However nbdinfo also
152 downloads a small amount of data from the beginning of the export
153 to try to probe the content with file(1).
154 When not using --list, the default is --content, ie. probing the
156 content. To prevent content probing, use --no-content.
157 When using --list, the default is --no-content (since downloading
159 from each export is expensive). To enable content probing use
160 --list --content.
161 --json
163 The output is displayed in JSON format.
164 --map
166 --map=MAP
167 Display the map (usually whether parts of the disk are allocated or
168 sparse) of the given export. This displays the "base:allocation"
169 map by default, you can choose a different map with the optional
170 parameter.
171 -L
173 --list
174 List all the exports on an NBD server. The export name in the NBD
175 URI is ignored.
176 --size
178 Display only the size in bytes of the export.
179 -V
181 --version
182 Display the package name and version and exit.
183
185 libnbd(3), nbdcopy(1), nbdfuse(1), nbdsh(1), file(1), jq(1),
186 qemu-img(1), qemu-nbd(8).
187
189 Richard W.M. Jones
190 Eric Blake
192
194 Copyright (C) 2020-2021 Red Hat Inc.
195
197 This library is free software; you can redistribute it and/or modify it
198 under the terms of the GNU Lesser General Public License as published
199 by the Free Software Foundation; either version 2 of the License, or
200 (at your option) any later version.
201 This library is distributed in the hope that it will be useful, but
203 WITHOUT ANY WARRANTY; without even the implied warranty of
204 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
205 Lesser General Public License for more details.
206 You should have received a copy of the GNU Lesser General Public
208 License along with this library; if not, write to the Free Software
209 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
210 02110-1301 USA
211libnbd-1.7.12 2021-05-29 nbdinfo(1)