man: extend watchdog docs a bit

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index e444efeb44e70d95aaec0971130b072f1ecc43f1..c57bce0ecf125446c834b409e4b0865f2ccc30d7 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -9,16 +9,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it

-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or

   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

-  General Public License for more details.
+  Lesser General Public License for more details.

 
 

-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License

   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 


@@ -121,12 +121,14 @@
                                 <option>forking</option>,
                                 <option>oneshot</option>,
                                 <option>dbus</option>,
                                 <option>forking</option>,
                                 <option>oneshot</option>,
                                 <option>dbus</option>,

-                                <option>notify</option>.</para>
+                                <option>notify</option> or
+                                <option>idle</option>.</para>

 
                                 <para>If set to
                                 <option>simple</option> (the default
 
                                 <para>If set to
                                 <option>simple</option> (the default

-                                value) it is expected that the process
-                                configured with
+                                value if <varname>BusName=</varname>
+                                is not specified) it is expected that
+                                the process configured with

                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this
                                 mode, if the process offers
                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this
                                 mode, if the process offers


@@ -181,7 +183,9 @@
                                 option configured implicitly gain
                                 dependencies on the
                                 <filename>dbus.socket</filename>
                                 option configured implicitly gain
                                 dependencies on the
                                 <filename>dbus.socket</filename>

-                                unit.</para>
+                                unit. This type is the default if
+                                <varname>BusName=</varname> is
+                                specified.</para>

 
                                 <para>Behaviour of
                                 <option>notify</option> is similar to
 
                                 <para>Behaviour of
                                 <option>notify</option> is similar to


@@ -198,9 +202,19 @@
                                 below) should be set to open access to
                                 the notification socket provided by
                                 systemd. If
                                 below) should be set to open access to
                                 the notification socket provided by
                                 systemd. If

-                                <varname>NotifyAccess=</varname> is not
-                                set, it will implicitly be set to
+                                <varname>NotifyAccess=</varname> is
+                                not set, it will be implicitly set to

                                 <option>main</option>.</para>
                                 <option>main</option>.</para>

+
+                                <para>Behaviour of
+                                <option>idle</option> is very similar
+                                to <option>simple</option>, however
+                                actual execution of a the service
+                                binary is delayed until all jobs are
+                                dispatched. This may be used to avoid
+                                interleaving of output of shell
+                                services with the status output on the
+                                console.</para>

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


@@ -311,20 +325,28 @@
                                 main process of the daemon. The
                                 command line accepts % specifiers as
                                 described in
                                 main process of the daemon. The
                                 command line accepts % specifiers as
                                 described in

-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. On
-                                top of that basic environment variable
-                                substitution is supported, where
-                                <literal>${FOO}</literal> is replaced
-                                by the string value of the environment
-                                variable of the same name. Also
-                                <literal>$FOO</literal> may appear as
-                                separate word on the command line in
-                                which case the variable is replaced by
-                                its value split at whitespaces. Note
-                                that the first argument (i.e. the
-                                binary to execute) may not be a
-                                variable, and must be a literal and
-                                absolute path name.</para></listitem>
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+                                <para>On top of that basic environment
+                                variable substitution is
+                                supported. Use
+                                <literal>${FOO}</literal> as part of a
+                                word, or as word of its own on the
+                                command line, in which case it will be
+                                replaced by the value of the
+                                environment variable including all
+                                whitespace it contains, resulting in a
+                                single argument.  Use
+                                <literal>$FOO</literal> as a separate
+                                word on the command line, in which
+                                case it will be replaced by the value
+                                of the environment variable split up
+                                at whitespace, resulting in no or more
+                                arguments. Note that the first
+                                argument (i.e. the program to execute)
+                                may not be a variable, and must be a
+                                literal and absolute path
+                                name.</para></listitem>

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


@@ -448,7 +470,44 @@
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 logic. Defaults to
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 logic. Defaults to

