core: add support for naming file descriptors passed using socket activation

This adds support for naming file descriptors passed using socket
activation. The names are passed in a new $LISTEN_FDNAMES= environment
variable, that matches the existign $LISTEN_FDS= one and contains a
colon-separated list of names.

This also adds support for naming fds submitted to the per-service fd
store using FDNAME= in the sd_notify() message.

This also adds a new FileDescriptorName= setting for socket unit files
to set the name for fds created by socket units.

This also adds a new call sd_listen_fds_with_names(), that is similar to
sd_listen_fds(), but also returns the names of the fds.

systemd-activate gained the new --fdname= switch to specify a name for
testing socket activation.

This is based on #1247 by Maciej Wereski.

Fixes #1247.

5 files changed, 168 insertions, 33 deletions

diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml
index 9b9705eb2e..ea55671e4f 100644
--- a/man/sd_listen_fds.xml
+++ b/man/sd_listen_fds.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
@@ -45,6 +45,7 @@
 
   <refnamediv>
     <refname>sd_listen_fds</refname>
+    <refname>sd_listen_fds_with_names</refname>
     <refname>SD_LISTEN_FDS_START</refname>
     <refpurpose>Check for file descriptors passed by the system manager</refpurpose>
   </refnamediv>
@@ -59,23 +60,26 @@
         <funcdef>int <function>sd_listen_fds</function></funcdef>
         <paramdef>int <parameter>unset_environment</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_listen_fds_with_names</function></funcdef>
+        <paramdef>int <parameter>unset_environment</parameter></paramdef>
+        <paramdef>char*** <parameter>names</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_listen_fds()</function> shall be called by a
-    daemon to check for file descriptors passed by the init system as
-    part of the socket-based activation logic.</para>
-
-    <para>If the <parameter>unset_environment</parameter> parameter is
-    non-zero, <function>sd_listen_fds()</function> will unset the
-    <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname>
-    environment variables before returning (regardless of whether the
-    function call itself succeeded or not). Further calls to
-    <function>sd_listen_fds()</function> will then fail, but the
-    variables are no longer inherited by child processes.</para>
+    <para><function>sd_listen_fds()</function> may be invoked by a
+    daemon to check for file descriptors passed by the service manager as
+    part of the socket-based activation logic. It returns the number
+    of received file descriptors. If no file descriptors have been
+    received zero is returned. The first file descriptor may be found
+    at file descriptor number 3
+    (i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining
+    descriptors follow at 4, 5, 6, ..., if any.</para>
 
     <para>If a daemon receives more than one file descriptor, they
     will be passed in the same order as configured in the systemd
@@ -108,12 +112,86 @@
     <literal>FDSTORE=1</literal> messages, these file descriptors are
     passed last, in arbitrary order, and with duplicates
     removed.</para>
+
+    <para>If the <parameter>unset_environment</parameter> parameter is
+    non-zero, <function>sd_listen_fds()</function> will unset the
+    <varname>$LISTEN_FDS</varname>, <varname>$LISTEN_PID</varname> and
+    <varname>$LISTEN_FDNAMES</varname> environment variables before
+    returning (regardless of whether the function call itself
+    succeeded or not). Further calls to
+    <function>sd_listen_fds()</function> will then return zero, but the
+    variables are no longer inherited by child processes.</para>
+
+    <para><function>sd_listen_fds_with_names()</function> is like
+    <function>sd_listen_fds()</function> but optionally also returns
+    an array of strings with identification names for the passed file
+    descriptors, if that is available, and the
+    <parameter>names</parameter> parameter is non-NULL. This
+    information is read from the <varname>$LISTEN_FDNAMES</varname>
+    variable, which may contain a colon-separated list of names. For
+    socket-activated services, these names may be configured with the
+    <varname>FileDescriptorName=</varname> setting in socket unit
+    files, see
+    <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for details. For file descriptors pushed into the file descriptor
+    store (see above) the name is set via the
+    <varname>FDNAME=</varname> field transmitted via
+    <function>sd_pid_notify_with_fds()</function>. The primary usecase
+    for these names are services which accept a variety of file
+    descriptors which are not recognizable with functions like
+    <function>sd_is_socket()</function> alone, and thus require
+    identification via a name. It is recommended to rely on named file
+    descriptors only if identification via
+    <function>sd_is_socket()</function> and related calls is not
+    sufficient. Note that the names used are not unique in any
+    way. The returned array of strings has as many entries as file
+    descriptors has been received, plus a final NULL pointer
+    terminating the array. The caller needs to free the array itself
+    and each of its elements with libc's <varname>free()</varname>
+    call after use. If the <parameter>names</parameter> parameter is
+    NULL the call is entirely equivalent to
+    <function>sd_listen_fds()</function>.</para>
+
+    <para>Under specific conditions the following automatic file
+    descriptor names are returned:
+
+    <table>
+      <title>
+         <command>Special names</command>
+      </title>
+
+      <tgroup cols='2'>
+        <thead>
+          <row>
+            <entry>Name</entry>
+            <entry>Description</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry><literal>unknown</literal></entry>
+            <entry>The process received no name for the specific file descriptor from the service manager.</entry>
+          </row>
+
+          <row>
+            <entry><literal>stored</literal></entry>
+            <entry>The file descriptor originates in the service manager's per-service file descriptor store, and the <varname>FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry>
+          </row>
+
+          <row>
+            <entry><literal>connection</literal></entry>
+            <entry>The service was activated in per-connection style using <varname>Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+    </para>
   </refsect1>
 
   <refsect1>
     <title>Return Value</title>
 
-    <para>On failure, this call returns a negative errno-style error
+    <para>On failure, these calls returns a negative errno-style error
     code. If
     <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> was
     not set or was not correctly set for this daemon and hence no file
@@ -128,13 +206,16 @@
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 
-    <para>Internally, this function checks whether the
-    <varname>$LISTEN_PID</varname> environment variable equals the
-    daemon PID. If not, it returns immediately. Otherwise, it parses
-    the number passed in the <varname>$LISTEN_FDS</varname>
+    <para>Internally, <function>sd_listen_fds()</function> checks
+    whether the <varname>$LISTEN_PID</varname> environment variable
+    equals the daemon PID. If not, it returns immediately. Otherwise,
+    it parses the number passed in the <varname>$LISTEN_FDS</varname>
     environment variable, then sets the FD_CLOEXEC flag for the parsed
     number of file descriptors starting from SD_LISTEN_FDS_START.
-    Finally, it returns the parsed number.</para>
+    Finally, it returns the parsed
+    number. <function>sd_listen_fds_with_names()</function> does the
+    same but also parses <varname>$LISTEN_FDNAMES</varname> if
+    set.</para>
   </refsect1>
 
   <refsect1>
@@ -144,15 +225,14 @@
       <varlistentry>
         <term><varname>$LISTEN_PID</varname></term>
         <term><varname>$LISTEN_FDS</varname></term>
+        <term><varname>$LISTEN_FDNAMES</varname></term>
 
-        <listitem><para>Set by the init system
-        for supervised processes that use
-        socket-based activation. This
-        environment variable specifies the
-        data
-        <function>sd_listen_fds()</function>
-        parses. See above for
-        details.</para></listitem>
+        <listitem><para>Set by the service manager for supervised
+        processes that use socket-based activation. This environment
+        variable specifies the data
+        <function>sd_listen_fds()</function> and
+        <function>sd_listen_fds_with_names()</function> parses. See
+        above for details.</para></listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
@@ -167,6 +247,7 @@
       <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 14030f56b1..2d73c27f62 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
@@ -229,6 +229,27 @@
         below.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term>FDNAME=...</term>
+
+        <listitem><para>When used in combination with
+        <varname>FDSTORE=1</varname> specifies a name for the
+        submitted file descriptors. This name is passed to the service
+        during activation, and may be queried using
+        <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
+        descriptors submitted without this field set, will implicitly
+        get the name <literal>stored</literal> assigned. Note that if
+        multiple file descriptors are submitted at once the specified
+        name will be assigned to all of them. In order to assign
+        different names to submitted file descriptors, submit them in
+        seperate invocations of
+        <function>sd_pid_notify_with_fds()</function>. The name may
+        consist of any ASCII characters, but must not contain control
+        characters or <literal>:</literal>. It may not be longer than
+        255 characters. If a submitted name does not follow these
+        restrictions it is ignored.</para></listitem>
+      </varlistentry>
+
     </variablelist>
 
     <para>It is recommended to prefix variable names that are not
@@ -358,7 +379,7 @@
       in order to continue operation after a service restart without
       losing state use <literal>FDSTORE=1</literal>:</para>
 
-      <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &amp;fd, 1);</programlisting>
+      <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &amp;fd, 1);</programlisting>
     </example>
   </refsect1>
 
