NAME

       nbdkit-nbd-plugin - nbdkit nbd plugin

SYNOPSIS

        nbdkit nbd { socket=SOCKNAME | hostname=HOST [port=PORT] | [uri=]URI }
           [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 an NBD forwarding plugin for nbdkit(1).

       It provides an NBD server that forwards all traffic as a client to another existing NBD
       server.  A primary usage of this setup is to alter the set of features available to the
       ultimate end client, without having to change the original server (for example, to convert
       between oldstyle and newstyle, or to add TLS support where the original server lacks it).
       Use of this plugin along with nbdkit filters (adding --filter to the nbdkit command line)
       makes it possible to apply any nbdkit filter to any other NBD server.

       Remember that when using this plugin as a bridge between an encrypted and a non-encrypted
       endpoint, it is best to preserve encryption over TCP and use plaintext only on a Unix
       socket.

PARAMETERS

       One of socket, hostname or uri must be provided to designate the server. The server can
       speak either new or old style protocol. "uri=" is a magic config key and may be omitted in
       most cases.  See "Magic parameters" in nbdkit(1).

       The following parameters are available whether or not the plugin was compiled against
       libnbd:

       socket=SOCKNAME
           Connect to the NBD server located at the Unix socket "SOCKNAME".

       hostname=HOST
           Connect to the NBD server at the given remote "HOST" using a TCP socket.

       port=PORT
           When hostname is supplied, use PORT instead of the default port 10809.

       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.

       retry=N
           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=BOOL
           If this parameter is false (default), the plugin will open a distinct connection to
           the server for each client making a connection to nbdkit, and the remote server does
           not have to be started until immediately before the first nbdkit client.  If this
           parameter is set to true, the plugin will open a single connection to the server when
           nbdkit is first started (the "delay" parameter may be necessary to coordinate timing
           of the remote server startup), and all clients to nbdkit will share that single
           connection.

       The following parameters are only available if the plugin was compiled against libnbd:

       uri=URI
           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") or a Unix socket
           (such as "nbd+unix:///export?socket=/path/to/sock").  Remember to use proper shell
           quoting to prevent URI from accidentally being handled as a shell glob. 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.

       tls=MODE
           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
           This specifies the directory containing X.509 client certificates to present to the
           server.

       tls-verify=BOOL
           This defaults to true; setting it 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
           If provided, this overrides the user name to present to the server alongside the
           certificate.

       tls-psk=FILE
           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

       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     └────────────┘

       Combine nbdkit's partition filter with qemu-nbd's ability to visit qcow2 files (nbdkit
       does not have a native qcow2 plugin), performing the same task as the deprecated "qemu-nbd
       -P 1 -f qcow2 /path/to/image.qcow2" command. Allow multiple clients, even though
       "qemu-nbd" without -t normally quits after the first client, and utilize a 5-second retry
       to give qemu-nbd time to create the socket:

        ( sock=`mktemp -u`
          nbdkit --exit-with-parent --filter=partition nbd \
            nbd+unix:///\?socket=$sock shared=1 retry=5 partition=1 &
          exec qemu-nbd -k $sock -f qcow2 /path/to/image.qcow2 )

       Conversely, expose the contents of export foo from a new style 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    └────────────┘

       Learn which features are provided by libnbd by inspecting the "libnbd_*" lines:

        nbdkit --dump-plugin nbd

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-tls(1), nbdkit-plugin(3),
       libnbd(3), qemu-nbd(1).

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.