.\" Automatically generated by Podwrapper::Man 1.14.2 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdinfo 1"
.TH nbdinfo 1 "2023-01-04" "libnbd-1.14.2" "LIBNBD"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdinfo \- display information and metadata about NBD servers and exports
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& nbdinfo [\-\-json] NBD
.Ve
.PP
\&\f(CW\*(C`NBD\*(C'\fR is an \s-1NBD URI\s0 or subprocess:
.PP
.Vb 2
\& NBD := nbd://... | nbd+unix:// (or other URI formats)
\&      | [ CMD ARGS ... ]
.Ve
.PP
.Vb 1
\& nbdinfo \-\-size [\-\-json] NBD
.Ve
.PP
.Vb 1
\& nbdinfo \-\-is read\-only|rotational NBD
.Ve
.PP
.Vb 1
\& nbdinfo \-\-can cache|connect|... NBD
.Ve
.PP
.Vb 1
\& nbdinfo \-\-map [\-\-totals] [\-\-json] NBD
.Ve
.PP
.Vb 1
\& nbdinfo \-L|\-\-list [\-\-json] NBD
.Ve
.PP
.Vb 1
\& nbdinfo \-\-help
.Ve
.PP
.Vb 1
\& nbdinfo \-\-version
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
nbdinfo displays information and metadata about an \s-1NBD\s0 server.
.PP
The single required parameter can be the \s-1NBD URI\s0 of the server (see
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md):
.PP
.Vb 10
\& $ 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
.Ve
.PP
For an \s-1NBD\s0 server on a local Unix domain socket you would use a
command such as this (with similar output to above):
.PP
.Vb 1
\& $ nbdinfo "nbd+unix:///?socket=/tmp/unixsock"
.Ve
.PP
Or you can run the \s-1NBD\s0 server as a subprocess (see section
\&\*(L"Subprocess\*(R" below):
.PP
.Vb 1
\& $ nbdinfo \-\- [ qemu\-nbd \-r \-f qcow2 file.qcow2 ]
.Ve
.SS "\s-1JSON\s0 output"
.IX Subsection "JSON output"
To display the output as \s-1JSON\s0 (eg. for scripting with \fBjq\fR\|(1)) add
the \fI\-\-json\fR parameter:
.PP
.Vb 10
\& $ 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"
\&     }
\&   ]
\& }
.Ve
.SS "Size"
.IX Subsection "Size"
To display only the size in bytes of the \s-1NBD\s0 export (useful for
scripting) use the \fI\-\-size\fR parameter:
.PP
.Vb 2
\& $ nbdinfo \-\-size nbd://localhost
\& 1048576
.Ve
.PP
.Vb 2
\& $ nbdinfo \-\-size [ nbdkit null 1M ]
\& 1048576
.Ve
.SS "Test for flags"
.IX Subsection "Test for flags"
Use one of the options below to test \s-1NBD\s0 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:
.PP
.Vb 5
\& if nbdinfo \-\-is read\-only nbd://localhost ||
\&    ! nbdinfo \-\-can trim nbd://localhost
\& then
\&     error "the device must support writing and trimming"
\& fi
.Ve
.IP "nbdinfo \-\-is read-only \s-1URI\s0" 4
.IX Item "nbdinfo --is read-only URI"
Test if the server export is read-only.
.IP "nbdinfo \-\-can write \s-1URI\s0" 4
.IX Item "nbdinfo --can write URI"
For convenience this is the opposite of \fI\-\-is read-only\fR.
.IP "nbdinfo \-\-can read \s-1URI\s0" 4
.IX Item "nbdinfo --can read URI"
All \s-1NBD\s0 servers must support read, so this always exits with success
(unless there is a failure connecting to the \s-1URI\s0).
.IP "nbdinfo \-\-can connect \s-1URI\s0" 4
.IX Item "nbdinfo --can connect URI"
Test if we can connect to the \s-1NBD URI.\s0
.IP "nbdinfo \-\-is tls \s-1URI\s0" 4
.IX Item "nbdinfo --is tls URI"
Test if the \s-1NBD URI\s0 connection is using \s-1TLS.\s0
.IP "nbdinfo \-\-can structured-reply \s-1URI\s0" 4
.IX Item "nbdinfo --can structured-reply URI"
Test if server can respond with structured replies (a prerequisite
for supporting block status commands).
.IP "nbdinfo \-\-is rotational \s-1URI\s0" 4
.IX Item "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.
.IP "nbdinfo \-\-can cache \s-1URI\s0" 4
.IX Item "nbdinfo --can cache URI"
.PD 0
.IP "nbdinfo \-\-can df \s-1URI\s0" 4
.IX Item "nbdinfo --can df URI"
.IP "nbdinfo \-\-can fast-zero \s-1URI\s0" 4
.IX Item "nbdinfo --can fast-zero URI"
.IP "nbdinfo \-\-can flush \s-1URI\s0" 4
.IX Item "nbdinfo --can flush URI"
.IP "nbdinfo \-\-can fua \s-1URI\s0" 4
.IX Item "nbdinfo --can fua URI"
.IP "nbdinfo \-\-can multi-conn \s-1URI\s0" 4
.IX Item "nbdinfo --can multi-conn URI"
.IP "nbdinfo \-\-can trim \s-1URI\s0" 4
.IX Item "nbdinfo --can trim URI"
.IP "nbdinfo \-\-can zero \s-1URI\s0" 4
.IX Item "nbdinfo --can zero URI"
.PD
Test other properties of the \s-1NBD\s0 server export.
.SS "Map"
.IX Subsection "Map"
To show a map of which areas of the disk are allocated and sparse, use
the \fI\-\-map\fR option:
.PP
.Vb 3
\& $ nbdinfo \-\-map nbd://localhost/
\&       0  1048576  0  data
\& 1048576  1048576  3  hole,zero
.Ve
.PP
The fields are: start, size, type, description (optional).
.PP
The type field is an integer showing the raw value from the \s-1NBD\s0
protocol.  For some maps nbdinfo knows how to translate the type into
a printable description.
.PP
To get parseable \s-1JSON\s0 output, add \fI\-\-json\fR:
.PP
.Vb 5
\& $ nbdinfo \-\-map \-\-json nbd://localhost/
\& [{ "offset": 0, "length": 1048576,
\&    "type": 0, "description": "data" },
\&  { "offset": 1048576, "length": 1048576,
\&    "type": 3, "description": "hole,zero" }]
.Ve
.PP
By default this shows the \f(CW"base:allocation"\fR map, but you can show
other maps too:
.PP
.Vb 2
\& $ nbdinfo \-\-map=qemu:dirty\-bitmap:bitmap nbd://localhost/
\& 0  1048576  1  dirty
.Ve
.PP
For more information on \s-1NBD\s0 maps, see \fIMetadata querying\fR in the \s-1NBD\s0
protocol.
.SS "Map totals"
.IX Subsection "Map totals"
Using \fI\-\-map \-\-totals\fR performs the same operation as \fI\-\-map\fR 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 \fBnbdcopy\fR\|(1).
.PP
In the example below, half (50.0%) of the disk is allocated data and
half is unallocated:
.PP
.Vb 3
\& $ nbdinfo \-\-map \-\-totals nbd://localhost/
\& 1048576  50.0%  0  data
\& 1048576  50.0%  3  hole,zero
.Ve
.PP
The fields are: total size in bytes, percentage of the virtual size,
type, description (optional).
.PP
You can also get the same information in parseable form using \fI\-\-json\fR:
.PP
.Vb 5
\& $ nbdinfo \-\-map \-\-totals \-\-json nbd://localhost/
\& [{ "size": 1048576, "percent": 50,
\&    "type": 0, "description": "data" },
\&  { "size": 1048576, "percent": 50,
\&    "type": 3, "description": "hole,zero" }]
.Ve
.PP
As with the \fI\-\-map\fR option, by default this shows the
\&\f(CW"base:allocation"\fR map, but you can show the summary for other maps.
.SS "List all exports"
.IX Subsection "List all exports"
To list all the exports available on an \s-1NBD\s0 server use the \fI\-\-list\fR
(\fI\-L\fR) option.  To get parseable \s-1JSON\s0 output, add \fI\-\-json\fR.
.PP
For example:
.PP
.Vb 10
\& $ nbdkit file dir=. \-\-run \*(Aqnbdinfo \-\-list "$uri"\*(Aq
\& 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
\&     [...]
.Ve
.SS "Subprocess"
.IX Subsection "Subprocess"
nbdinfo can also run an \s-1NBD\s0 server as a subprocess.  This requires an
\&\s-1NBD\s0 server which understands systemd socket activation, such as
\&\fBqemu\-nbd\fR\|(8) or \fBnbdkit\fR\|(1).  All the usual nbdinfo modes can be
used.
.PP
For example, to give general information or display the map of a qcow2
file:
.PP
.Vb 1
\& nbdinfo \-\- [ qemu\-nbd \-r \-f qcow2 file.qcow2 ]
.Ve
.PP
.Vb 1
\& nbdinfo \-\-map \-\- [ qemu\-nbd \-r \-f qcow2 file.qcow2 ]
.Ve
.PP
Note that \f(CW\*(C`[ ... ]\*(C'\fR are separate parameters, and must be
surrounded by spaces.  \f(CW\*(C`\-\-\*(C'\fR separates nbdinfo parameters from
subprocess parameters.
.SS "Alternative tools"
.IX Subsection "Alternative tools"
You could use \f(CW\*(C`qemu\-img info\*(C'\fR (see \fBqemu\-img\fR\|(1)) to query a
single export from an \s-1NBD\s0 server.  \f(CW\*(C`qemu\-nbd \-L\*(C'\fR (see
\&\fBqemu\-nbd\fR\|(8)) can list \s-1NBD\s0 exports.  \fBnbdsh\fR\|(1) or the \fBlibnbd\fR\|(3)
\&\s-1API\s0 can be used for more complex queries.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Display brief command line help and exit.
.IP "\fB\-\-can cache\fR" 4
.IX Item "--can cache"
.PD 0
.IP "\fB\-\-can connect\fR" 4
.IX Item "--can connect"
.IP "\fB\-\-can df\fR" 4
.IX Item "--can df"
.IP "\fB\-\-can fast-zero\fR" 4
.IX Item "--can fast-zero"
.IP "\fB\-\-can flush\fR" 4
.IX Item "--can flush"
.IP "\fB\-\-can fua\fR" 4
.IX Item "--can fua"
.IP "\fB\-\-can multi-conn\fR" 4
.IX Item "--can multi-conn"
.IP "\fB\-\-can read\fR" 4
.IX Item "--can read"
.IP "\fB\-\-can structured-reply\fR" 4
.IX Item "--can structured-reply"
.IP "\fB\-\-can trim\fR" 4
.IX Item "--can trim"
.IP "\fB\-\-can write\fR" 4
.IX Item "--can write"
.IP "\fB\-\-can zero\fR" 4
.IX Item "--can zero"
.PD
Test properties of the \s-1NBD\s0 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).
.Sp
For further information see the \s-1NBD\s0
protocol
and the following libnbd functions: \fBnbd_can_cache\fR\|(3),
\&\fBnbd_can_df\fR\|(3), \fBnbd_can_fast_zero\fR\|(3), \fBnbd_can_flush\fR\|(3),
\&\fBnbd_can_fua\fR\|(3), \fBnbd_can_multi_conn\fR\|(3), \fBnbd_can_trim\fR\|(3),
\&\fBnbd_can_zero\fR\|(3), \fBnbd_is_read_only\fR\|(3),
\&\fBnbd_get_structured_replies_negotiated\fR\|(3).
.IP "\fB\-\-color\fR" 4
.IX Item "--color"
.PD 0
.IP "\fB\-\-colour\fR" 4
.IX Item "--colour"
.IP "\fB\-\-no\-color\fR" 4
.IX Item "--no-color"
.IP "\fB\-\-no\-colour\fR" 4
.IX Item "--no-colour"
.PD
Enable or disable \s-1ANSI\s0 colours in output.  By default we use colours
if the output seems to be a terminal, and disable them if not.
.IP "\fB\-\-content\fR" 4
.IX Item "--content"
.PD 0
.IP "\fB\-\-no\-content\fR" 4
.IX Item "--no-content"
.PD
Mostly the information displayed comes from the metadata sent by the
\&\s-1NBD\s0 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 \fBfile\fR\|(1).
.Sp
When \fInot\fR using \fI\-\-list\fR, the default is \fI\-\-content\fR, ie.  probing
the content.  To prevent content probing, use \fI\-\-no\-content\fR.
.Sp
When using \fI\-\-list\fR, the default is \fI\-\-no\-content\fR (since
downloading from each export is expensive).  To enable content probing
use \fI\-\-list \-\-content\fR.
.IP "\fB\-\-is read-only\fR" 4
.IX Item "--is read-only"
.PD 0
.IP "\fB\-\-is rotational\fR" 4
.IX Item "--is rotational"
.IP "\fB\-\-is tls\fR" 4
.IX Item "--is tls"
.PD
Test if the \s-1NBD\s0 server export is read-only and rotational, or whether
the connection itself is using \s-1TLS.\s0  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).
.Sp
For further information see the \s-1NBD\s0
protocol
and the following libnbd functions: \fBnbd_is_read_only\fR\|(3),
\&\fBnbd_is_rotational\fR\|(3), \fBnbd_get_tls_negotiated\fR\|(3).
.IP "\fB\-\-json\fR" 4
.IX Item "--json"
The output is displayed in \s-1JSON\s0 format.
.IP "\fB\-L\fR" 4
.IX Item "-L"
.PD 0
.IP "\fB\-\-list\fR" 4
.IX Item "--list"
.PD
List all the exports on an \s-1NBD\s0 server.  The export name in the \s-1NBD URI\s0
is ignored.
.IP "\fB\-\-map\fR" 4
.IX Item "--map"
.PD 0
.IP "\fB\-\-map=\fR\s-1MAP\s0" 4
.IX Item "--map=MAP"
.PD
Display the map (usually whether parts of the disk are allocated or
sparse) of the given export.  This displays the \f(CW"base:allocation"\fR
map by default, you can choose a different map with the optional
parameter.
.Sp
See the \*(L"Map\*(R" section above.
.IP "\fB\-\-map\fR \fB\-\-totals\fR" 4
.IX Item "--map --totals"
.PD 0
.IP "\fB\-\-map=\fR\s-1MAP\s0 \fB\-\-totals\fR" 4
.IX Item "--map=MAP --totals"
.PD
The same as \fI\-\-map\fR, but displays a summary of the total size of each
type of allocation.
.Sp
See the \*(L"Map totals\*(R" section above.
.IP "\fB\-\-size\fR" 4
.IX Item "--size"
Display only the size in bytes of the export.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the package name and version and exit.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlibnbd\fR\|(3),
\&\fBnbdcopy\fR\|(1),
\&\fBnbddump\fR\|(1),
\&\fBnbdfuse\fR\|(1),
\&\fBnbdsh\fR\|(1),
\&\fBfile\fR\|(1),
\&\fBjq\fR\|(1),
\&\fBqemu\-img\fR\|(1),
\&\fBqemu\-nbd\fR\|(8).
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones
.PP
Eric Blake
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2020\-2021 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
.PP
This library is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA 02110\-1301 USA\s0