Libguestfs - Jan 2017 - [PATCH nbdkit] Add support for socket activation.

Socket activation (aka systemd socket activation) is a simple protocol
that lets you pass in an opened, listening socket to a server.
Supporting socket activation allows you to use a modern superserver to
serve infrequent NBD requests without needing nbdkit to be running the
whole time.

Although the protocol was invented by systemd, it has been implemented
in a few other places, and the protocol is almost trivially simple.
This implementation is based on the one in libvirt.

Thanks: Dan Berrange, libvirt team
---
 .gitignore                     |   1 +
 docs/nbdkit.pod                |  67 +++++++++++-
 src/main.c                     | 111 ++++++++++++++++++++
 tests/Makefile.am              |  10 +-
 tests/test-socket-activation.c | 226 +++++++++++++++++++++++++++++++++++++++++
 5 files changed, 411 insertions(+), 4 deletions(-)
 create mode 100644 tests/test-socket-activation.c

diff --git a/.gitignore b/.gitignore
index 4a51dea..f8918a7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -50,6 +50,7 @@ Makefile.in
 /tests/test-perl
 /tests/test-python
 /tests/test-ruby
+/tests/test-socket-activation
 /tests/test-streaming
 /tests/test-xz
 /test-driver
diff --git a/docs/nbdkit.pod b/docs/nbdkit.pod
index 2b11eed..ad02ec3 100644
--- a/docs/nbdkit.pod
+++ b/docs/nbdkit.pod
@@ -192,9 +192,11 @@ This option implies I<--foreground>.
 Don't fork.  Handle a single NBD connection on stdin/stdout.  After
 stdin closes, the server exits.
 
-You can use this option to run nbdkit from inetd, systemd or similar
+You can use this option to run nbdkit from inetd or similar
 superservers; or just for testing; or if you want to run nbdkit in a
-non-conventional way.
+non-conventional way.  Note that if you want to run nbdkit from
+systemd, then it may be better to use L</SOCKET ACTIVATION> instead of
+this option.
 
 This option implies I<--foreground>.
 
@@ -263,6 +265,48 @@ To list all the options supported by a plugin, do:
 
  nbdkit --help file
 
+=head1 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) passes in pre-opened file descriptors.  Socket activation
+lets you serve infrequent NBD requests using a superserver without
+needing nbdkit to be running the whole time.
+
+Socket activation is triggered when both the C<LISTEN_FDS> and
+C<LISTEN_PID> environment variables are set.  In this mode using
+I<-i>, I<-p>, I<--run>, I<-s> or I<-U> flags on
the command line is
+illegal and will cause an error.  Also in this mode nbdkit does not
+fork into the background (ie. I<-f> is implied).
+
+=head2 Using socket activation with systemd
+
+To use nbdkit with socket activation from systemd, create a unit file
+ending in C<.socket> (eg. C</etc/systemd/system/nbdkit.socket>)
+containing:
+
+ [Unit]
+ Description=NBDKit Network Block Device server
+ 
+ [Socket]
+ ListenStream=0.0.0.0:10809
+ 
+ [Install]
+ WantedBy=sockets.target
+
+There are various formats for the C<ListenStream> key.  See
+L<systemd.socket(5)> for more information.
+
+Also create a service unit (eg. C</etc/systemd/system/nbdkit.service>)
+containing:
+
+ [Service]
+ ExecStart=/usr/sbin/nbdkit file file=/path/to/serve
+
+For more information on systemd and socket activation, see
+L<http://0pointer.de/blog/projects/socket-activation.html>
+
 =head1 CAPTIVE NBDKIT
 
 You can run nbdkit as a "captive process", using the I<--run>
option.
@@ -382,8 +426,23 @@ This signal is ignored.
 
 =back
 
+=head1 ENVIRONMENT VARIABLES
+
+=over 4
+
+=item C<LISTEN_FDS>
+
+=item C<LISTEN_PID>
+
+If present in the environment when nbdkit starts up, these trigger
+L</SOCKET ACTIVATION>.
+
+=back
+
 =head1 SEE ALSO
 
+Other nbdkit manual pages:
+
 L<nbdkit-plugin(3)>,
 L<nbdkit-curl-plugin(1)>,
 L<nbdkit-example1-plugin(1)>,
@@ -398,6 +457,10 @@ L<nbdkit-python-plugin(3)>,
 L<nbdkit-vddk-plugin(1)>.
 L<nbdkit-xz-plugin(1)>.
 
+Other manual pages of interest:
+
+L<systemd.socket(5)>.
+
 =head1 AUTHORS
 
 Richard W.M. Jones
