=head1 NAME

nbdkit-service - running nbdkit as a service, and systemd socket activation

=head1 DESCRIPTION

Most people start nbdkit from the command line or run it from another
program (see L<nbdkit-captive(1)>.  It is also possible to run nbdkit
as a standalone service, which is what this page describes.

=head1 SOCKET ACTIVATION

nbdkit supports socket activation (sometimes called systemd socket
activation).  This is a simple protocol where instead of nbdkit itself
opening the listening socket(s), the parent process (typically
systemd) passes in pre-opened file descriptors.  Socket activation
lets you serve infrequent NBD requests using a superserver without
needing nbdkit to be running the whole time.

Socket activation is triggered when both the C<LISTEN_FDS> and
C<LISTEN_PID> environment variables are set.  In this mode using
I<-i>, I<-p>, I<--run>, I<-s> or I<-U> flags on the command line is
illegal and will cause an error.  Also in this mode nbdkit does not
fork into the background (ie. I<-f> is implied).

=head2 Using socket activation with systemd

To use nbdkit with socket activation from systemd, create a unit file
ending in C<.socket> (eg. F</etc/systemd/system/nbdkit.socket>)
containing:

 [Unit]
 Description=NBDKit Network Block Device server
 
 [Socket]
 ListenStream=10809
 
 [Install]
 WantedBy=sockets.target

There are various formats for the C<ListenStream> key.  See
L<systemd.socket(5)> for more information.

Also create a service unit (eg. F</etc/systemd/system/nbdkit.service>)
containing:

 [Service]
 ExecStart=/usr/sbin/nbdkit file /path/to/serve

For more information on systemd and socket activation, see
L<http://0pointer.de/blog/projects/socket-activation.html>

=head1 LOGGING

Error messages from nbdkit can be sent to standard error
(I<--log=stderr>), or to the system log (I<--log=syslog>), or can be
discarded completely (I<--log=null>, not recommended for normal use).

The default, if I<--log> is not specified on the command line, is to
send error messages to stderr, unless nbdkit forks into the background
in which case they are sent to syslog.

In detail:

=over 4

=item Messages go to standard error (stderr):

When running from the command line in the foreground.

When using systemd socket activation.

Using I<--log=stderr> forces all messages to go to standard error.

=item Messages go to the system log (syslog):

When running from the command line, forked into the background.

Using I<--log=syslog> forces all messages to go to the system log.

=back

Debug messages (I<-v>/I<--verbose>) always go to standard error and
are never sent to the system log.

=head1 AF_VSOCK

On Linux nbdkit supports the C<AF_VSOCK> address family / protocol.
This allows you to serve NBD devices into virtual machines without
using a regular network connection.

B<Note> that this is different from the usual case where you present
NBD as a virtual block device to a guest (which the guest sees as
something like a SATA or virtio-scsi disk).  With C<AF_VSOCK> the
virtual machine sees a raw NBD socket which it can connect to by
opening an C<AF_VSOCK> connection.  Only libnbd supports C<AF_VSOCK>
NBD client connections at the time of writing (2019).  For more about
this protocol, see L<https://wiki.qemu.org/Features/VirtioVsock>

=head2 AF_VSOCK example

To set up an C<AF_VSOCK> server, use for example:

 nbdkit --vsock [--port PORT] memory 1G

The optional I<-p>/I<--port> argument is used to change the
C<AF_VSOCK> port number.  These port numbers exist in a different
namespace from TCP/IP port numbers.  Also unlike TCP, the port numbers
are 32 bit.  The default port is 10809.

The guest that wishes to access nbdkit must be configured for
virtio-vsock.  On the qemu command line use:

 qemu ... -device vhost-vsock-pci,id=vhost-vsock-pci0

For libvirt add this element to the C<<< <devices> >>> section:

 <vsock/>

If you see the error C<unable to open vhost-vsock device> then you may
have to unload the VMCI transport on the host:

 modprobe -r vmw_vsock_vmci_transport

Once nbdkit and the guest are running, from inside the guest you can
connect to nbdkit on the host using libnbd:

 nbdsh -c 'h.connect_vsock(2, 10809)' -c 'print(h.get_size())'

=head1 ENVIRONMENT VARIABLES

=over 4

=item C<LISTEN_FDS>

=item C<LISTEN_PID>

If present in the environment when nbdkit starts up, these trigger
L</SOCKET ACTIVATION>.

=back

=head1 SEE ALSO

L<nbdkit(1)>,
L<systemd(1)>,
L<systemd.socket(5)>,
L<syslog(3)>,
L<rsyslogd(8)>,
L<journalctl(1)>,
L<nbdsh(1)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

Pino Toscano

=head1 COPYRIGHT

Copyright (C) 2013-2018 Red Hat Inc.
