Spec: document systemd activation

We didn't say that SystemdService existed. Now we do, together with
enough context to make it make sense.

Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: Philip Withnall <philip.withnall@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=98671

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 5feffa331af909f8cd074859d241de25ce9f2501..2e72c313439fd0bc92ddcb0c3fa2460521d346cd 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -5152,6 +5152,39 @@
           property on screen 0 of the display, pointing to this bus.
         </para>
       </sect3>
+
+      <sect3 id="message-bus-starting-services-systemd">
+        <title>systemd Activation</title>
+
+        <para>
+          Service description files may contain a
+          <literal>SystemdService</literal> key. Its value is the name of a
+          <ulink
+            url="https://www.freedesktop.org/wiki/Software/systemd/">systemd</ulink>
+          service, for example
+          <literal>dbus-com.example.MyDaemon.service</literal>.
+        </para>
+
+        <para>
+          If this key is present, the bus daemon may carry out activation for
+          this D-Bus service by sending a request to systemd asking it to
+          start the systemd service whose name is the value of
+          <literal>SystemdService</literal>. For example, the reference
+          <literal>dbus-daemon</literal> has a
+          <literal>--systemd-activation</literal> option that enables this
+          feature, and that option is given when it is started by systemd.
+        </para>
+
+        <para>
+          On the well-known system bus, it is a common practice to set
+          <literal>SystemdService</literal> to <literal>dbus-</literal>,
+          followed by the well-known bus name, followed by
+          <literal>.service</literal>, then register that name as an alias
+          for the real systemd service. This allows D-Bus activation of a
+          service to be enabled or disabled independently of whether the
+          service is started by systemd during boot.
+        </para>
+      </sect3>
     </sect2>
 
     <sect2 id="message-bus-types">