1nbdkit-nbd-plugin(1)                NBDKIT                nbdkit-nbd-plugin(1)
2
3
4

NAME

6       nbdkit-nbd-plugin - nbdkit nbd plugin
7

SYNOPSIS

9        nbdkit nbd { socket=SOCKNAME | hostname=HOST [port=PORT] | [uri=]URI }
10           [export=NAME] [retry=N] [shared=BOOL] [tls=MODE] [tls-certificates=DIR]
11           [tls-verify=BOOL] [tls-username=NAME] [tls-psk=FILE]
12

DESCRIPTION

14       "nbdkit-nbd-plugin" is an NBD forwarding plugin for nbdkit(1).
15
16       It provides an NBD server that forwards all traffic as a client to
17       another existing NBD server.  A primary usage of this setup is to alter
18       the set of features available to the ultimate end client, without
19       having to change the original server (for example, to convert between
20       oldstyle and newstyle, or to add TLS support where the original server
21       lacks it).  Use of this plugin along with nbdkit filters (adding
22       --filter to the nbdkit command line) makes it possible to apply any
23       nbdkit filter to any other NBD server.
24
25       Remember that when using this plugin as a bridge between an encrypted
26       and a non-encrypted endpoint, it is best to preserve encryption over
27       TCP and use plaintext only on a Unix socket.
28

PARAMETERS

30       One of socket, hostname or uri must be provided to designate the
31       server. The server can speak either new or old style protocol. "uri="
32       is a magic config key and may be omitted in most cases.  See "Magic
33       parameters" in nbdkit(1).
34
35       The following parameters are available whether or not the plugin was
36       compiled against libnbd:
37
38       socket=SOCKNAME
39           Connect to the NBD server located at the Unix socket "SOCKNAME".
40
41       hostname=HOST
42           Connect to the NBD server at the given remote "HOST" using a TCP
43           socket.
44
45       port=PORT
46           When hostname is supplied, use PORT instead of the default port
47           10809.
48
49       export=NAME
50           If this parameter is given, and the server speaks new style
51           protocol, then connect to the named export instead of the default
52           export (the empty string). If "uri" is supplied, the export name
53           should be embedded in the URI instead.
54
55       retry=N
56           If the initial connection attempt to the server fails, retry up to
57           N times more after a one-second delay between tries (default 0).
58
59       shared=BOOL
60           If this parameter is false (default), the plugin will open a
61           distinct connection to the server for each client making a
62           connection to nbdkit, and the remote server does not have to be
63           started until immediately before the first nbdkit client.  If this
64           parameter is set to true, the plugin will open a single connection
65           to the server when nbdkit is first started (the "delay" parameter
66           may be necessary to coordinate timing of the remote server
67           startup), and all clients to nbdkit will share that single
68           connection.
69
70       The following parameters are only available if the plugin was compiled
71       against libnbd:
72
73       uri=URI
74           When uri is supplied, decode URI to determine the address to
75           connect to. A URI can specify a TCP connection (such as
76           "nbd://localhost:10809/export") or a Unix socket (such as
77           "nbd+unix:///export?socket=/path/to/sock").  Remember to use proper
78           shell quoting to prevent URI from accidentally being handled as a
79           shell glob. The uri parameter is only available when the plugin was
80           compiled against libnbd with URI support; "nbdkit --dump-plugin
81           nbd" will contain "libnbd_uri=1" if this is the case.
82
83       tls=MODE
84           Selects which TLS mode to use with the server. If no other tls
85           option is present, this defaults to "off", where the client does
86           not attempt encryption (and may be rejected by a server that
87           requires it). If omitted but another tls option is present, this
88           defaults to "on", where the client opportunistically attempts a TLS
89           handshake, but will continue running unencrypted if the server does
90           not support encryption. If set to "require" or if the "uri"
91           parameter is used with a scheme that requires encryption (such as
92           "nbds://host"), then this requires an encrypted connection to the
93           server.
94
95           The tls parameter is only available when the plugin was compiled
96           against libnbd with TLS support; "nbdkit --dump-plugin nbd" will
97           contain "libnbd_tls=1" if this is the case.  Note the difference
98           between "--tls=..." controlling what nbdkit serves, and "tls=..."
99           controlling what the nbd plugin connects to as a client.
100
101       tls-certificates=DIR
102           This specifies the directory containing X.509 client certificates
103           to present to the server.
104
105       tls-verify=BOOL
106           This defaults to true; setting it to false disables server name
107           verification, which opens you to potential Man-in-the-Middle (MITM)
108           attacks, but allows for a simpler setup for distributing
109           certificates.
110
111       tls-username=NAME
112           If provided, this overrides the user name to present to the server
113           alongside the certificate.
114
115       tls-psk=FILE
116           If provided, this is the filename containing the Pre-Shared Keys
117           (PSK) to present to the server. While this is easier to set up than
118           X.509, it requires that the PSK file be transmitted over a secure
119           channel.
120

