service: introduce WatchdogSec and hook up the watchdog with the existing failure...

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 94a21d3fe3d99c2160611e590c15d70de69a2344..0b5edb85603059229364f9f8dc4d00af9900c41d 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -119,7 +119,7 @@
                                 start-up type for this service
                                 unit. One of <option>simple</option>,
                                 <option>forking</option>,
                                 start-up type for this service
                                 unit. One of <option>simple</option>,
                                 <option>forking</option>,

-                                <option>finish</option>,
+                                <option>oneshot</option>,

                                 <option>dbus</option>,
                                 <option>notify</option>.</para>
 
                                 <option>dbus</option>,
                                 <option>notify</option>.</para>
 


@@ -129,25 +129,27 @@
                                 configured with
                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this
                                 configured with
                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this

-                                mode, communication channels must be
-                                installed before the daemon is started
-                                up (e.g. sockets set up by systemd,
-                                via socket activation), as systemd
-                                will immediately proceed starting
-                                follow-up units.</para>
+                                mode, if the process offers
+                                functionality to other processes on
+                                the system its communication channels
+                                should be installed before the daemon
+                                is started up (e.g. sockets set up by
+                                systemd, via socket activation), as
+                                systemd will immediately proceed
+                                starting follow-up units.</para>

 
                                 <para>If set to
                                 <option>forking</option> it is
                                 expected that the process configured
                                 with <varname>ExecStart=</varname>
 
                                 <para>If set to
                                 <option>forking</option> it is
                                 expected that the process configured
                                 with <varname>ExecStart=</varname>

-                                will start up and call
-                                <function>fork()</function>. The
-                                parent process is expected to finish
-                                when start-up is complete and all
-                                communication channels set up. The
-                                child continues to run as the main
-                                daemon process. This is the behaviour
-                                of traditional UNIX daemons. If this
+                                will call <function>fork()</function>
+                                as part of its start-up. The parent process is
+                                expected to exit when start-up is
+                                complete and all communication
+                                channels set up. The child continues
+                                to run as the main daemon
+                                process. This is the behaviour of
+                                traditional UNIX daemons. If this

                                 setting is used, it is recommended to
                                 also use the
                                 <varname>PIDFile=</varname> option, so
                                 setting is used, it is recommended to
                                 also use the
                                 <varname>PIDFile=</varname> option, so


@@ -158,11 +160,11 @@
                                 exits.</para>
 
                                 <para>Behaviour of
                                 exits.</para>
 
                                 <para>Behaviour of

-                                <option>finish</option> is similar
+                                <option>oneshot</option> is similar

                                 to <option>simple</option>, however
                                 it is expected that the process has to
                                 exit before systemd starts follow-up
                                 to <option>simple</option>, however
                                 it is expected that the process has to
                                 exit before systemd starts follow-up

-                                units. <varname>ValidNoProcess=</varname>
+                                units. <varname>RemainAfterExit=</varname>

                                 is particularly useful for this type
                                 of service.</para>
 
                                 is particularly useful for this type
                                 of service.</para>
 


@@ -176,9 +178,9 @@
                                 will proceed starting follow-up units
                                 after the D-Bus bus name has been
                                 acquired. Service units with this
                                 will proceed starting follow-up units
                                 after the D-Bus bus name has been
                                 acquired. Service units with this

-                                option configured implicitly have
+                                option configured implicitly gain

                                 dependencies on the
                                 dependencies on the

-                                <filename>dbus.target</filename>
+                                <filename>dbus.socket</filename>

                                 unit.</para>
 
                                 <para>Behaviour of
                                 unit.</para>
 
                                 <para>Behaviour of


@@ -193,17 +195,17 @@
                                 notification message has been sent. If
                                 this option is used
                                 <varname>NotifyAccess=</varname> (see
                                 notification message has been sent. If
                                 this option is used
                                 <varname>NotifyAccess=</varname> (see

-                                below) must be set to open access to
+                                below) should be set to open access to

                                 the notification socket provided by
                                 systemd. If
                                 <varname>NotifyAccess=</varname> is not
                                 the notification socket provided by
                                 systemd. If
                                 <varname>NotifyAccess=</varname> is not

-                                set, it will be implicitly set to
+                                set, it will implicitly be set to

                                 <option>main</option>.</para>
                                 </listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 <option>main</option>.</para>
                                 </listitem>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><varname>ValidNoProcess=</varname></term>
+                                <term><varname>RemainAfterExit=</varname></term>

 
                                 <listitem><para>Takes a boolean value
                                 that specifies whether the service
 
                                 <listitem><para>Takes a boolean value
                                 that specifies whether the service


@@ -213,6 +215,30 @@
                                 </listitem>
                         </varlistentry>
 
                                 </listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>GuessMainPID=</varname></term>
