4bff0a
From d77d5a9399e393734fe8c8a5ad085036775854a7 Mon Sep 17 00:00:00 2001
4bff0a
From: Lennart Poettering <lennart@poettering.net>
4bff0a
Date: Tue, 17 Jul 2018 12:01:26 +0200
4bff0a
Subject: [PATCH] man: document the new Type=exec type
4bff0a
4bff0a
And while we are at it, let's rearrange and extend the Type=
4bff0a
documentation a bit. Let's make it an itemized list, and let's add a
4bff0a
paragraph explaining which type best to use.
4bff0a
4bff0a
(cherry picked from commit 79905a246d645d21633f09f564b3672d5085a85c)
4bff0a
4bff0a
Resolves: #1683334
4bff0a
---
4bff0a
 man/systemd-run.xml     |  10 +++
4bff0a
 man/systemd.service.xml | 158 ++++++++++++++++++++++------------------
4bff0a
 2 files changed, 97 insertions(+), 71 deletions(-)
4bff0a
4bff0a
diff --git a/man/systemd-run.xml b/man/systemd-run.xml
4bff0a
index 1c254afae3..a134b2c0dc 100644
4bff0a
--- a/man/systemd-run.xml
4bff0a
+++ b/man/systemd-run.xml
4bff0a
@@ -83,6 +83,16 @@
4bff0a
     <replaceable>COMMAND</replaceable> may be omitted. In this case, <command>systemd-run</command> creates only a
4bff0a
     <filename>.path</filename>, <filename>.socket</filename>, or <filename>.timer</filename> unit that triggers the
4bff0a
     specified unit.</para>
4bff0a
+
4bff0a
+    <para>By default, services created with <command>systemd-run</command> default to the <option>simple</option> type,
4bff0a
+    see the description of <varname>Type=</varname> in
4bff0a
+    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
4bff0a
+    details. Note that when this type is used the service manager (and thus the <command>systemd-run</command> command)
4bff0a
+    considers service start-up successful as soon as the <function>fork()</function> for the main service process
4bff0a
+    succeeded, i.e. before the <function>execve()</function> is invoked, and thus even if the specified command cannot
4bff0a
+    be started. Consider using the <option>exec</option> service type (i.e. <option>--property=Type=exec</option>) to
4bff0a
+    ensure that <command>systemd-run</command> returns successfully only if the specified command line has been
4bff0a
+    successfully started.</para>
4bff0a
   </refsect1>
4bff0a
 
4bff0a
   <refsect1>
4bff0a
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
4bff0a
index add54524ce..315b80e704 100644
4bff0a
--- a/man/systemd.service.xml
4bff0a
+++ b/man/systemd.service.xml
4bff0a
@@ -153,77 +153,93 @@
4bff0a
       <varlistentry>
4bff0a
         <term><varname>Type=</varname></term>
4bff0a
 
