man: add sd_event_add_child(3)

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 1d804807721d5a613d51bf07ac75638791c11b73..b9a2f8d82f952532ad8901827b8c10e1620bfdd8 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -139,9 +139,10 @@
 
                                 <para>If set to
                                 <option>simple</option> (the default
 
                                 <para>If set to
                                 <option>simple</option> (the default

-                                value if neither
+                                if neither

                                 <varname>Type=</varname> nor
                                 <varname>Type=</varname> nor

-                                <varname>BusName=</varname> are
+                                <varname>BusName=</varname>, but
+                                <varname>ExecStart=</varname> are

                                 specified), it is expected that the
                                 process configured with
                                 <varname>ExecStart=</varname> is the
                                 specified), it is expected that the
                                 process configured with
                                 <varname>ExecStart=</varname> is the


@@ -177,13 +178,17 @@
                                 exits.</para>
 
                                 <para>Behavior of
                                 exits.</para>
 
                                 <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

                                 exit before systemd starts follow-up
                                 units. <varname>RemainAfterExit=</varname>
                                 is particularly useful for this type
                                 exit before systemd starts follow-up
                                 units. <varname>RemainAfterExit=</varname>
                                 is particularly useful for this type

-                                of service.</para>
+                                of service. This is the implied
+                                default if neither
+                                <varname>Type=</varname> or
+                                <varname>ExecStart=</varname> are
+                                specified.</para>

 
                                 <para>Behavior of
                                 <option>dbus</option> is similar to
 
                                 <para>Behavior of
                                 <option>dbus</option> is similar to


@@ -302,6 +307,47 @@
                                 </listitem>
                         </varlistentry>
 
                                 </listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>BusPolicy=</varname></term>
+
+                                <listitem><para>If specified, a custom
+                                <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
+                                endpoint will be created and installed as the
+                                default bus node for the service. Such a custom
+                                endpoint can hold an own set of policy rules
+                                that are enforced on top of the bus-wide ones.
+                                The custom endpoint is named after the service
+                                it was created for, and its node will be
+                                bind-mounted over the default bus node
+                                location, so the service can only access the
+                                bus through its own endpoint. Note that custom
+                                bus endpoints default to a 'deny all' policy.
+                                Hence, if at least one
+                                <varname>BusPolicy=</varname> directive is
+                                given, you have to make sure to add explicit
+                                rules for everything the service should be able
+                                to do.</para>
+                                <para>The value of this directive is comprised
+                                of two parts; the bus name, and a verb to
+                                specify to granted access, which is one of
+                                <option>see</option>,
+                                <option>talk</option>, or
+                                <option>own</option>.
+                                <option>talk</option> implies
+                                <option>see</option>, and <option>own</option>
+                                implies both <option>talk</option> and
+                                <option>see</option>.
+                                If multiple access levels are specified for the
+                                same bus name, the most powerful one takes
+                                effect.
+                                </para>
+                                <para>Examples:</para>
+                                <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
+                                <programlisting>BusPolicy=org.foo.bar see</programlisting>
+                                <para>This option is only available on kdbus enabled systems.</para>
+                                </listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                         <varlistentry>
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their


@@ -313,22 +359,27 @@
 
                                 <para>When <varname>Type</varname> is
                                 not <option>oneshot</option>, only one
 
                                 <para>When <varname>Type</varname> is
                                 not <option>oneshot</option>, only one

-                                command may be given. When
+                                command may and must be given. When

                                 <varname>Type=oneshot</varname> is
                                 <varname>Type=oneshot</varname> is

-                                used, more than one command may be
-                                specified. Multiple command lines may
-                                be concatenated in a single directive
-                                by separating them with semicolons
-                                (these semicolons must be passed as
-                                separate words). Alternatively, this
-                                directive may be specified more than
-                                once with the same effect.
-                                Lone semicolons may be escaped as
+                                used, none or more than one command
+                                may be specified. Multiple command
+                                lines may be concatenated in a single
+                                directive by separating them with
+                                semicolons (these semicolons must be
+                                passed as separate
+                                words). Alternatively, this directive
+                                may be specified more than once with
+                                the same effect.  Lone semicolons may
+                                be escaped as

                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the
                                 list of commands to start is reset,
                                 prior assignments of this option will
                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the
                                 list of commands to start is reset,
                                 prior assignments of this option will

-                                have no effect.</para>
+                                have no effect. If no
+                                <varname>ExecStart=</varname> is
+                                specified, then the service must have
+                                <varname>RemainAfterExit=yes</varname>
+                                set.</para>

 
                                 <para>Each command line is split on
                                 whitespace, with the first item being
 
                                 <para>Each command line is split on
                                 whitespace, with the first item being


@@ -605,11 +656,12 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 time span value such as "5min
                                 20s". Pass <literal>0</literal> to
                                 disable the timeout logic. Defaults to
                                 time span value such as "5min
                                 20s". Pass <literal>0</literal> to
                                 disable the timeout logic. Defaults to

-                                <varname>TimeoutStartSec=</varname> from
+                                <varname>DefaultTimeoutStartSec=</varname> from

                                 the manager configuration file, except
                                 when <varname>Type=oneshot</varname> is
                                 used, in which case the timeout
                                 the manager configuration file, except
                                 when <varname>Type=oneshot</varname> is
                                 used, in which case the timeout

