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, using structured packets
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 "structured": true,
76 "extended": false,
77 "exports": [
78 {
79 "export-name": "",
80 "content": "DOS/MBR boot sector; partition 1 : ID=0xc, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 2048, 4148704 sectors",
81 "uri": "nbd://localhost:10809/",
82 "is_rotational": false,
83 "is_read_only": true,
84 "can_cache": true,
85 "can_df": true,
86 "can_fast_zero": false,
87 "can_flush": false,
88 "can_fua": false,
89 "can_multi_conn": true,
90 "can_trim": false,
91 "can_zero": false,
92 "block_size_minimum": 1,
93 "block_size_preferred": 4096,
94 "block_size_maximum": 33554432,
95 "export-size": 2125119488,
96 "export-size-str": "2075312K"
97 }
98 ]
99 }
100 Size
102 To display only the size in bytes of the NBD export (useful for
103 scripting) use the --size parameter:
104 $ nbdinfo --size nbd://localhost
106 1048576
107 $ nbdinfo --size [ nbdkit null 1M ]
109 1048576
110 Test for flags
112 Use one of the options below to test NBD flags. The command does not
113 print anything. Instead it exits with success (exit code 0) if true,
114 or failure (exit code 2) if false. (Other exit codes indicate an error
115 querying the flag). You can use it in shell scripts like this:
116 if nbdinfo --is read-only nbd://localhost ||
118 ! nbdinfo --can trim nbd://localhost
119 then
120 error "the device must support writing and trimming"
121 fi
122 nbdinfo --is read-only URI
124 Test if the server export is read-only.
125 nbdinfo --can write URI
127 For convenience this is the opposite of --is read-only.
128 nbdinfo --can read URI
130 All NBD servers must support read, so this always exits with
131 success (unless there is a failure connecting to the URI).
132 nbdinfo --can connect URI
134 Test if we can connect to the NBD URI.
135 nbdinfo --is tls URI
137 Test if the NBD URI connection is using TLS.
138 nbdinfo --has structured-reply URI
140 Test if server has support for structured replies (a prerequisite
141 for supporting block status commands).
142 nbdinfo --has extended-headers URI
144 Test if server supports extended headers (a prerequisite for
145 supporting 64-bit commands; implies structured replies as well).
146 nbdinfo --is rotational URI
148 Test if the server export is backed by something which behaves like
149 a rotating disk: accessing nearby blocks may be faster than random
150 access and requests should be sorted to improve performance. Many
151 servers do not or cannot report this accurately.
152 nbdinfo --can block-status-payload URI
154 Test if the server export has support for passing a client payload
155 to limit the response to a block status command.
156 nbdinfo --can cache URI
158 nbdinfo --can df URI
159 nbdinfo --can fast-zero URI
160 nbdinfo --can flush URI
161 nbdinfo --can fua URI
162 nbdinfo --can multi-conn URI
163 nbdinfo --can trim URI
164 nbdinfo --can zero URI
165 Test other properties of the NBD server export.
166 Map
168 To show a map of which areas of the disk are allocated and sparse, use
169 the --map option:
170 $ nbdinfo --map nbd://localhost/
172 0 1048576 0 data
173 1048576 1048576 3 hole,zero
174 The fields are: start, size, type, description (optional).
176 The type field is an integer showing the raw value from the NBD
178 protocol. For some maps nbdinfo knows how to translate the type into a
179 printable description.
180 To get parseable JSON output, add --json:
182 $ nbdinfo --map --json nbd://localhost/
184 [{ "offset": 0, "length": 1048576,
185 "type": 0, "description": "data" },
186 { "offset": 1048576, "length": 1048576,
187 "type": 3, "description": "hole,zero" }]
188 By default this shows the "base:allocation" map, but you can show other
190 maps too:
191 $ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
193 0 1048576 1 dirty
194 For more information on NBD maps, see Metadata querying in the NBD
196 protocol.
197 Map totals
199 Using --map --totals performs the same operation as --map but displays
200 a summary of the total size of each type of allocation, in bytes and as
201 a percentage (of the virtual size of the export). This is useful for
202 estimating how much real storage is used on the server, or might be
203 required when copying a sparse image with nbdcopy(1).
204 In the example below, half (50.0%) of the disk is allocated data and
206 half is unallocated:
207 $ nbdinfo --map --totals nbd://localhost/
209 1048576 50.0% 0 data
210 1048576 50.0% 3 hole,zero
211 The fields are: total size in bytes, percentage of the virtual size,
213 type, description (optional).
214 You can also get the same information in parseable form using --json:
216 $ nbdinfo --map --totals --json nbd://localhost/
218 [{ "size": 1048576, "percent": 50,
219 "type": 0, "description": "data" },
220 { "size": 1048576, "percent": 50,
221 "type": 3, "description": "hole,zero" }]
222 As with the --map option, by default this shows the "base:allocation"
224 map, but you can show the summary for other maps.
225 List all exports
227 To list all the exports available on an NBD server use the --list (-L)
228 option. To get parseable JSON output, add --json.
229 For example:
231 $ nbdkit file dir=. --run 'nbdinfo --list "$uri"'
233 protocol: newstyle-fixed without TLS
234 export="Fedora-Workstation-Live-x86_64-29-1.2.iso":
235 export-size: 1931476992 (1842M)
236 uri: nbd://localhost:10809/Fedora-Workstation-Live-x86_64-29-1.2.iso
237 [...]
238 export="debian-10.4.0-amd64-DVD-1.iso":
239 export-size: 3955556352 (3862848K)
240 uri: nbd://localhost:10809/debian-10.4.0-amd64-DVD-1.iso
241 [...]
242 Subprocess
244 nbdinfo can also run an NBD server as a subprocess. This requires an
245 NBD server which understands systemd socket activation, such as
246 qemu-nbd(8) or nbdkit(1). All the usual nbdinfo modes can be used.
247 For example, to give general information or display the map of a qcow2
249 file:
250 nbdinfo -- [ qemu-nbd -r -f qcow2 file.qcow2 ]
252 nbdinfo --map -- [ qemu-nbd -r -f qcow2 file.qcow2 ]
254 Note that "[ ... ]" are separate parameters, and must be surrounded by
256 spaces. "--" separates nbdinfo parameters from subprocess parameters.
257 Alternative tools
259 You could use "qemu-img info" (see qemu-img(1)) to query a single
260 export from an NBD server. "qemu-nbd -L" (see qemu-nbd(8)) can list
261 NBD exports. nbdsh(1) or the libnbd(3) API can be used for more
262 complex queries.
263
265 --help
266 Display brief command line help and exit.
267 --can block-status-payload
269 --can cache
270 --can connect
271 --can df
272 --can fast-zero
273 --can flush
274 --can fua
275 --can multi-conn
276 --can read
277 --can trim
278 --can write
279 --can zero
280 Test properties of the NBD server export. The command does not
281 print anything. Instead it exits with success (exit code 0) if
282 true, or failure (exit code 2) if false. (Other exit codes
283 indicate an error querying the flag).
284 For further information see the NBD protocol and the following
286 libnbd functions: nbd_can_block_status_payload(3),
287 nbd_can_cache(3), nbd_can_df(3), nbd_can_fast_zero(3),
288 nbd_can_flush(3), nbd_can_fua(3), nbd_can_multi_conn(3),
289 nbd_can_trim(3), nbd_can_zero(3), nbd_is_read_only(3).
290 --color
292 --colour
293 --no-color
294 --no-colour
295 Enable or disable ANSI colours in output. By default we use
296 colours if the output seems to be a terminal, and disable them if
297 not.
298 --content
300 --no-content
301 Mostly the information displayed comes from the metadata sent by
302 the NBD server during the handshake. However nbdinfo also
303 downloads a small amount of data from the beginning of the export
304 to try to probe the content with file(1).
305 When not using --list, the default is --content, ie. probing the
307 content. To prevent content probing, use --no-content.
308 When using --list, the default is --no-content (since downloading
310 from each export is expensive). To enable content probing use
311 --list --content.
312 --has extended-headers
314 --has structured-reply
315 Test properties of the NBD server connection. The command does not
316 print anything. Instead it exits with success (exit code 0) if
317 true, or failure (exit code 2) if false. (Other exit codes
318 indicate an error querying the flag).
319 For further information see the NBD protocol and the following
321 libnbd functions: nbd_get_extended_headers_negotiated(3),
322 nbd_get_structured_replies_negotiated(3).
323 --is read-only
325 --is rotational
326 --is tls
327 Test if the NBD server export is read-only and rotational, or
328 whether the connection itself is using TLS. The command does not
329 print anything. Instead it exits with success (exit code 0) if
330 true, or failure (exit code 2) if false. (Other exit codes
331 indicate an error querying the flag).
332 For further information see the NBD protocol and the following
334 libnbd functions: nbd_is_read_only(3), nbd_is_rotational(3),
335 nbd_get_tls_negotiated(3).
336 --json
338 The output is displayed in JSON format.
339 -L
341 --list
342 List all the exports on an NBD server. The export name in the NBD
343 URI is ignored.
344 --map
346 --map=MAP
347 Display the map (usually whether parts of the disk are allocated or
348 sparse) of the given export. This displays the "base:allocation"
349 map by default, you can choose a different map with the optional
350 parameter.
351 See the "Map" section above.
353 --map --totals
355 --map=MAP --totals
356 The same as --map, but displays a summary of the total size of each
357 type of allocation.
358 See the "Map totals" section above.
360 --size
362 Display only the size in bytes of the export.
363 -V
365 --version
366 Display the package name and version and exit.
367
369 libnbd(3), nbdcopy(1), nbddump(1), nbdfuse(1), nbdsh(1), nbdublk(1),
370 file(1), jq(1), qemu-img(1), qemu-nbd(8).
371
373 Richard W.M. Jones
374 Eric Blake
376
378 Copyright Red Hat
379
381 This library is free software; you can redistribute it and/or modify it
382 under the terms of the GNU Lesser General Public License as published
383 by the Free Software Foundation; either version 2 of the License, or
384 (at your option) any later version.
385 This library is distributed in the hope that it will be useful, but
387 WITHOUT ANY WARRANTY; without even the implied warranty of
388 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
389 Lesser General Public License for more details.
390 You should have received a copy of the GNU Lesser General Public
392 License along with this library; if not, write to the Free Software
393 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
394 02110-1301 USA
395libnbd-1.18.1 2023-10-31 nbdinfo(1)