1nbdinfo(1) LIBNBD nbdinfo(1)
2
6 nbdinfo - display information and metadata about NBD servers and
7 exports
8
10 nbdinfo [--json] [--map] [--size] NBD-URI
11 nbdinfo -L|--list NBD-URI
13 nbdinfo --help
15 nbdinfo --version
17
19 nbdinfo displays information and metadata about an NBD server. The
20 only required parameter is the NBD URI of the server (see
21 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md):
22 $ nbdinfo nbd://localhost
24 protocol: newstyle-fixed without TLS
25 export="":
26 export-size: 1048576
27 content: data
28 is_rotational: false
29 is_read_only: false
30 can_cache: true
31 can_df: true
32 can_fast_zero: true
33 can_flush: true
34 can_fua: true
35 can_multi_conn: true
36 can_trim: true
37 can_zero: true
38 block_size_minimum: 1
39 block_size_preferred: 4096
40 block_size_maximum: 33554432
41 For an NBD server on a local Unix domain socket you would use a command
43 such as this (with the same output as above):
44 $ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"
46 Size
48 To display only the size in bytes of the NBD export (useful for
49 scripting) use the --size parameter:
50 $ nbdinfo --size nbd://localhost
52 1048576
53 JSON output
55 To display the output as JSON (eg. for scripting with jq(1)) add the
56 --json parameter:
57 $ nbdinfo --json nbd://localhost | jq
59 {
60 "protocol": "newstyle-fixed",
61 "TLS": false,
62 "exports": [
63 {
64 "export-name": "",
65 "content": "DOS/MBR boot sector; partition 1 : ID=0xc, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 2048, 4148704 sectors",
66 "is_rotational": false,
67 "is_read_only": true,
68 "can_cache": true,
69 "can_df": true,
70 "can_fast_zero": false,
71 "can_flush": false,
72 "can_fua": false,
73 "can_multi_conn": true,
74 "can_trim": false,
75 "can_zero": false,
76 "block_size_minimum": 1,
77 "block_size_preferred": 4096,
78 "block_size_maximum": 33554432,
79 "export-size": 2125119488
80 }
81 ]
82 }
83 Map
85 To show a map of which areas of the disk are allocated and sparse, use
86 the --map option:
87 $ nbdinfo --map nbd://localhost/
89 0 1048576 0 allocated
90 1048576 1048576 3 hole,zero
91 The fields are: start, size, type, description (optional).
93 The type field is an integer showing the raw value from the NBD
95 protocol. For some maps nbdinfo knows how to translate the type into a
96 printable description.
97 To get parseable JSON output, add --json:
99 $ nbdinfo --map --json nbd://localhost/
101 [{ "offset": 0, "length": 1048576,
102 "type": 0, "description": "allocated" },
103 { "offset": 1048576, "length": 1048576,
104 "type": 3, "description": "hole,zero" }]
105 By default this shows the "base:allocation" map, but you can show other
107 maps too:
108 $ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
110 0 1048576 1 dirty
111 For more information on NBD maps, see Metadata querying in the NBD
113 protocol.
114 List all exports
116 To list all the exports available on an NBD server use the --list (-L)
117 option.
118 Alternative tools
120 You could use "qemu-img info" (see qemu-img(1)) to query a single
121 export from an NBD server. "qemu-nbd -L" (see qemu-nbd(8)) can list
122 NBD exports. nbdsh(1) or the libnbd(3) API can be used for more
123 complex queries.
124
126 --help
127 Display brief command line help and exit.
128 --content
130 --no-content
131 Mostly the information displayed comes from the metadata sent by
132 the NBD server during the handshake. However nbdinfo also
133 downloads a small amount of data from the beginning of the export
134 to try to probe the content with file(1).
135 When not using --list, the default is --content, ie. probing the
137 content. To prevent content probing, use --no-content.
138 When using --list, the default is --no-content (since downloading
140 from each export is expensive). To enable content probing use
141 --list --content.
142 --json
144 The output is displayed in JSON format.
145 --map
147 --map=MAP
148 Display the map (usually whether parts of the disk are allocated or
149 sparse) of the given export. This displays the "base:allocation"
150 map by default, you can choose a different map with the optional
151 parameter.
152 -L
154 --list
155 List all the exports on an NBD server. The export name in the NBD
156 URI is ignored.
157 --size
159 Display only the size in bytes of the export.
160 -V
162 --version
163 Display the package name and version and exit.
164
166 libnbd(3), nbdcopy(1), nbdfuse(1), nbdsh(1), file(1), jq(1),
167 qemu-img(1), qemu-nbd(8).
168
170 Richard W.M. Jones
171 Eric Blake
173
175 Copyright (C) 2020 Red Hat Inc.
176
178 This library is free software; you can redistribute it and/or modify it
179 under the terms of the GNU Lesser General Public License as published
180 by the Free Software Foundation; either version 2 of the License, or
181 (at your option) any later version.
182 This library is distributed in the hope that it will be useful, but
184 WITHOUT ANY WARRANTY; without even the implied warranty of
185 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
186 Lesser General Public License for more details.
187 You should have received a copy of the GNU Lesser General Public
189 License along with this library; if not, write to the Free Software
190 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
191 02110-1301 USA
192libnbd-1.6.2 2021-03-02 nbdinfo(1)