diff --git a/src/main.c b/src/main.c
index 9453cce..e935da2 100644
--- a/src/main.c
+++ b/src/main.c
@@ -54,6 +54,8 @@
 #include "nbdkit-plugin.h"
 #include "internal.h"
 
+#define FIRST_SOCKET_ACTIVATION_FD 3 /* defined by systemd ABI */
+
 static char *make_random_fifo (void);
 static void open_plugin_so (const char *filename);
 static void start_serving (void);
@@ -64,6 +66,7 @@ static void write_pidfile (void);
 static void fork_into_background (void);
 static uid_t parseuser (const char *);
 static gid_t parsegroup (const char *);
+static unsigned int get_socket_activation (void);
 
 const char *exportname;         /* -e */
 int foreground;                 /* -f */
@@ -77,6 +80,7 @@ int listen_stdin;               /* -s */
 char *unixsocket;               /* -U */
 const char *user, *group;       /* -u & -g */
 int verbose;                    /* -v */
+unsigned int socket_activation  /* $LISTEN_FDS and $LISTEN_PID set */;
 
 volatile int quit;
 
@@ -157,6 +161,9 @@ main (int argc, char *argv[])
 
   tls_init ();
 
+  /* Returns 0 if no socket activation, or the number of FDs. */
+  socket_activation = get_socket_activation ();
+
   for (;;) {
     c = getopt_long (argc, argv, short_options, long_options,
&option_index);
     if (c == -1)
@@ -172,6 +179,11 @@ main (int argc, char *argv[])
         dump_plugin = 1;
       }
       else if (strcmp (long_options[option_index].name, "run") == 0)
{
+        if (socket_activation) {
+          fprintf (stderr, "%s: cannot use socket activation with --run
flag\n",
+                   program_name);
+          exit (EXIT_FAILURE);
+        }
         run = optarg;
         foreground = 1;
       }
@@ -196,6 +208,11 @@ main (int argc, char *argv[])
       break;
 
     case 'i':