4bff0a
-        <listitem><para>Configures the process start-up type for this
4bff0a
-        service unit. One of
4bff0a
-        <option>simple</option>,
4bff0a
-        <option>forking</option>,
4bff0a
-        <option>oneshot</option>,
4bff0a
-        <option>dbus</option>,
4bff0a
-        <option>notify</option> or
4bff0a
-        <option>idle</option>.</para>
4bff0a
-
4bff0a
-        <para>If set to <option>simple</option> (the default if
4bff0a
-        neither <varname>Type=</varname> nor
4bff0a
-        <varname>BusName=</varname>, but <varname>ExecStart=</varname>
4bff0a
-        are specified), it is expected that the process configured
4bff0a
-        with <varname>ExecStart=</varname> is the main process of the
4bff0a
-        service. In this mode, if the process offers functionality to
4bff0a
-        other processes on the system, its communication channels
4bff0a
-        should be installed before the daemon is started up (e.g.
4bff0a
-        sockets set up by systemd, via socket activation), as systemd
4bff0a
-        will immediately proceed starting follow-up units.</para>
4bff0a
-
4bff0a
-        <para>If set to <option>forking</option>, it is expected that
4bff0a
-        the process configured with <varname>ExecStart=</varname> will
4bff0a
-        call <function>fork()</function> as part of its start-up. The
4bff0a
-        parent process is expected to exit when start-up is complete
4bff0a
-        and all communication channels are set up. The child continues
4bff0a
-        to run as the main daemon process. This is the behavior of
4bff0a
-        traditional UNIX daemons. If this setting is used, it is
4bff0a
-        recommended to also use the <varname>PIDFile=</varname>
4bff0a
-        option, so that systemd can identify the main process of the
4bff0a
-        daemon. systemd will proceed with starting follow-up units as
4bff0a
-        soon as the parent process exits.</para>
4bff0a
-
4bff0a
-        <para>Behavior of <option>oneshot</option> is similar to
4bff0a
-        <option>simple</option>; however, it is expected that the
4bff0a
-        process has to exit before systemd starts follow-up units.
4bff0a
-        <varname>RemainAfterExit=</varname> is particularly useful for
4bff0a
-        this type of service. This is the implied default if neither
4bff0a
-        <varname>Type=</varname> nor <varname>ExecStart=</varname> are
4bff0a
-        specified.</para>
4bff0a
-
4bff0a
-        <para>Behavior of <option>dbus</option> is similar to
4bff0a
-        <option>simple</option>; however, it is expected that the
4bff0a
-        daemon acquires a name on the D-Bus bus, as configured by
4bff0a
-        <varname>BusName=</varname>. systemd will proceed with
4bff0a
-        starting follow-up units after the D-Bus bus name has been
4bff0a
-        acquired. Service units with this option configured implicitly
4bff0a
-        gain dependencies on the <filename>dbus.socket</filename>
4bff0a
-        unit. This type is the default if <varname>BusName=</varname>
4bff0a
-        is specified.</para>
4bff0a
-
4bff0a
-        <para>Behavior of <option>notify</option> is similar to
4bff0a
-        <option>simple</option>; however, it is expected that the
4bff0a
-        daemon sends a notification message via
4bff0a
-        <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
4bff0a
-        or an equivalent call when it has finished starting up.
4bff0a
-        systemd will proceed with starting follow-up units after this
4bff0a
-        notification message has been sent. If this option is used,
4bff0a
-        <varname>NotifyAccess=</varname> (see below) should be set to
4bff0a
-        open access to the notification socket provided by systemd. If
4bff0a
-        <varname>NotifyAccess=</varname> is missing or set to
4bff0a
-        <option>none</option>, it will be forcibly set to
4bff0a
-        <option>main</option>. Note that currently
4bff0a
-        <varname>Type=</varname><option>notify</option> will not work
4bff0a
-        if used in combination with
4bff0a
-        <varname>PrivateNetwork=</varname><option>yes</option>.</para>
4bff0a
-
4bff0a
-        <para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, actual execution
4bff0a
-        of the service program is delayed until all active jobs are dispatched. This may be used to avoid interleaving
4bff0a
-        of output of shell services with the status output on the console. Note that this type is useful only to
4bff0a
-        improve console output, it is not useful as a general unit ordering tool, and the effect of this service type
4bff0a
-        is subject to a 5s time-out, after which the service program is invoked anyway.</para>
4bff0a
+        <listitem>
4bff0a
+          <para>Configures the process start-up type for this service unit. One of <option>simple</option>,
4bff0a
+          <option>exec</option>, <option>forking</option>, <option>oneshot</option>, <option>dbus</option>,
4bff0a
+          <option>notify</option> or <option>idle</option>:</para>
4bff0a
+
4bff0a
+          <itemizedlist>
4bff0a
+            <listitem><para>If set to <option>simple</option> (the default if <varname>ExecStart=</varname> is
4bff0a
+            specified but neither <varname>Type=</varname> nor <varname>BusName=</varname> are), the service manager
4bff0a
+            will consider the unit started immediately after the main service process has been forked off. It is
4bff0a
+            expected that the process configured with <varname>ExecStart=</varname> is the main process of the
4bff0a
+            service. In this mode, if the process offers functionality to other processes on the system, its
4bff0a
+            communication channels should be installed before the service is started up (e.g.  sockets set up by
4bff0a
+            systemd, via socket activation), as the service manager will immediately proceed starting follow-up units,
4bff0a
+            right after creating the main service process, and before executing the service's binary. Note that this
4bff0a
+            means <command>systemctl start</command> command lines for <option>simple</option> services will report
4bff0a
+            success even if the service's binary cannot be invoked successfully (for example because the selected
4bff0a
+            <varname>User=</varname> doesn't exist, or the service binary is missing).</para></listitem>
4bff0a
+
4bff0a
+            <listitem><para>The <option>exec</option> type is similar to <option>simple</option>, but the service
4bff0a
+            manager will consider the unit started immediately after the main service binary has been executed. The service
4bff0a
+            manager will delay starting of follow-up units until that point. (Or in other words:
4bff0a
+            <option>simple</option> proceeds with further jobs right after <function>fork()</function> returns, while
4bff0a
+            <option>exec</option> will not proceed before both <function>fork()</function> and
4bff0a
+            <function>execve()</function> in the service process succeeded.) Note that this means <command>systemctl
4bff0a
+            start</command> command lines for <option>exec</option> services will report failure when the service's
4bff0a
+            binary cannot be invoked successfully (for example because the selected <varname>User=</varname> doesn't
4bff0a
+            exist, or the service binary is missing).</para></listitem>
4bff0a
+
4bff0a
+            <listitem><para>If set to <option>forking</option>, it is expected that the process configured with
4bff0a
+            <varname>ExecStart=</varname> will call <function>fork()</function> as part of its start-up. The parent
4bff0a
+            process is expected to exit when start-up is complete and all communication channels are set up. The child
4bff0a
+            continues to run as the main service process, and the service manager will consider the unit started when
4bff0a
+            the parent process exits. This is the behavior of traditional UNIX services. If this setting is used, it is
4bff0a
+            recommended to also use the <varname>PIDFile=</varname> option, so that systemd can reliably identify the
4bff0a
+            main process of the service. systemd will proceed with starting follow-up units as soon as the parent
4bff0a
+            process exits.</para></listitem>
4bff0a
+
4bff0a
+            <listitem><para>Behavior of <option>oneshot</option> is similar to <option>simple</option>; however, the
4bff0a
+            service manager will consider the unit started after the main process exits. It will then start follow-up
4bff0a
+            units. <varname>RemainAfterExit=</varname> is particularly useful for this type of
4bff0a
+            service. <varname>Type=</varname><option>oneshot</option> is the implied default if neither
4bff0a
+            <varname>Type=</varname> nor <varname>ExecStart=</varname> are specified.</para></listitem>
4bff0a
+
4bff0a
+            <listitem><para>Behavior of <option>dbus</option> is similar to <option>simple</option>; however, it is
4bff0a
+            expected that the service acquires a name on the D-Bus bus, as configured by
4bff0a
+            <varname>BusName=</varname>. systemd will proceed with starting follow-up units after the D-Bus bus name
4bff0a
+            has been acquired. Service units with this option configured implicitly gain dependencies on the
4bff0a
+            <filename>dbus.socket</filename> unit. This type is the default if <varname>BusName=</varname> is
4bff0a
+            specified.</para></listitem>
4bff0a
+
4bff0a
+            <listitem><para>Behavior of <option>notify</option> is similar to <option>exec</option>; however, it is
4bff0a
+            expected that the service sends a notification message via
4bff0a
+            <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> or an
4bff0a
+            equivalent call when it has finished starting up. systemd will proceed with starting follow-up units after
4bff0a
+            this notification message has been sent. If this option is used, <varname>NotifyAccess=</varname> (see
4bff0a
+            below) should be set to open access to the notification socket provided by systemd. If
4bff0a
+            <varname>NotifyAccess=</varname> is missing or set to <option>none</option>, it will be forcibly set to
4bff0a
+            <option>main</option>. Note that currently <varname>Type=</varname><option>notify</option> will not work if
4bff0a
+            used in combination with <varname>PrivateNetwork=</varname><option>yes</option>.</para></listitem>
4bff0a
+
4bff0a
+            <listitem><para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however,
4bff0a
+            actual execution of the service program is delayed until all active jobs are dispatched. This may be used
4bff0a
+            to avoid interleaving of output of shell services with the status output on the console. Note that this
4bff0a
+            type is useful only to improve console output, it is not useful as a general unit ordering tool, and the
4bff0a
+            effect of this service type is subject to a 5s time-out, after which the service program is invoked
4bff0a
+            anyway.</para></listitem>
4bff0a
+          </itemizedlist>
4bff0a
+
4bff0a
+          <para>It is generally recommended to use <varname>Type=</varname><option>simple</option> for long-running
4bff0a
+          services whenever possible, as it is the simplest and fastest option. However, as this service type won't
4bff0a
+          propagate service start-up failures and doesn't allow ordering of other units against completion of
4bff0a
+          initialization of the service (which for example is useful if clients need to connect to the service through
4bff0a
+          some form of IPC, and the IPC channel is only established by the service itself — in contrast to doing this
4bff0a
+          ahead of time through socket or bus activation or similar), it might not be sufficient for many cases. If so,
4bff0a
+          <option>notify</option> or <option>dbus</option> (the latter only in case the service provides a D-Bus
4bff0a
+          interface) are the preferred options as they allow service program code to precisely schedule when to
4bff0a
+          consider the service started up successfully and when to proceed with follow-up units. The
4bff0a
+          <option>notify</option> service type requires explicit support in the service codebase (as
4bff0a
+          <function>sd_notify()</function> or an equivalent API needs to be invoked by the service at the appropriate
4bff0a
+          time) — if it's not supported, then <option>forking</option> is an alternative: it supports the traditional
4bff0a
+          UNIX service start-up protocol. Finally, <option>exec</option> might be an option for cases where it is
4bff0a
+          enough to ensure the service binary is invoked, and where the service binary itself executes no or little
4bff0a
+          initialization on its own (and its initialization is unlikely to fail). Note that using any type other than
4bff0a
+          <option>simple</option> possibly delays the boot process, as the service manager needs to wait for service
4bff0a
+          initialization to complete. It is hence recommended not to needlessly use any types other than
4bff0a
+          <option>simple</option>. (Also note it is generally not recommended to use <option>idle</option> or
4bff0a
+          <option>oneshot</option> for long-running services.)</para>
4bff0a
         </listitem>
4bff0a
       </varlistentry>
4bff0a