-                                60s.</para></listitem>
+                                90s, except when <varname>Type=oneshot</varname> is
+                                used in which case the timeout
+                                is disabled by default.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>WatchdogSec=</varname></term>
+                                <listitem><para>Configures the
+                                watchdog timeout for a service. This
+                                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
+                                "keep-alive ping"). If the time
+                                between two such calls is larger than
+                                the configured time then the service
+                                is placed in a failure state. By
+                                setting <varname>Restart=</varname> to
+                                <option>on-failure</option> or
+                                <option>always</option> the service
+                                will be automatically restarted. The
+                                time configured here will be passed to
+                                the executed service process in the
+                                <varname>WATCHDOG_USEC=</varname>
+                                environment variable. This allows
+                                daemons to automatically enable the
+                                keep-alive pinging logic if watchdog
+                                support is enabled for the service. If
+                                this option is used
+                                <varname>NotifyAccess=</varname> (see
+                                below) should be set to open access to
+                                the notification socket provided by
+                                systemd. If
+                                <varname>NotifyAccess=</varname> is
+                                not set, it will be implicitly set to
+                                <option>main</option>. Defaults to 0,
+                                which disables this
+                                feature.</para></listitem>

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


@@ -470,16 +529,19 @@
                                 0. If set to
                                 <option>on-failure</option> it will be
                                 restarted only when it exited with an
                                 0. If set to
                                 <option>on-failure</option> it will be
                                 restarted only when it exited with an

-                                exit code not equalling 0, or when
-                                terminated by a signal. If set to
+                                exit code not equalling 0, when
+                                terminated by a signal, when an
+                                operation 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. If
                                 set to <option>always</option> the
                                 service will be restarted regardless
                                 <option>on-abort</option> it will be
                                 restarted only if it exits due to
                                 reception of an uncaught signal. If
                                 set to <option>always</option> the
                                 service will be restarted regardless

-                                whether it exited cleanly or not, or
+                                whether it exited cleanly or not,

                                 got terminated abnormally by a
                                 got terminated abnormally by a

-                                signal.</para></listitem>
+                                signal or hit a timeout.</para></listitem>

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


@@ -529,36 +591,12 @@
                                 false.</para></listitem>
                         </varlistentry>
 
                                 false.</para></listitem>
                         </varlistentry>
 

-                        <varlistentry>
-                                <term><varname>SysVStartPriority=</varname></term>
-                                <listitem><para>Set the SysV start
-                                priority to use to order this service
-                                in relation to SysV services lacking
-                                LSB headers. This option is only
-                                necessary to fix ordering in relation
-                                to legacy SysV services, that have no
-                                ordering information encoded in the
-                                script headers. As such it should only
-                                be used as temporary compatibility
-                                option, and not be used in new unit
-                                files. Almost always it is a better
-                                choice to add explicit ordering
-                                directives via
-                                <varname>After=</varname> or
-                                <varname>Before=</varname>,
-                                instead. For more details see
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
-                                used, pass an integer value in the
-                                range 0-99.</para></listitem>
-                        </varlistentry>
-

                         <varlistentry>
                                 <term><varname>KillMode=</varname></term>
                                 <listitem><para>Specifies how
                                 processes of this service shall be
                                 killed. One of
                                 <option>control-group</option>,
                         <varlistentry>
                                 <term><varname>KillMode=</varname></term>
                                 <listitem><para>Specifies how
                                 processes of this service shall be
                                 killed. One of
                                 <option>control-group</option>,

-                                <option>process-group</option>,

                                 <option>process</option>,
                                 <option>none</option>.</para>
 
                                 <option>process</option>,
                                 <option>none</option>.</para>
 


@@ -570,10 +608,6 @@
                                 stop command (as configured with
                                 <varname>ExecStop=</varname>) is
                                 executed. If set to
                                 stop command (as configured with
                                 <varname>ExecStop=</varname>) is
                                 executed. If set to

-                                <option>process-group</option> only
-                                the members of the process group of
-                                the main service process are
-                                killed. If set to

                                 <option>process</option> only the main
                                 process itself is killed. If set to
                                 <option>none</option> no process is
                                 <option>process</option> only the main
                                 process itself is killed. If set to
                                 <option>none</option> no process is


@@ -657,10 +691,16 @@
                                 accepted. If <option>all</option> all
                                 services updates from all members of
                                 the service's control group are
                                 accepted. If <option>all</option> all
                                 services updates from all members of
                                 the service's control group are

-                                accepted. This option must be set to
+                                accepted. This option should be set to

                                 open access to the notification socket
                                 when using
                                 open access to the notification socket
                                 when using