+
+                                <listitem><para>Takes a boolean value
+                                that specifies whether systemd should
+                                try to guess the main PID of a service
+                                should if it cannot be determined
+                                reliably. This option is ignored
+                                unless <option>Type=forking</option>
+                                is set and <option>PIDFile=</option>
+                                is unset because for the other types
+                                or with an explicitly configured PID
+                                file the main PID is always known. The
+                                guessing algorithm might come to
+                                incorrect conclusions if a daemon
+                                consists of more than one process. If
+                                the main PID cannot be determined
+                                failure detection and automatic
+                                restarting of a service will not work
+                                reliably. Defaults to
+                                <option>yes</option>.</para>
+                                </listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>PIDFile=</varname></term>
 
                         <varlistentry>
                                 <term><varname>PIDFile=</varname></term>
 


@@ -221,7 +247,11 @@
                                 daemon. Use of this option is
                                 recommended for services where
                                 <varname>Type=</varname> is set to
                                 daemon. Use of this option is
                                 recommended for services where
                                 <varname>Type=</varname> is set to

-                                <option>forking</option>.</para>
+                                <option>forking</option>. systemd will
+                                read the PID of the main process of
+                                the daemon after start-up of the
+                                service. systemd will not write to the
+                                file configured here.</para>

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


@@ -250,38 +280,59 @@
                                 arguments for the process. It is
                                 mandatory to set this option for all
                                 services. This option may not be
                                 arguments for the process. It is
                                 mandatory to set this option for all
                                 services. This option may not be

-                                specified more than once. Optionally,
-                                if the absolute file name is prefixed
-                                with <literal>@</literal>, the second
-                                token will be passed as
+                                specified more than once, except when
+                                <varname>Type=oneshot</varname> is
+                                used in which case more than one
+                                <varname>ExecStart=</varname> line is
+                                accepted which are then invoked one by
+                                one, sequentially in the order they
+                                appear in the unit file.</para>
+
+                                <para>Optionally, if the absolute file
+                                name is prefixed with
+                                <literal>@</literal>, the second token
+                                will be passed as

                                 <literal>argv[0]</literal> to the
                                 executed process, followed by the
                                 further arguments specified. If the
                                 first token is prefixed with
                                 <literal>argv[0]</literal> to the
                                 executed process, followed by the
                                 further arguments specified. If the
                                 first token is prefixed with

-                                <literal>-</literal> an error code of
+                                <literal>-</literal> an exit code of

                                 the command normally considered a
                                 the command normally considered a

-                                failure is ignored and considered
-                                success. If both <literal>-</literal>
-                                and <literal>@</literal> are used for
-                                the same command the latter must
-                                preceed the latter. Unless
+                                failure (i.e. non-zero exit status or
+                                abnormal exit due to signal) is ignored
+                                and considered success. If both
+                                <literal>-</literal> and
+                                <literal>@</literal> are used for the
+                                same command the former must precede
+                                the latter. Unless

                                 <varname>Type=forking</varname> is
                                 set, the process started via this
                                 command line will be considered the
                                 main process of the daemon. The
                                 command line accepts % specifiers as
                                 described in
                                 <varname>Type=forking</varname> is
                                 set, the process started via this
                                 command line will be considered the
                                 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
-                                seperate word on the command line in
-                                which case the variable is replaced by
-                                its value split at
-                                whitespaces.</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>


@@ -292,14 +343,14 @@
                                 the command in
                                 <varname>ExecStart=</varname>. Multiple
                                 command lines may be concatenated in a
                                 the command in
                                 <varname>ExecStart=</varname>. Multiple
                                 command lines may be concatenated in a

-                                single directive, by seperating them
+                                single directive, by separating them

                                 by semicolons (these semicolons must
                                 by semicolons (these semicolons must

-                                be passed as seperate words). In that
+                                be passed as separate words). In that

                                 case, the commands are executed one
                                 after the other,
                                 serially. Alternatively, these
                                 directives may be specified more than
                                 case, the commands are executed one
                                 after the other,
                                 serially. Alternatively, these
                                 directives may be specified more than

-                                once whith the same effect. However,
+                                once with the same effect. However,

                                 the latter syntax is not recommended
                                 for compatibility with parsers
                                 suitable for XDG
                                 the latter syntax is not recommended
                                 for compatibility with parsers
                                 suitable for XDG


@@ -329,7 +380,7 @@
                                 daemon, and may be used for command
                                 lines like the following:
                                 <command>/bin/kill -HUP
                                 daemon, and may be used for command
                                 lines like the following:
                                 <command>/bin/kill -HUP

-                                $(MAINPID)</command>.</para></listitem>
+                                $MAINPID</command>.</para></listitem>

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


@@ -353,7 +404,7 @@
                                 requested. Specifier and environment
                                 variable substitution is supported
                                 (including
                                 requested. Specifier and environment
                                 variable substitution is supported
                                 (including

-                                <literal>$(MAINPID)</literal>, see
+                                <literal>$MAINPID</literal>, see

                                 above).</para></listitem>
                         </varlistentry>
 
                                 above).</para></listitem>
                         </varlistentry>
 


@@ -405,25 +456,52 @@
                                 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.</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". If the time
+                                between two such calls is larger than
+                                the configured time then the service
+                                enters a failure state. By setting
+                                <term><varname>Restart=</varname></term>
+                                to <option>on-failure</option> or
+                                <option>always</option> the service can
+                                be restarted. Defaults to 0s, which
+                                disables this feature.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>Restart=</varname></term>
                                 <listitem><para>Configures whether the
                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>Restart=</varname></term>
                                 <listitem><para>Configures whether the

