Provided by: libnbd-bin_1.10.5-1_amd64 
NAME
nbdinfo - display information and metadata about NBD servers and exports
SYNOPSIS
nbdinfo [--json] NBD-URI
nbdinfo --size [--json] NBD-URI
nbdinfo --is read-only|rotational NBD-URI
nbdinfo --can cache|connect|... NBD-URI
nbdinfo --map [--totals] [--json] NBD-URI
nbdinfo -L|--list [--json] NBD-URI
nbdinfo --help
nbdinfo --version
DESCRIPTION
nbdinfo displays information and metadata about an NBD server. The only required parameter is the NBD
URI of the server (see https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md):
$ nbdinfo nbd://localhost
protocol: newstyle-fixed without TLS
export="":
export-size: 1048576 (1M)
content: data
uri: nbd://localhost:10809/
is_rotational: false
is_read_only: false
can_cache: true
can_df: true
can_fast_zero: true
can_flush: true
can_fua: true
can_multi_conn: true
can_trim: true
can_zero: true
block_size_minimum: 1
block_size_preferred: 4096
block_size_maximum: 33554432
For an NBD server on a local Unix domain socket you would use a command such as this (with similar output
to above):
$ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"
JSON output
To display the output as JSON (eg. for scripting with jq(1)) add the --json parameter:
$ nbdinfo --json nbd://localhost | jq .
{
"protocol": "newstyle-fixed",
"TLS": false,
"exports": [
{
"export-name": "",
"content": "DOS/MBR boot sector; partition 1 : ID=0xc, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 2048, 4148704 sectors",
"uri": "nbd://localhost:10809/",
"is_rotational": false,
"is_read_only": true,
"can_cache": true,
"can_df": true,
"can_fast_zero": false,
"can_flush": false,
"can_fua": false,
"can_multi_conn": true,
"can_trim": false,
"can_zero": false,
"block_size_minimum": 1,
"block_size_preferred": 4096,
"block_size_maximum": 33554432,
"export-size": 2125119488,
"export-size-str": "2075312K"
}
]
}
Size
To display only the size in bytes of the NBD export (useful for scripting) use the --size parameter:
$ nbdinfo --size nbd://localhost
1048576
Test for flags
Use one of the options below to test NBD flags. The command does not print anything. Instead it exits
with success (exit code 0) if true, or failure (exit code 2) if false. (Other exit codes indicate an
error querying the flag). You can use it in shell scripts like this:
if nbdinfo --is read-only nbd://localhost ||
! nbdinfo --can trim nbd://localhost
then
error "the device must support writing and trimming"
fi
nbdinfo --is read-only URI
Test if the server export is read-only.
nbdinfo --can write URI
For convenience this is the opposite of --is read-only.
nbdinfo --can read URI
All NBD servers must support read, so this always exits with success (unless there is a failure
connecting to the URI).
nbdinfo --can connect URI
Test if we can connect to the NBD URI.
nbdinfo --is rotational URI
Test if the server export is backed by something which behaves like a rotating disk: accessing nearby
blocks may be faster than random access and requests should be sorted to improve performance. Many
servers do not or cannot report this accurately.
nbdinfo --can cache URI
nbdinfo --can df URI
nbdinfo --can fast-zero URI
nbdinfo --can flush URI
nbdinfo --can fua URI
nbdinfo --can multi-conn URI
nbdinfo --can trim URI
nbdinfo --can zero URI
Test other properties of the NBD server export.
Map
To show a map of which areas of the disk are allocated and sparse, use the --map option:
$ nbdinfo --map nbd://localhost/
0 1048576 0 data
1048576 1048576 3 hole,zero
The fields are: start, size, type, description (optional).
The type field is an integer showing the raw value from the NBD protocol. For some maps nbdinfo knows
how to translate the type into a printable description.
To get parseable JSON output, add --json:
$ nbdinfo --map --json nbd://localhost/
[{ "offset": 0, "length": 1048576,
"type": 0, "description": "data" },
{ "offset": 1048576, "length": 1048576,
"type": 3, "description": "hole,zero" }]
By default this shows the "base:allocation" map, but you can show other maps too:
$ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
0 1048576 1 dirty
For more information on NBD maps, see Metadata querying in the NBD protocol.
Map totals
Using --map --totals performs the same operation as --map but displays a summary of the total size of
each type of allocation, in bytes and as a percentage (of the virtual size of the export). This is
useful for estimating how much real storage is used on the server, or might be required when copying a
sparse image with nbdcopy(1).
In the example below, half (50.0%) of the disk is allocated data and half is unallocated:
$ nbdinfo --map --totals nbd://localhost/
1048576 50.0% 0 data
1048576 50.0% 3 hole,zero
The fields are: total size in bytes, percentage of the virtual size, type, description (optional).
You can also get the same information in parseable form using --json:
$ nbdinfo --map --totals --json nbd://localhost/
[{ "size": 1048576, "percent": 50,
"type": 0, "description": "data" },
{ "size": 1048576, "percent": 50,
"type": 3, "description": "hole,zero" }]
As with the --map option, by default this shows the "base:allocation" map, but you can show the summary
for other maps.
List all exports
To list all the exports available on an NBD server use the --list (-L) option. To get parseable JSON
output, add --json.
For example:
$ nbdkit file dir=. --run 'nbdinfo --list "$uri"'
protocol: newstyle-fixed without TLS
export="Fedora-Workstation-Live-x86_64-29-1.2.iso":
export-size: 1931476992 (1842M)
uri: nbd://localhost:10809/Fedora-Workstation-Live-x86_64-29-1.2.iso
[...]
export="debian-10.4.0-amd64-DVD-1.iso":
export-size: 3955556352 (3862848K)
uri: nbd://localhost:10809/debian-10.4.0-amd64-DVD-1.iso
[...]
Alternative tools
You could use "qemu-img info" (see qemu-img(1)) to query a single export from an NBD server.
"qemu-nbd -L" (see qemu-nbd(8)) can list NBD exports. nbdsh(1) or the libnbd(3) API can be used for more
complex queries.
OPTIONS
--help
Display brief command line help and exit.
--can cache
--can connect
--can df
--can fast-zero
--can flush
--can fua
--can multi-conn
--can read
--can trim
--can write
--can zero
Test properties of the NBD server export. The command does not print anything. Instead it exits
with success (exit code 0) if true, or failure (exit code 2) if false. (Other exit codes indicate an
error querying the flag).
For further information see the NBD protocol and the following libnbd functions: nbd_can_cache(3),
nbd_can_df(3), nbd_can_fast_zero(3), nbd_can_flush(3), nbd_can_fua(3), nbd_can_multi_conn(3),
nbd_can_trim(3), nbd_can_zero(3), nbd_is_read_only(3).
--content
--no-content
Mostly the information displayed comes from the metadata sent by the NBD server during the handshake.
However nbdinfo also downloads a small amount of data from the beginning of the export to try to
probe the content with file(1).
When not using --list, the default is --content, ie. probing the content. To prevent content
probing, use --no-content.
When using --list, the default is --no-content (since downloading from each export is expensive). To
enable content probing use --list --content.
--is read-only
--is rotational
Test if the NBD server export is read-only and rotational. The command does not print anything.
Instead it exits with success (exit code 0) if true, or failure (exit code 2) if false. (Other exit
codes indicate an error querying the flag).
For further information see the NBD protocol and the following libnbd functions: nbd_is_read_only(3),
nbd_is_rotational(3).
--json
The output is displayed in JSON format.
-L
--list
List all the exports on an NBD server. The export name in the NBD URI is ignored.
--map
--map=MAP
Display the map (usually whether parts of the disk are allocated or sparse) of the given export.
This displays the "base:allocation" map by default, you can choose a different map with the optional
parameter.
See the "Map" section above.
--map --totals
--map=MAP --totals
The same as --map, but displays a summary of the total size of each type of allocation.
See the "Map totals" section above.
--size
Display only the size in bytes of the export.
-V
--version
Display the package name and version and exit.
SEE ALSO
libnbd(3), nbdcopy(1), nbdfuse(1), nbdsh(1), file(1), jq(1), qemu-img(1), qemu-nbd(8).
AUTHORS
Richard W.M. Jones
Eric Blake
COPYRIGHT
Copyright (C) 2020-2021 Red Hat Inc.
LICENSE
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser
General Public License as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not,
write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
libnbd-1.10.5 2022-02-11 nbdinfo(1)