-                                <varname>Type=notify</varname> (see above).</para></listitem>
+                                <varname>Type=notify</varname> or
+                                <varname>WatchdogUsec=</varname> (see
+                                above). If those options are used but
+                                <varname>NotifyAccess=</varname> not
+                                configured it will be implicitly set
+                                to
+                                <option>main</option>.</para></listitem>

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


@@ -668,11 +708,11 @@
                                 <listitem><para>Specifies the name of
                                 the socket units this service shall
                                 inherit the sockets from when the
                                 <listitem><para>Specifies the name of
                                 the socket units this service shall
                                 inherit the sockets from when the

-                                service (ignoring the different suffix
-                                of course) is started. Normally it
+                                service is started. Normally it

                                 should not be necessary to use this
                                 setting as all sockets whose unit
                                 shares the same name as the service
                                 should not be necessary to use this
                                 setting as all sockets whose unit
                                 shares the same name as the service

+                                (ignoring the different suffix of course)

                                 are passed to the spawned
                                 process.</para>
 
                                 are passed to the spawned
                                 process.</para>
 


@@ -690,6 +730,101 @@
                                 refers to.</para></listitem>
                         </varlistentry>
 
                                 refers to.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>StartLimitInterval=</varname></term>
+                                <term><varname>StartLimitBurst=</varname></term>
+
+                                <listitem><para>Configure service
+                                start rate limiting. By default
+                                services which are started more often
+                                than 5 times within 10s are not
+                                permitted to start any more times
+                                until the 10s interval ends. With
+                                these two options this rate limiting
+                                may be modified. Use
+                                <varname>StartLimitInterval=</varname>
+                                to configure the checking interval
+                                (defaults to 10s, set to 0 to disable
+                                any kind of rate limiting). Use
+                                <varname>StartLimitBurst=</varname> to
+                                configure how many starts per interval
+                                are allowed (defaults to 5). These
+                                configuration options are particularly
+                                useful in conjunction with
+                                <varname>Restart=</varname>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>StartLimitAction=</varname></term>
+
+                                <listitem><para>Configure the action
+                                to take if the rate limit configured
+                                with
+                                <varname>StartLimitInterval=</varname>
+                                and
+                                <varname>StartLimitBurst=</varname> is
+                                hit. Takes one of
+                                <option>none</option>,
+                                <option>reboot</option>,
+                                <option>reboot-force</option> or
+                                <option>reboot-immediate</option>. If
+                                <option>none</option> is set,
+                                hitting the rate limit will trigger no
+                                action besides that the start will not
+                                be
+                                permitted. <option>reboot</option>
+                                causes a reboot following the normal
+                                shutdown procedure (i.e. equivalent to
+                                <command>systemctl reboot</command>),
+                                <option>reboot-force</option> causes
+                                an forced reboot which will terminate
+                                all processes forcibly but should
+                                cause no dirty file systems on reboot
+                                (i.e. equivalent to <command>systemctl
+                                reboot -f</command>) and
+                                <option>reboot-immediate</option>
+                                causes immediate execution of the
+                                <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                system call, which might result in
+                                data loss.  Defaults to
+                                <option>none</option>.</para></listitem>
+                        </varlistentry>
+
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
+                <title>Compatibility Options</title>
+
+                <para>The following options are also available in the
+                <literal>[Service]</literal> section, but exist purely
+                for compatibility reasons and should not be used in
+                newly written service files.</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>SysVStartPriority=</varname></term>
+                                <listitem><para>Set the SysV start
+                                priority to use to order this service
+                                in relation to SysV services lacking
+                                LSB headers. This option is only
+                                necessary to fix ordering in relation
+                                to legacy SysV services, that have no
+                                ordering information encoded in the
+                                script headers. As such it should only
+                                be used as temporary compatibility
+                                option, and not be used in new unit
+                                files. Almost always it is a better
+                                choice to add explicit ordering
+                                directives via
+                                <varname>After=</varname> or
+                                <varname>Before=</varname>,
+                                instead. For more details see
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
+                                used, pass an integer value in the
+                                range 0-99.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>FsckPassNo=</varname></term>
                                 <listitem><para>Set the fsck passno
                         <varlistentry>
                                 <term><varname>FsckPassNo=</varname></term>
                                 <listitem><para>Set the fsck passno