.\" Automatically generated by Podwrapper::Man 1.24.1 (Pod::Simple 3.40)
.\"
.\" 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 "nbdkit-nbd-plugin 1"
.TH nbdkit-nbd-plugin 1 "2021-01-20" "nbdkit-1.24.1" "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\-nbd\-plugin \- proxy / forward to another NBD server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 9
\& nbdkit nbd { command=COMMAND [arg=ARG [...]] |
\&              hostname=HOST [port=PORT] |
\&              vhost\-cid=CID [port=PORT] |
\&              socket=SOCKNAME |
\&              socket\-fd=FD |
\&              [uri=]URI }
\&            [dynamic\-export=BOOL] [export=NAME] [retry=N] [shared=BOOL]
\&            [tls=MODE] [tls\-certificates=DIR] [tls\-verify=BOOL]
\&            [tls\-username=NAME] [tls\-psk=FILE]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-nbd\-plugin\*(C'\fR is a plugin for \fBnbdkit\fR\|(1) that lets you
forward the connection to another \s-1NBD\s0 server.  There are several uses
for this plugin:
.IP "\(bu" 4
Adjust the set of features seen by the ultimate \s-1NBD\s0 client without
having to change the original server.  For example, convert between
the oldstyle and newstyle protocols, or add \s-1TLS\s0 support if the
original server lacks it.
.IP "\(bu" 4
Apply nbdkit filters to any other \s-1NBD\s0 server.
.IP "\(bu" 4
With \fBqemu\-nbd\fR\|(8), read and write qcow2 files with nbdkit.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
One of \fBsocket\fR, \fBhostname\fR (optionally with \fBport\fR), \fBvsock\fR
(optionally with \fBport\fR), \fBuri\fR, \fBsocket-fd\fR or \fBcommand\fR must be
given to specify which \s-1NBD\s0 server to forward to:
.IP "\fBcommand=\fR\s-1COMMAND\s0" 4
.IX Item "command=COMMAND"
.PD 0
.IP "\fBarg=\fR\s-1ARG\s0" 4
.IX Item "arg=ARG"
.PD
(nbdkit ≥ 1.22)
.Sp
Run an \s-1NBD\s0 server, usually \fBqemu\-nbd\fR\|(8), as an external command.
See \*(L"\s-1EXAMPLES\*(R"\s0 below.
.Sp
\&\f(CW\*(C`COMMAND\*(C'\fR is the program to run, followed by zero or more \f(CW\*(C`arg=ARG\*(C'\fR
parameters for each argument.  For example:
.Sp
.Vb 1
\& nbdkit nbd command=qemu\-nbd arg=\-f arg=qcow2 arg=$PWD/disk.qcow2
.Ve
.Sp
would run the command \f(CW\*(C`qemu\-nbd \-f qcow2 $PWD/disk.qcow2\*(C'\fR.  Because
nbdkit may change directory before running the command, you may need
to ensure that all file paths used in parameters (like the disk name
above) are absolute paths.
.Sp
This uses the libnbd \s-1API\s0 \fBnbd_connect_systemd_socket_activation\fR\|(3).
This option implies \f(CW\*(C`shared=true\*(C'\fR.
.IP "\fBhostname=\fR\s-1HOST\s0" 4
.IX Item "hostname=HOST"
.PD 0
.IP "\fBport=\fR\s-1PORT\s0" 4
.IX Item "port=PORT"
.PD
(nbdkit ≥ 1.14)
.Sp
Connect to the \s-1NBD\s0 server at the remote \f(CW\*(C`HOST\*(C'\fR using a \s-1TCP\s0 socket.
The optional port parameter overrides the default port (10809), and
may be a 16\-bit number or a non-numeric string to look up the
well-known port for a service name.
.IP "\fBvsock=\fR\s-1CID\s0" 4
.IX Item "vsock=CID"
.PD 0
.IP "\fBport=\fR\s-1PORT\s0" 4
.IX Item "port=PORT"
.PD
(nbdkit ≥ 1.22)
.Sp
Connect to the \s-1NBD\s0 server at the given vsock \f(CW\*(C`CID\*(C'\fR (for example, in a
guest \s-1VM,\s0 using the cid 2 will connect to a server in the host).  The
optional port parameter overrides the default port (10809), and must
be a 32\-bit number.  This only works for platforms with the
\&\f(CW\*(C`AF_VSOCK\*(C'\fR family of sockets and libnbd new enough to use it;
\&\f(CW\*(C`nbdkit \-\-dump\-plugin nbd\*(C'\fR will contain \f(CW\*(C`libnbd_vsock=1\*(C'\fR if this is
the case.  For more details on \s-1AF_VSOCK,\s0 see
\&\*(L"\s-1AF_VSOCK\*(R"\s0 in \fBnbdkit\-service\fR\|(1).
.IP "\fBsocket=\fR\s-1SOCKNAME\s0" 4
.IX Item "socket=SOCKNAME"
Connect to the \s-1NBD\s0 server using Unix domain socket \f(CW\*(C`SOCKNAME\*(C'\fR.
.IP "\fBsocket\-fd=\fR\s-1FD\s0" 4
.IX Item "socket-fd=FD"
(nbdkit ≥ 1.22)
.Sp
Connect to the \s-1NBD\s0 server over a socket file descriptor inherited by
nbdkit.  This uses the libnbd \s-1API\s0 \fBnbd_connect_socket\fR\|(3).  This
option implies \f(CW\*(C`shared=true\*(C'\fR.
.IP "[\fBuri=\fR]URI" 4
.IX Item "[uri=]URI"
(nbdkit ≥ 1.14)
.Sp
When \f(CW\*(C`uri\*(C'\fR is supplied, decode \f(CW\*(C`URI\*(C'\fR to determine the address to
connect to.  A \s-1URI\s0 can specify a \s-1TCP\s0 connection (such as
\&\f(CW\*(C`nbd://localhost:10809/export\*(C'\fR), a Unix socket (such as
\&\f(CW\*(C`nbd+unix:///export?socket=/path/to/sock\*(C'\fR), or a vsock connection
(such as \f(CW\*(C`nbd+vsock:///2:10809/export\*(C'\fR).  Remember you may need to
quote the parameter to protect it from the shell.
.Sp
The \f(CW\*(C`uri\*(C'\fR parameter is only available when the plugin was compiled
against libnbd with \s-1URI\s0 support; \f(CW\*(C`nbdkit \-\-dump\-plugin nbd\*(C'\fR will
contain \f(CW\*(C`libnbd_uri=1\*(C'\fR if this is the case.
.Sp
The export portion of the \s-1URI\s0 is ignored when using
\&\f(CW\*(C`dynamic\-export=true\*(C'\fR.
.Sp
\&\f(CW\*(C`uri=\*(C'\fR is a magic config key and may be omitted in most
cases.  See \*(L"Magic parameters\*(R" in \fBnbdkit\fR\|(1).
.PP
Other parameters control the \s-1NBD\s0 connection:
.IP "\fBexport=\fR\s-1NAME\s0" 4
.IX Item "export=NAME"
If this parameter is given, and the server speaks new style protocol,
then connect to the named export instead of the default export (the
empty string).  If \f(CW\*(C`uri\*(C'\fR is supplied, the export name should be
embedded in the \s-1URI\s0 instead.  This is incompatible with
\&\f(CW\*(C`dynamic\-export=true\*(C'\fR.
.IP "\fBretry=\fRN" 4
.IX Item "retry=N"
(nbdkit ≥ 1.14)
.Sp
If the initial connection attempt to the server fails, retry up to
\&\f(CW\*(C`N\*(C'\fR times more after a one-second delay between tries (default 0).
.IP "\fBshared=false\fR" 4
.IX Item "shared=false"
.PD 0
.IP "\fBshared=true\fR" 4
.IX Item "shared=true"
.PD
(nbdkit ≥ 1.14)
.Sp
If using \f(CW\*(C`command\*(C'\fR or \f(CW\*(C`socket\-fd\*(C'\fR modes then this defaults to true,
otherwise false.
.Sp
If false the plugin will open a new connection to the server for each
client making a connection to nbdkit.  The remote server does not have
to be started until immediately before the first nbdkit client
connects.
.Sp
If this parameter is set to \f(CW\*(C`true\*(C'\fR, the plugin will open a single
connection to the server when nbdkit is first started (the \f(CW\*(C`retry\*(C'\fR
parameter may be necessary to coordinate timing of the remote server
startup), and all clients to nbdkit will share that single connection.
This mode is incompatible with \fBdynamic\-export=true\fR.
.IP "\fBdynamic\-export=false\fR" 4
.IX Item "dynamic-export=false"
.PD 0
.IP "\fBdynamic\-export=true\fR" 4
.IX Item "dynamic-export=true"
.PD
(nbdkit ≥ 1.24)
.Sp
This parameter defaults to false, in which case all clients to nbdkit
use the same export of the server, as set by \f(CW\*(C`export\*(C'\fR or \f(CW\*(C`uri\*(C'\fR,
regardless of the client's export name request.  If it is set to true,
nbdkit will pass the client's requested export name over to the final
\&\s-1NBD\s0 server, which means clients requesting different export names can
see different content when the server differentiates content by export
name.  Dynamic exports prevent the use of \f(CW\*(C`shared\*(C'\fR mode, and thus are
not usable with \f(CW\*(C`command\*(C'\fR or \f(CW\*(C`socket\-fd\*(C'\fR.
.Sp
If libnbd is new enough, dynamic export mode is able to advertise the
same exports as listed by the server; \f(CW\*(C`nbdkit \-\-dump\-plugin nbd\*(C'\fR will
contain \f(CW\*(C`libnbd_dynamic_list=1\*(C'\fR if this is the case.  Regardless of
what this plugin lists, it is also possible to use
\&\fBnbdkit\-exportname\-filter\fR\|(1) to adjust what export names the client
sees or uses as a default.
.IP "\fBtls=off\fR" 4
.IX Item "tls=off"
.PD 0
.IP "\fBtls=on\fR" 4
.IX Item "tls=on"
.IP "\fBtls=require\fR" 4
.IX Item "tls=require"
.PD
(nbdkit ≥ 1.14)
.Sp
Selects which \s-1TLS\s0 mode to use with the server.  If no other tls option
is present, this defaults to \f(CW\*(C`off\*(C'\fR, where the client does not attempt
encryption (and may be rejected by a server that requires it).  If
omitted but another tls option is present, this defaults to \f(CW\*(C`on\*(C'\fR,
where the client opportunistically attempts a \s-1TLS\s0 handshake, but will
continue running unencrypted if the server does not support
encryption.  If set to \f(CW\*(C`require\*(C'\fR or if the \f(CW\*(C`uri\*(C'\fR parameter is used
with a scheme that requires encryption (such as \f(CW\*(C`nbds://host\*(C'\fR), then
this requires an encrypted connection to the server.
.Sp
The \f(CW\*(C`tls\*(C'\fR parameter is only available when the plugin was compiled
against libnbd with \s-1TLS\s0 support; \f(CW\*(C`nbdkit \-\-dump\-plugin nbd\*(C'\fR will
contain \f(CW\*(C`libnbd_tls=1\*(C'\fR if this is the case.  Note the difference
between \f(CW\*(C`\-\-tls=...\*(C'\fR controlling what nbdkit serves, and \f(CW\*(C`tls=...\*(C'\fR
controlling what the nbd plugin connects to as a client.
.IP "\fBtls\-certificates=\fR\s-1DIR\s0" 4
.IX Item "tls-certificates=DIR"
(nbdkit ≥ 1.14)
.Sp
This specifies the directory containing X.509 client certificates to
present to the server.
.IP "\fBtls\-verify=false\fR" 4
.IX Item "tls-verify=false"
(nbdkit ≥ 1.14)
.Sp
Setting this parameter to false disables server name verification,
which opens you to potential Man-in-the-Middle (\s-1MITM\s0) attacks, but
allows for a simpler setup for distributing certificates.
.IP "\fBtls\-username=\fR\s-1NAME\s0" 4
.IX Item "tls-username=NAME"
(nbdkit ≥ 1.14)
.Sp
If provided, this overrides the user name to present to the server
alongside the certificate.
.IP "\fBtls\-psk=\fR\s-1FILE\s0" 4
.IX Item "tls-psk=FILE"
(nbdkit ≥ 1.14)
.Sp
If provided, this is the filename containing the Pre-Shared Keys (\s-1PSK\s0)
to present to the server.  While this is easier to set up than X.509,
it requires that the \s-1PSK\s0 file be transmitted over a secure channel.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Convert oldstyle server to encrypted newstyle"
.IX Subsection "Convert oldstyle server to encrypted newstyle"
Expose the contents of an export served by an old style server over a
Unix socket to \s-1TCP\s0 network clients that only want to consume encrypted
data.  Use \fI\-\-exit\-with\-parent\fR to clean up nbdkit at the same time
that the old server exits.
.PP
.Vb 3
\& ( sock=\`mktemp \-u\`
\&   nbdkit \-\-exit\-with\-parent \-\-tls=require nbd socket=$sock &
\&   exec /path/to/oldserver \-\-socket=$sock )
\&
\& ┌────────────┐   TLS    ┌────────┐  plaintext  ┌────────────┐
\& │ new client │ ────────▶│ nbdkit │ ───────────▶│ old server │
\& └────────────┘   TCP    └────────┘    Unix     └────────────┘
.Ve
.SS "Use qemu-nbd to open a qcow2 file"
.IX Subsection "Use qemu-nbd to open a qcow2 file"
Run qemu-nbd as the server, allowing you to read and write qcow2 files
(since nbdkit does not have a native qcow2 plugin).  This allows you
to use nbdkit filters on top, see the next example.
.PP
.Vb 1
\& nbdkit nbd command=qemu\-nbd arg=\-f arg=qcow2 arg=/path/to/image.qcow2
.Ve
.PP
qemu-nbd is cleaned up when nbdkit exits.
.SS "Add nbdkit-partition-filter to qemu-nbd"
.IX Subsection "Add nbdkit-partition-filter to qemu-nbd"
Combine \fBnbdkit\-partition\-filter\fR\|(1) with \fBqemu\-nbd\fR\|(8)’s ability to
visit qcow2 files:
.PP
.Vb 3
\& nbdkit \-\-filter=partition nbd \e
\&        command=qemu\-nbd arg=\-f arg=qcow2 arg=/path/to/image.qcow2 \e
\&        partition=1
.Ve
.PP
This performs the same task as the deprecated qemu-nbd \fI\-P\fR option:
.PP
.Vb 1
\& qemu\-nbd \-P 1 \-f qcow2 /path/to/image.qcow2
.Ve
.SS "Convert newstyle server for oldstyle-only client"
.IX Subsection "Convert newstyle server for oldstyle-only client"
Expose the contents of export \f(CW\*(C`foo\*(C'\fR from a newstyle server with
encrypted data to a client that can only consume unencrypted old
style.  Use \fI\-\-run\fR to clean up nbdkit at the time the client exits.
In general, note that it is best to keep the plaintext connection
limited to a Unix socket on the local machine.
.PP
.Vb 2
\& nbdkit \-U \- \-o \-\-tls=off nbd hostname=example.com export=foo tls=require \e
\&  \-\-run \*(Aq/path/to/oldclient \-\-socket=$unixsocket\*(Aq
\&
\& ┌────────────┐  plaintext  ┌────────┐   TLS    ┌────────────┐
\& │ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
\& └────────────┘    Unix     └────────┘   TCP    └────────────┘
.Ve
.SH "DUMP PLUGIN OUTPUT"
.IX Header "DUMP PLUGIN OUTPUT"
You can learn which features are provided by libnbd by inspecting the
\&\f(CW\*(C`libnbd_*\*(C'\fR lines in \fI\-\-dump\-plugin\fR output:
.PP
.Vb 5
\& $ nbdkit \-\-dump\-plugin nbd
\& [...]
\& libnbd_version=1.2.3
\& libnbd_tls=1
\& libnbd_uri=1
.Ve
.SH "FILES"
.IX Header "FILES"
.IP "\fI\f(CI$plugindir\fI/nbdkit\-nbd\-plugin.so\fR" 4
.IX Item "$plugindir/nbdkit-nbd-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\-nbd\-plugin\*(C'\fR first appeared in nbdkit 1.2.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-captive\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3),
\&\fBnbdkit\-exportname\-filter\fR\|(1),
\&\fBnbdkit\-tls\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBlibnbd\fR\|(3),
\&\fBqemu\-nbd\fR\|(8).
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2017, 2019 Red Hat Inc.
.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
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0