1nbdinfo(1) LIBNBD nbdinfo(1)
2
6 nbdinfo - display information and metadata about NBD servers and
7 exports
8
10 nbdinfo [--json] NBD
11 "NBD" is an NBD URI or subprocess:
13 NBD := nbd://... | nbd+unix:// (or other URI formats)
15 | [ CMD ARGS ... ]
16 nbdinfo --size [--json] NBD
18 nbdinfo --is read-only|rotational NBD
20 nbdinfo --can cache|connect|... NBD
22 nbdinfo --map [--totals] [--json] NBD
24 nbdinfo -L|--list [--json] NBD
26 nbdinfo --help
28 nbdinfo --version
30
32 nbdinfo displays information and metadata about an NBD server.
33 The single required parameter can be the NBD URI of the server (see
35 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md):
36 $ nbdinfo nbd://localhost
38 protocol: newstyle-fixed without TLS
39 export="":
40 export-size: 1048576 (1M)
41 content: data
42 uri: nbd://localhost:10809/
43 is_rotational: false
44 is_read_only: false
45 can_cache: true
46 can_df: true
47 can_fast_zero: true
48 can_flush: true
49 can_fua: true
50 can_multi_conn: true
51 can_trim: true
52 can_zero: true
53 block_size_minimum: 1
54 block_size_preferred: 4096
55 block_size_maximum: 33554432
56 For an NBD server on a local Unix domain socket you would use a command
58 such as this (with similar output to above):
59 $ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"
61 Or you can run the NBD server as a subprocess (see section "Subprocess"
63 below):
64 $ nbdinfo -- [ qemu-nbd -r -f qcow2 file.qcow2 ]
66 JSON output
68 To display the output as JSON (eg. for scripting with jq(1)) add the
69 --json parameter:
70 $ nbdinfo --json nbd://localhost | jq .
72 {
73 "protocol": "newstyle-fixed",
74 "TLS": false,
75 "exports": [
76 {
77 "export-name": "",
78 "content": "DOS/MBR boot sector; partition 1 : ID=0xc, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 2048, 4148704 sectors",
79 "uri": "nbd://localhost:10809/",
80 "is_rotational": false,
81 "is_read_only": true,
82 "can_cache": true,
83 "can_df": true,
84 "can_fast_zero": false,
85 "can_flush": false,
86 "can_fua": false,
87 "can_multi_conn": true,
88 "can_trim": false,
89 "can_zero": false,
90 "block_size_minimum": 1,
91 "block_size_preferred": 4096,
92 "block_size_maximum": 33554432,
93 "export-size": 2125119488,
94 "export-size-str": "2075312K"
95 }
96 ]
97 }
98 Size
100 To display only the size in bytes of the NBD export (useful for
101 scripting) use the --size parameter:
102 $ nbdinfo --size nbd://localhost
104 1048576
105 $ nbdinfo --size [ nbdkit null 1M ]
107 1048576
108 Test for flags
110 Use one of the options below to test NBD flags. The command does not
111 print anything. Instead it exits with success (exit code 0) if true,
112 or failure (exit code 2) if false. (Other exit codes indicate an error
113 querying the flag). You can use it in shell scripts like this:
114 if nbdinfo --is read-only nbd://localhost ||
116 ! nbdinfo --can trim nbd://localhost
117 then
118 error "the device must support writing and trimming"
119 fi
120 nbdinfo --is read-only URI
122 Test if the server export is read-only.
123 nbdinfo --can write URI
125 For convenience this is the opposite of --is read-only.
126 nbdinfo --can read URI
128 All NBD servers must support read, so this always exits with
129 success (unless there is a failure connecting to the URI).
130 nbdinfo --can connect URI
132 Test if we can connect to the NBD URI.
133 nbdinfo --is rotational URI
135 Test if the server export is backed by something which behaves like
136 a rotating disk: accessing nearby blocks may be faster than random
137 access and requests should be sorted to improve performance. Many
138 servers do not or cannot report this accurately.
139 nbdinfo --can cache URI
141 nbdinfo --can df URI
142 nbdinfo --can fast-zero URI
143 nbdinfo --can flush URI
144 nbdinfo --can fua URI
145 nbdinfo --can multi-conn URI
146 nbdinfo --can trim URI
147 nbdinfo --can zero URI
148 Test other properties of the NBD server export.
149 Map
151 To show a map of which areas of the disk are allocated and sparse, use
152 the --map option:
153 $ nbdinfo --map nbd://localhost/
155 0 1048576 0 data
156 1048576 1048576 3 hole,zero
157 The fields are: start, size, type, description (optional).
159 The type field is an integer showing the raw value from the NBD
161 protocol. For some maps nbdinfo knows how to translate the type into a
162 printable description.
163 To get parseable JSON output, add --json:
165 $ nbdinfo --map --json nbd://localhost/
167 [{ "offset": 0, "length": 1048576,
168 "type": 0, "description": "data" },
169 { "offset": 1048576, "length": 1048576,
170 "type": 3, "description": "hole,zero" }]
171 By default this shows the "base:allocation" map, but you can show other
173 maps too:
174 $ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
176 0 1048576 1 dirty
177 For more information on NBD maps, see Metadata querying in the NBD
179 protocol.
180 Map totals
182 Using --map --totals performs the same operation as --map but displays
183 a summary of the total size of each type of allocation, in bytes and as
184 a percentage (of the virtual size of the export). This is useful for
185 estimating how much real storage is used on the server, or might be
186 required when copying a sparse image with nbdcopy(1).
187 In the example below, half (50.0%) of the disk is allocated data and
189 half is unallocated:
190 $ nbdinfo --map --totals nbd://localhost/
192 1048576 50.0% 0 data
193 1048576 50.0% 3 hole,zero
194 The fields are: total size in bytes, percentage of the virtual size,
196 type, description (optional).
197 You can also get the same information in parseable form using --json:
199 $ nbdinfo --map --totals --json nbd://localhost/
201 [{ "size": 1048576, "percent": 50,
202 "type": 0, "description": "data" },
203 { "size": 1048576, "percent": 50,
204 "type": 3, "description": "hole,zero" }]
205 As with the --map option, by default this shows the "base:allocation"
207 map, but you can show the summary for other maps.
208 List all exports
210 To list all the exports available on an NBD server use the --list (-L)
211 option. To get parseable JSON output, add --json.
212 For example:
214 $ nbdkit file dir=. --run 'nbdinfo --list "$uri"'
216 protocol: newstyle-fixed without TLS
217 export="Fedora-Workstation-Live-x86_64-29-1.2.iso":
218 export-size: 1931476992 (1842M)
219 uri: nbd://localhost:10809/Fedora-Workstation-Live-x86_64-29-1.2.iso
220 [...]
221 export="debian-10.4.0-amd64-DVD-1.iso":
222 export-size: 3955556352 (3862848K)
223 uri: nbd://localhost:10809/debian-10.4.0-amd64-DVD-1.iso
224 [...]
225 Subprocess
227 nbdinfo can also run an NBD server as a subprocess. This requires an
228 NBD server which understands systemd socket activation, such as
229 qemu-nbd(8) or nbdkit(1). All the usual nbdinfo modes can be used.
230 For example, to give general information or display the map of a qcow2
232 file:
233 nbdinfo -- [ qemu-nbd -r -f qcow2 file.qcow2 ]
235 nbdinfo --map -- [ qemu-nbd -r -f qcow2 file.qcow2 ]
237 Note that "[ ... ]" are separate parameters, and must be surrounded by
239 spaces. "--" separates nbdinfo parameters from subprocess parameters.
240 Alternative tools
242 You could use "qemu-img info" (see qemu-img(1)) to query a single
243 export from an NBD server. "qemu-nbd -L" (see qemu-nbd(8)) can list
244 NBD exports. nbdsh(1) or the libnbd(3) API can be used for more
245 complex queries.
246
248 --help
249 Display brief command line help and exit.
250 --can cache
252 --can connect
253 --can df
254 --can fast-zero
255 --can flush
256 --can fua
257 --can multi-conn
258 --can read
259 --can trim
260 --can write
261 --can zero
262 Test properties of the NBD server export. The command does not
263 print anything. Instead it exits with success (exit code 0) if
264 true, or failure (exit code 2) if false. (Other exit codes
265 indicate an error querying the flag).
266 For further information see the NBD protocol and the following
268 libnbd functions: nbd_can_cache(3), nbd_can_df(3),
269 nbd_can_fast_zero(3), nbd_can_flush(3), nbd_can_fua(3),
270 nbd_can_multi_conn(3), nbd_can_trim(3), nbd_can_zero(3),
271 nbd_is_read_only(3).
272 --content
274 --no-content
275 Mostly the information displayed comes from the metadata sent by
276 the NBD server during the handshake. However nbdinfo also
277 downloads a small amount of data from the beginning of the export
278 to try to probe the content with file(1).
279 When not using --list, the default is --content, ie. probing the
281 content. To prevent content probing, use --no-content.
282 When using --list, the default is --no-content (since downloading
284 from each export is expensive). To enable content probing use
285 --list --content.
286 --is read-only
288 --is rotational
289 Test if the NBD server export is read-only and rotational. The
290 command does not print anything. Instead it exits with success
291 (exit code 0) if true, or failure (exit code 2) if false. (Other
292 exit codes indicate an error querying the flag).
293 For further information see the NBD protocol and the following
295 libnbd functions: nbd_is_read_only(3), nbd_is_rotational(3).
296 --json
298 The output is displayed in JSON format.
299 -L
301 --list
302 List all the exports on an NBD server. The export name in the NBD
303 URI is ignored.
304 --map
306 --map=MAP
307 Display the map (usually whether parts of the disk are allocated or
308 sparse) of the given export. This displays the "base:allocation"
309 map by default, you can choose a different map with the optional
310 parameter.
311 See the "Map" section above.
313 --map --totals
315 --map=MAP --totals
316 The same as --map, but displays a summary of the total size of each
317 type of allocation.
318 See the "Map totals" section above.
320 --size
322 Display only the size in bytes of the export.
323 -V
325 --version
326 Display the package name and version and exit.
327
329 libnbd(3), nbdcopy(1), nbdfuse(1), nbdsh(1), file(1), jq(1),
330 qemu-img(1), qemu-nbd(8).
331
333 Richard W.M. Jones
334 Eric Blake
336
338 Copyright (C) 2020-2021 Red Hat Inc.
339
341 This library is free software; you can redistribute it and/or modify it
342 under the terms of the GNU Lesser General Public License as published
343 by the Free Software Foundation; either version 2 of the License, or
344 (at your option) any later version.
345 This library is distributed in the hope that it will be useful, but
347 WITHOUT ANY WARRANTY; without even the implied warranty of
348 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
349 Lesser General Public License for more details.
350 You should have received a copy of the GNU Lesser General Public
352 License along with this library; if not, write to the Free Software
353 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
354 02110-1301 USA
355libnbd-1.12.5 2022-07-10 nbdinfo(1)