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 To display usage information about a specific plugin:
  42
  43  nbdkit --help .../plugins/libnbdkit-example1.so
  44
  45 =head1 GLOBAL OPTIONS
  46
  47 =over 4
  48
  49 =item B<--help>
  50
  51 Display brief command line usage information and exit.
  52
  53 =item B<-f>
  54
  55 =item B<--foreground>
  56
  57 =item B<--no-fork>
  58
  59 I<Don't> fork into the background.
  60
  61 =item B<-g> GROUP
  62
  63 =item B<--group> GROUP
  64
  65 Change group to C<GROUP> after starting up.  A group name or numeric
  66 group ID can be used.
  67
  68 The server needs sufficient permissions to be able to do this.
  69 Normally this would mean starting the server up as root.
  70
  71 See also I<-u>.
  72
  73 =item B<-i> IPADDR
  74
  75 =item B<--ip-addr> IPADDR
  76
  77 =item B<--ipaddr> IPADDR
  78
  79 Listen on the specified interface.  The default is to listen on all
  80 interfaces.  See also I<-p>.
  81
  82 =item B<-P> PIDFILE
  83
  84 =item B<--pid-file> PIDFILE
  85
  86 =item B<--pidfile> PIDFILE
  87
  88 Write C<PIDFILE> (containing the process ID of the server) after
  89 nbdkit becomes ready to accept connections.
  90
  91 If the file already exists, it is overwritten.  nbdkit I<does not>
  92 delete the file when it exits.
  93
  94 =item B<-p> PORT
  95
  96 =item B<--port> PORT
  97
  98 Change the TCP/IP port number on which nbdkit serves requests.
  99 The default is C<10809>.  See also I<-i>.
 100
 101 =item B<-r>
 102
 103 =item B<--read-only>
 104
 105 =item B<--readonly>
 106
 107 The export will be read-only.  If a client writes, then it will get an
 108 error.
 109
 110 Note that some plugins inherently don't support writes.  With those
 111 plugins the I<-r> option is added implicitly.
 112
 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.
 116
 117 =item B<-s>
 118
 119 =item B<--single>
 120
 121 =item B<--stdin>
 122
 123 Don't fork.  Handle a single NBD connection on stdin/stdout.  After
 124 stdin closes, the server exits.
 125
 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.
 129
 130 This option implies I<--foreground>.
 131
 132 =item B<-U> SOCKET
 133
 134 =item B<--unix> SOCKET
 135
 136 Accept connections on the Unix domain socket C<SOCKET> (which is a
 137 path).
 138
 139 nbdkit neither creates nor deletes this socket.  You should create the
 140 socket and set the desired permissions and ownership before running
 141 the server.
 142
 143 =item B<-u> USER
 144
 145 =item B<--user> USER
 146
 147 Change user to C<USER> after starting up.  A user name or numeric user
 148 ID can be used.
 149
 150 The server needs sufficient permissions to be able to do this.
 151 Normally this would mean starting the server up as root.
 152
 153 See also I<-g>.
 154
 155 =item B<-v>
 156
 157 =item B<--verbose>
 158
 159 Enable verbose messages.
 160
 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).
 163
 164 =item B<-V>
 165
 166 =item B<--version>
 167
 168 Print the version number of nbdkit and exit.
 169
 170 =back
 171
 172 =head1 PLUGIN CONFIGURATION
 173
 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:
 177
 178  nbdkit .../plugins/libnbdkit-file.so file=disk.img
 179
 180 To list all the options supported by a plugin, do:
 181
 182  nbdkit --help .../plugins/libnbdkit-file.so
 183
 184 =head1 SEE ALSO
 185
 186 L<nbdkit-plugin(3)>
 187
 188 =head1 AUTHORS
 189
 190 Richard W.M. Jones
 191
 192 =head1 COPYRIGHT
 193
 194 Copyright (C) 2013 Red Hat Inc.
 195
 196 =head1 LICENSE
 197
 198 Redistribution and use in source and binary forms, with or without
 199 modification, are permitted provided that the following conditions are
 200 met:
 201
 202 =over 4
 203
 204 =item *
 205
 206 Redistributions of source code must retain the above copyright
 207 notice, this list of conditions and the following disclaimer.
 208
 209 =item *
 210
 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.
 214
 215 =item *
 216
 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.
 220
 221 =back
 222
 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
 234 SUCH DAMAGE.