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 (see also
32 nbdkit-qcow2dec-filter(1)).
33
35 One of socket, hostname (optionally with port), vsock (optionally with
36 port), uri, socket-fd or command must be given to specify which NBD
37 server to forward to:
38 command=COMMAND
40 arg=ARG
41 (nbdkit ≥ 1.22)
42 Run an NBD server, usually qemu-nbd(8), as an external command.
44 See "EXAMPLES" below.
45 "COMMAND" is the program to run, followed by zero or more "arg=ARG"
47 parameters for each argument. For example:
48 nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=$PWD/disk.qcow2
50 would run the command "qemu-nbd -f qcow2 $PWD/disk.qcow2". Because
52 nbdkit may change directory before running the command, you may
53 need to ensure that all file paths used in parameters (like the
54 disk name above) are absolute paths.
55 This uses the libnbd API nbd_connect_systemd_socket_activation(3).
57 This option implies "shared=true".
58 hostname=HOST
60 port=PORT
61 (nbdkit ≥ 1.14)
62 Connect to the NBD server at the remote "HOST" using a TCP socket.
64 The optional port parameter overrides the default port (10809), and
65 may be a 16-bit number or a non-numeric string to look up the well-
66 known port for a service name.
67 vsock=CID
69 port=PORT
70 (nbdkit ≥ 1.22)
71 Connect to the NBD server at the given vsock "CID" (for example, in
73 a guest VM, using the cid 2 will connect to a server in the host).
74 The optional port parameter overrides the default port (10809), and
75 must be a 32-bit number. This only works for platforms with the
76 "AF_VSOCK" family of sockets and libnbd new enough to use it;
77 "nbdkit --dump-plugin nbd" will contain "libnbd_vsock=1" if this is
78 the case. For more details on AF_VSOCK, see "AF_VSOCK" in
79 nbdkit-service(1).
80 socket=SOCKNAME
82 Connect to the NBD server using Unix domain socket "SOCKNAME".
83 socket-fd=FD
85 (nbdkit ≥ 1.22)
86 Connect to the NBD server over a socket file descriptor inherited
88 by nbdkit. This uses the libnbd API nbd_connect_socket(3). This
89 option implies "shared=true".
90 [uri=]URI
92 (nbdkit ≥ 1.14)
93 When "uri" is supplied, decode "URI" to determine the address to
95 connect to. A URI can specify a TCP connection (such as
96 "nbd://localhost:10809/export"), a Unix socket (such as
97 "nbd+unix:///export?socket=/path/to/sock"), or a vsock connection
98 (such as "nbd+vsock:///2:10809/export"). Remember you may need to
99 quote the parameter to protect it from the shell.
100 The "uri" parameter is only available when the plugin was compiled
102 against libnbd with URI support; "nbdkit --dump-plugin nbd" will
103 contain "libnbd_uri=1" if this is the case.
104 The export portion of the URI is ignored when using
106 "dynamic-export=true".
107 "uri=" is a magic config key and may be omitted in most cases. See
109 "Magic parameters" in nbdkit(1).
110 Other parameters control the NBD connection:
112 export=NAME
114 If this parameter is given, and the server speaks new style
115 protocol, then connect to the named export instead of the default
116 export (the empty string). If "uri" is supplied, the export name
117 should be embedded in the URI instead. This is incompatible with
118 "dynamic-export=true".
119 retry=N
121 (nbdkit ≥ 1.14)
122 If the initial connection attempt to the server fails, retry up to
124 "N" times more after a one-second delay between tries (default 0).
125 shared=false
127 shared=true
128 (nbdkit ≥ 1.14)
129 If using "command" or "socket-fd" modes then this defaults to true,
131 otherwise false.
132 If false the plugin will open a new connection to the server for
134 each client making a connection to nbdkit. The remote server does
135 not have to be started until immediately before the first nbdkit
136 client connects.
137 If this parameter is set to "true", the plugin will open a single
139 connection to the server when nbdkit is first started (the "retry"
140 parameter may be necessary to coordinate timing of the remote
141 server startup), and all clients to nbdkit will share that single
142 connection. This mode is incompatible with dynamic-export=true.
143 dynamic-export=false
145 dynamic-export=true
146 (nbdkit ≥ 1.24)
147 This parameter defaults to false, in which case all clients to
149 nbdkit use the same export of the server, as set by "export" or
150 "uri", regardless of the client's export name request. If it is
151 set to true, nbdkit will pass the client's requested export name
152 over to the final NBD server, which means clients requesting
153 different export names can see different content when the server
154 differentiates content by export name. Dynamic exports prevent the
155 use of "shared" mode, and thus are not usable with "command" or
156 "socket-fd".
157 If libnbd is new enough, dynamic export mode is able to advertise
159 the same exports as listed by the server; "nbdkit --dump-plugin
160 nbd" will contain "libnbd_dynamic_list=1" if this is the case.
161 Regardless of what this plugin lists, it is also possible to use
162 nbdkit-exportname-filter(1) to adjust what export names the client
163 sees or uses as a default.
164 tls=off
166 tls=on
167 tls=require
168 (nbdkit ≥ 1.14)
169 Selects which TLS mode to use with the server. If no other tls
171 option is present, this defaults to "off", where the client does
172 not attempt encryption (and may be rejected by a server that
173 requires it). If omitted but another tls option is present, this
174 defaults to "on", where the client opportunistically attempts a TLS
175 handshake, but will continue running unencrypted if the server does
176 not support encryption. If set to "require" or if the "uri"
177 parameter is used with a scheme that requires encryption (such as
178 "nbds://host"), then this requires an encrypted connection to the
179 server.
180 The "tls" parameter is only available when the plugin was compiled
182 against libnbd with TLS support; "nbdkit --dump-plugin nbd" will
183 contain "libnbd_tls=1" if this is the case. Note the difference
184 between --tls=... controlling what nbdkit serves, and "tls=..."
185 controlling what the nbd plugin connects to as a client.
186 tls-certificates=DIR
188 (nbdkit ≥ 1.14)
189 This specifies the directory containing X.509 client certificates
191 to present to the server.
192 tls-verify=false
194 (nbdkit ≥ 1.14)
195 Setting this parameter to false disables server name verification,
197 which opens you to potential Man-in-the-Middle (MITM) attacks, but
198 allows for a simpler setup for distributing certificates.
199 tls-username=NAME
201 (nbdkit ≥ 1.14)
202 If provided, this overrides the user name to present to the server
204 alongside the certificate.
205 tls-psk=FILE
207 (nbdkit ≥ 1.14)
208 If provided, this is the filename containing the Pre-Shared Keys
210 (PSK) to present to the server. While this is easier to set up
211 than X.509, it requires that the PSK file be transmitted over a
212 secure channel.
213
215 Convert oldstyle server to encrypted newstyle
216 Expose the contents of an export served by an old style server over a
217 Unix socket to TCP network clients that only want to consume encrypted
218 data. Use --exit-with-parent to clean up nbdkit at the same time that
219 the old server exits.
220 ( sock=`mktemp -u`
222 nbdkit --exit-with-parent --tls=require nbd socket=$sock &
223 exec /path/to/oldserver --socket=$sock )
224 ┌────────────┐ TLS ┌────────┐ plaintext ┌────────────┐
226 │ new client │ ────────▶│ nbdkit │ ───────────▶│ old server │
227 └────────────┘ TCP └────────┘ Unix └────────────┘
228 Use qemu-nbd to open a qcow2 file
230 Run qemu-nbd as the server, allowing you to read and write qcow2 files
231 (since nbdkit does not have a native qcow2 plugin). This allows you to
232 use nbdkit filters on top, see the next example.
233 nbdkit nbd command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2
235 qemu-nbd is cleaned up when nbdkit exits.
237 Add nbdkit-partition-filter to qemu-nbd
239 Combine nbdkit-partition-filter(1) with qemu-nbd(8)’s ability to visit
240 qcow2 files:
241 nbdkit --filter=partition nbd \
243 command=qemu-nbd arg=-f arg=qcow2 arg=/path/to/image.qcow2 \
244 partition=1
245 This performs the same task as the deprecated qemu-nbd -P option:
247 qemu-nbd -P 1 -f qcow2 /path/to/image.qcow2
249 Convert newstyle server for oldstyle-only client
251 Expose the contents of export "foo" from a newstyle server with
252 encrypted data to a client that can only consume unencrypted old style.
253 Use --run to clean up nbdkit at the time the client exits. In general,
254 note that it is best to keep the plaintext connection limited to a Unix
255 socket on the local machine.
256 nbdkit -o --tls=off nbd hostname=example.com export=foo tls=require \
258 --run '/path/to/oldclient --socket=$unixsocket'
259 ┌────────────┐ plaintext ┌────────┐ TLS ┌────────────┐
261 │ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
262 └────────────┘ Unix └────────┘ TCP └────────────┘
263
265 You can learn which features are provided by libnbd by inspecting the
266 "libnbd_*" lines in --dump-plugin output:
267 $ nbdkit --dump-plugin nbd
269 [...]
270 libnbd_version=1.2.3
271 libnbd_tls=1
272 libnbd_uri=1
273
275 $plugindir/nbdkit-nbd-plugin.so
276 The plugin.
277 Use "nbdkit --dump-config" to find the location of $plugindir.
279
281 "nbdkit-nbd-plugin" first appeared in nbdkit 1.2.
282
284 nbdkit(1), nbdkit-captive(1), nbdkit-filter(3),
285 nbdkit-exportname-filter(1), nbdkit-qcow2dec-filter(1), nbdkit-tls(1),
286 nbdkit-plugin(3), libnbd(3), qemu-nbd(8).
287
289 Eric Blake
290
292 Copyright Red Hat
293
295 Redistribution and use in source and binary forms, with or without
296 modification, are permitted provided that the following conditions are
297 met:
298 • Redistributions of source code must retain the above copyright
300 notice, this list of conditions and the following disclaimer.
301 • Redistributions in binary form must reproduce the above copyright
303 notice, this list of conditions and the following disclaimer in the
304 documentation and/or other materials provided with the
305 distribution.
306 • Neither the name of Red Hat nor the names of its contributors may
308 be used to endorse or promote products derived from this software
309 without specific prior written permission.
310 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
312 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
313 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
314 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
315 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
316 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
317 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
318 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
319 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
320 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
321 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
322nbdkit-1.36.2 2023-11-26 nbdkit-nbd-plugin(1)