docs: document new sd_notify() extensions

2 files changed, 101 insertions, 14 deletions

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index a56d039468..d8fe6468a2 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -446,9 +446,14 @@
     </variablelist>
 
     <para>The notification messages sent by services are interpreted by the service manager. Unknown
-    assignments may be logged, but are otherwise ignored. Thus, it is not useful to send assignments which
-    are not in this list. The service manager also sends some messages to <emphasis>its</emphasis>
-    notification socket, which are then consumed by the machine or container manager.</para>
+    assignments are ignored. Thus, it is is safe (but often without effect) to send assignments which are not
+    in this list. The protocol is extensible, but care should be taken to ensure private extensions are
+    recognizable as such. Specifically, it is recommend to prefix them with <literal>X_</literal> followed by
+    some namespace identifier. The service manager also sends some messages to <emphasis>its</emphasis>
+    notification socket, which may then consumed by a supervising machine or container manager further up the
+    stack. The service manager sends a number of extension fields, for example
+    <varname>X_SYSTEMD_UNIT_ACTIVE=</varname>, for details see
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
   </refsect1>
 
   <refsect1>
diff --git a/man/systemd.xml b/man/systemd.xml
index 960df97f0b..b66707faba 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -372,6 +372,14 @@
   <refsect1>
     <title>Signals</title>
 
+    <para>The service listens to various UNIX process signals that can be used to request various actions
+    asynchronously. The signal handling is enabled very early during boot, before any further processes are
+    invoked. However, a supervising container manager or similar that intends to request these operations via
+    this mechanism must take into consideration that this functionality is not available during the earliest
+    initialization phase. An <function>sd_notify()</function> notification message carrying the
+    <varname>X_SYSTEMD_SIGNALS_LEVEL=2</varname> field is emitted once the signal handlers are enabled, see
+    below. This may be used to schedule submission of these signals correctly.</para>
+
     <variablelist>
       <varlistentry>
         <term><constant>SIGTERM</constant></term>
@@ -769,10 +777,11 @@
       <varlistentry>
         <term><varname>$NOTIFY_SOCKET</varname></term>
 
-        <listitem><para>Set by systemd for supervised processes for
-        status and start-up completion notification. See
-        <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-        for more information.</para></listitem>
+        <listitem><para>Set by service manager for its services for status and readiness notifications. Also
+        consumed by service manager for notifying supervising container managers or service managers up the
+        stack about its own progress. See
+        <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> and the
+        relevant section below for more information.</para></listitem>
       </varlistentry>
     </variablelist>
 
@@ -1109,7 +1118,7 @@
   </refsect1>
 
   <refsect1>
-    <title>System credentials</title>
+    <title>System Credentials</title>
 
     <para>During initialization the service manager will import credentials from various sources into the
     system's set of credentials, which can then be propagated into services and consumed by
@@ -1151,14 +1160,16 @@
         <term><varname>vmm.notify_socket</varname></term>
         <listitem>
           <para>Contains a <constant>AF_VSOCK</constant> or <constant>AF_UNIX</constant> address where to
-          send a <constant>READY=1</constant> notification datagram when the system has finished booting. See
-          <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
-          more information. Note that in case the hypervisor does not support <constant>SOCK_DGRAM</constant>
-          over <constant>AF_VSOCK</constant>, <constant>SOCK_SEQPACKET</constant> will be tried instead. The
-          credential payload for <constant>AF_VSOCK</constant> should be in the form
+          send a <constant>READY=1</constant> notification message when the service manager has completed
+          booting. See
+          <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+          the next section for more information. Note that in case the hypervisor does not support
+          <constant>SOCK_DGRAM</constant> over <constant>AF_VSOCK</constant>,
+          <constant>SOCK_SEQPACKET</constant> will be tried instead. The credential payload for
+          <constant>AF_VSOCK</constant> should be a string in the form
           <literal>vsock:CID:PORT</literal>.</para>
 
