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] [--map] [--size] NBD-URI
11
12        nbdinfo -L|--list NBD-URI
13
14        nbdinfo --help
15
16        nbdinfo --version
17

DESCRIPTION

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
23        $ 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
42       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
45        $ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"
46
47   Size
48       To display only the size in bytes of the NBD export (useful for
49       scripting) use the --size parameter:
50
51        $ nbdinfo --size nbd://localhost
52        1048576
53
54   JSON output
55       To display the output as JSON (eg. for scripting with jq(1)) add the
56       --json parameter:
57
58        $ 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
84   Map
85       To show a map of which areas of the disk are allocated and sparse, use
86       the --map option:
87
88        $ nbdinfo --map nbd://localhost/
89              0  1048576  0  allocated
90        1048576  1048576  3  hole,zero
91
92       The fields are: start, size, type, description (optional).
93
94       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
98       To get parseable JSON output, add --json:
99
100        $ 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
106       By default this shows the "base:allocation" map, but you can show other
107       maps too:
108
109        $ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
110        0  1048576  1  dirty
111
112       For more information on NBD maps, see Metadata querying in the NBD
113       protocol.
114
115   List all exports
116       To list all the exports available on an NBD server use the --list (-L)
117       option.
118
119   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

OPTIONS

126       --help
127           Display brief command line help and exit.
128
129       --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
136           When not using --list, the default is --content, ie.  probing the
137           content.  To prevent content probing, use --no-content.
138
139           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
143       --json
144           The output is displayed in JSON format.
145
146       --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
153       -L
154       --list
155           List all the exports on an NBD server.  The export name in the NBD
156           URI is ignored.
157
158       --size
159           Display only the size in bytes of the export.
160
161       -V
162       --version
163           Display the package name and version and exit.
164

SEE ALSO

166       libnbd(3), nbdcopy(1), nbdfuse(1), nbdsh(1), file(1), jq(1),
167       qemu-img(1), qemu-nbd(8).
168

AUTHORS

170       Richard W.M. Jones
171
172       Eric Blake
173
175       Copyright (C) 2020 Red Hat Inc.
176

LICENSE

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
183       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
188       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
192
193
194
195libnbd-1.6.2                      2021-03-02                        nbdinfo(1)
Impressum