1nbdinfo(1)                          LIBNBD                          nbdinfo(1)
2
3
4

NAME

6       nbdinfo - display information and metadata about NBD servers and
7       exports
8

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

SEE ALSO

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

AUTHORS

361       Richard W.M. Jones
362
363       Eric Blake
364
366       Copyright Red Hat
367

LICENSE

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)
Impressum