nbdkit-service(1)

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

AUTHORS

134       Eric Blake
135
136       Richard W.M. Jones
137
138       Pino Toscano
139

COPYRIGHT

141       Copyright (C) 2013-2020 Red Hat Inc.
142

LICENSE

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