2. EL 8
  3. libnbd
  4. nbdinfo(1)

Scroll to navigation

nbdinfo(1) LIBNBD nbdinfo(1)

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

Display brief command line help and exit.
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.

The output is displayed in JSON format.
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.
List all the exports on an NBD server. The export name in the NBD URI is ignored.
Display only the size in bytes of the export.
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 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

2023-10-06 libnbd-1.6.0