1nbdkit-service(1) NBDKIT nbdkit-service(1)
2
6 nbdkit-service - running nbdkit as a service, and systemd socket
7 activation
8
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
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 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 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 [Unit]
33 Description=NBDKit Network Block Device server
34 [Socket]
36 ListenStream=10809
37 [Install]
39 WantedBy=sockets.target
40 There are various formats for the "ListenStream" key. See
42 systemd.socket(5) for more information.
43 Also create a service unit (eg. /etc/systemd/system/nbdkit.service)
45 containing:
46 [Service]
48 ExecStart=/usr/sbin/nbdkit file /path/to/serve
49 For more information on systemd and socket activation, see
51 http://0pointer.de/blog/projects/socket-activation.html
52
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 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 In detail:
63 Messages go to standard error (stderr):
65 When running from the command line in the foreground.
66 When using systemd socket activation.
68 Using --log=stderr forces all messages to go to standard error.
70 Messages go to the system log (syslog):
72 When running from the command line, forked into the background.
73 Using --log=syslog forces all messages to go to the system log.
75 Debug messages (-v/--verbose) always go to standard error and are never
77 sent to the system log.
78
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 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 AF_VSOCK example
93 To set up an "AF_VSOCK" server, use for example:
94 nbdkit --vsock [--port PORT] memory 1G
96 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 The guest that wishes to access nbdkit must be configured for virtio-
103 vsock. On the qemu command line use:
104 qemu ... -device vhost-vsock-pci,id=vhost-vsock-pci0
106 For libvirt add this element to the "<devices>" section:
108 <vsock/>
110 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 modprobe -r vmw_vsock_vmci_transport
115 Once nbdkit and the guest are running, from inside the guest you can
117 connect to nbdkit on the host using libnbd:
118 nbdsh -c 'h.connect_vsock(2, 10809)' -c 'print(h.get_size())'
120
122 "LISTEN_FDS"
123 "LISTEN_PID"
124 If present in the environment when nbdkit starts up, these trigger
125 "SOCKET ACTIVATION".
126
128 nbdkit(1), nbdkit-ip-filter(1), systemd(1), systemd.socket(5),
129 syslog(3), rsyslogd(8), journalctl(1), nbdsh(1).
130
132 Eric Blake
133 Richard W.M. Jones
135 Pino Toscano
137
139 Copyright (C) 2013-2018 Red Hat Inc.
140
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 · Redistributions of source code must retain the above copyright
147 notice, this list of conditions and the following disclaimer.
148 · 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 · 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 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.
169nbdkit-1.18.4 2020-04-16 nbdkit-service(1)