diff options
Diffstat (limited to 'man/systemd.service.xml')
| -rw-r--r-- | man/systemd.service.xml | 176 |
1 files changed, 48 insertions, 128 deletions
diff --git a/man/systemd.service.xml b/man/systemd.service.xml index d7b19ee27f..e55534700a 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -273,42 +273,6 @@ </varlistentry> <varlistentry> - <term><varname>BusPolicy=</varname></term> - - <listitem><para>If specified, a custom kdbus - 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 arguments that are executed when this service is started. The value is split into @@ -371,7 +335,7 @@ with a <literal>-</literal> exit successfully.</para> <para><varname>ExecStartPost=</varname> commands are only run after - the service has started, as determined by <varname>Type=</varname> + the service has started successfully, as determined by <varname>Type=</varname> (i.e. the process has been started for <varname>Type=simple</varname> or <varname>Type=idle</varname>, the process exits successfully for <varname>Type=oneshot</varname>, the initial process exits successfully @@ -383,6 +347,11 @@ used to start long-running processes. All processes forked off by processes invoked via <varname>ExecStartPre=</varname> will be killed before the next service process is run.</para> + + <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>, + <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with + <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands + specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para> </listitem> </varlistentry> @@ -438,21 +407,36 @@ <constant>SIGKILL</constant> immediately after the command exited, this would not result in a clean stop. The specified command should hence be a synchronous operation, not an - asynchronous one.</para></listitem> + asynchronous one.</para> + + <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service + started successfully first. They are not invoked if the service was never started at all, or in case its + start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>, + <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with + <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a + service failed to start up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for commands that communicate with the service requesting clean + termination. When the commands specified with this option are executed it should be assumed that the service is + still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use + <varname>ExecStopPost=</varname> instead.</para></listitem> </varlistentry> <varlistentry> <term><varname>ExecStopPost=</varname></term> - <listitem><para>Additional commands that are executed after - the service was stopped. This includes cases where the - commands configured in <varname>ExecStop=</varname> were used, - where the service does not have any - <varname>ExecStop=</varname> defined, or where the service - exited unexpectedly. This argument takes multiple command - lines, following the same scheme as described for - <varname>ExecStart=</varname>. Use of these settings is - optional. Specifier and environment variable substitution is - supported.</para></listitem> + <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where + the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any + <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple + command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings + is optional. Specifier and environment variable substitution is supported. Note that – unlike + <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start + up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for clean-up operations that shall be executed even when the + service failed to start up correctly. Commands configured with this setting need to be able to operate even if + the service failed starting up half-way and left incompletely initialized data around. As the service's + processes have been terminated already when the commands specified with this setting are executed they should + not attempt to communicate with them.</para></listitem> </varlistentry> <varlistentry> @@ -470,7 +454,7 @@ configured time, the service will be considered failed and will be shut down again. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass - <literal>0</literal> to disable the timeout logic. Defaults to + <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutStartSec=</varname> from the manager configuration file, except when <varname>Type=oneshot</varname> is used, in which case the @@ -489,7 +473,7 @@ <varname>KillMode=</varname> 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 <literal>0</literal> to disable the + as "5min 20s". Pass <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutStopSec=</varname> from the manager configuration file (see @@ -506,6 +490,16 @@ </varlistentry> <varlistentry> + <term><varname>RuntimeMaxSec=</varname></term> + + <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been + active for longer than the specified time it is terminated and put into a failure state. Note that this setting + does not have any effect on <varname>Type=oneshot</varname> services, as they terminate immediately after + activation completed. Pass <literal>infinity</literal> (the default) to configure no runtime + limit.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>WatchdogSec=</varname></term> <listitem><para>Configures the watchdog timeout for a service. The watchdog is activated when the start-up is completed. The @@ -844,85 +838,11 @@ </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 than 5 times within - 10 seconds are not permitted to start any more times until the - 10 second interval ends. With these two options, this rate - limiting may be modified. Use - <varname>StartLimitInterval=</varname> to configure the - checking interval (defaults to - <varname>DefaultStartLimitInterval=</varname> in manager - configuration file, 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 <varname>DefaultStartLimitBurst=</varname> in manager - configuration file). These configuration options are - particularly useful in conjunction with - <varname>Restart=</varname>; however, they apply to all kinds - of starts (including manual), not just those triggered by the - <varname>Restart=</varname> logic. Note that units which are - configured for <varname>Restart=</varname> and which reach the - start limit are not attempted to be restarted anymore; - however, they may still be restarted manually at a later - point, from which point on, the restart logic is again - activated. Note that <command>systemctl reset-failed</command> - will cause the restart rate counter for a service to be - flushed, which is useful if the administrator wants to - manually start a service and the start limit interferes with - that.</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>, - <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>). - <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 data loss. Similarly, - <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> - - <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 argument for the - <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> + <listitem><para>Configure the action to take when the service enters a failed state. Takes the same values as + the unit setting <varname>StartLimitAction=</varname> and executes the same actions (see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Defaults to + <option>none</option>. </para></listitem> </varlistentry> <varlistentry> |