shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2025-01-22 22:03:43 +03:00
Code

man: describe the syntax for {Job,}{Running,}TimeoutSec=

Browse Source 
Fixes #16644.

Also break the text into paragraphs to make it a bit easier to read.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2021-02-28 14:12:12 +01:00
parent 09d9081447
commit fc070a2574
2 changed files with 62 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
man/systemd.unit.xml
View File

@ -976,16 +976,24 @@
<term><varname>JobTimeoutSec=</varname></term>
<term><varname>JobRunningTimeoutSec=</varname></term>
<listitem><para>When a job for this unit is queued, a timeout <varname>JobTimeoutSec=</varname> may be
configured. Similarly, <varname>JobRunningTimeoutSec=</varname> starts counting when the queued job is actually
started. If either 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 (<varname>JobRunningTimeoutSec=</varname> defaults to
<varname>DefaultTimeoutStartSec=</varname>). 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><varname>JobTimeoutSec=</varname> specifies a timeout for the whole job that starts
running when the job is queued. <varname>JobRunningTimeoutSec=</varname> specifies a timeout that
starts running when the queued job is actually started. If either limit is reached, the job will be
cancelled, the unit however will not change state or even enter the <literal>failed</literal> mode.
</para>
<para>Both settings take a time span with the default unit of seconds, but other units may be
specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
The default is <literal>infinity</literal> (job timeouts disabled), except for device units where
<varname>JobRunningTimeoutSec=</varname> defaults to <varname>DefaultTimeoutStartSec=</varname>.
</para>
<para>Note: these timeouts are independent from any unit-specific timeouts (for example, the timeout
set with <varname>TimeoutStartSec=</varname> in service units). The job timeout has no effect on the
unit itself. 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>
</varlistentry>
@ -993,13 +1001,14 @@
<term><varname>JobTimeoutAction=</varname></term>
<term><varname>JobTimeoutRebootArgument=</varname></term>
<listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when
the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and
<listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to
take when the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and
<varname>JobRunningTimeoutSec=</varname> above. It takes the same values as
<varname>StartLimitAction=</varname>. Defaults to <option>none</option>.
<varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to the
<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call.
</para></listitem>
<varname>StartLimitAction=</varname>. Defaults to <option>none</option>.</para>
<para><varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to
the <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system
call.</para></listitem>
</varlistentry>
<varlistentry>
@ -1007,28 +1016,39 @@
<term><varname>StartLimitBurst=<replaceable>burst</replaceable></varname></term>
<listitem><para>Configure unit start rate limiting. Units which are started more than
<replaceable>burst</replaceable> times within an <replaceable>interval</replaceable> time interval are not
permitted to start any more. Use <varname>StartLimitIntervalSec=</varname> to configure the checking interval
(defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, set it 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, after the <replaceable>interval</replaceable> has passed. From this point on, the
restart logic is activated again. 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. Note that this rate-limiting is enforced after any unit condition
checks are executed, and hence unit activations with failing conditions do not count towards this rate
limit. This setting does not apply to slice, target, device, and scope units, since they are unit types whose
activation may either never fail, or may succeed only a single time.</para>
<replaceable>burst</replaceable> times within an <replaceable>interval</replaceable> time span are
not permitted to start any more. Use <varname>StartLimitIntervalSec=</varname> to configure the
checking interval and <varname>StartLimitBurst=</varname> to configure how many starts per interval
are allowed.</para>
<para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are
flushed out too. This means that configuring start rate limiting for a unit that is not referenced continuously
has no effect.</para></listitem>
<para><replaceable>interval</replaceable> is a time span with the default unit of seconds, but other
units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, and may
be set to 0 to disable any kind of rate limiting. <replaceable>burst</replaceable> is a number and
defaults to <varname>DefaultStartLimitBurst=</varname> in manager configuration file.</para>
<para>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.</para>
<para>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, after the <replaceable>interval</replaceable> has passed. From that point on, the
restart logic is activated again. <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. Rate-limiting is enforced after any unit
condition checks are executed, and hence unit activations with failing conditions do not count
towards the rate limit.</para>
<para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters
are flushed out too. This means that configuring start rate limiting for a unit that is not
referenced continuously has no effect.</para>
<para>This setting does not apply to slice, target, device, and scope units, since they are unit
types whose activation may either never fail, or may succeed only a single time.</para></listitem>
</varlistentry>
<varlistentry>

9
man/timesyncd.conf.xml
View File

@ -73,7 +73,7 @@
the current server does not satisfy this limit, <command>systemd-timesyncd</command> will switch
to a different server.</para>
<para>Takes a time value. The default unit is seconds, but other units may be specified, see
<para>Takes a time span value. The default unit is seconds, but other units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to 5 seconds.</para></listitem>
</varlistentry>
@ -85,8 +85,9 @@
minimum poll interval, and is adjusted within the specified limits in response to received packets.
</para>
<para>Each setting takes a time value. The default unit is seconds, but other units may be specified,
see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
<para>Each setting takes a time span value. The default unit is seconds, but other units may be
specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
<varname>PollIntervalMinSec=</varname> defaults to 32 seconds and must not be smaller than
16 seconds. <varname>PollIntervalMaxSec=</varname> defaults to 34 min 8 s (2048 seconds) and must be
larger than <varname>PollIntervalMinSec=</varname>.</para></listitem>
@ -97,7 +98,7 @@
<listitem><para>Specifies the minimum delay before subsequent attempts to contact a new NTP server
are made.</para>
<para>Takes a time value. The default unit is seconds, but other units may be specified, see
<para>Takes a time span value. The default unit is seconds, but other units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to 30 seconds and must not be smaller than 1 second.</para></listitem>
</varlistentry>