diff options
Diffstat (limited to 'man/systemd.unit.xml')
| -rw-r--r-- | man/systemd.unit.xml | 136 |
1 files changed, 86 insertions, 50 deletions
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index a95c160954..5794681963 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -178,18 +178,14 @@ directory suffix is <filename>.requires/</filename> in this case.</para> - <para>Along with a unit file <filename>foo.service</filename>, a - directory <filename>foo.service.d/</filename> may exist. All files - with the suffix <literal>.conf</literal> from this directory will - be parsed after the file itself is parsed. This is useful to alter - or add configuration settings to a unit, without having to modify - their unit files. Make sure that the file that is included has the - appropriate section headers before any directive. Note that, for - instanced units, this logic will first look for the instance - <literal>.d/</literal> subdirectory and read its - <literal>.conf</literal> files, followed by the template - <literal>.d/</literal> subdirectory and reads its - <literal>.conf</literal> files.</para> + <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory + <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this + directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for + a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for + instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory and read its + <literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory and the + <literal>.conf</literal> files there. Also note that settings from the <literal>[Install]</literal> section are not + honoured in drop-in unit files, and have no effect.</para> <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.conf</literal> files for system services @@ -728,20 +724,14 @@ <term><varname>JobTimeoutAction=</varname></term> <term><varname>JobTimeoutRebootArgument=</varname></term> - <listitem><para>When a job for this unit is queued, a time-out - may be configured. If this time limit is reached, the job will - be cancelled, the unit however will not change state or even - enter the <literal>failed</literal> mode. This value defaults - to 0 (job timeouts disabled), except for device units. NB: - this timeout is independent from any unit-specific timeout - (for example, the timeout set with - <varname>TimeoutStartSec=</varname> in service units) as the - job timeout has no effect on the unit itself, only on the job - that might be pending for it. Or in other words: unit-specific - timeouts are useful to abort unit state changes, and revert - them. The job timeout set with this option however is useful - to abort only the job waiting for the unit state to - change.</para> + <listitem><para>When a job for this unit is queued, a time-out may be configured. If this time limit is + reached, the job will be cancelled, the unit however will not change state or even enter the + <literal>failed</literal> mode. This value defaults to <literal>infinity</literal> (job timeouts disabled), + except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the + timeout set with <varname>TimeoutStartSec=</varname> in service units) as the job timeout has no effect on the + unit itself, only on the job that might be pending for it. Or in other words: unit-specific timeouts are useful + to abort unit state changes, and revert them. The job timeout set with this option however is useful to abort + only the job waiting for the unit state to change.</para> <para><varname>JobTimeoutAction=</varname> optionally configures an additional @@ -760,6 +750,55 @@ </varlistentry> <varlistentry> + <term><varname>StartLimitInterval=</varname></term> + <term><varname>StartLimitBurst=</varname></term> + + <listitem><para>Configure unit start rate limiting. By default, units 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 the service + setting <varname>Restart=</varname> (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); 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 unit 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>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 a service's <varname>FailureAction=</varname> is a reboot action. This + works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>ConditionArchitecture=</varname></term> <term><varname>ConditionVirtualization=</varname></term> <term><varname>ConditionHost=</varname></term> @@ -784,13 +823,14 @@ useful and probably just confusing. --> - <listitem><para>Before starting a unit verify that the - specified condition is true. If it is not true, the starting - of the unit will be skipped, however all ordering dependencies - of it are still respected. A failing condition will not result - in the unit being moved into a failure state. The condition is - checked at the time the queued start job is to be - executed.</para> + <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the + starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still + respected. A failing condition will not result in the unit being moved into a failure state. The condition is + checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip + units that do not apply to the local running system, for example because the kernel or runtime environment + doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>, + <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure + state and logs about the failed check (see below).</para> <para><varname>ConditionArchitecture=</varname> may be used to check whether the system is running on a specific @@ -1024,14 +1064,12 @@ <term><varname>AssertFileNotEmpty=</varname></term> <term><varname>AssertFileIsExecutable=</varname></term> - <listitem><para>Similar to the - <varname>ConditionArchitecture=</varname>, - <varname>ConditionVirtualization=</varname>, etc., condition - settings described above, these settings add assertion checks - to the start-up of the unit. However, unlike the conditions - settings, any assertion setting that is not met results in - failure of the start job it was triggered - by.</para></listitem> + <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>, + <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add + assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting + that is not met results in failure of the start job (which means this is logged loudly). Use assertion + expressions for units that cannot operate when specific requirements are not met, and when this is something + the administrator or user should look into.</para></listitem> </varlistentry> <varlistentry> @@ -1051,15 +1089,13 @@ <refsect1> <title>[Install] Section Options</title> - <para>Unit file may include an <literal>[Install]</literal> - section, which carries installation information for the unit. This - section is not interpreted by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - during runtime. It is used exclusively by the - <command>enable</command> and <command>disable</command> commands - of the - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool during installation of a unit:</para> + <para>Unit files may include an <literal>[Install]</literal> section, which carries installation information for + the unit. This section is not interpreted by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is + used by the <command>enable</command> and <command>disable</command> commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during + installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in + <filename>.d/*.conf</filename> unit file drop-ins (see above).</para> <variablelist class='unit-directives'> <varlistentry> |