nbdinfo(1)

💖 nbdinfo(1) — the LIBNBD manual, bestie edition 💖

okay so bestie, this is the LIBNBD manual page for nbdinfo, and it is genuinely iconic: it tells you all the info and metadata about NBD servers and exports. Part 1 energy, no cap. Let's get into it. 💅

---

✨ NAME ✨

• nbdinfo — display information and metadata about NBD servers and exports.

🦋 SYNOPSIS 🦋

Here's the shape of it, bestie:

nbdinfo [--json] NBD

"NBD" is an NBD URI or subprocess:

NBD := nbd://... | nbd+unix:// (or other URI formats)
     | [ CMD ARGS ... ]

nbdinfo --size [--json] NBD

nbdinfo --uri [--json] NBD

nbdinfo --is read-only|rotational NBD
nbdinfo --isnt read-only|rotational NBD

nbdinfo --can cache|connect|... NBD
nbdinfo --cannot cache|connect|... NBD

nbdinfo --map [--totals] [--json] NBD

nbdinfo -L|--list [--json] NBD

nbdinfo --help

nbdinfo --version

🌸 DESCRIPTION 🌸

nbdinfo displays information and metadata about an NBD server.

The single required parameter can be 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, using structured packets
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 (4K)
        block_size_maximum: 33554432 (32M)

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"

Or you can run the NBD server as a subprocess (see section "Subprocess" below):

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

🎀 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 open URI — test if we can connect to the NBD URI and open the named export.
• nbdinfo --can read URI — test if we can connect to the NBD URI and open the named export. As all NBD servers must support read, --can read is a synonym.
• nbdinfo --can connect URI — test if we can connect to the NBD URI. This tests the NBD handshake as far as NBD options processing, but does not guarantee that the export can be opened (see --can open).
• 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.

✨ OPTIONS ✨

• --help — pops up a brief command line help and exits. 💅
• --can block-status-payload, --can cache, --can connect, --can df, --can fast-zero, --can flush, --can fua, --can multi-conn, --can open, --can read, --can trim, --can write, --can zero — okay bestie, these 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 these libnbd functions: nbd_can_block_status_payload(3), 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). 🔥
• --cannot flag — tests the negation of flag. 🙃
• --color, --colour, --no-color, --no-colour — enables or disables ANSI colours in output. By default we use colours if the output seems to be a terminal, and disable them if not. 🌈
• --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.

• --has extended-headers, --has structured-reply — these test properties of the NBD server connection. 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 these libnbd functions: nbd_get_extended_headers_negotiated(3), nbd_get_structured_replies_negotiated(3). ⭐
• --hasnt flag — tests the negation of flag. 🙈
• --is read-only, --is rotational, --is tls — tests if the NBD server export is read-only and rotational, or whether the connection itself is using TLS. 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 these libnbd functions: nbd_is_read_only(3), nbd_is_rotational(3), nbd_get_tls_negotiated(3). 💖
• --isnt flag — tests the negation of flag. 🫶
• --json — the output is displayed in JSON format. Slay for scripts. 🧚
• -L, --list — lists all the exports on an NBD server. The export name in the NBD URI is ignored. 👑
• --map, --map=MAP — displays 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 — same as --map, but displays a summary of the total size of each type of allocation.

See the Map totals section above. 📊

• --size — displays only the size in bytes of the export. Tiny but mighty. 🍓
• --uri — displays only the canonical URI. If combined with --json then the output is a JSON-quoted string. 🔗
• -V, --version — displays the package name and version and exits. Byeee 👋

---

🌈 SEE ALSO 🌈

• libnbd(3)
• nbdcopy(1)
• nbddiscard(1)
• nbddump(1)
• nbdfuse(1)
• nbdsh(1)
• nbdublk(1)
• nbdzero(1)
• file(1)
• jq(1)
• qemu-img(1)
• qemu-nbd(8)

---

👑 AUTHORS 👑

• Richard W.M. Jones
• Eric Blake

---

🎀 COPYRIGHT 🎀

Copyright Red Hat

---

💖 LICENSE 💖

Okay legal bestie, here’s the exact text, no edits: 📜

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

---

That’s the whole vibe from libnbd-1.25.8, dated 2026-10-13 — byeee, ily, go probe some NBD exports 💋🦋✨