Provided by: libnbd-bin_1.14.2-1_amd64 bug

NAME

       nbdinfo - display information and metadata about NBD servers and exports

SYNOPSIS

        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 --is read-only|rotational NBD

        nbdinfo --can 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
                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"

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

   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 tls URI
           Test if the NBD URI connection is using TLS.

       nbdinfo --can structured-reply URI
           Test if server can respond with structured replies (a prerequisite for supporting
           block status commands).

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

   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
           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 structured-reply
       --can trim
       --can write
       --can zero
           Test properties of the NBD server export or the connection itself.  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), nbd_get_structured_replies_negotiated(3).

       --color
       --colour
       --no-color
       --no-colour
           Enable or disable 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.

       --is read-only
       --is rotational
       --is tls
           Test 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 the following libnbd functions:
           nbd_is_read_only(3), nbd_is_rotational(3), nbd_get_tls_negotiated(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), nbddump(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