.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.38.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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "nbdkit-info-plugin 1"
.TH nbdkit-info-plugin 1 2024-05-10 nbdkit-1.38.2 NBDKIT
.\" 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
nbdkit\-info\-plugin \- serve client and server information
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& nbdkit info [mode=]exportname|base64exportname|address|
\&                    time|uptime|conntime
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-info\-plugin\*(C'\fR is a test plugin which serves information about
the client and server in a disk image back to the client.
.PP
In its default mode (\f(CW\*(C`mode=exportname\*(C'\fR) it converts the export name
passed from the client into a disk image.  \f(CW\*(C`mode=base64exportname\*(C'\fR is
similar except the client must base64\-encode the data in the export
name, allowing arbitrary binary data to be sent (see "EXAMPLES"
below to make this clearer).  Export names are limited to 4096 bytes
by the NBD protocol, although some clients have smaller limits.
.PP
\&\f(CW\*(C`mode=address\*(C'\fR creates a disk which contains the client's IP address
and port number as a string.
.PP
\&\f(CW\*(C`mode=time\*(C'\fR, \f(CW\*(C`mode=uptime\*(C'\fR and \f(CW\*(C`mode=conntime\*(C'\fR report server
wallclock time, nbdkit uptime, or time since the connection was opened
respectively and may be used to measure latency.
.PP
The plugin only supports read-only access.  To make the disk writable,
add \fBnbdkit\-cow\-filter\fR\|(1) on top.
.SH EXAMPLES
.IX Header "EXAMPLES"
Create a “reflection disk”.  By setting the export name to \f(CW"hello"\fR
when we open it, a virtual disk of only 5 bytes containing these
characters is created.  We then display the contents:
.PP
.Vb 7
\& $ nbdkit \-\-exit\-with\-parent info mode=exportname &
\& $ nbdsh \-u \*(Aqnbd://localhost/hello\*(Aq \-c \- <<\*(AqEOF\*(Aq
\& size = h.get_size()
\& print("size = %d" % size)
\& buf = h.pread(size, 0)
\& print("buf = %r" % buf)
\& EOF
.Ve
.PP
.Vb 2
\& size = 5
\& buf = b"hello"
.Ve
.PP
By running the info plugin, you can pass whole bootable VMs on the
qemu command line:
.PP
.Vb 10
\& $ nbdkit info mode=base64exportname
\& $ qemu\-system\-x86_64 \e
\&   \-drive \*(Aqsnapshot=on,file.driver=nbd,file.host=localhost,file.port=10809,file.export=
\& tACwA80QtBOzCrABuRwAtgCyAL0ZfM0Q9CoqKiBIZWxsbyBmcm9tIG5iZGtp
\& dCEgKioqDQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
\& AAAAAAAAAAAAAAAAAAAAVao=
\& \*(Aq
.Ve
.PP
Another use for the info plugin is to send back the client's IP
address:
.PP
.Vb 2
\& $ nbdkit info mode=address
\& $ nbdsh \-u \*(Aqnbd://localhost\*(Aq \-c \*(Aqprint(h.pread(h.get_size(), 0))\*(Aq
.Ve
.PP
which will print something like:
.PP
.Vb 1
\& b\*(Aq[::1]:58912\*(Aq
.Ve
.PP
This plugin can also return the wallclock time:
.PP
.Vb 7
\& $ nbdkit info time \-\-run \*(Aqnbdsh \-u "$uri" \-c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump \-C\*(Aq
\& 00000000  00 00 00 00 5d 8f 24 c7  00 04 24 01
\&                      └─────┬─────┘
\&                          ┌─┘
\&                          │
\& $ date \-\-date="@$(( 0x5d8f24c7 ))"
\& Sat 28 Sep 10:15:51 BST 2019
.Ve
.PP
or the nbdkit server uptime:
.PP
.Vb 4
\& $ nbdkit info uptime \-\-run \*(Aqnbdsh \-u "$uri" \-c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump \-C\*(Aq
\& 00000000  00 00 00 00 00 00 00 00  00 00 60 4b
\&                                         └──┬──┘
\&                                   0x604b is about 25ms
.Ve
.PP
or the time since the client opened the connection:
.PP
.Vb 4
\& $ nbdkit info conntime \-\-run \*(Aqnbdsh \-u "$uri" \-c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump \-C\*(Aq
\& 00000000  00 00 00 00 00 00 00 00  00 00 00 e0
\&                                            └─┬─┘
\&                                     0xe0 is about 200μs
.Ve
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP [\fBmode=\fR]\fBaddress\fR 4
.IX Item "[mode=]address"
Send the client's IP address and client port number as a string in the
usual format.  For Unix sockets this sets the disk to the string
\&\f(CW"unix"\fR to avoid leaking host paths.
.Sp
This mode is only supported on some platforms.  You can find out if it
is supported by checking if:
.Sp
.Vb 1
\& $ nbdkit info \-\-dump\-plugin
.Ve
.Sp
contains:
.Sp
.Vb 1
\& info_address=yes
.Ve
.IP [\fBmode=\fR]\fBbase64exportname\fR 4
.IX Item "[mode=]base64exportname"
Send the export name passed by the client, assuming the client string
is base64 encoded.
.Sp
This mode is only supported if nbdkit was compiled with GnuTLS ≥
3.6.0.  You can find out by checking if:
.Sp
.Vb 1
\& $ nbdkit info \-\-dump\-plugin
.Ve
.Sp
contains:
.Sp
.Vb 1
\& info_base64=yes
.Ve
.IP [\fBmode=\fR]\fBexportname\fR 4
.IX Item "[mode=]exportname"
Send the raw export name passed by the client.  Note the export name
cannot contain ASCII NUL characters.
.Sp
This is the default mode.
.IP [\fBmode=\fR]\fBtime\fR 4
.IX Item "[mode=]time"
Reflect server wallclock time as seconds and microseconds since the
Epoch (see \fBgettimeofday\fR\|(2)):
.Sp
.Vb 9
\& ┌────────┬────────┬────────────┬──────────────────────┐
\& │ offset │ length │ format     │ field                │
\& ╞════════╪════════╪════════════╪══════════════════════╡
\& │   0    │    8   │ 64 bit int │ seconds              │
\& │        │        │ big endian │                      │
\& ├────────┼────────┼────────────┼──────────────────────┤
\& │   8    │    4   │ 32 bit int │ microseconds         │
\& │        │        │ big endian │                      │
\& └────────┴────────┴────────────┴──────────────────────┘
.Ve
.Sp
To be able to read this atomically you must read the whole 12 bytes in
a single request.
.Sp
Note that exposing server time may be insecure.  It is safer to use
\&\f(CW\*(C`mode=uptime\*(C'\fR or \f(CW\*(C`mode=conntime\*(C'\fR instead.
.IP [\fBmode=\fR]\fBuptime\fR 4
.IX Item "[mode=]uptime"
Reflect nbdkit uptime in seconds and microseconds (ie. both fields are
\&\f(CW0\fR immediately after nbdkit starts, although a client would never be
able to observe this).  The format is exactly the same as for
\&\f(CW\*(C`mode=time\*(C'\fR above.
.Sp
In the current implementation this can jump forwards or backwards
discontinuously if the server time is adjusted.  In future we may fix
this bug.
.IP [\fBmode=\fR]\fBconntime\fR 4
.IX Item "[mode=]conntime"
Reflect time since the NBD client connection was opened in seconds and
microseconds.  The format is exactly the same as for \f(CW\*(C`mode=time\*(C'\fR
above.
.Sp
In the current implementation this can jump forwards or backwards
discontinuously if the server time is adjusted.  In future we may fix
this bug.
.Sp
\&\f(CW\*(C`mode=\*(C'\fR is a magic config key and may be omitted in most cases.
See "Magic parameters" in \fBnbdkit\fR\|(1).
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$plugindir\fR\fI/nbdkit\-info\-plugin.so\fR 4
.el .IP \fR\f(CI$plugindir\fR\fI/nbdkit\-info\-plugin.so\fR 4
.IX Item "$plugindir/nbdkit-info-plugin.so"
The plugin.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$plugindir\fR.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-info\-plugin\*(C'\fR first appeared in nbdkit 1.16.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBnbdkit\-cow\-filter\fR\|(1),
\&\fBnbdkit\-data\-plugin\fR\|(1).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
.IP \(bu 4
Neither the name of Red Hat nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
.PP
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.