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

INETD AND XINETD

54       You can run nbdkit from inetd(8) or xinetd(8).  For inetd use:
55
56        nbd stream tcp nowait root /usr/sbin/nbdkit nbdkit -s file /tmp/disk.img
57
58       For xinetd create a file /etc/xinetd.d/nbdkit containing:
59
60        service nbd
61        {
62            socket_type = stream
63            wait = no
64            user = root
65            server = /usr/sbin/nbdkit
66            server_args = -s file /tmp/disk.img
67        }
68

LOGGING

70       Error messages from nbdkit can be sent to standard error
71       (--log=stderr), or to the system log (--log=syslog), or can be
72       discarded completely (--log=null, not recommended for normal use).
73
74       The default, if --log is not specified on the command line, is to send
75       error messages to stderr, unless nbdkit forks into the background in
76       which case they are sent to syslog.
77
78       In detail:
79
80       Messages go to standard error (stderr):
81           When running from the command line in the foreground.
82
83           When using systemd socket activation.
84
85           Using --log=stderr forces all messages to go to standard error.
86
87       Messages go to the system log (syslog):
88           When running from the command line, forked into the background.
89
90           Using --log=syslog forces all messages to go to the system log.
91
92       Debug messages (-v/--verbose) always go to standard error and are never
93       sent to the system log.
94

AF_VSOCK

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

ENVIRONMENT VARIABLES

138       "LISTEN_FDS"
139       "LISTEN_PID"
140           If present in the environment when nbdkit starts up, these trigger
141           "SOCKET ACTIVATION".
142

AUTHORS

150       Eric Blake
151
152       Richard W.M. Jones
153
154       Pino Toscano
155

COPYRIGHT

157       Copyright Red Hat
158

LICENSE

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