-                                main service process shall be restarted when
-                                it exists. Takes one of
-                                <option>once</option>,
-                                <option>restart-on-success</option> or
-                                <option>restart-always</option>. If
-                                set to <option>once</option> (the
-                                default) the service will not be
-                                restarted when it exits. If set to
-                                <option>restart-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>restart-always</option> the
+                                main service process shall be
+                                restarted when it exits. Takes one of
+                                <option>no</option>,
+                                <option>on-success</option>,
+                                <option>on-failure</option>,
+                                <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
+                                <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 equalling 0, or when
+                                terminated by a signal. 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
                                 whether it exited cleanly or not, or
                                 got terminated abnormally by a
                                 service will be restarted regardless
                                 whether it exited cleanly or not, or
                                 got terminated abnormally by a


@@ -506,7 +584,6 @@
                                 processes of this service shall be
                                 killed. One of
                                 <option>control-group</option>,
                                 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>
 


@@ -518,10 +595,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


@@ -533,20 +606,44 @@
                                 group and the control group continues
                                 to exist after stop unless it is
                                 empty. Defaults to
                                 group and the control group continues
                                 to exist after stop unless it is
                                 empty. Defaults to

-                                <option>control-croup</option>.</para>
+                                <option>control-group</option>.</para>

 
                                 <para>Processes will first be
 
                                 <para>Processes will first be

-                                terminated via SIGTERM. If then after
-                                a delay (configured via the
+                                terminated via SIGTERM (unless the
+                                signal to send is changed via
+                                <varname>KillSignal=</varname>). If
+                                then after a delay (configured via the

                                 <varname>TimeoutSec=</varname> option)
                                 processes still remain, the
                                 termination request is repeated with
                                 <varname>TimeoutSec=</varname> option)
                                 processes still remain, the
                                 termination request is repeated with

-                                the SIGKILL signal. See
+                                the SIGKILL signal (unless this is
+                                disabled via the
+                                <varname>SendSIGKILL=</varname>
+                                option). See

                                 <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                 for more
                                 information.</para></listitem>
                         </varlistentry>
 
                                 <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                 for more
                                 information.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>KillSignal=</varname></term>
+                                <listitem><para>Specifies which signal
+                                to use when killing a
+                                service. Defaults to SIGTERM.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>SendSIGKILL=</varname></term>
+                                <listitem><para>Specifies whether to
+                                send SIGKILL to remaining processes
+                                after a timeout, if the normal
+                                shutdown procedure left processes of
+                                the service around. Takes a boolean
+                                value. Defaults to "yes".
+                                </para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>NonBlocking=</varname></term>
                                 <listitem><para>Set O_NONBLOCK flag
                         <varlistentry>
                                 <term><varname>NonBlocking=</varname></term>
                                 <listitem><para>Set O_NONBLOCK flag


@@ -573,7 +670,7 @@
                                 <option>main</option> or
                                 <option>all</option>. If
                                 <option>none</option> no daemon status
                                 <option>main</option> or
                                 <option>all</option>. If
                                 <option>none</option> no daemon status

-                                updates are accepted by the service
+                                updates are accepted from the service

                                 processes, all status update messages
                                 are ignored. If <option>main</option>
                                 only service updates sent from the
                                 processes, all status update messages
                                 are ignored. If <option>main</option>
                                 only service updates sent from the


@@ -587,6 +684,60 @@
                                 <varname>Type=notify</varname> (see above).</para></listitem>
                         </varlistentry>
 
                                 <varname>Type=notify</varname> (see above).</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>Sockets=</varname></term>
+                                <listitem><para>Specifies the name of
+                                the socket units this service shall
+                                inherit the sockets from when the
+                                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
+                                (ignoring the different suffix of course)
+                                are passed to the spawned
+                                process.</para>
+
+                                <para>Note that the same socket may be
+                                passed to multiple processes at the
+                                same time. Also note that a different
+                                service may be activated on incoming
+                                traffic than inherits the sockets. Or
+                                in other words: The
+                                <varname>Service=</varname> setting of
+                                <filename>.socket</filename> units
+                                doesn't have to match the inverse of the
+                                <varname>Sockets=</varname> setting of
+                                the <filename>.service</filename> it
+                                refers to.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>FsckPassNo=</varname></term>
+                                <listitem><para>Set the fsck passno
+                                priority to use to order this service
+                                in relation to other file system
+                                checking services. This option is only
+                                necessary to fix ordering in relation
+                                to fsck jobs automatically created for
+                                all <filename>/etc/fstab</filename>
+                                entries with a value in the fs_passno
+                                column > 0. As such it should only be
+                                used as option for fsck
+                                services. 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
+                                same range as
+                                <filename>/etc/fstab</filename>'s
+                                fs_passno column. See
+                                <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for details.</para></listitem>
+                        </varlistentry>
+

                 </variablelist>
         </refsect1>
 
                 </variablelist>
         </refsect1>