docs/nbdkit.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 nbdkit - A toolkit for creating NBD servers
   6
   7 =head1 SYNOPSIS
   8
   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 [...]]]
  12
  13 =head1 DESCRIPTION
  14
  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.
  17
  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
  21 proprietary code.
  22
  23 If you want to write an nbdkit plugin, you should read
  24 L<nbdkit-plugin(3)>.
  25
  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>.
  29
  30 =head1 EXAMPLES
  31
  32 Serve file C<disk.img> on port 10809:
  33
  34  nbdkit .../plugins/libnbdkit-file.so file=disk.img
  35
  36 Run the example1 plugin and connect to it using L<guestfish(1)>:
  37
  38  nbdkit .../plugins/libnbdkit-example1.so
  39  guestfish --ro -a nbd://localhost
  40
  41 Run the example3 plugin and connect to it using L<guestfish(1)>:
  42
  43  nbdkit .../plugins/libnbdkit-example3.so size=1G
  44  guestfish --ro -a nbd://localhost
  45
  46 To display usage information about a specific plugin:
  47
  48  nbdkit --help .../plugins/libnbdkit-example1.so
  49
  50 =head1 GLOBAL OPTIONS
  51
  52 =over 4
  53
  54 =item B<--help>
  55
  56 Display brief command line usage information and exit.
  57
  58 =item B<-f>
  59
  60 =item B<--foreground>
  61
  62 =item B<--no-fork>
  63
  64 I<Don't> fork into the background.
  65
  66 =item B<-g> GROUP
  67
  68 =item B<--group> GROUP
  69
  70 Change group to C<GROUP> after starting up.  A group name or numeric
  71 group ID can be used.
  72
  73 The server needs sufficient permissions to be able to do this.
  74 Normally this would mean starting the server up as root.
  75
  76 See also I<-u>.
  77
  78 =item B<-i> IPADDR
  79
  80 =item B<--ip-addr> IPADDR
  81
  82 =item B<--ipaddr> IPADDR
  83
  84 Listen on the specified interface.  The default is to listen on all
  85 interfaces.  See also I<-p>.
  86
  87 =item B<-P> PIDFILE
  88
  89 =item B<--pid-file> PIDFILE
  90
  91 =item B<--pidfile> PIDFILE
  92
  93 Write C<PIDFILE> (containing the process ID of the server) after
  94 nbdkit becomes ready to accept connections.
  95
  96 If the file already exists, it is overwritten.  nbdkit I<does not>
  97 delete the file when it exits.
  98
  99 =item B<-p> PORT
 100
 101 =item B<--port> PORT
 102
 103 Change the TCP/IP port number on which nbdkit serves requests.
 104 The default is C<10809>.  See also I<-i>.
 105
 106 =item B<-r>
 107
 108 =item B<--read-only>
 109
 110 =item B<--readonly>
 111
 112 The export will be read-only.  If a client writes, then it will get an
 113 error.
 114
 115 Note that some plugins inherently don't support writes.  With those
 116 plugins the I<-r> option is added implicitly.
 117
 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.
 121
 122 =item B<-s>
 123
 124 =item B<--single>
 125
 126 =item B<--stdin>
 127
 128 Don't fork.  Handle a single NBD connection on stdin/stdout.  After
 129 stdin closes, the server exits.
 130
 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.
 134
 135 This option implies I<--foreground>.
 136
 137 =item B<-U> SOCKET
 138
 139 =item B<--unix> SOCKET
 140
 141 Accept connections on the Unix domain socket C<SOCKET> (which is a
 142 path).
 143
 144 nbdkit neither creates nor deletes this socket.  You should create the
 145 socket and set the desired permissions and ownership before running
 146 the server.
 147
 148 =item B<-u> USER
 149
 150 =item B<--user> USER
 151
 152 Change user to C<USER> after starting up.  A user name or numeric user
 153 ID can be used.
 154
 155 The server needs sufficient permissions to be able to do this.
 156 Normally this would mean starting the server up as root.
 157
 158 See also I<-g>.
 159
 160 =item B<-v>
 161
 162 =item B<--verbose>
 163
 164 Enable verbose messages.
 165
 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).
 168
 169 =item B<-V>
 170
 171 =item B<--version>
 172
 173 Print the version number of nbdkit and exit.
 174
 175 =back
 176
 177 =head1 PLUGIN CONFIGURATION
 178
 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:
 182
 183  nbdkit .../plugins/libnbdkit-file.so file=disk.img
 184
 185 To list all the options supported by a plugin, do:
 186
 187  nbdkit --help .../plugins/libnbdkit-file.so
 188
 189 =head1 SEE ALSO
 190
 191 L<nbdkit-plugin(3)>,
 192 L<libnbdkit-example1(1)>,
 193 L<libnbdkit-example2(1)>,
 194 L<libnbdkit-example3(1)>,
 195 L<libnbdkit-file(1)>,
 196 L<libnbdkit-libvirt-plugin(1)>.
 197
 198 =head1 AUTHORS
 199
 200 Richard W.M. Jones
 201
 202 =head1 COPYRIGHT
 203
 204 Copyright (C) 2013 Red Hat Inc.
 205
 206 =head1 LICENSE
 207
 208 Redistribution and use in source and binary forms, with or without
 209 modification, are permitted provided that the following conditions are
 210 met:
 211
 212 =over 4
 213
 214 =item *
 215
 216 Redistributions of source code must retain the above copyright
 217 notice, this list of conditions and the following disclaimer.
 218
 219 =item *
 220
 221 Redistributions in binary form must reproduce the above copyright
 222 notice, this list of conditions and the following disclaimer in the
 223 documentation and/or other materials provided with the distribution.
 224
 225 =item *
 226
 227 Neither the name of Red Hat nor the names of its contributors may be
 228 used to endorse or promote products derived from this software without
 229 specific prior written permission.
 230
 231 =back
 232
 233 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
 234 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 235 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 236 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
 237 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 238 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 239 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 240 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 241 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 242 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 243 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 244 SUCH DAMAGE.