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