tmpfiles: don't do automatic cleanup in $XDG_RUNTIME_DIR

[elogind.git] / man / systemd.service.xml

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 8ad665643db0202b6bdaa2dc248cb2a34afc8ccb..1d804807721d5a613d51bf07ac75638791c11b73 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -519,6 +519,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 following:</para>
 
                                 <programlisting>/bin/kill -HUP $MAINPID</programlisting>
                                 following:</para>
 
                                 <programlisting>/bin/kill -HUP $MAINPID</programlisting>

+
+                                <para>Note however that reloading a
+                                daemon by sending a signal (as with
+                                the example line above) is usually not
+                                a good choice, because this is an
+                                asynchronous operation and hence not
+                                suitable to order reloads of multiple
+                                services against each other. It is
+                                strongly recommended to set
+                                <varname>ExecReload=</varname> to a
+                                command that not only triggers a
+                                configuration reload of the daemon,
+                                but also synchronously waits for it to
+                                complete.</para>

                                 </listitem>
                         </varlistentry>
 
                                 </listitem>
                         </varlistentry>
 


@@ -674,7 +688,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 processes specified with
                                 <varname>ExecStartPre=</varname>,
                                 <varname>ExecStartPost=</varname>,
                                 processes specified with
                                 <varname>ExecStartPre=</varname>,
                                 <varname>ExecStartPost=</varname>,

-                                <varname>ExecStopPre=</varname>,
+                                <varname>ExecStop=</varname>,

                                 <varname>ExecStopPost=</varname>, or
                                 <varname>ExecReload=</varname>.
                                 When the death of the process is a
                                 <varname>ExecStopPost=</varname>, or
                                 <varname>ExecReload=</varname>.
                                 When the death of the process is a


@@ -689,51 +703,146 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <option>no</option>,
                                 <option>on-success</option>,
                                 <option>on-failure</option>,
                                 <option>no</option>,
                                 <option>on-success</option>,
                                 <option>on-failure</option>,

+                                <option>on-abnormal</option>,

                                 <option>on-watchdog</option>,
                                 <option>on-abort</option>, or
                                 <option>always</option>. If set to
                                 <option>no</option> (the default), the
                                 <option>on-watchdog</option>,
                                 <option>on-abort</option>, or
                                 <option>always</option>. If set to
                                 <option>no</option> (the default), the

-                                service will not be restarted. If set to
-                                <option>on-success</option>, it will be
-                                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
+                                service will not be restarted. If set
+                                to <option>on-success</option>, it
+                                will be 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

                                 <constant>SIGHUP</constant>,
                                 <constant>SIGINT</constant>,
                                 <constant>SIGHUP</constant>,
                                 <constant>SIGINT</constant>,

-                                <constant>SIGTERM</constant>,
-                                or <constant>SIGPIPE</constant>, and
-                                additionally, exit statuses and signals
-                                specified in <varname>SuccessExitStatus=</varname>.
+                                <constant>SIGTERM</constant> or
+                                <constant>SIGPIPE</constant>, and
+                                additionally, exit statuses and
+                                signals specified in
+                                <varname>SuccessExitStatus=</varname>.

                                 If set to <option>on-failure</option>,
                                 the service will be restarted when the
                                 If set to <option>on-failure</option>,
                                 the service will be restarted when the

