1nbdkit-service(1)                   NBDKIT                   nbdkit-service(1)
2
3
4

NAME

6       nbdkit-service - running nbdkit as a service, and systemd socket
7       activation
8

DESCRIPTION

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

SOCKET ACTIVATION

15       nbdkit supports socket activation (sometimes called systemd socket
16       activation).  This is a simple protocol where instead of nbdkit itself
17       opening the listening socket(s), the parent process (typically systemd)
18       passes in pre-opened file descriptors.  Socket activation lets you
19       serve infrequent NBD requests using a superserver without needing
20       nbdkit to be running the whole time.
21
22       Socket activation is triggered when both the "LISTEN_FDS" and
23       "LISTEN_PID" environment variables are set.  In this mode using -i, -p,
24       --run, -s or -U flags on the command line is illegal and will cause an
25       error.  Also in this mode nbdkit does not fork into the background (ie.
26       -f is implied).
27
28   Using socket activation with systemd
29       To use nbdkit with socket activation from systemd, create a unit file
30       ending in ".socket" (eg. /etc/systemd/system/nbdkit.socket) 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 "ListenStream" key.  See
42       systemd.socket(5) for more information.
43
44       Also create a service unit (eg. /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       http://0pointer.de/blog/projects/socket-activation.html
52

LOGGING

54       Error messages from nbdkit can be sent to standard error
55       (--log=stderr), or to the system log (--log=syslog), or can be
56       discarded completely (--log=null, not recommended for normal use).
57
58       The default, if --log is not specified on the command line, is to send
59       error messages to stderr, unless nbdkit forks into the background in
60       which case they are sent to syslog.
61
62       In detail:
63
64       Messages go to standard error (stderr):
65           When running from the command line in the foreground.
66
67           When using systemd socket activation.
68
69           Using --log=stderr forces all messages to go to standard error.
70
71       Messages go to the system log (syslog):
72           When running from the command line, forked into the background.
73
74           Using --log=syslog forces all messages to go to the system log.
75
76       Debug messages (-v/--verbose) always go to standard error and are never
77       sent to the system log.
78

AF_VSOCK

80       On Linux nbdkit supports the "AF_VSOCK" address family / protocol.
81       This allows you to serve NBD devices into virtual machines without
82       using a regular network connection.
83
84       Note that this is different from the usual case where you present NBD
85       as a virtual block device to a guest (which the guest sees as something
86       like a SATA or virtio-scsi disk).  With "AF_VSOCK" the virtual machine
87       sees a raw NBD socket which it can connect to by opening an "AF_VSOCK"
88       connection.  Only libnbd supports "AF_VSOCK" NBD client connections at
89       the time of writing (2019).  For more about this protocol, see
90       https://wiki.qemu.org/Features/VirtioVsock
91
92   AF_VSOCK example
93       To set up an "AF_VSOCK" server, use for example:
94
95        nbdkit --vsock [--port PORT] memory 1G
96
97       The optional -p/--port argument is used to change the "AF_VSOCK" port
98       number.  These port numbers exist in a different namespace from TCP/IP
99       port numbers.  Also unlike TCP, the port numbers are 32 bit.  The
100       default port is 10809.
101
102       The guest that wishes to access nbdkit must be configured for virtio-
103       vsock.  On the qemu command line use:
104
105        qemu ... -device vhost-vsock-pci,id=vhost-vsock-pci0
106
107       For libvirt add this element to the "<devices>" section:
108
109        <vsock/>
110
111       If you see the error "unable to open vhost-vsock device" then you may
112       have to unload the VMCI transport on the host:
113
114        modprobe -r vmw_vsock_vmci_transport
115
116       Once nbdkit and the guest are running, from inside the guest you can
117       connect to nbdkit on the host using libnbd:
118
119        nbdsh -c 'h.connect_vsock(2, 10809)' -c 'print(h.get_size())'
120

ENVIRONMENT VARIABLES

122       "LISTEN_FDS"
123       "LISTEN_PID"
124           If present in the environment when nbdkit starts up, these trigger
125           "SOCKET ACTIVATION".
126

SEE ALSO

128       nbdkit(1), systemd(1), systemd.socket(5), syslog(3), rsyslogd(8),
129       journalctl(1), nbdsh(1).
130

AUTHORS

132       Eric Blake
133
134       Richard W.M. Jones
135
136       Pino Toscano
137
139       Copyright (C) 2013-2018 Red Hat Inc.
140

LICENSE

142       Redistribution and use in source and binary forms, with or without
143       modification, are permitted provided that the following conditions are
144       met:
145
146       ·   Redistributions of source code must retain the above copyright
147           notice, this list of conditions and the following disclaimer.
148
149       ·   Redistributions in binary form must reproduce the above copyright
150           notice, this list of conditions and the following disclaimer in the
151           documentation and/or other materials provided with the
152           distribution.
153
154       ·   Neither the name of Red Hat nor the names of its contributors may
155           be used to endorse or promote products derived from this software
156           without specific prior written permission.
157
158       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
159       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
160       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
161       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
162       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
163       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
164       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
165       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
166       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
167       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
168       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
169
170
171
172nbdkit-1.16.1                     2019-12-03                 nbdkit-service(1)
Impressum