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-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
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
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
300 libnbd(3), nbdcopy(1), nbdfuse(1), nbdsh(1), file(1), jq(1),
301 qemu-img(1), qemu-nbd(8).
302
304 Richard W.M. Jones
305
306 Eric Blake
307
309 Copyright (C) 2020-2021 Red Hat Inc.
310
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)