1nbdkit-nbd-plugin(1) NBDKIT nbdkit-nbd-plugin(1)
2
6 nbdkit-nbd-plugin - proxy / forward to another NBD server
7
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
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 • 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 • Apply nbdkit filters to any other NBD server.
30 • With qemu-nbd(8), read and write qcow2 files with nbdkit.
32
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 command=COMMAND
39 arg=ARG
40 (nbdkit ≥ 1.22)
41 Run an NBD server, usually qemu-nbd(8), as an external command.
43 See "EXAMPLES" below.
44 "COMMAND" is the program to run, followed by zero or more "arg=ARG"
46 parameters for each argument. For example:
47 nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=$PWD/disk.qcow2
49 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 This uses the libnbd API nbd_connect_systemd_socket_activation(3).
56 This option implies "shared=true".
57 hostname=HOST
59 port=PORT
60 (nbdkit ≥ 1.14)
61 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 vsock=CID
68 port=PORT
69 (nbdkit ≥ 1.22)
70 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 socket=SOCKNAME
81 Connect to the NBD server using Unix domain socket "SOCKNAME".
82 socket-fd=FD
84 (nbdkit ≥ 1.22)
85 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 [uri=]URI
91 (nbdkit ≥ 1.14)
92 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 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 The export portion of the URI is ignored when using
105 "dynamic-export=true".
106 "uri=" is a magic config key and may be omitted in most cases. See
108 "Magic parameters" in nbdkit(1).
109 Other parameters control the NBD connection:
111 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 retry=N
120 (nbdkit ≥ 1.14)
121 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 shared=false
126 shared=true
127 (nbdkit ≥ 1.14)
128 If using "command" or "socket-fd" modes then this defaults to true,
130 otherwise false.
131 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 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 dynamic-export=false
144 dynamic-export=true
145 (nbdkit ≥ 1.24)
146 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 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 tls=off
165 tls=on
166 tls=require
167 (nbdkit ≥ 1.14)
168 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 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 tls-certificates=DIR
187 (nbdkit ≥ 1.14)
188 This specifies the directory containing X.509 client certificates
190 to present to the server.
191 tls-verify=false
193 (nbdkit ≥ 1.14)
194 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 tls-username=NAME
200 (nbdkit ≥ 1.14)
201 If provided, this overrides the user name to present to the server
203 alongside the certificate.
204 tls-psk=FILE
206 (nbdkit ≥ 1.14)
207 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
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 ( sock=`mktemp -u`
221 nbdkit --exit-with-parent --tls=require nbd socket=$sock &
222 exec /path/to/oldserver --socket=$sock )
223 ┌────────────┐ TLS ┌────────┐ plaintext ┌────────────┐
225 │ new client │ ────────▶│ nbdkit │ ───────────▶│ old server │
226 └────────────┘ TCP └────────┘ Unix └────────────┘
227 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 nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2
234 qemu-nbd is cleaned up when nbdkit exits.
236 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 nbdkit --filter=partition nbd \
242 command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2 \
243 partition=1
244 This performs the same task as the deprecated qemu-nbd -P option:
246 qemu-nbd -P 1 -f qcow2 /path/to/image.qcow2
248 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 nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
257 --run '/path/to/oldclient --socket=$unixsocket'
258 ┌────────────┐ plaintext ┌────────┐ TLS ┌────────────┐
260 │ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
261 └────────────┘ Unix └────────┘ TCP └────────────┘
262
264 You can learn which features are provided by libnbd by inspecting the
265 "libnbd_*" lines in --dump-plugin output:
266 $ nbdkit --dump-plugin nbd
268 [...]
269 libnbd_version=1.2.3
270 libnbd_tls=1
271 libnbd_uri=1
272
274 $plugindir/nbdkit-nbd-plugin.so
275 The plugin.
276 Use "nbdkit --dump-config" to find the location of $plugindir.
278
280 "nbdkit-nbd-plugin" first appeared in nbdkit 1.2.
281
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
288 Eric Blake
289
291 Copyright Red Hat
292
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 • Redistributions of source code must retain the above copyright
299 notice, this list of conditions and the following disclaimer.
300 • 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 • 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 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.
321nbdkit-1.34.4 2023-09-26 nbdkit-nbd-plugin(1)