man: clarify what Restart= means

Related to https://bugzilla.redhat.com/show_bug.cgi?id=957135.

2 files changed, 56 insertions, 24 deletions

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index b82a5c1817..09d1d5ff7d 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -553,8 +553,8 @@
                         <varlistentry>
                                 <term><varname>WatchdogSec=</varname></term>
                                 <listitem><para>Configures the
-                                watchdog timeout for a service. This
-                                is activated when the start-up is
+                                watchdog timeout for a service. The
+                                watchdog is activated when the start-up is
                                 completed. The service must call
                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                 regularly with "WATCHDOG=1" (i.e. the
@@ -588,37 +588,66 @@
                         <varlistentry>
                                 <term><varname>Restart=</varname></term>
                                 <listitem><para>Configures whether the
-                                main service process shall be
-                                restarted when it exits. Takes one of
+                                service shall be restarted when the
+                                service process exits, is killed,
+                                or a timeout is reached. The service
+                                process may be the main service
+                                process, but also one of the processes
+                                specified with
+                                <varname>ExecStartPre=</varname>,
+                                <varname>ExecStartPost=</varname>,
+                                <varname>ExecStopPre=</varname>,
+                                <varname>ExecStopPost=</varname>, or
+                                <varname>ExecReload=</varname>.
+                                When the death of the process is a
+                                result of systemd operation (e.g. service
+                                stop or restart), the service will not be
+                                restarted. Timeouts include missing
+                                the watchdog "keep-alive ping"
+                                deadline and a service start, reload,
+                                and stop operation timeouts.</para>
+
+                                <para>Takes one of
                                 <option>no</option>,
                                 <option>on-success</option>,
                                 <option>on-failure</option>,
-                                <option>on-abort</option> or
+                                <option>on-abort</option>, or
                                 <option>always</option>. If set to
                                 <option>no</option> (the default) the
-                                service will not be restarted when it
-                                exits. If set to
+                                service will not be restarted. If set to
                                 <option>on-success</option> it will be
-                                restarted only when it exited cleanly,
-                                i.e. terminated with an exit code of
-                                0. If set to
-                                <option>on-failure</option> it will be
-                                restarted only when it exited with an
-                                exit code not equaling 0, when
-                                terminated by a signal (including on
+                                restarted only when the service process
+                                exits cleanly.
+                                In this context, a clean exit means
+                                an exit code of 0, or one of the signals
+                                SIGHUP, SIGINT, SIGTERM, or SIGPIPE, and
+                                additonally, exit statuses and signals
+                                specified in <varname>SuccessExitStatus=</varname>.
+                                If set to <option>on-failure</option>
+                                the service will be restarted when the
+                                process exits with an nonzero exit code,
+                                is terminated by a signal (including on
                                 core dump), when an operation (such as
-                                service reload) times out or when the
-                                configured watchdog timeout is
-                                triggered. If set to
-                                <option>on-abort</option> it will be
-                                restarted only if it exits due to
-                                reception of an uncaught signal
-                                (including on core dump). If set to
+                                service reload) times out, and when the
+                                configured watchdog timeout is triggered.
+                                If set to
+                                <option>on-abort</option> the service
+                                will be restarted only if the service
+                                process exits due to an uncaught
+                                signal not specified as a clean exit
+                                status.
+                                If set to
                                 <option>always</option> the service
                                 will be restarted regardless whether
                                 it exited cleanly or not, got
                                 terminated abnormally by a signal or
-                                hit a timeout.</para></listitem>
+                                hit a timeout.</para>
+
+                                <para>In addition to the above settings,
+                                the service will not be restarted if the
+                                exit code or signal is specified in
+                                <varname>RestartPreventExitStatus=</varname>
+                                (see below).</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -631,8 +660,8 @@
                                 code 0 and the signals SIGHUP, SIGINT,
                                 SIGTERM and SIGPIPE. Exit status
                                 definitions can either be numeric exit
-                                codes or termination signal names, and
-                                are separated by spaces. Example:
+                                codes or termination signal names,
+                                separated by spaces. Example:
                                 "<literal>SuccessExitStatus=1 2 8
                                 SIGKILL</literal>", ensures that exit
                                 codes 1, 2, 8 and the termination
diff --git a/src/core/service.c b/src/core/service.c
index cf0bbe05fc..5803f798e0 100644
--- a/src/core/service.c
+++ b/src/core/service.c
@@ -1466,6 +1466,9 @@ static int service_search_main_pid(Service *s) {
         r = unit_watch_pid(UNIT(s), pid);
         if (r < 0)
                 /* FIXME: we need to do something here */
+                log_warning_unit(UNIT(s)->id,
+                                 "Failed to watch PID %lu from service %s",
+                                 (unsigned long) pid, UNIT(s)->id);
                 return r;
 
         return 0;