-                                process exits with a non-zero exit code,
-                                is terminated by a signal (including on
-                                core dump), when an operation (such as
-                                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>on-watchdog</option>, the service
-                                will be restarted only if the watchdog
-                                timeout for the service expires.
-                                If set to
+                                process exits with a non-zero exit
+                                code, is terminated by a signal
+                                (including on core dump, but excluding
+                                the aforementiond four signals), when
+                                an operation (such as service reload)
+                                times out, and when the configured
+                                watchdog timeout is triggered.  If set
+                                to <option>on-abnormal</option>, the
+                                service will be restarted when the
+                                process is terminated by a signal
+                                (including on core dump, excluding the
+                                aforementioned four signals), when an
+                                operation times out, or when the
+                                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>on-watchdog</option>, the
+                                service will be restarted only if the
+                                watchdog timeout for the service
+                                expires.  If set to

                                 <option>always</option>, the service
                                 <option>always</option>, the service

-                                will be restarted regardless of whether
-                                it exited cleanly or not, got
+                                will be restarted regardless of
+                                whether it exited cleanly or not, got

                                 terminated abnormally by a signal, or
                                 hit a timeout.</para>
 
                                 terminated abnormally by a signal, or
                                 hit a timeout.</para>
 

+                                <table>
+                                        <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
+
+                                        <tgroup cols='2'>
+                                                <colspec colname='path' />
+                                                <colspec colname='expl' />
+                                                <thead>
+                                                        <row>
+                                                                <entry>Restart settings/Exit causes</entry>
+                                                                <entry><option>no</option></entry>
+                                                                <entry><option>always</option></entry>
+                                                                <entry><option>on-success</option></entry>
+                                                                <entry><option>on-failure</option></entry>
+                                                                <entry><option>on-abnormal</option></entry>
+                                                                <entry><option>on-abort</option></entry>
+                                                                <entry><option>on-watchdog</option></entry>
+                                                        </row>
+                                                </thead>
+                                                <tbody>
+                                                        <row>
+                                                                <entry>Clean exit code or signal</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry/>
+                                                                <entry/>
+                                                                <entry/>
+                                                        </row>
+                                                        <row>
+                                                                <entry>Unclean exit code</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry/>
+                                                                <entry/>
+                                                        </row>
+                                                        <row>
+                                                                <entry>Unclean signal</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry>X</entry>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                        </row>
+                                                        <row>
+                                                                <entry>Timeout</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry/>
+                                                        </row>
+                                                        <row>
+                                                                <entry>Watchdog</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                                <entry>X</entry>
+                                                                <entry/>
+                                                                <entry>X</entry>
+                                                        </row>
+                                                </tbody>
+                                        </tgroup>
+                                </table>
+

                                 <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>
                                 <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>
+                                (see below).</para>
+
+                                <para>Setting this to
+                                <option>on-failure</option> is the
+                                recommended choice for long-running
+                                services, in order to increase
+                                reliability by attempting automatic
+                                recovery from errors. For services
+                                that shall be able to terminate on
+                                their own choice (and avoiding
+                                immediate restart),
+                                <option>on-abnormal</option> is an
+                                alternative choice.</para>
+                                </listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -747,10 +856,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
                                 definitions can either be numeric exit
                                 codes or termination signal names,
                                 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
                                 definitions can either be numeric exit
                                 codes or termination signal names,

-                                separated by spaces. Signals will only
-                                be considered if the service does not implement
-                                a signal handler and exits as a direct result
-                                of receiving the signal. For example:
+                                separated by spaces. For example:

                                 <programlisting>SuccessExitStatus=1 2 8 <constant>SIGKILL</constant></programlisting>
                                 ensures that exit codes 1, 2, 8 and
                                 the termination signal
                                 <programlisting>SuccessExitStatus=1 2 8 <constant>SIGKILL</constant></programlisting>
                                 ensures that exit codes 1, 2, 8 and
                                 the termination signal


@@ -767,7 +873,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 Programs should instead perform cleanup and kill themselves with the same signal instead. See
                                 <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
 
                                 Programs should instead perform cleanup and kill themselves with the same signal instead. See
                                 <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
 

-                                <para>This option may appear more than once
+                                <para>This option may appear more than once,

                                 in which case the list of successful
                                 exit statuses is merged. If the empty
                                 string is assigned to this option, the
                                 in which case the list of successful
                                 exit statuses is merged. If the empty
                                 string is assigned to this option, the


@@ -1020,6 +1126,30 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <option>none</option>.</para></listitem>
                         </varlistentry>
 
                                 <option>none</option>.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>RebootArgument=</varname></term>
+                                <listitem><para>Configure the optional
+                                argument for the
+                                <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                system call if
+                                <varname>StartLimitAction=</varname>
+                                is a reboot action. This works just
+                                like the optional argument to
+                                <command>systemctl reboot</command>
+                                command.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>FailureAction=</varname></term>
+                                <listitem><para>Configure the action
+                                to take when the service enters a failed
+                                state. Takes the same values as
+                                <varname>StartLimitAction=</varname>
+                                and executes the same actions.
+                                Defaults to <option>none</option>.
+                                </para></listitem>
+                        </varlistentry>
+

                 </variablelist>
 
                 <para>Check
                 </variablelist>
 
                 <para>Check