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 LOGGING
  54
  55 Error messages from nbdkit can be sent to standard error
  56 (I<--log=stderr>), or to the system log (I<--log=syslog>), or can be
  57 discarded completely (I<--log=null>, not recommended for normal use).
  58
  59 The default, if I<--log> is not specified on the command line, is to
  60 send error messages to stderr, unless nbdkit forks into the background
  61 in which case they are sent to syslog.
  62
  63 In detail:
  64
  65 =over 4
  66
  67 =item Messages go to standard error (stderr):
  68
  69 When running from the command line in the foreground.
  70
  71 When using systemd socket activation.
  72
  73 Using I<--log=stderr> forces all messages to go to standard error.
  74
  75 =item Messages go to the system log (syslog):
  76
  77 When running from the command line, forked into the background.
  78
  79 Using I<--log=syslog> forces all messages to go to the system log.
  80
  81 =back
  82
  83 Debug messages (I<-v>/I<--verbose>) always go to standard error and
  84 are never sent to the system log.
  85
  86 =head1 AF_VSOCK
  87
  88 On Linux nbdkit supports the C<AF_VSOCK> address family / protocol.
  89 This allows you to serve NBD devices into virtual machines without
  90 using a regular network connection.
  91
  92 B<Note> that this is different from the usual case where you present
  93 NBD as a virtual block device to a guest (which the guest sees as
  94 something like a SATA or virtio-scsi disk).  With C<AF_VSOCK> the
  95 virtual machine sees a raw NBD socket which it can connect to by
  96 opening an C<AF_VSOCK> connection.  Only libnbd supports C<AF_VSOCK>
  97 NBD client connections at the time of writing (2019).  For more about
  98 this protocol, see L<https://wiki.qemu.org/Features/VirtioVsock>
  99
 100 =head2 AF_VSOCK example
 101
 102 To set up an C<AF_VSOCK> server, use for example:
 103
 104  nbdkit --vsock [--port PORT] memory 1G
 105
 106 The optional I<-p>/I<--port> argument is used to change the
 107 C<AF_VSOCK> port number.  These port numbers exist in a different
 108 namespace from TCP/IP port numbers.  Also unlike TCP, the port numbers
 109 are 32 bit.  The default port is 10809.
 110
 111 The guest that wishes to access nbdkit must be configured for
 112 virtio-vsock.  On the qemu command line use:
 113
 114  qemu ... -device vhost-vsock-pci,id=vhost-vsock-pci0
 115
 116 For libvirt add this element to the C<<< <devices> >>> section:
 117
 118  <vsock/>
 119
 120 If you see the error C<unable to open vhost-vsock device> then you may
 121 have to unload the VMCI transport on the host:
 122
 123  modprobe -r vmw_vsock_vmci_transport
 124
 125 Once nbdkit and the guest are running, from inside the guest you can
 126 connect to nbdkit on the host using libnbd:
 127
 128  nbdsh -c 'h.connect_vsock(2, 10809)' -c 'print(h.get_size())'
 129
 130 =head1 ENVIRONMENT VARIABLES
 131
 132 =over 4
 133
 134 =item C<LISTEN_FDS>
 135
 136 =item C<LISTEN_PID>
 137
 138 If present in the environment when nbdkit starts up, these trigger
 139 L</SOCKET ACTIVATION>.
 140
 141 =back
 142
 143 =head1 SEE ALSO
 144
 145 L<nbdkit(1)>,
 146 L<systemd(1)>,
 147 L<systemd.socket(5)>,
 148 L<syslog(3)>,
 149 L<rsyslogd(8)>,
 150 L<journalctl(1)>,
 151 L<nbdsh(1)>.
 152
 153 =head1 AUTHORS
 154
 155 Eric Blake
 156
 157 Richard W.M. Jones
 158
 159 Pino Toscano
 160
 161 =head1 COPYRIGHT
 162
 163 Copyright (C) 2013-2018 Red Hat Inc.