1nbdkit-nbd-plugin(1) NBDKIT nbdkit-nbd-plugin(1)
2
6 nbdkit-nbd-plugin - nbdkit nbd plugin
7
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
14 "nbdkit-nbd-plugin" is an NBD forwarding plugin for nbdkit(1).
15 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 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
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 The following parameters are available whether or not the plugin was
36 compiled against libnbd:
37 socket=SOCKNAME
39 Connect to the NBD server located at the Unix socket "SOCKNAME".
40 hostname=HOST
42 Connect to the NBD server at the given remote "HOST" using a TCP
43 socket.
44 port=PORT
46 When hostname is supplied, use PORT instead of the default port
47 10809.
48 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 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 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 The following parameters are only available if the plugin was compiled
71 against libnbd:
72 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 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 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 tls-certificates=DIR
102 This specifies the directory containing X.509 client certificates
103 to present to the server.
104 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 tls-username=NAME
112 If provided, this overrides the user name to present to the server
113 alongside the certificate.
114 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
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 ( sock=`mktemp -u`
128 nbdkit --exit-with-parent --tls=require nbd socket=$sock &
129 exec /path/to/oldserver --socket=$sock )
130 ┌────────────┐ TLS ┌────────┐ plaintext ┌────────────┐
132 │ new client │ ────────▶│ nbdkit │ ───────────▶│ old server │
133 └────────────┘ TCP └────────┘ Unix └────────────┘
134 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 ( 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 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 nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
154 --run '/path/to/oldclient --socket=$unixsocket'
155 ┌────────────┐ plaintext ┌────────┐ TLS ┌────────────┐
157 │ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
158 └────────────┘ Unix └────────┘ TCP └────────────┘
159 Learn which features are provided by libnbd by inspecting the
161 "libnbd_*" lines:
162 nbdkit --dump-plugin nbd
164
166 $plugindir/nbdkit-nbd-plugin.so
167 The plugin.
168 Use "nbdkit --dump-config" to find the location of $plugindir.
170
172 "nbdkit-nbd-plugin" first appeared in nbdkit 1.2.
173
175 nbdkit(1), nbdkit-captive(1), nbdkit-filter(3), nbdkit-tls(1),
176 nbdkit-plugin(3), libnbd(3), qemu-nbd(1).
177
179 Eric Blake
180
182 Copyright (C) 2017, 2019 Red Hat Inc.
183
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 · Redistributions of source code must retain the above copyright
190 notice, this list of conditions and the following disclaimer.
191 · 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 · 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 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.
212nbdkit-1.16.1 2019-12-03 nbdkit-nbd-plugin(1)