-          <para>This feature is useful for hypervisors/VMMs or other processes on the host to receive a
+          <para>This feature is useful for machine managers or other processes on the host to receive a
           notification via VSOCK when a virtual machine has finished booting.</para>
 
           <xi:include href="version-info.xml" xpointer="v254"/>
@@ -1177,6 +1188,77 @@
         </listitem>
       </varlistentry>
     </variablelist>
+
+    <para>For a list of system credentials various other components of systemd consume, see
+    <citerefentry><refentrytitle>systemd.system-credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Readiness Protocol</title>
+
+    <para>The service manager implements a readiness notification protocol both between the manager and its
+    services (i.e. down the stack), and between the manager and a potential supervisor further up the stack
+    (the latter could be a machine or container manager, or in case of a per-user service manager the system
+    service manager instance). The basic protocol (and the suggested API for it) is described in
+    <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>The notification socket the service manager (including PID 1) uses for reporting readiness to its
+    own supervisor is set via the usual <varname>$NOTIFY_SOCKET</varname> environment variable (see
+    above). Since this is directly settable only for container managers and for the per-user instance of the
+    service manager, an additional mechanism to configure this is available, in particular intended for use
+    in VM environments: the <varname>vmm.notify_socket</varname> system credential (see above) may be set to
+    a suitable socket (typically an <constant>AF_VSOCK</constant> one) via SMBIOS Type 11 vendor strings. For
+    details see above.</para>
+
+    <para>The notification protocol from the service manager up the stack towards a supervisor supports a
+    number of extension fields that allow a supervisor to learn about specific properties of the system and
+    track its boot progress. Specifically the following fields are sent:</para>
+
+    <itemizedlist>
+      <listitem><para>An <varname>X_SYSTEMD_HOSTNAME=…</varname> message will be sent out once the initial
+      hostname for the system has been determined. Note that during later runtime the hostname might be
+      changed again programmatically, and (currently) no further notifications are sent out in that case.</para>
+
+      <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+      <listitem><para>An <varname>X_SYSTEMD_MACHINE_ID=…</varname> message will be sent out once the machine
+      ID of the system has been determined. See
+      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+      details.</para>
+
+      <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+      <listitem><para>An <varname>X_SYSTEMD_SIGNALS_LEVEL=…</varname> message will be sent out once the
+      service manager installed the various UNIX process signal handlers described above. The field's value
+      is an unsigned integer formatted as decimal string, and indicates the supported UNIX process signal
+      feature level of the service manager. Currently, only a single feature level is defined:</para>
+
+      <itemizedlist>
+        <listitem><para><varname>X_SYSTEMD_SIGNALS_LEVEL=2</varname> covers the various UNIX process signals
+        documented above – which are a superset of those supported by the historical SysV init
+        system.</para></listitem>
+      </itemizedlist>
+
+      <para>Signals sent to PID 1 before this message is sent might not be handled correctly yet. A consumer
+      of these messages should parse the value as an unsigned integer indication the level of support. For
+      now only the mentioned level 2 is defined, but later on additional levels might be defined with higher
+      integers, that will implement a superset of the currently defined behaviour.</para>
+
+      <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+      <listitem><para><varname>X_SYSTEMD_UNIT_ACTIVE=…</varname> and
+      <varname>X_SYSTEMD_UNIT_INACTIVE=…</varname> messages will be sent out for each target unit as it
+      becomes active or stops being active. This is useful to track boot progress and functionality. For
+      example, once the <filename>ssh-access.target</filename> unit is reported started SSH access is
+      typically available, see
+      <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+      details.</para>
+
+      <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+    </itemizedlist>
+
+    <para>Note that these extension fields are sent in addition to the regular <literal>READY=1</literal> and
+    <literal>RELOADING=1</literal> notifications.</para>
   </refsect1>
 
   <refsect1>