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

NAME

6       nbdkit-nbd-plugin - proxy / forward to another NBD server
7

SYNOPSIS

9        nbdkit nbd { command=COMMAND [arg=ARG [...]] |
10                     hostname=HOST [port=PORT] |
11                     vhost-cid=CID [port=PORT] |
12                     socket=SOCKNAME |
13                     socket-fd=FD |
14                     [uri=]URI }
15                   [dynamic-export=BOOL] [export=NAME] [retry=N] [shared=BOOL]
16                   [tls=MODE] [tls-certificates=DIR] [tls-verify=BOOL]
17                   [tls-username=NAME] [tls-psk=FILE]
18

DESCRIPTION

20       "nbdkit-nbd-plugin" is a plugin for nbdkit(1) that lets you forward the
21       connection to another NBD server.  There are several uses for this
22       plugin:
23
24       •   Adjust the set of features seen by the ultimate NBD client without
25           having to change the original server.  For example, convert between
26           the oldstyle and newstyle protocols, or add TLS support if the
27           original server lacks it.
28
29       •   Apply nbdkit filters to any other NBD server.
30
31       •   With qemu-nbd(8), read and write qcow2 files with nbdkit.
32

PARAMETERS

34       One of socket, hostname (optionally with port), vsock (optionally with
35       port), uri, socket-fd or command must be given to specify which NBD
36       server to forward to:
37
38       command=COMMAND
39       arg=ARG
40           (nbdkit ≥ 1.22)
41
42           Run an NBD server, usually qemu-nbd(8), as an external command.
43           See "EXAMPLES" below.
44
45           "COMMAND" is the program to run, followed by zero or more "arg=ARG"
46           parameters for each argument.  For example:
47
48            nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=$PWD/disk.qcow2
49
50           would run the command "qemu-nbd -f qcow2 $PWD/disk.qcow2".  Because
51           nbdkit may change directory before running the command, you may
52           need to ensure that all file paths used in parameters (like the
53           disk name above) are absolute paths.
54
55           This uses the libnbd API nbd_connect_systemd_socket_activation(3).
56           This option implies "shared=true".
57
58       hostname=HOST
59       port=PORT
60           (nbdkit ≥ 1.14)
61
62           Connect to the NBD server at the remote "HOST" using a TCP socket.
63           The optional port parameter overrides the default port (10809), and
64           may be a 16-bit number or a non-numeric string to look up the well-
65           known port for a service name.
66
67       vsock=CID
68       port=PORT
69           (nbdkit ≥ 1.22)
70
71           Connect to the NBD server at the given vsock "CID" (for example, in
72           a guest VM, using the cid 2 will connect to a server in the host).
73           The optional port parameter overrides the default port (10809), and
74           must be a 32-bit number.  This only works for platforms with the
75           "AF_VSOCK" family of sockets and libnbd new enough to use it;
76           "nbdkit --dump-plugin nbd" will contain "libnbd_vsock=1" if this is
77           the case.  For more details on AF_VSOCK, see "AF_VSOCK" in
78           nbdkit-service(1).
79
80       socket=SOCKNAME
81           Connect to the NBD server using Unix domain socket "SOCKNAME".
82
83       socket-fd=FD
84           (nbdkit ≥ 1.22)
85
86           Connect to the NBD server over a socket file descriptor inherited
87           by nbdkit.  This uses the libnbd API nbd_connect_socket(3).  This
88           option implies "shared=true".
89
90       [uri=]URI
91           (nbdkit ≥ 1.14)
92
93           When "uri" is supplied, decode "URI" to determine the address to
94           connect to.  A URI can specify a TCP connection (such as
95           "nbd://localhost:10809/export"), a Unix socket (such as
96           "nbd+unix:///export?socket=/path/to/sock"), or a vsock connection
97           (such as "nbd+vsock:///2:10809/export").  Remember you may need to
98           quote the parameter to protect it from the shell.
99
100           The "uri" parameter is only available when the plugin was compiled
101           against libnbd with URI support; "nbdkit --dump-plugin nbd" will
102           contain "libnbd_uri=1" if this is the case.
103
104           The export portion of the URI is ignored when using
105           "dynamic-export=true".
106
107           "uri=" is a magic config key and may be omitted in most cases.  See
108           "Magic parameters" in nbdkit(1).
109
110       Other parameters control the NBD connection:
111
112       export=NAME
113           If this parameter is given, and the server speaks new style
114           protocol, then connect to the named export instead of the default
115           export (the empty string).  If "uri" is supplied, the export name
116           should be embedded in the URI instead.  This is incompatible with
117           "dynamic-export=true".
118
119       retry=N
120           (nbdkit ≥ 1.14)
121
122           If the initial connection attempt to the server fails, retry up to
123           "N" times more after a one-second delay between tries (default 0).
124
125       shared=false
126       shared=true
127           (nbdkit ≥ 1.14)
128
129           If using "command" or "socket-fd" modes then this defaults to true,
130           otherwise false.
131
132           If false the plugin will open a new connection to the server for
133           each client making a connection to nbdkit.  The remote server does
134           not have to be started until immediately before the first nbdkit
135           client connects.
136
137           If this parameter is set to "true", the plugin will open a single
138           connection to the server when nbdkit is first started (the "retry"
139           parameter may be necessary to coordinate timing of the remote
140           server startup), and all clients to nbdkit will share that single
141           connection.  This mode is incompatible with dynamic-export=true.
142
143       dynamic-export=false
144       dynamic-export=true
145           (nbdkit ≥ 1.24)
146
147           This parameter defaults to false, in which case all clients to
148           nbdkit use the same export of the server, as set by "export" or
149           "uri", regardless of the client's export name request.  If it is
150           set to true, nbdkit will pass the client's requested export name
151           over to the final NBD server, which means clients requesting
152           different export names can see different content when the server
153           differentiates content by export name.  Dynamic exports prevent the
154           use of "shared" mode, and thus are not usable with "command" or
155           "socket-fd".
156
157           If libnbd is new enough, dynamic export mode is able to advertise
158           the same exports as listed by the server; "nbdkit --dump-plugin
159           nbd" will contain "libnbd_dynamic_list=1" if this is the case.
160           Regardless of what this plugin lists, it is also possible to use
161           nbdkit-exportname-filter(1) to adjust what export names the client
162           sees or uses as a default.
163
164       tls=off
165       tls=on
166       tls=require
167           (nbdkit ≥ 1.14)
168
169           Selects which TLS mode to use with the server.  If no other tls
170           option is present, this defaults to "off", where the client does
171           not attempt encryption (and may be rejected by a server that
172           requires it).  If omitted but another tls option is present, this
173           defaults to "on", where the client opportunistically attempts a TLS
174           handshake, but will continue running unencrypted if the server does
175           not support encryption.  If set to "require" or if the "uri"
176           parameter is used with a scheme that requires encryption (such as
177           "nbds://host"), then this requires an encrypted connection to the
178           server.
179
180           The "tls" parameter is only available when the plugin was compiled
181           against libnbd with TLS support; "nbdkit --dump-plugin nbd" will
182           contain "libnbd_tls=1" if this is the case.  Note the difference
183           between --tls=... controlling what nbdkit serves, and "tls=..."
184           controlling what the nbd plugin connects to as a client.
185
186       tls-certificates=DIR
187           (nbdkit ≥ 1.14)
188
189           This specifies the directory containing X.509 client certificates
190           to present to the server.
191
192       tls-verify=false
193           (nbdkit ≥ 1.14)
194
195           Setting this parameter to false disables server name verification,
196           which opens you to potential Man-in-the-Middle (MITM) attacks, but
197           allows for a simpler setup for distributing certificates.
198
199       tls-username=NAME
200           (nbdkit ≥ 1.14)
201
202           If provided, this overrides the user name to present to the server
203           alongside the certificate.
204
205       tls-psk=FILE
206           (nbdkit ≥ 1.14)
207
208           If provided, this is the filename containing the Pre-Shared Keys
209           (PSK) to present to the server.  While this is easier to set up
210           than X.509, it requires that the PSK file be transmitted over a
211           secure channel.
212

