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-URI
11
12        nbdinfo --size [--json] NBD-URI
13
14        nbdinfo --is read-only|rotational NBD-URI
15
16        nbdinfo --can cache|connect|... NBD-URI
17
18        nbdinfo --map [--totals] [--json] NBD-URI
19
20        nbdinfo -L|--list [--json] NBD-URI
21
22        nbdinfo --help
23
24        nbdinfo --version
25

DESCRIPTION

27       nbdinfo displays information and metadata about an NBD server.  The
28       only required parameter is the NBD URI of the server (see
29       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md):
30
31        $ nbdinfo nbd://localhost
32        protocol: newstyle-fixed without TLS
33        export="":
34                export-size: 1048576 (1M)
35                content: data
36                uri: nbd://localhost:10809/
37                is_rotational: false
38                is_read_only: false
39                can_cache: true
40                can_df: true
41                can_fast_zero: true
42                can_flush: true
43                can_fua: true
44                can_multi_conn: true
45                can_trim: true
46                can_zero: true
47                block_size_minimum: 1
48                block_size_preferred: 4096
49                block_size_maximum: 33554432
50
51       For an NBD server on a local Unix domain socket you would use a command
52       such as this (with similar output to above):
53
54        $ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"
55
56   JSON output
57       To display the output as JSON (eg. for scripting with jq(1)) add the
58       --json parameter:
59
60        $ nbdinfo --json nbd://localhost | jq .
61        {
62          "protocol": "newstyle-fixed",
63          "TLS": false,
64          "exports": [
65            {
66              "export-name": "",
67              "content": "DOS/MBR boot sector; partition 1 : ID=0xc, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 2048, 4148704 sectors",
68              "uri": "nbd://localhost:10809/",
69              "is_rotational": false,
70              "is_read_only": true,
71              "can_cache": true,
72              "can_df": true,
73              "can_fast_zero": false,
74              "can_flush": false,
75              "can_fua": false,
76              "can_multi_conn": true,
77              "can_trim": false,
78              "can_zero": false,
79              "block_size_minimum": 1,
80              "block_size_preferred": 4096,
81              "block_size_maximum": 33554432,
82              "export-size": 2125119488,
83              "export-size-str": "2075312K"
84            }
85          ]
86        }
87
88   Size
89       To display only the size in bytes of the NBD export (useful for
90       scripting) use the --size parameter:
91
92        $ nbdinfo --size nbd://localhost
93        1048576
94
95   Test for flags
96       Use one of the options below to test NBD flags.  The command does not
97       print anything.  Instead it exits with success (exit code 0) if true,
98       or failure (exit code 2) if false.  (Other exit codes indicate an error
99       querying the flag).  You can use it in shell scripts like this:
100
101        if nbdinfo --is read-only nbd://localhost ||
102           ! nbdinfo --can trim nbd://localhost
103        then
104            error "the device must support writing and trimming"
105        fi
106
107       nbdinfo --is read-only URI
108           Test if the server export is read-only.
109
110       nbdinfo --can write URI
111           For convenience this is the opposite of --is read-only.
112
113       nbdinfo --can read URI
114           All NBD servers must support read, so this always exits with
115           success (unless there is a failure connecting to the URI).
116
117       nbdinfo --can connect URI
118           Test if we can connect to the NBD URI.
119
120       nbdinfo --is rotational URI
121           Test if the server export is backed by something which behaves like
122           a rotating disk: accessing nearby blocks may be faster than random
123           access and requests should be sorted to improve performance.  Many
124           servers do not or cannot report this accurately.
125
126       nbdinfo --can cache URI
127       nbdinfo --can df URI
128       nbdinfo --can fast-zero URI
129       nbdinfo --can flush URI
130       nbdinfo --can fua URI
131       nbdinfo --can multi-conn URI
132       nbdinfo --can trim URI
133       nbdinfo --can zero URI
134           Test other properties of the NBD server export.
135
136   Map
137       To show a map of which areas of the disk are allocated and sparse, use
138       the --map option:
139
140        $ nbdinfo --map nbd://localhost/
141              0  1048576  0  data
142        1048576  1048576  3  hole,zero
143
144       The fields are: start, size, type, description (optional).
145
146       The type field is an integer showing the raw value from the NBD
147       protocol.  For some maps nbdinfo knows how to translate the type into a
148       printable description.
149
150       To get parseable JSON output, add --json:
151
152        $ nbdinfo --map --json nbd://localhost/
153        [{ "offset": 0, "length": 1048576,
154           "type": 0, "description": "data" },
155         { "offset": 1048576, "length": 1048576,
156           "type": 3, "description": "hole,zero" }]
157
158       By default this shows the "base:allocation" map, but you can show other
159       maps too:
160
161        $ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
162        0  1048576  1  dirty
163
164       For more information on NBD maps, see Metadata querying in the NBD
165       protocol.
166
167   Map totals
168       Using --map --totals performs the same operation as --map but displays
169       a summary of the total size of each type of allocation, in bytes and as
170       a percentage (of the virtual size of the export).  This is useful for
171       estimating how much real storage is used on the server, or might be
172       required when copying a sparse image with nbdcopy(1).
173
174       In the example below, half (50.0%) of the disk is allocated data and
175       half is unallocated:
176
177        $ nbdinfo --map --totals nbd://localhost/
178        1048576  50.0%  0  data
179        1048576  50.0%  3  hole,zero
180
181       The fields are: total size in bytes, percentage of the virtual size,
182       type, description (optional).
183
184       You can also get the same information in parseable form using --json:
185
186        $ nbdinfo --map --totals --json nbd://localhost/
187        [{ "size": 1048576, "percent": 50,
188           "type": 0, "description": "data" },
189         { "size": 1048576, "percent": 50,
190           "type": 3, "description": "hole,zero" }]
191
192       As with the --map option, by default this shows the "base:allocation"
193       map, but you can show the summary for other maps.
194
195   List all exports
196       To list all the exports available on an NBD server use the --list (-L)
197       option.  To get parseable JSON output, add --json.
198
199       For example:
200
201        $ nbdkit file dir=. --run 'nbdinfo --list "$uri"'
202        protocol: newstyle-fixed without TLS
203        export="Fedora-Workstation-Live-x86_64-29-1.2.iso":
204            export-size: 1931476992 (1842M)
205            uri: nbd://localhost:10809/Fedora-Workstation-Live-x86_64-29-1.2.iso
206            [...]
207        export="debian-10.4.0-amd64-DVD-1.iso":
208            export-size: 3955556352 (3862848K)
209            uri: nbd://localhost:10809/debian-10.4.0-amd64-DVD-1.iso
210            [...]
211
212   Alternative tools
213       You could use "qemu-img info" (see qemu-img(1)) to query a single
214       export from an NBD server.  "qemu-nbd -L" (see qemu-nbd(8)) can list
215       NBD exports.  nbdsh(1) or the libnbd(3) API can be used for more
216       complex queries.
217

