Provided by: nbdkit_1.24.1-2ubuntu4_amd64 
NAME
nbdkit-nbd-plugin - proxy / forward to another NBD server
SYNOPSIS
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]
DESCRIPTION
"nbdkit-nbd-plugin" is a plugin for nbdkit(1) that lets you forward the connection to
another NBD server. There are several uses for this plugin:
• Adjust the set of features seen by the ultimate NBD client without having to change
the original server. For example, convert between the oldstyle and newstyle
protocols, or add TLS support if the original server lacks it.
• Apply nbdkit filters to any other NBD server.
• With qemu-nbd(8), read and write qcow2 files with nbdkit.
PARAMETERS
One of socket, hostname (optionally with port), vsock (optionally with port), uri, socket-
fd or command must be given to specify which NBD server to forward to:
command=COMMAND
arg=ARG
(nbdkit ≥ 1.22)
Run an NBD server, usually qemu-nbd(8), as an external command. See "EXAMPLES" below.
"COMMAND" is the program to run, followed by zero or more "arg=ARG" parameters for
each argument. For example:
nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=$PWD/disk.qcow2
would run the command "qemu-nbd -f qcow2 $PWD/disk.qcow2". 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.
This uses the libnbd API nbd_connect_systemd_socket_activation(3). This option
implies "shared=true".
hostname=HOST
port=PORT
(nbdkit ≥ 1.14)
Connect to the NBD server at the remote "HOST" using a TCP 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.
vsock=CID
port=PORT
(nbdkit ≥ 1.22)
Connect to the NBD server at the given vsock "CID" (for example, in a guest VM, 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 "AF_VSOCK" family of sockets and libnbd new enough to use it;
"nbdkit --dump-plugin nbd" will contain "libnbd_vsock=1" if this is the case. For
more details on AF_VSOCK, see "AF_VSOCK" in nbdkit-service(1).
socket=SOCKNAME
Connect to the NBD server using Unix domain socket "SOCKNAME".
socket-fd=FD
(nbdkit ≥ 1.22)
Connect to the NBD server over a socket file descriptor inherited by nbdkit. This
uses the libnbd API nbd_connect_socket(3). This option implies "shared=true".
[uri=]URI
(nbdkit ≥ 1.14)
When "uri" is supplied, decode "URI" to determine the address to connect to. A URI
can specify a TCP connection (such as "nbd://localhost:10809/export"), a Unix socket
(such as "nbd+unix:///export?socket=/path/to/sock"), or a vsock connection (such as
"nbd+vsock:///2:10809/export"). Remember you may need to quote the parameter to
protect it from the shell.
The "uri" parameter is only available when the plugin was compiled against libnbd with
URI support; "nbdkit --dump-plugin nbd" will contain "libnbd_uri=1" if this is the
case.
The export portion of the URI is ignored when using "dynamic-export=true".
"uri=" is a magic config key and may be omitted in most cases. See "Magic parameters"
in nbdkit(1).
Other parameters control the NBD connection:
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 "uri" is
supplied, the export name should be embedded in the URI instead. This is incompatible
with "dynamic-export=true".
retry=N
(nbdkit ≥ 1.14)
If the initial connection attempt to the server fails, retry up to "N" times more
after a one-second delay between tries (default 0).
shared=false
shared=true
(nbdkit ≥ 1.14)
If using "command" or "socket-fd" modes then this defaults to true, otherwise false.
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.
If this parameter is set to "true", the plugin will open a single connection to the
server when nbdkit is first started (the "retry" 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 dynamic-export=true.
dynamic-export=false
dynamic-export=true
(nbdkit ≥ 1.24)
This parameter defaults to false, in which case all clients to nbdkit use the same
export of the server, as set by "export" or "uri", 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 NBD 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 "shared" mode, and thus are not usable with
"command" or "socket-fd".
If libnbd is new enough, dynamic export mode is able to advertise the same exports as
listed by the server; "nbdkit --dump-plugin nbd" will contain "libnbd_dynamic_list=1"
if this is the case. Regardless of what this plugin lists, it is also possible to use
nbdkit-exportname-filter(1) to adjust what export names the client sees or uses as a
default.
tls=off
tls=on
tls=require
(nbdkit ≥ 1.14)
Selects which TLS mode to use with the server. If no other tls option is present,
this defaults to "off", 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 "on", where the client opportunistically attempts a TLS handshake,
but will continue running unencrypted if the server does not support encryption. If
set to "require" or if the "uri" parameter is used with a scheme that requires
encryption (such as "nbds://host"), then this requires an encrypted connection to the
server.
The "tls" parameter is only available when the plugin was compiled against libnbd with
TLS support; "nbdkit --dump-plugin nbd" will contain "libnbd_tls=1" if this is the
case. Note the difference between "--tls=..." controlling what nbdkit serves, and
"tls=..." controlling what the nbd plugin connects to as a client.
tls-certificates=DIR
(nbdkit ≥ 1.14)
This specifies the directory containing X.509 client certificates to present to the
server.
tls-verify=false
(nbdkit ≥ 1.14)
Setting this parameter to false disables server name verification, which opens you to
potential Man-in-the-Middle (MITM) attacks, but allows for a simpler setup for
distributing certificates.
tls-username=NAME
(nbdkit ≥ 1.14)
If provided, this overrides the user name to present to the server alongside the
certificate.
tls-psk=FILE
(nbdkit ≥ 1.14)
If provided, this is the filename containing the Pre-Shared Keys (PSK) to present to
the server. While this is easier to set up than X.509, it requires that the PSK file
be transmitted over a secure channel.
EXAMPLES
Convert oldstyle server to encrypted newstyle
Expose the contents of an export served by an old style server over a Unix socket to TCP
network clients that only want to consume encrypted data. Use --exit-with-parent to clean
up nbdkit at the same time that the old server exits.
( 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 └────────────┘
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.
nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2
qemu-nbd is cleaned up when nbdkit exits.
Add nbdkit-partition-filter to qemu-nbd
Combine nbdkit-partition-filter(1) with qemu-nbd(8)’s ability to visit qcow2 files:
nbdkit --filter=partition nbd \
command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2 \
partition=1
This performs the same task as the deprecated qemu-nbd -P option:
qemu-nbd -P 1 -f qcow2 /path/to/image.qcow2
Convert newstyle server for oldstyle-only client
Expose the contents of export "foo" from a newstyle server with encrypted data to a client
that can only consume unencrypted old style. Use --run 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.
nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
--run '/path/to/oldclient --socket=$unixsocket'
┌────────────┐ plaintext ┌────────┐ TLS ┌────────────┐
│ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
└────────────┘ Unix └────────┘ TCP └────────────┘
DUMP PLUGIN OUTPUT
You can learn which features are provided by libnbd by inspecting the "libnbd_*" lines in
--dump-plugin output:
$ nbdkit --dump-plugin nbd
[...]
libnbd_version=1.2.3
libnbd_tls=1
libnbd_uri=1
FILES
$plugindir/nbdkit-nbd-plugin.so
The plugin.
Use "nbdkit --dump-config" to find the location of $plugindir.
VERSION
"nbdkit-nbd-plugin" first appeared in nbdkit 1.2.
SEE ALSO
nbdkit(1), nbdkit-captive(1), nbdkit-filter(3), nbdkit-exportname-filter(1),
nbdkit-tls(1), nbdkit-plugin(3), libnbd(3), qemu-nbd(8).
AUTHORS
Eric Blake
COPYRIGHT
Copyright (C) 2017, 2019 Red Hat Inc.
LICENSE
Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:
• Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
• 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.
• 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.
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.