+      if (socket_activation) {
+        fprintf (stderr, "%s: cannot use socket activation with -i
flag\n",
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
       ipaddr = optarg;
       break;
 
@@ -214,6 +231,11 @@ main (int argc, char *argv[])
       break;
 
     case 'p':
+      if (socket_activation) {
+        fprintf (stderr, "%s: cannot use socket activation with -p
flag\n",
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
       port = optarg;
       break;
 
@@ -222,10 +244,20 @@ main (int argc, char *argv[])
       break;
 
     case 's':
+      if (socket_activation) {
+        fprintf (stderr, "%s: cannot use socket activation with -s
flag\n",
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
       listen_stdin = 1;
       break;
 
     case 'U':
+      if (socket_activation) {
+        fprintf (stderr, "%s: cannot use socket activation with -U
flag\n",
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
       if (strcmp (optarg, "-") == 0)
         unixsocket = make_random_fifo ();
       else
@@ -454,6 +486,7 @@ start_serving (void)
 {
   int *socks;
   size_t nr_socks;
+  size_t i;
 
   /* If the user has mixed up -p/-U/-s options, then give an error.
    *
@@ -470,6 +503,27 @@ start_serving (void)
 
   set_up_signals ();
 
+  /* Socket activation -- we are handling connections on pre-opened
+   * file descriptors [FIRST_SOCKET_ACTIVATION_FD ..
+   * FIRST_SOCKET_ACTIVATION_FD+nr_socks-1].
+   */
+  if (socket_activation) {
+    nr_socks = socket_activation;
+    debug ("using socket activation, nr_socks = %zu", nr_socks);
+    socks = malloc (sizeof (int) * nr_socks);
+    if (socks == NULL) {
+      perror ("malloc");
+      exit (EXIT_FAILURE);
+    }
+    for (i = 0; i < nr_socks; ++i)
+      socks[i] = FIRST_SOCKET_ACTIVATION_FD + i;
+    change_user ();
+    write_pidfile ();
+    accept_incoming_connections (socks, nr_socks);
+    free_listening_sockets (socks, nr_socks); /* also closes them */
+    return;
+  }
+
   /* Handling a single connection on stdin/stdout. */
   if (listen_stdin) {
     change_user ();
@@ -752,3 +806,60 @@ parsegroup (const char *id)
 
   return grp->gr_gid;
 }
+
+/* Returns 0 if no socket activation, or the number of FDs.
+ * See also virGetListenFDs in libvirt.org:src/util/virutil.c
+ */
+static unsigned int
+get_socket_activation (void)
+{
+  const char *s;
+  unsigned int pid;
+  unsigned int nr_fds;
+  unsigned int i;
+  int fd;
+
+  s = getenv ("LISTEN_PID");
+  if (s == NULL)
+    return 0;
+  if (sscanf (s, "%u", &pid) != 1) {
+    fprintf (stderr, "%s: malformed %s environment variable
(ignored)\n",
+             program_name, "LISTEN_PID");
+    return 0;
+  }
+  if (pid != getpid ()) {
+    fprintf (stderr, "%s: %s was not for us (ignored)\n",
+             program_name, "LISTEN_PID");
+    return 0;
+  }
+
+  s = getenv ("LISTEN_FDS");
+  if (s == NULL)
+    return 0;
+  if (sscanf (s, "%u", &nr_fds) != 1) {
+    fprintf (stderr, "%s: malformed %s environment variable
(ignored)\n",
+             program_name, "LISTEN_FDS");
+    return 0;
+  }
+
+  /* So these are not passed to any child processes we might start. */
+  unsetenv ("LISTEN_FDS");
+  unsetenv ("LISTEN_PID");
+
+  /* So the file descriptors don't leak into child processes. */
+  for (i = 0; i < nr_fds; ++i) {
+    fd = FIRST_SOCKET_ACTIVATION_FD + i;
+    if (fcntl (fd, F_SETFD, FD_CLOEXEC) == -1) {
+      /* If we cannot set FD_CLOEXEC then it probably means the file
+       * descriptor is invalid, so socket activation has gone wrong
+       * and we should exit.
+       */
+      fprintf (stderr, "%s: socket activation: "
+               "invalid file descriptor fd = %d: %m\n",
+               program_name, fd);
+      exit (EXIT_FAILURE);
+    }
+  }
+
+  return nr_fds;
+}
diff --git a/tests/Makefile.am b/tests/Makefile.am
index afb9975..389bcfa 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -83,7 +83,14 @@ TESTS = \
 	test-single.sh \
 	test-captive.sh \
 	test-random-sock.sh \
-	test-ipv4.sh
+	test-ipv4.sh \
+	test-socket-activation
+
+check_PROGRAMS = \
+	test-socket-activation
+
+test_socket_activation_SOURCES = test-socket-activation.c
+test_socket_activation_CFLAGS = $(WARNINGS_CFLAGS)
 
 # In-depth tests need libguestfs, since that is a convenient way to
 # drive qemu.
@@ -103,7 +110,6 @@ check_LTLIBRARIES = libtest.la
 libtest_la_SOURCES = test.c test.h
 libtest_la_CFLAGS = $(WARNINGS_CFLAGS)
 
-check_PROGRAMS  check_DATA  check_SCRIPTS  
diff --git a/tests/test-socket-activation.c b/tests/test-socket-activation.c
new file mode 100644
index 0000000..5ecdde1
--- /dev/null
+++ b/tests/test-socket-activation.c
@@ -0,0 +1,226 @@
+/* nbdkit
+ * Copyright (C) 2017 Red Hat Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of Red Hat nor the names of its contributors may be
+ * used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS
IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+/* Test socket activation.
+ *
+ * We cannot use the test framework for this since the framework
+ * always uses the -U flag which is incompatible with socket
+ * activation.  Unfortunately this does mean we duplicate some code
+ * from the test framework.
+ *
+ * It's *almost* possible to test this from a shell script
+ * (cf. test-ipv4.sh) but as far as I can tell setting LISTEN_PID
+ * correctly is impossible from shell.
+ */
+
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <signal.h>
+#include <errno.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <sys/wait.h>
+
+#define FIRST_SOCKET_ACTIVATION_FD 3
+
+#define NBDKIT_START_TIMEOUT 30 /* seconds */
+
+#define NBDKIT_PLUGIN(name) \
+  "../plugins/" name "/.libs/nbdkit-" name
"-plugin.so"
+
+/* Declare program_name. */
+#if HAVE_DECL_PROGRAM_INVOCATION_SHORT_NAME == 1
+#include <errno.h>
+#define program_name program_invocation_short_name
+#else
+#define program_name "nbdkit"
+#endif
+
+static char tmpdir[] =   "/tmp/nbdkitXXXXXX";
+static char sockpath[] = "/tmp/nbdkitXXXXXX/sock";
+static char pidpath[] =  "/tmp/nbdkitXXXXXX/pid";
+
+static pid_t pid = 0;
+
+static void
+cleanup (void)
+{
+  if (pid > 0)
+    kill (pid, SIGTERM);
+
+  unlink (pidpath);
+  unlink (sockpath);
+  rmdir (tmpdir);
+}
+
+int
+main (int argc, char *argv[])
+{
+  int sock;
+  struct sockaddr_un addr;
+  char pid_str[16];
+  size_t i, len;
+  char magic[8];
+
+  if (mkdtemp (tmpdir) == NULL) {
+    perror ("mkdtemp");
+    exit (EXIT_FAILURE);
+  }
+  len = strlen (tmpdir);
+  memcpy (sockpath, tmpdir, len);
+  memcpy (pidpath, tmpdir, len);
+
+  atexit (cleanup);
+
+  /* Open the listening socket which will be passed into nbdkit. */
+  sock = socket (AF_UNIX, SOCK_STREAM /* NB do not use SOCK_CLOEXEC */, 0);
+  if (sock == -1) {
+    perror ("socket");
+    exit (EXIT_FAILURE);
+  }
+
+  addr.sun_family = AF_UNIX;
+  len = strlen (sockpath);
+  memcpy (addr.sun_path, sockpath, len+1 /* trailing \0 */);
+
+  if (bind (sock, (struct sockaddr *) &addr, sizeof addr) == -1) {
+    perror (sockpath);
+    exit (EXIT_FAILURE);
+  }
+
+  if (listen (sock, 1) == -1) {
+    perror ("listen");
+    exit (EXIT_FAILURE);
+  }
+
+  if (sock != FIRST_SOCKET_ACTIVATION_FD) {
+    if (dup2 (sock, FIRST_SOCKET_ACTIVATION_FD) == -1) {
+      perror ("dup2");
+      exit (EXIT_FAILURE);
+    }
+    close (sock);
+  }
+
+  /* Run nbdkit. */
+  pid = fork ();
+  if (pid == -1) {
+    perror ("fork");
+    exit (EXIT_FAILURE);
+  }
+  if (pid == 0) {
+    /* Run nbdkit in the child. */
+    setenv ("LISTEN_FDS", "1", 1);
+    snprintf (pid_str, sizeof pid_str, "%d", (int) getpid ());
+    setenv ("LISTEN_PID", pid_str, 1);
+
+    execlp ("../src/nbdkit",
+            "nbdkit",
+            "-P", pidpath,
+            "-o",
+            "-v",
+            NBDKIT_PLUGIN ("example1"), NULL);
+    perror ("exec: nbdkit");
+    _exit (EXIT_FAILURE);
+  }
+
+  /* We don't need the listening socket now. */
+  close (sock);
+
+  /* Wait for the pidfile to turn up, which indicates that nbdkit has
+   * started up successfully and is ready to serve requests.  However
+   * if 'pid' exits in this time it indicates a failure to start up.
+   * Also there is a timeout in case nbdkit hangs.
+   */
+  for (i = 0; i < NBDKIT_START_TIMEOUT; ++i) {
+    if (waitpid (pid, NULL, WNOHANG) == pid)
+      goto early_exit;
+
+    if (kill (pid, 0) == -1) {
+      if (errno == ESRCH) {
+      early_exit:
+        fprintf (stderr,
+                 "%s FAILED: nbdkit exited before starting to serve
files\n",
+                 program_name);
+        pid = 0;
+        exit (EXIT_FAILURE);
+      }
+      perror ("kill");
+    }
+
+    if (access (pidpath, F_OK) == 0)
+      break;
+
+    sleep (1);
+  }
+
+  /* Now nbdkit is supposed to be listening on the Unix domain socket
+   * (which it got via the listening socket that we passed down to it,
+   * not from the path), so we should be able to connect to the Unix
+   * domain socket by its path and receive an NBD magic string.
+   */
+  sock = socket (AF_UNIX, SOCK_STREAM|SOCK_CLOEXEC, 0);
+  if (sock == -1) {
+    perror ("socket");
+    exit (EXIT_FAILURE);
+  }
+
+  /* Reuse addr which was set up above. */
+  if (connect (sock, (struct sockaddr *) &addr, sizeof addr) == -1) {
+    perror (sockpath);
+    exit (EXIT_FAILURE);
+  }
+
+  if (read (sock, magic, 8) != 8) {
+    perror ("read");
+    exit (EXIT_FAILURE);
+  }
+
+  if (memcmp (magic, "NBDMAGIC", 8) != 0) {
+    fprintf (stderr, "%s FAILED: did not read magic string from
server\n",
+             program_name);
+    exit (EXIT_FAILURE);
+  }
+
+  close (sock);
+
+  /* Test succeeded. */
+  exit (EXIT_SUCCESS);
+}
-- 
2.10.2