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 [--dump-config] [-f] [-g GROUP] [-i IPADDR]
  10         [-P PIDFILE] [-p PORT] [-r] [-s]
  11         [-U SOCKET] [-u USER] [-v] [-V]
  12         PLUGIN [key=value [key=value [...]]]
  13
  14 =head1 DESCRIPTION
  15
  16 C<nbdkit> is both a toolkit for creating Network Block Device (NBD)
  17 servers from "unconventional" sources and the name of an NBD server.
  18
  19 To create a new block device source, all you have to do is write a few
  20 glue functions.  The liberal licensing of nbdkit is meant to allow you
  21 to link nbdkit with proprietary libraries or include nbdkit in
  22 proprietary code.
  23
  24 If you want to write an nbdkit plugin, you should read
  25 L<nbdkit-plugin(3)>.
  26
  27 Several plugins may be found in C<$libdir/nbdkit/plugins>.  You can
  28 give the full path to the plugin, like this:
  29
  30  nbdkit $libdir/nbdkit/plugins/nbdkit-file-plugin.so [...]
  31
  32 but it is usually more convenient to use this equivalent syntax:
  33
  34  nbdkit file [...]
  35
  36 C<$libdir> is set at compile time.  To print it out, do:
  37
  38  nbdkit --dump-config
  39
  40 =head1 EXAMPLES
  41
  42 Serve file C<disk.img> on port 10809:
  43
  44  nbdkit file file=disk.img
  45
  46 Run the example1 plugin and connect to it using L<guestfish(1)>:
  47
  48  nbdkit example1
  49  guestfish --ro -a nbd://localhost
  50
  51 Run the example3 plugin and connect to it using L<guestfish(1)>:
  52
  53  nbdkit example3 size=1G
  54  guestfish --ro -a nbd://localhost
  55
  56 To display usage information about a specific plugin:
  57
  58  nbdkit --help example1
  59
  60 =head1 GLOBAL OPTIONS
  61
  62 =over 4
  63
  64 =item B<--help>
  65
  66 Display brief command line usage information and exit.
  67
  68 =item B<--dump-config>
  69
  70 Dump out the compile-time configuration values and exit.
  71
  72 =item B<-f>
  73
  74 =item B<--foreground>
  75
  76 =item B<--no-fork>
  77
  78 I<Don't> fork into the background.
  79
  80 =item B<-g> GROUP
  81
  82 =item B<--group> GROUP
  83
  84 Change group to C<GROUP> after starting up.  A group name or numeric
  85 group ID can be used.
  86
  87 The server needs sufficient permissions to be able to do this.
  88 Normally this would mean starting the server up as root.
  89
  90 See also I<-u>.
  91
  92 =item B<-i> IPADDR
  93
  94 =item B<--ip-addr> IPADDR
  95
  96 =item B<--ipaddr> IPADDR
  97
  98 Listen on the specified interface.  The default is to listen on all
  99 interfaces.  See also I<-p>.
 100
 101 =item B<-P> PIDFILE
 102
 103 =item B<--pid-file> PIDFILE
 104
 105 =item B<--pidfile> PIDFILE
 106
 107 Write C<PIDFILE> (containing the process ID of the server) after
 108 nbdkit becomes ready to accept connections.
 109
 110 If the file already exists, it is overwritten.  nbdkit I<does not>
 111 delete the file when it exits.
 112
 113 =item B<-p> PORT
 114
 115 =item B<--port> PORT
 116
 117 Change the TCP/IP port number on which nbdkit serves requests.
 118 The default is C<10809>.  See also I<-i>.
 119
 120 =item B<-r>
 121
 122 =item B<--read-only>
 123
 124 =item B<--readonly>
 125
 126 The export will be read-only.  If a client writes, then it will get an
 127 error.
 128
 129 Note that some plugins inherently don't support writes.  With those
 130 plugins the I<-r> option is added implicitly.
 131
 132 Copy-on-write (or "snapshot") functionality is not supported by this
 133 server.  However if you are using qemu as a client (or indirectly via
 134 libguestfs) then it supports snapshots.
 135
 136 =item B<-s>
 137
 138 =item B<--single>
 139
 140 =item B<--stdin>
 141
 142 Don't fork.  Handle a single NBD connection on stdin/stdout.  After
 143 stdin closes, the server exits.
 144
 145 You can use this option to run nbdkit from inetd, systemd or similar
 146 superservers; or just for testing; or if you want to run nbdkit in a
 147 non-conventional way.
 148
 149 This option implies I<--foreground>.
 150
 151 =item B<-U> SOCKET
 152
 153 =item B<--unix> SOCKET
 154
 155 Accept connections on the Unix domain socket C<SOCKET> (which is a
 156 path).
 157
 158 nbdkit creates this socket, but it will probably have incorrect
 159 permissions (too permissive).  If it is a problem that some
 160 unauthorized user could connect to this socket between the time that
 161 nbdkit starts up and the authorized user connects, then put the socket
 162 into a directory that has restrictive permissions.
 163
 164 nbdkit does B<not> delete the socket file when it exits.  The caller
 165 should delete the socket file after use (else if you try to start
 166 nbdkit up again you will get an C<Address already in use> error).
 167
 168 =item B<-u> USER
 169
 170 =item B<--user> USER
 171
 172 Change user to C<USER> after starting up.  A user name or numeric user
 173 ID can be used.
 174
 175 The server needs sufficient permissions to be able to do this.
 176 Normally this would mean starting the server up as root.
 177
 178 See also I<-g>.
 179
 180 =item B<-v>
 181
 182 =item B<--verbose>
 183
 184 Enable verbose messages.
 185
 186 It's a good idea to use I<-f> as well so the process does not fork
 187 into the background (but not required).
 188
 189 =item B<-V>
 190
 191 =item B<--version>
 192
 193 Print the version number of nbdkit and exit.
 194
 195 =back
 196
 197 =head1 PLUGIN CONFIGURATION
 198
 199 After specifying the plugin name you can (optionally, it depends
 200 on the plugin) give plugin configuration on the command line in
 201 the form of C<key=value>.  For example:
 202
 203  nbdkit file file=disk.img
 204
 205 To list all the options supported by a plugin, do:
 206
 207  nbdkit --help file
 208
 209 =head1 SEE ALSO
 210
 211 L<nbdkit-plugin(3)>,
 212 L<nbdkit-example1-plugin(1)>,
 213 L<nbdkit-example2-plugin(1)>,
 214 L<nbdkit-example3-plugin(1)>,
 215 L<nbdkit-file-plugin(1)>,
 216 L<nbdkit-gzip-plugin(1)>,
 217 L<nbdkit-libvirt-plugin(1)>,
 218 L<nbdkit-perl-plugin(3)>,
 219 L<nbdkit-python-plugin(3)>,
 220 L<nbdkit-vddk-plugin(1)>.
 221 L<nbdkit-xz-plugin(1)>.
 222
 223 =head1 AUTHORS
 224
 225 Richard W.M. Jones
 226
 227 =head1 COPYRIGHT
 228
 229 Copyright (C) 2013 Red Hat Inc.
 230
 231 =head1 LICENSE
 232
 233 Redistribution and use in source and binary forms, with or without
 234 modification, are permitted provided that the following conditions are
 235 met:
 236
 237 =over 4
 238
 239 =item *
 240
 241 Redistributions of source code must retain the above copyright
 242 notice, this list of conditions and the following disclaimer.
 243
 244 =item *
 245
 246 Redistributions in binary form must reproduce the above copyright
 247 notice, this list of conditions and the following disclaimer in the
 248 documentation and/or other materials provided with the distribution.
 249
 250 =item *
 251
 252 Neither the name of Red Hat nor the names of its contributors may be
 253 used to endorse or promote products derived from this software without
 254 specific prior written permission.
 255
 256 =back
 257
 258 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
 259 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 260 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 261 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
 262 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 263 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 264 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 265 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 266 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 267 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 268 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 269 SUCH DAMAGE.