EXAMPLES

122       Expose the contents of an export served by an old style server over a
123       Unix socket to TCP network clients that only want to consume encrypted
124       data. Use --exit-with-parent to clean up nbdkit at the same time that
125       the old server exits.
126
127        ( sock=`mktemp -u`
128          nbdkit --exit-with-parent --tls=require nbd socket=$sock &
129          exec /path/to/oldserver --socket=$sock )
130
131        ┌────────────┐   TLS    ┌────────┐  plaintext  ┌────────────┐
132        │ new client │ ────────▶│ nbdkit │ ───────────▶│ old server │
133        └────────────┘   TCP    └────────┘    Unix     └────────────┘
134
135       Combine nbdkit's partition filter with qemu-nbd's ability to visit
136       qcow2 files (nbdkit does not have a native qcow2 plugin), performing
137       the same task as the deprecated "qemu-nbd -P 1 -f qcow2
138       /path/to/image.qcow2" command. Allow multiple clients, even though
139       "qemu-nbd" without -t normally quits after the first client, and
140       utilize a 5-second retry to give qemu-nbd time to create the socket:
141
142        ( sock=`mktemp -u`
143          nbdkit --exit-with-parent --filter=partition nbd \
144            nbd+unix:///\?socket=$sock shared=1 retry=5 partition=1 &
145          exec qemu-nbd -k $sock -f qcow2 /path/to/image.qcow2 )
146
147       Conversely, expose the contents of export foo from a new style server
148       with encrypted data to a client that can only consume unencrypted old
149       style. Use --run to clean up nbdkit at the time the client exits.  In
150       general, note that it is best to keep the plaintext connection limited
151       to a Unix socket on the local machine.
152
153        nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
154         --run '/path/to/oldclient --socket=$unixsocket'
155
156        ┌────────────┐  plaintext  ┌────────┐   TLS    ┌────────────┐
157        │ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
158        └────────────┘    Unix     └────────┘   TCP    └────────────┘
159
160       Learn which features are provided by libnbd by inspecting the
161       "libnbd_*" lines:
162
163        nbdkit --dump-plugin nbd
164

FILES

166       $plugindir/nbdkit-nbd-plugin.so
167           The plugin.
168
169           Use "nbdkit --dump-config" to find the location of $plugindir.
170

VERSION

172       "nbdkit-nbd-plugin" first appeared in nbdkit 1.2.
173

SEE ALSO

175       nbdkit(1), nbdkit-captive(1), nbdkit-filter(3), nbdkit-tls(1),
176       nbdkit-plugin(3), libnbd(3), qemu-nbd(1).
177

AUTHORS

179       Eric Blake
180
182       Copyright (C) 2017, 2019 Red Hat Inc.
183

LICENSE

185       Redistribution and use in source and binary forms, with or without
186       modification, are permitted provided that the following conditions are
187       met:
188
189       ·   Redistributions of source code must retain the above copyright
190           notice, this list of conditions and the following disclaimer.
191
192       ·   Redistributions in binary form must reproduce the above copyright
193           notice, this list of conditions and the following disclaimer in the
194           documentation and/or other materials provided with the
195           distribution.
196
197       ·   Neither the name of Red Hat nor the names of its contributors may
198           be used to endorse or promote products derived from this software
199           without specific prior written permission.
200
201       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
202       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
203       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
204       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
205       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
206       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
207       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
208       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
209       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
210       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
211       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
212
213
214
215nbdkit-1.16.1                     2019-12-03              nbdkit-nbd-plugin(1)
Impressum