EXAMPLES

214   Convert oldstyle server to encrypted newstyle
215       Expose the contents of an export served by an old style server over a
216       Unix socket to TCP network clients that only want to consume encrypted
217       data.  Use --exit-with-parent to clean up nbdkit at the same time that
218       the old server exits.
219
220        ( sock=`mktemp -u`
221          nbdkit --exit-with-parent --tls=require nbd socket=$sock &
222          exec /path/to/oldserver --socket=$sock )
223
224        ┌────────────┐   TLS    ┌────────┐  plaintext  ┌────────────┐
225        │ new client │ ────────▶│ nbdkit │ ───────────▶│ old server │
226        └────────────┘   TCP    └────────┘    Unix     └────────────┘
227
228   Use qemu-nbd to open a qcow2 file
229       Run qemu-nbd as the server, allowing you to read and write qcow2 files
230       (since nbdkit does not have a native qcow2 plugin).  This allows you to
231       use nbdkit filters on top, see the next example.
232
233        nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2
234
235       qemu-nbd is cleaned up when nbdkit exits.
236
237   Add nbdkit-partition-filter to qemu-nbd
238       Combine nbdkit-partition-filter(1) with qemu-nbd(8)’s ability to visit
239       qcow2 files:
240
241        nbdkit --filter=partition nbd \
242               command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2 \
243               partition=1
244
245       This performs the same task as the deprecated qemu-nbd -P option:
246
247        qemu-nbd -P 1 -f qcow2 /path/to/image.qcow2
248
249   Convert newstyle server for oldstyle-only client
250       Expose the contents of export "foo" from a newstyle server with
251       encrypted data to a client that can only consume unencrypted old style.
252       Use --run to clean up nbdkit at the time the client exits.  In general,
253       note that it is best to keep the plaintext connection limited to a Unix
254       socket on the local machine.
255
256        nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
257         --run '/path/to/oldclient --socket=$unixsocket'
258
259        ┌────────────┐  plaintext  ┌────────┐   TLS    ┌────────────┐
260        │ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
261        └────────────┘    Unix     └────────┘   TCP    └────────────┘
262

