docs/nbdkit-service.pod

   1 =head1 NAME
   2
   3 nbdkit-service - running nbdkit as a service, and systemd socket activation
   4
   5 =head1 DESCRIPTION
   6
   7 Most people start nbdkit from the command line or run it from another
   8 program (see L<nbdkit-captive(1)>.  It is also possible to run nbdkit
   9 as a standalone service, which is what this page describes.
  10
  11 =head1 SOCKET ACTIVATION
  12
  13 nbdkit supports socket activation (sometimes called systemd socket
  14 activation).  This is a simple protocol where instead of nbdkit itself
  15 opening the listening socket(s), the parent process (typically
  16 systemd) passes in pre-opened file descriptors.  Socket activation
  17 lets you serve infrequent NBD requests using a superserver without
  18 needing nbdkit to be running the whole time.
  19
  20 Socket activation is triggered when both the C<LISTEN_FDS> and
  21 C<LISTEN_PID> environment variables are set.  In this mode using
  22 I<-i>, I<-p>, I<--run>, I<-s> or I<-U> flags on the command line is
  23 illegal and will cause an error.  Also in this mode nbdkit does not
  24 fork into the background (ie. I<-f> is implied).
  25
  26 =head2 Using socket activation with systemd
  27
  28 To use nbdkit with socket activation from systemd, create a unit file
  29 ending in C<.socket> (eg. F</etc/systemd/system/nbdkit.socket>)
  30 containing:
  31
  32  [Unit]
  33  Description=NBDKit Network Block Device server
  34
  35  [Socket]
  36  ListenStream=10809
  37
  38  [Install]
  39  WantedBy=sockets.target
  40
  41 There are various formats for the C<ListenStream> key.  See
  42 L<systemd.socket(5)> for more information.
  43
  44 Also create a service unit (eg. F</etc/systemd/system/nbdkit.service>)
  45 containing:
  46
  47  [Service]
  48  ExecStart=/usr/sbin/nbdkit file /path/to/serve
  49
  50 For more information on systemd and socket activation, see
  51 L<http://0pointer.de/blog/projects/socket-activation.html>
  52
  53 =head1 INETD AND XINETD
  54
  55 You can run nbdkit from L<inetd(8)> or L<xinetd(8)>.  For inetd use:
  56
  57  nbd stream tcp nowait root /usr/sbin/nbdkit nbdkit -s file /tmp/disk.img
  58
  59 For xinetd create a file F</etc/xinetd.d/nbdkit> containing:
  60
  61  service nbd
  62  {
  63      socket_type = stream
  64      wait = no
  65      user = root
  66      server = /usr/sbin/nbdkit
  67      server_args = -s file /tmp/disk.img
  68  }
  69
  70 =head1 LOGGING
  71
  72 Error messages from nbdkit can be sent to standard error
  73 (I<--log=stderr>), or to the system log (I<--log=syslog>), or can be
  74 discarded completely (I<--log=null>, not recommended for normal use).
  75
  76 The default, if I<--log> is not specified on the command line, is to
  77 send error messages to stderr, unless nbdkit forks into the background
  78 in which case they are sent to syslog.
  79
  80 In detail:
  81
  82 =over 4
  83
  84 =item Messages go to standard error (stderr):
  85
  86 When running from the command line in the foreground.
  87
  88 When using systemd socket activation.
  89
  90 Using I<--log=stderr> forces all messages to go to standard error.
  91
  92 =item Messages go to the system log (syslog):
  93
  94 When running from the command line, forked into the background.
  95
  96 Using I<--log=syslog> forces all messages to go to the system log.
  97
  98 =back
  99
 100 Debug messages (I<-v>/I<--verbose>) always go to standard error and
 101 are never sent to the system log.
 102
 103 =head1 AF_VSOCK
 104
 105 On Linux nbdkit supports the C<AF_VSOCK> address family / protocol.
 106 This allows you to serve NBD devices into virtual machines without
 107 using a regular network connection.
 108
 109 B<Note> that this is different from the usual case where you present
 110 NBD as a virtual block device to a guest (which the guest sees as
 111 something like a SATA or virtio-scsi disk).  With C<AF_VSOCK> the
 112 virtual machine sees a raw NBD socket which it can connect to by
 113 opening an C<AF_VSOCK> connection.  Only libnbd supports C<AF_VSOCK>
 114 NBD client connections at the time of writing (2019).  For more about
 115 this protocol, see L<https://wiki.qemu.org/Features/VirtioVsock>
 116
 117 =head2 AF_VSOCK example
 118
 119 To set up an C<AF_VSOCK> server, use for example:
 120
 121  nbdkit --vsock [--port PORT] memory 1G
 122
 123 The optional I<-p>/I<--port> argument is used to change the
 124 C<AF_VSOCK> port number.  These port numbers exist in a different
 125 namespace from TCP/IP port numbers.  Also unlike TCP, the port numbers
 126 are 32 bit.  The default port is 10809.
 127
 128 The guest that wishes to access nbdkit must be configured for
 129 virtio-vsock.  On the qemu command line use:
 130
 131  qemu ... -device vhost-vsock-pci,id=vhost-vsock-pci0
 132
 133 For libvirt add this element to the C<<< <devices> >>> section:
 134
 135  <vsock/>
 136
 137 If you see the error C<unable to open vhost-vsock device> then you may
 138 have to unload the VMCI transport on the host:
 139
 140  modprobe -r vmw_vsock_vmci_transport
 141
 142 Once nbdkit and the guest are running, from inside the guest you can
 143 connect to nbdkit on the host using libnbd:
 144
 145  nbdsh -c 'h.connect_vsock(2, 10809)' -c 'print(h.get_size())'
 146
 147 =head1 ENVIRONMENT VARIABLES
 148
 149 =over 4
 150
 151 =item C<LISTEN_FDS>
 152
 153 =item C<LISTEN_PID>
 154
 155 If present in the environment when nbdkit starts up, these trigger
 156 L</SOCKET ACTIVATION>.
 157
 158 =back
 159
 160 =head1 SEE ALSO
 161
 162 L<nbdkit(1)>,
 163 L<nbdkit-client(1)>,
 164 L<nbdkit-exitlast-filter(1)>,
 165 L<nbdkit-exitwhen-filter(1)>,
 166 L<nbdkit-ip-filter(1)>,
 167 L<nbdkit-limit-filter(1)>,
 168 L<systemd(1)>,
 169 L<systemd.socket(5)>,
 170 L<inetd(8)>,
 171 L<xinetd(8)>,
 172 L<syslog(3)>,
 173 L<rsyslogd(8)>,
 174 L<journalctl(1)>,
 175 L<nbdsh(1)>.
 176
 177 =head1 AUTHORS
 178
 179 Eric Blake
 180
 181 Richard W.M. Jones
 182
 183 Pino Toscano
 184
 185 =head1 COPYRIGHT
 186
 187 Copyright Red Hat