-                                is disabled by default.
+                                is disabled by default
+                                (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).

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


@@ -628,8 +680,9 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 time span value such as "5min
                                 20s". Pass <literal>0</literal> to disable
                                 the timeout logic. Defaults to
                                 time span value such as "5min
                                 20s". Pass <literal>0</literal> to disable
                                 the timeout logic. Defaults to

-                                <varname>TimeoutStartSec=</varname> from the
-                                manager configuration file.
+                                <varname>DefaultTimeoutStopSec=</varname> from the
+                                manager configuration file
+                                (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).

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


@@ -825,10 +878,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                         </tgroup>
                                 </table>
 
                                         </tgroup>
                                 </table>
 

-                                <para>In addition to the above settings,
-                                the service will not be restarted if the
-                                exit code or signal is specified in
+                                <para>As exceptions to the setting
+                                above the service will not be
+                                restarted if the exit code or signal
+                                is specified in

                                 <varname>RestartPreventExitStatus=</varname>
                                 <varname>RestartPreventExitStatus=</varname>

+                                (see below). Also, the services will
+                                always be restarted if the exit code
+                                or signal is specified in
+                                <varname>RestartForceExitStatus=</varname>

                                 (see below).</para>
 
                                 <para>Setting this to
                                 (see below).</para>
 
                                 <para>Setting this to


@@ -838,8 +896,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 reliability by attempting automatic
                                 recovery from errors. For services
                                 that shall be able to terminate on
                                 reliability by attempting automatic
                                 recovery from errors. For services
                                 that shall be able to terminate on

-                                their own choice (and avoiding
-                                immediate restart),
+                                their own choice (and avoid
+                                immediate restarting),

                                 <option>on-abnormal</option> is an
                                 alternative choice.</para>
                                 </listitem>
                                 <option>on-abnormal</option> is an
                                 alternative choice.</para>
                                 </listitem>


@@ -857,7 +915,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 definitions can either be numeric exit
                                 codes or termination signal names,
                                 separated by spaces. For example:
                                 definitions can either be numeric exit
                                 codes or termination signal names,
                                 separated by spaces. For example:

-                                <programlisting>SuccessExitStatus=1 2 8 <constant>SIGKILL</constant></programlisting>
+                                <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>

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


@@ -897,9 +955,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 spaces. Defaults to the empty list, so
                                 that, by default, no exit status is
                                 excluded from the configured restart
                                 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
+                                logic. For example:
+                                <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit

                                 codes 1 and 6 and the termination
                                 signal <constant>SIGABRT</constant> will
                                 not result in automatic service
                                 codes 1 and 6 and the termination
                                 signal <constant>SIGABRT</constant> will
                                 not result in automatic service


@@ -913,6 +970,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 effect.</para></listitem>
                         </varlistentry>
 
                                 effect.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>RestartForceExitStatus=</varname></term>
+                                <listitem><para>Takes a list of exit
+                                status definitions that when returned
+                                by the main service process will force
+                                automatic service restarts, regardless
+                                of the restart setting configured with
+                                <varname>Restart=</varname>. The
+                                argument format is similar to
+                                <varname>RestartPreventExitStatus=</varname>.</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


@@ -1103,29 +1172,49 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 hit. Takes one of
                                 <option>none</option>,
                                 <option>reboot</option>,
                                 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>
+                                <option>reboot-force</option>,
+                                <option>reboot-immediate</option>,
+                                <option>poweroff</option>,
+                                <option>poweroff-force</option> or
+                                <option>poweroff-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>).
                                 causes a reboot following the normal
                                 shutdown procedure (i.e. equivalent to
                                 <command>systemctl reboot</command>).

-                                <option>reboot-force</option> causes
-                                a forced reboot which will terminate
-                                all processes forcibly but should
-                                cause no dirty file systems on reboot
+                                <option>reboot-force</option> causes a
+                                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
                                 (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
+                                data loss. Similar,
+                                <option>poweroff</option>,
+                                <option>poweroff-force</option>,
+                                <option>poweroff-immediate</option>
+                                have the effect of powering down the
+                                system with similar
+                                semantics. Defaults to

                                 <option>none</option>.</para></listitem>
                         </varlistentry>
 
                                 <option>none</option>.</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>
+

                         <varlistentry>
                                 <term><varname>RebootArgument=</varname></term>
                                 <listitem><para>Configure the optional
                         <varlistentry>
                                 <term><varname>RebootArgument=</varname></term>
                                 <listitem><para>Configure the optional


@@ -1133,23 +1222,13 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                 system call if
                                 <varname>StartLimitAction=</varname>
                                 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                 system call if
                                 <varname>StartLimitAction=</varname>

+                                or <varname>FailureAction=</varname>

                                 is a reboot action. This works just
                                 like the optional argument to
                                 <command>systemctl reboot</command>
                                 command.</para></listitem>
                         </varlistentry>
 
                                 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


@@ -1198,7 +1277,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                   <title>See Also</title>
                   <para>
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                   <title>See Also</title>
                   <para>
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

-                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,