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,
   "structured": true,
   "extended": 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

 $ nbdinfo --size [ nbdkit null 1M ]
 1048576

URI¶

To display the canonical URI:

 $ nbdinfo --uri nbd://localhost
 nbd://localhost:10809/

Test for flags¶

Use one of the --can, --is or --has 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).

--cannot, --isnt and --hasnt negate the test.

You can use it in shell scripts like this:

 if nbdinfo --is read-only nbd://localhost ||
    nbdinfo --cannot 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 tls URI

Test if the NBD URI connection is using TLS.

nbdinfo --has structured-reply URI

Test if server has support for structured replies (a prerequisite for supporting block status commands).

nbdinfo --has extended-headers URI

Test if server supports extended headers (a prerequisite for supporting 64-bit commands; implies structured replies as well).

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 block-status-payload URI

Test if the server export has support for passing a client payload to limit the response to a block status command.

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.

In fact --can/--is/--has, and --cannot/--isnt/--hasnt are synonyms, you can use them interchangeably.

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

Subprocess¶

nbdinfo can also run an NBD server as a subprocess. This requires an NBD server which understands systemd socket activation, such as qemu-nbd(8) or nbdkit(1). All the usual nbdinfo modes can be used.

For example, to give general information or display the map of a qcow2 file:

 nbdinfo -- [ qemu-nbd -r -f qcow2 file.qcow2 ]

 nbdinfo --map -- [ qemu-nbd -r -f qcow2 file.qcow2 ]

Note that "[ ... ]" are separate parameters, and must be surrounded by spaces. "--" separates nbdinfo parameters from subprocess parameters.

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.