@@ -367,9 +388,11 @@
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/systemd-activate.xml b/man/systemd-activate.xml
index 3b854fd8ec..90e974c991 100644
--- a/man/systemd-activate.xml
+++ b/man/systemd-activate.xml
@@ -115,6 +115,16 @@
         </para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--fdname=</option><replaceable>NAME</replaceable></term>
+
+        <listitem><para>Specify a name for the activation file
+        descriptors. This is equivalent to setting
+        <varname>FileDescriptorName=</varname> in socket unit files, and
+        enables use of
+        <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+      </varlistentry>
+
       <xi:include href="standard-options.xml" xpointer="help" />
       <xi:include href="standard-options.xml" xpointer="version" />
     </variablelist>
@@ -126,6 +136,7 @@
       <varlistentry>
         <term><varname>$LISTEN_FDS</varname></term>
         <term><varname>$LISTEN_PID</varname></term>
+        <term><varname>$LISTEN_FDNAMES</varname></term>
 
         <listitem><para>See
         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
@@ -165,6 +176,8 @@
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index 212764075d..46a47b2d95 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
@@ -748,6 +748,22 @@
         list.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>FileDescriptorName=</varname></term>
+        <listitem><para>Assigns a name to all file descriptors this
+        socket unit encapsulates. This is useful to help activated
+        services to identify specific file descriptors, if multiple
+        are passed. Services may use the
+        <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+        call to acquire the names configured for the received file
+        descriptors. Names may contain any ASCII character, but must
+        exclude control characters or <literal>:</literal>, and must
+        be at most 255 characters in length. If this setting is not
+        used the file descriptor name defaults to the name of the
+        socket unit, including its <filename>.socket</filename>
+        suffix.</para></listitem>
+      </varlistentry>
+
     </variablelist>
 
     <para>Check
@@ -768,9 +784,10 @@
         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>
       </para>
-
       <para>
         For more extensive descriptions see the "systemd for Developers" series:
         <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
diff --git a/man/systemd.xml b/man/systemd.xml
index 9e927c3204..391333bfb4 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -835,6 +835,7 @@
       <varlistentry>
         <term><varname>$LISTEN_PID</varname></term>
         <term><varname>$LISTEN_FDS</varname></term>
+        <term><varname>$LISTEN_FDNAMES</varname></term>
 
         <listitem><para>Set by systemd for supervised processes during
         socket-based activation. See