nbdinfo

Section: LIBNBD (1)
Updated: 2021-04-03
Page Index

NAME

nbdinfo - display information and metadata about NBD servers and exports

SYNOPSIS

 nbdinfo [--json] [--map] [--size] NBD-URI

 nbdinfo -L|--list 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
         content: data
         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 the same output as above):

 $ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"

Size

To display only the size in bytes of the NBD export (useful for scripting) use the --size parameter:

 $ nbdinfo --size nbd://localhost
 1048576

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",
       "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
     }
   ]
 }

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  allocated
 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": "allocated" },
  { "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.

List all exports

To list all the exports available on an NBD server use the --list (-L) option.

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.

--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.

--json

The output is displayed in JSON format.

--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.

-L

--list

List all the exports on an NBD server. The export name in the NBD URI is ignored.

--size

Display only the size in bytes of the export.

-V

--version

Display the package name and version and exit.

AUTHORS

Richard W.M. Jones

Eric Blake

COPYRIGHT

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