5 nbdkit - A toolkit for creating NBD servers
9 nbdkit [-f] [-g GROUP] [-i IPADDR] [-P PIDFILE] [-p PORT]
10 [-r] [-s] [-U SOCKET] [-u USER] [-v] [-V]
11 PLUGIN.so [key=value [key=value [...]]]
15 C<nbdkit> is both a toolkit for creating Network Block Device (NBD)
16 servers from "unconventional" sources and the name of an NBD server.
18 To create a new block device source, all you have to do is write a few
19 glue functions. The liberal licensing of nbdkit is meant to allow you
20 to link nbdkit with proprietary libraries or include nbdkit in
23 If you want to write an nbdkit plugin, you should read
26 Several plugins may be found in C<LIBDIR/nbdkit/plugins> where
27 C<LIBDIR> is set at compile time and might be a path such as
28 C</usr/lib>, C</usr/lib64> or C</usr/local/lib>.
32 Serve file C<disk.img> on port 10809:
34 nbdkit .../plugins/nbdkit-file-plugin.so file=disk.img
36 Run the example1 plugin and connect to it using L<guestfish(1)>:
38 nbdkit .../plugins/nbdkit-example1-plugin.so
39 guestfish --ro -a nbd://localhost
41 Run the example3 plugin and connect to it using L<guestfish(1)>:
43 nbdkit .../plugins/nbdkit-example3-plugin.so size=1G
44 guestfish --ro -a nbd://localhost
46 To display usage information about a specific plugin:
48 nbdkit --help .../plugins/nbdkit-example1-plugin.so
56 Display brief command line usage information and exit.
64 I<Don't> fork into the background.
68 =item B<--group> GROUP
70 Change group to C<GROUP> after starting up. A group name or numeric
73 The server needs sufficient permissions to be able to do this.
74 Normally this would mean starting the server up as root.
80 =item B<--ip-addr> IPADDR
82 =item B<--ipaddr> IPADDR
84 Listen on the specified interface. The default is to listen on all
85 interfaces. See also I<-p>.
89 =item B<--pid-file> PIDFILE
91 =item B<--pidfile> PIDFILE
93 Write C<PIDFILE> (containing the process ID of the server) after
94 nbdkit becomes ready to accept connections.
96 If the file already exists, it is overwritten. nbdkit I<does not>
97 delete the file when it exits.
103 Change the TCP/IP port number on which nbdkit serves requests.
104 The default is C<10809>. See also I<-i>.
112 The export will be read-only. If a client writes, then it will get an
115 Note that some plugins inherently don't support writes. With those
116 plugins the I<-r> option is added implicitly.
118 Copy-on-write (or "snapshot") functionality is not supported by this
119 server. However if you are using qemu as a client (or indirectly via
120 libguestfs) then it supports snapshots.
128 Don't fork. Handle a single NBD connection on stdin/stdout. After
129 stdin closes, the server exits.
131 You can use this option to run nbdkit from inetd, systemd or similar
132 superservers; or just for testing; or if you want to run nbdkit in a
133 non-conventional way.
135 This option implies I<--foreground>.
139 =item B<--unix> SOCKET
141 Accept connections on the Unix domain socket C<SOCKET> (which is a
144 nbdkit neither creates nor deletes this socket. You should create the
145 socket and set the desired permissions and ownership before running
152 Change user to C<USER> after starting up. A user name or numeric user
155 The server needs sufficient permissions to be able to do this.
156 Normally this would mean starting the server up as root.
164 Enable verbose messages.
166 It's a good idea to use I<-f> as well so the process does not fork
167 into the background (but not required).
173 Print the version number of nbdkit and exit.
177 =head1 PLUGIN CONFIGURATION
179 After specifying the plugin name you can (optionally, it depends
180 on the plugin) give plugin configuration on the command line in
181 the form of C<key=value>. For example:
183 nbdkit .../plugins/nbdkit-file-plugin.so file=disk.img
185 To list all the options supported by a plugin, do:
187 nbdkit --help .../plugins/nbdkit-file-plugin.so
192 L<nbdkit-example1-plugin(1)>,
193 L<nbdkit-example2-plugin(1)>,
194 L<nbdkit-example3-plugin(1)>,
195 L<nbdkit-file-plugin(1)>,
196 L<nbdkit-gzip-plugin(1)>,
197 L<nbdkit-libvirt-plugin(1)>.
205 Copyright (C) 2013 Red Hat Inc.
209 Redistribution and use in source and binary forms, with or without
210 modification, are permitted provided that the following conditions are
217 Redistributions of source code must retain the above copyright
218 notice, this list of conditions and the following disclaimer.
222 Redistributions in binary form must reproduce the above copyright
223 notice, this list of conditions and the following disclaimer in the
224 documentation and/or other materials provided with the distribution.
228 Neither the name of Red Hat nor the names of its contributors may be
229 used to endorse or promote products derived from this software without
230 specific prior written permission.
234 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
235 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
236 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
237 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
238 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
239 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
240 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
241 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
242 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
243 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
244 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF