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/nbdkit-file-plugin.so file=disk.img
  35
  36 Run the example1 plugin and connect to it using L<guestfish(1)>:
  37
  38  nbdkit .../plugins/nbdkit-example1-plugin.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/nbdkit-example3-plugin.so size=1G
  44  guestfish --ro -a nbd://localhost
  45
  46 To display usage information about a specific plugin:
  47
  48  nbdkit --help .../plugins/nbdkit-example1-plugin.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 creates this socket, but it will probably have incorrect
 145 permissions (too permissive).  If it is a problem that some
 146 unauthorized user could connect to this socket between the time that
 147 nbdkit starts up and the authorized user connects, then put the socket
 148 into a directory that has restrictive permissions.
 149
 150 nbdkit does B<not> delete the socket file when it exits.  The caller
 151 should delete the socket file after use (else if you try to start
 152 nbdkit up again you will get an C<Address already in use> error).
 153
 154 =item B<-u> USER
 155
 156 =item B<--user> USER
 157
 158 Change user to C<USER> after starting up.  A user name or numeric user
 159 ID can be used.
 160
 161 The server needs sufficient permissions to be able to do this.
 162 Normally this would mean starting the server up as root.
 163
 164 See also I<-g>.
 165
 166 =item B<-v>
 167
 168 =item B<--verbose>
 169
 170 Enable verbose messages.
 171
 172 It's a good idea to use I<-f> as well so the process does not fork
 173 into the background (but not required).
 174
 175 =item B<-V>
 176
 177 =item B<--version>
 178
 179 Print the version number of nbdkit and exit.
 180
 181 =back
 182
 183 =head1 PLUGIN CONFIGURATION
 184
 185 After specifying the plugin name you can (optionally, it depends
 186 on the plugin) give plugin configuration on the command line in
 187 the form of C<key=value>.  For example:
 188
 189  nbdkit .../plugins/nbdkit-file-plugin.so file=disk.img
 190
 191 To list all the options supported by a plugin, do:
 192
 193  nbdkit --help .../plugins/nbdkit-file-plugin.so
 194
 195 =head1 SEE ALSO
 196
 197 L<nbdkit-plugin(3)>,
 198 L<nbdkit-example1-plugin(1)>,
 199 L<nbdkit-example2-plugin(1)>,
 200 L<nbdkit-example3-plugin(1)>,
 201 L<nbdkit-file-plugin(1)>,
 202 L<nbdkit-gzip-plugin(1)>,
 203 L<nbdkit-libvirt-plugin(1)>,
 204 L<nbdkit-vddk-plugin(1)>.
 205 L<nbdkit-xz-plugin(1)>.
 206
 207 =head1 AUTHORS
 208
 209 Richard W.M. Jones
 210
 211 =head1 COPYRIGHT
 212
 213 Copyright (C) 2013 Red Hat Inc.
 214
 215 =head1 LICENSE
 216
 217 Redistribution and use in source and binary forms, with or without
 218 modification, are permitted provided that the following conditions are
 219 met:
 220
 221 =over 4
 222
 223 =item *
 224
 225 Redistributions of source code must retain the above copyright
 226 notice, this list of conditions and the following disclaimer.
 227
 228 =item *
 229
 230 Redistributions in binary form must reproduce the above copyright
 231 notice, this list of conditions and the following disclaimer in the
 232 documentation and/or other materials provided with the distribution.
 233
 234 =item *
 235
 236 Neither the name of Red Hat nor the names of its contributors may be
 237 used to endorse or promote products derived from this software without
 238 specific prior written permission.
 239
 240 =back
 241
 242 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
 243 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 244 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 245 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
 246 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 247 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 248 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 249 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 250 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 251 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 252 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 253 SUCH DAMAGE.