OPTIONS

219       --help
220           Display brief command line help and exit.
221
222       --can cache
223       --can connect
224       --can df
225       --can fast-zero
226       --can flush
227       --can fua
228       --can multi-conn
229       --can read
230       --can trim
231       --can write
232       --can zero
233           Test properties of the NBD server export.  The command does not
234           print anything.  Instead it exits with success (exit code 0) if
235           true, or failure (exit code 2) if false.  (Other exit codes
236           indicate an error querying the flag).
237
238           For further information see the NBD protocol and the following
239           libnbd functions: nbd_can_cache(3), nbd_can_df(3),
240           nbd_can_fast_zero(3), nbd_can_flush(3), nbd_can_fua(3),
241           nbd_can_multi_conn(3), nbd_can_trim(3), nbd_can_zero(3),
242           nbd_is_read_only(3).
243
244       --content
245       --no-content
246           Mostly the information displayed comes from the metadata sent by
247           the NBD server during the handshake.  However nbdinfo also
248           downloads a small amount of data from the beginning of the export
249           to try to probe the content with file(1).
250
251           When not using --list, the default is --content, ie.  probing the
252           content.  To prevent content probing, use --no-content.
253
254           When using --list, the default is --no-content (since downloading
255           from each export is expensive).  To enable content probing use
256           --list --content.
257
258       --is read-only
259       --is rotational
260           Test if the NBD server export is read-only and rotational.  The
261           command does not print anything.  Instead it exits with success
262           (exit code 0) if true, or failure (exit code 2) if false.  (Other
263           exit codes indicate an error querying the flag).
264
265           For further information see the NBD protocol and the following
266           libnbd functions: nbd_is_read_only(3), nbd_is_rotational(3).
267
268       --json
269           The output is displayed in JSON format.
270
271       -L
272       --list
273           List all the exports on an NBD server.  The export name in the NBD
274           URI is ignored.
275
276       --map
277       --map=MAP
278           Display the map (usually whether parts of the disk are allocated or
279           sparse) of the given export.  This displays the "base:allocation"
280           map by default, you can choose a different map with the optional
281           parameter.
282
283           See the "Map" section above.
284
285       --map --totals
286       --map=MAP --totals
287           The same as --map, but displays a summary of the total size of each
288           type of allocation.
289
290           See the "Map totals" section above.
291
292       --size
293           Display only the size in bytes of the export.
294
295       -V
296       --version
297           Display the package name and version and exit.
298

SEE ALSO

300       libnbd(3), nbdcopy(1), nbdfuse(1), nbdsh(1), file(1), jq(1),
301       qemu-img(1), qemu-nbd(8).
302

AUTHORS

304       Richard W.M. Jones
305
306       Eric Blake
307
309       Copyright (C) 2020-2021 Red Hat Inc.
310

LICENSE

312       This library is free software; you can redistribute it and/or modify it
313       under the terms of the GNU Lesser General Public License as published
314       by the Free Software Foundation; either version 2 of the License, or
315       (at your option) any later version.
316
317       This library is distributed in the hope that it will be useful, but
318       WITHOUT ANY WARRANTY; without even the implied warranty of
319       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
320       Lesser General Public License for more details.
321
322       You should have received a copy of the GNU Lesser General Public
323       License along with this library; if not, write to the Free Software
324       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
325       02110-1301 USA
326
327
328
329libnbd-1.10.1                     2021-10-25                        nbdinfo(1)
Impressum