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/libnbdkit-file.so file=disk.img
36 Run the example1 plugin and connect to it using L<guestfish(1)>:
38 nbdkit .../plugins/libnbdkit-example1.so
39 guestfish --ro -a nbd://localhost
41 To display usage information about a specific plugin:
43 nbdkit --help .../plugins/libnbdkit-example1.so
51 Display brief command line usage information and exit.
59 I<Don't> fork into the background.
63 =item B<--group> GROUP
65 Change group to C<GROUP> after starting up. A group name or numeric
68 The server needs sufficient permissions to be able to do this.
69 Normally this would mean starting the server up as root.
75 =item B<--ip-addr> IPADDR
77 =item B<--ipaddr> IPADDR
79 Listen on the specified interface. The default is to listen on all
80 interfaces. See also I<-p>.
84 =item B<--pid-file> PIDFILE
86 =item B<--pidfile> PIDFILE
88 Write C<PIDFILE> (containing the process ID of the server) after
89 nbdkit becomes ready to accept connections.
91 If the file already exists, it is overwritten. nbdkit I<does not>
92 delete the file when it exits.
98 Change the TCP/IP port number on which nbdkit serves requests.
99 The default is C<10809>. See also I<-i>.
107 The export will be read-only. If a client writes, then it will get an
110 Note that some plugins inherently don't support writes. With those
111 plugins the I<-r> option is added implicitly.
113 Copy-on-write (or "snapshot") functionality is not supported by this
114 server. However if you are using qemu as a client (or indirectly via
115 libguestfs) then it supports snapshots.
123 Don't fork. Handle a single NBD connection on stdin/stdout. After
124 stdin closes, the server exits.
126 You can use this option to run nbdkit from inetd, systemd or similar
127 superservers; or just for testing; or if you want to run nbdkit in a
128 non-conventional way.
130 This option implies I<--foreground>.
134 =item B<--unix> SOCKET
136 Accept connections on the Unix domain socket C<SOCKET> (which is a
139 nbdkit neither creates nor deletes this socket. You should create the
140 socket and set the desired permissions and ownership before running
147 Change user to C<USER> after starting up. A user name or numeric user
150 The server needs sufficient permissions to be able to do this.
151 Normally this would mean starting the server up as root.
159 Enable verbose messages.
161 It's a good idea to use I<-f> as well so the process does not fork
162 into the background (but not required).
168 Print the version number of nbdkit and exit.
172 =head1 PLUGIN CONFIGURATION
174 After specifying the plugin name you can (optionally, it depends
175 on the plugin) give plugin configuration on the command line in
176 the form of C<key=value>. For example:
178 nbdkit .../plugins/libnbdkit-file.so file=disk.img
180 To list all the options supported by a plugin, do:
182 nbdkit --help .../plugins/libnbdkit-file.so
194 Copyright (C) 2013 Red Hat Inc.
198 Redistribution and use in source and binary forms, with or without
199 modification, are permitted provided that the following conditions are
206 Redistributions of source code must retain the above copyright
207 notice, this list of conditions and the following disclaimer.
211 Redistributions in binary form must reproduce the above copyright
212 notice, this list of conditions and the following disclaimer in the
213 documentation and/or other materials provided with the distribution.
217 Neither the name of Red Hat nor the names of its contributors may be
218 used to endorse or promote products derived from this software without
219 specific prior written permission.
223 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
224 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
225 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
226 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
227 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
228 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
229 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
230 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
231 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
232 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
233 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF