journal: when browsing the journal via browse.html allow clicking on entries to show...

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 38a4035f67cb001825a693664f30ec1bf75182bb..339dea9aa503d8ab3787a3ea68edb8f38b7f4dc5 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -72,7 +72,10 @@
                 <para>Additional options are listed in
                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                 which define the execution environment the commands
                 <para>Additional options are listed in
                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                 which define the execution environment the commands

-                are executed in.</para>
+                are executed in, and in
+                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                which define the way the processes of the service are
+                terminated.</para>

 
                 <para>Unless <varname>DefaultDependencies=</varname>
                 is set to <option>false</option>, service units will
 
                 <para>Unless <varname>DefaultDependencies=</varname>
                 is set to <option>false</option>, service units will


@@ -112,7 +115,9 @@
                 supervises. A number of options that may be used in
                 this section are shared with other unit types. These
                 options are documented in
                 supervises. A number of options that may be used in
                 this section are shared with other unit types. These
                 options are documented in

-                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
+                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                and
+                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The

                 options specific to the <literal>[Service]</literal>
                 section of service units are the following:</para>
 
                 options specific to the <literal>[Service]</literal>
                 section of service units are the following:</para>
 


@@ -155,7 +160,7 @@
                                 complete and all communication
                                 channels set up. The child continues
                                 to run as the main daemon
                                 complete and all communication
                                 channels set up. The child continues
                                 to run as the main daemon

-                                process. This is the behaviour of
+                                process. This is the behavior of

                                 traditional UNIX daemons. If this
                                 setting is used, it is recommended to
                                 also use the
                                 traditional UNIX daemons. If this
                                 setting is used, it is recommended to
                                 also use the


@@ -166,7 +171,7 @@
                                 soon as the parent process
                                 exits.</para>
 
                                 soon as the parent process
                                 exits.</para>
 

-                                <para>Behaviour of
+                                <para>Behavior of

                                 <option>oneshot</option> is similar
                                 to <option>simple</option>, however
                                 it is expected that the process has to
                                 <option>oneshot</option> is similar
                                 to <option>simple</option>, however
                                 it is expected that the process has to


@@ -175,7 +180,7 @@
                                 is particularly useful for this type
                                 of service.</para>
 
                                 is particularly useful for this type
                                 of service.</para>
 

-                                <para>Behaviour of
+                                <para>Behavior of

                                 <option>dbus</option> is similar to
                                 <option>simple</option>, however it is
                                 expected that the daemon acquires a
                                 <option>dbus</option> is similar to
                                 <option>simple</option>, however it is
                                 expected that the daemon acquires a


@@ -192,7 +197,7 @@
                                 <varname>BusName=</varname> is
                                 specified.</para>
 
                                 <varname>BusName=</varname> is
                                 specified.</para>
 

-                                <para>Behaviour of
+                                <para>Behavior of

                                 <option>notify</option> is similar to
                                 <option>simple</option>, however it is
                                 expected that the daemon sends a
                                 <option>notify</option> is similar to
                                 <option>simple</option>, however it is
                                 expected that the daemon sends a


@@ -211,7 +216,7 @@
                                 not set, it will be implicitly set to
                                 <option>main</option>.</para>
 
                                 not set, it will be implicitly set to
                                 <option>main</option>.</para>
 

-                                <para>Behaviour of
+                                <para>Behavior of

                                 <option>idle</option> is very similar
                                 to <option>simple</option>, however
                                 actual execution of a the service
                                 <option>idle</option> is very similar
                                 to <option>simple</option>, however
                                 actual execution of a the service


@@ -351,7 +356,16 @@
                                 argument (i.e. the program to execute)
                                 may not be a variable, and must be a
                                 literal and absolute path
                                 argument (i.e. the program to execute)
                                 may not be a variable, and must be a
                                 literal and absolute path

-                                name.</para></listitem>
+                                name.</para>
+
+                                <para>Note that this setting does not
+                                directly support shell command
+                                lines. If shell command lines are to
+                                be used they need to be passed
+                                explicitly to a shell implementation
+                                of some kind. Example:
+                                <literal>ExecStart=/bin/sh -c 'dmesg | tac'</literal></para>
+                                </listitem>

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


@@ -417,12 +431,13 @@
                                 configured in this option are run are
                                 terminated according to the
                                 <varname>KillMode=</varname> setting
                                 configured in this option are run are
                                 terminated according to the
                                 <varname>KillMode=</varname> setting

-                                (see below). If this option is not
-                                specified the process is terminated
-                                right-away when service stop is
-                                requested. Specifier and environment
-                                variable substitution is supported
-                                (including
+                                (see
+                                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
+                                this option is not specified the
+                                process is terminated right-away when
+                                service stop is requested. Specifier
+                                and environment variable substitution
+                                is supported (including

                                 <literal>$MAINPID</literal>, see
                                 above).</para></listitem>
                         </varlistentry>
                                 <literal>$MAINPID</literal>, see
                                 above).</para></listitem>
                         </varlistentry>


@@ -457,27 +472,49 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><varname>TimeoutSec=</varname></term>
+                                <term><varname>TimeoutStartSec=</varname></term>

                                 <listitem><para>Configures the time to
                                 <listitem><para>Configures the time to

-                                wait for start-up and stop. If a
+                                wait for start-up. If a

                                 daemon service does not signal
                                 start-up completion within the
                                 daemon service does not signal
                                 start-up completion within the

-                                configured time the service will be
+                                configured time, the service will be

                                 considered failed and be shut down
                                 considered failed and be shut down

-                                again. If a service is asked to stop
-                                but does not terminate in the
-                                specified time it will be terminated
+                                again.
+                                Takes a unit-less value in seconds, or a
+                                time span value such as "5min
+                                20s". Pass 0 to disable the timeout
+                                logic. Defaults to 90s, except when
+                                <varname>Type=oneshot</varname> is
+                                used in which case the timeout
+                                is disabled by default.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>TimeoutStopSec=</varname></term>
+                                <listitem><para>Configures the time to
+                                wait for stop. If a service is asked
+                                to stop but does not terminate in the
+                                specified time, it will be terminated

                                 forcibly via SIGTERM, and after
                                 another delay of this time with
                                 forcibly via SIGTERM, and after
                                 another delay of this time with

-                                SIGKILL. (See
+                                SIGKILL (See

                                 <varname>KillMode=</varname>
                                 <varname>KillMode=</varname>

-                                below.) Takes a unit-less value in seconds, or a
+                                in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+                                Takes a unit-less value in seconds, or a

                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout

-                                logic. Defaults to
-                                90s, except when <varname>Type=oneshot</varname> is
-                                used in which case the timeout
-                                is disabled by default.</para></listitem>
+                                logic. Defaults to 90s.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>TimeoutSec=</varname></term>
+                                <listitem><para>A shorthand for configuring
+                                both <varname>TimeoutStartSec=</varname>
+                                and <varname>TimeoutStopSec=</varname>
+                                to the specified value.
+                                </para></listitem>

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


@@ -551,6 +588,49 @@
                                 hit a timeout.</para></listitem>
                         </varlistentry>
 
                                 hit a timeout.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>SuccessExitStatus=</varname></term>
+                                <listitem><para>Takes a list of exit
+                                status definitions that when returned
+                                by the main service process will be
+                                considered successful termination, in
+                                addition to the normal successful exit
+                                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:
+                                "<literal>SuccessExitStatus=1 2 8
+                                SIGKILL</literal>", ensures that exit
+                                codes 1, 2, 8 and the termination
+                                signal SIGKILL are considered clean
+                                service
+                                terminations.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>RestartPreventExitStatus=</varname></term>
+                                <listitem><para>Takes a list of exit
+                                status definitions that when returned
+                                by the main service process will
+                                prevent automatic service restarts
+                                regardless of the restart setting
+                                configured with
+                                <varname>Restart=</varname>. Exit
+                                status definitions can either be
+                                numeric exit codes or termination
+                                signal names, and are separated by
+                                spaces. Defaults to the empty list, so
+                                that by default no exit status is
+                                excluded from the configured restart
+                                logic. Example:
+                                "<literal>RestartPreventExitStatus=1 6
+                                SIGABRT</literal>", ensures that exit
+                                codes 1 and 6 and the termination signal
+                                SIGABRT will not result in automatic
+                                service restarting.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>PermissionsStartOnly=</varname></term>
                                 <listitem><para>Takes a boolean
                         <varlistentry>
                                 <term><varname>PermissionsStartOnly=</varname></term>
                                 <listitem><para>Takes a boolean


@@ -598,72 +678,6 @@
                                 false.</para></listitem>
                         </varlistentry>
 
                                 false.</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>,
-                                <option>process</option>,
-                                <option>none</option>.</para>
-
-                                <para>If set to
-                                <option>control-group</option> all
-                                remaining processes in the control
-                                group of this service will be
-                                terminated on service stop, after the
-                                stop command (as configured with
-                                <varname>ExecStop=</varname>) is
-                                executed. If set to
-                                <option>process</option> only the main
-                                process itself is killed. If set to
-                                <option>none</option> no process is
-                                killed. In this case only the stop
-                                command will be executed on service
-                                stop, but no process be killed
-                                otherwise. Processes remaining alive
-                                after stop are left in their control
-                                group and the control group continues
-                                to exist after stop unless it is
-                                empty. Defaults to
-                                <option>control-group</option>.</para>
-
-                                <para>Processes will first be
-                                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
-                                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>
-
-                        <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


@@ -818,6 +832,13 @@
                         </varlistentry>
 
                 </variablelist>
                         </varlistentry>
 
                 </variablelist>

+
+                <para>Check
+                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                and
+                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                for more settings.</para>
+

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


@@ -888,7 +909,8 @@
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>

                   </para>
         </refsect1>
 
                   </para>
         </refsect1>