nbdkit-service1

Overview

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

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 or libnbd) passes in pre-opened file descriptors.

One use for socket activation is to serve infrequent NBD requests using a superserver without needing nbdkit to be running the whole time. Another use is to run nbdkit from a controlling libnbd process.

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

 [Unit]
 Description=NBDKit Network Block Device server
 [Socket]
 ListenStream=10809
 # Optional settings to detect dead clients:
 #KeepAlive=true
 #KeepAliveTimeSec=60
 #KeepAliveIntervalSec=10
 #KeepAliveProbes=5
 [Install]
 WantedBy=sockets.target

 [Service]
 ExecStart=/usr/sbin/nbdkit file /path/to/serve
 # Optional settings to run as non-root:
 #User=nbd
 #Group=nbd

 struct nbd_handle *nbd = nbd_create ();
 if (nbd == NULL) {
   fprintf (stderr, "%s\n", nbd_get_error ());
   exit (EXIT_FAILURE);
 }
 char *argv[] = {
   "nbdkit", "--exit-with-parent", "memory", "1G", NULL
 };
 if (nbd_connect_systemd_socket_activation (nbd,
                                            args) == -1) {
   fprintf (stderr, "%s\n", nbd_get_error ());
   exit (EXIT_FAILURE);
 }

Inetd and xinetd

You can run nbdkit from inetd(8) or xinetd(8). For inetd use:

 nbd stream tcp nowait root /usr/sbin/nbdkit nbdkit -s file /tmp/disk.img

For xinetd create a file /etc/xinetd.d/nbdkit containing:

 service nbd
 {
     socket_type = stream
     wait = no
     user = root
     server = /usr/sbin/nbdkit
     server_args = -s file /tmp/disk.img
 }

Af_vsock

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

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 "AF_VSOCK" the virtual machine sees a raw NBD socket which it can connect to by opening an "AF_VSOCK" connection. For more about this protocol, see https://wiki.qemu.org/Features/VirtioVsock

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

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

 <vsock/>

 modprobe -r vmw_vsock_vmci_transport

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

Environment

"LISTEN_FDS"

"LISTEN_PID"

If present in the environment when nbdkit starts up, these trigger "SOCKET ACTIVATION".