DUMP PLUGIN OUTPUT

264       You can learn which features are provided by libnbd by inspecting the
265       "libnbd_*" lines in --dump-plugin output:
266
267        $ nbdkit --dump-plugin nbd
268        [...]
269        libnbd_version=1.2.3
270        libnbd_tls=1
271        libnbd_uri=1
272

FILES

274       $plugindir/nbdkit-nbd-plugin.so
275           The plugin.
276
277           Use "nbdkit --dump-config" to find the location of $plugindir.
278

VERSION

280       "nbdkit-nbd-plugin" first appeared in nbdkit 1.2.
281

SEE ALSO

283       nbdkit(1), nbdkit-captive(1), nbdkit-filter(3),
284       nbdkit-exportname-filter(1), nbdkit-tls(1), nbdkit-plugin(3),
285       libnbd(3), qemu-nbd(8).
286

AUTHORS

288       Eric Blake
289
291       Copyright (C) 2017, 2019 Red Hat Inc.
292

LICENSE

294       Redistribution and use in source and binary forms, with or without
295       modification, are permitted provided that the following conditions are
296       met:
297
298       •   Redistributions of source code must retain the above copyright
299           notice, this list of conditions and the following disclaimer.
300
301       •   Redistributions in binary form must reproduce the above copyright
302           notice, this list of conditions and the following disclaimer in the
303           documentation and/or other materials provided with the
304           distribution.
305
306       •   Neither the name of Red Hat nor the names of its contributors may
307           be used to endorse or promote products derived from this software
308           without specific prior written permission.
309
310       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
311       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
312       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
313       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
314       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
315       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
316       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
317       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
318       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
319       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
320       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
321
322
323
324nbdkit-1.32.5                     2023-01-03              nbdkit-nbd-plugin(1)
Impressum