From fc070a25742a2a0aa407a1ce0637db505e204c1d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 28 Feb 2021 14:12:12 +0100 Subject: [PATCH] man: describe the syntax for {Job,}{Running,}TimeoutSec= Fixes #16644. Also break the text into paragraphs to make it a bit easier to read. --- man/systemd.unit.xml | 94 +++++++++++++++++++++++++----------------- man/timesyncd.conf.xml | 9 ++-- 2 files changed, 62 insertions(+), 41 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 0453c783b6d..0441e4152dd 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -976,16 +976,24 @@ JobTimeoutSec= JobRunningTimeoutSec= - When a job for this unit is queued, a timeout JobTimeoutSec= may be - configured. Similarly, JobRunningTimeoutSec= 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 failed mode. This value defaults to infinity (job timeouts - disabled), except for device units (JobRunningTimeoutSec= defaults to - DefaultTimeoutStartSec=). NB: this timeout is independent from any unit-specific timeout - (for example, the timeout set with TimeoutStartSec= 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. + JobTimeoutSec= specifies a timeout for the whole job that starts + running when the job is queued. JobRunningTimeoutSec= 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 failed mode. + + + Both settings take a time span with the default unit of seconds, but other units may be + specified, see + systemd.time5. + The default is infinity (job timeouts disabled), except for device units where + JobRunningTimeoutSec= defaults to DefaultTimeoutStartSec=. + + + Note: these timeouts are independent from any unit-specific timeouts (for example, the timeout + set with TimeoutStartSec= 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. @@ -993,13 +1001,14 @@ JobTimeoutAction= JobTimeoutRebootArgument= - JobTimeoutAction= optionally configures an additional action to take when - the timeout is hit, see description of JobTimeoutSec= and + JobTimeoutAction= optionally configures an additional action to + take when the timeout is hit, see description of JobTimeoutSec= and JobRunningTimeoutSec= above. It takes the same values as - StartLimitAction=. Defaults to . - JobTimeoutRebootArgument= configures an optional reboot string to pass to the - reboot2 system call. - + StartLimitAction=. Defaults to . + + JobTimeoutRebootArgument= configures an optional reboot string to pass to + the reboot2 system + call. @@ -1007,28 +1016,39 @@ StartLimitBurst=burst Configure unit start rate limiting. Units which are started more than - burst times within an interval time interval are not - permitted to start any more. Use StartLimitIntervalSec= to configure the checking interval - (defaults to DefaultStartLimitIntervalSec= in manager configuration file, set it to 0 to - disable any kind of rate limiting). Use StartLimitBurst= to configure how many starts per - interval are allowed (defaults to DefaultStartLimitBurst= in manager configuration - file). These configuration options are particularly useful in conjunction with the service setting + burst times within an interval time span are + not permitted to start any more. Use StartLimitIntervalSec= to configure the + checking interval and StartLimitBurst= to configure how many starts per interval + are allowed. + + interval is a time span with the default unit of seconds, but other + units may be specified, see + systemd.time5. + Defaults to DefaultStartLimitIntervalSec= in manager configuration file, and may + be set to 0 to disable any kind of rate limiting. burst is a number and + defaults to DefaultStartLimitBurst= in manager configuration file. + + These configuration options are particularly useful in conjunction with the service setting Restart= (see - systemd.service5); however, - they apply to all kinds of starts (including manual), not just those triggered by the - Restart= logic. Note that units which are configured for Restart= 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 interval has passed. From this point on, the - restart logic is activated again. Note that systemctl reset-failed 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. - - 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. + systemd.service5); + however, they apply to all kinds of starts (including manual), not just those triggered by the + Restart= logic. + + Note that units which are configured for Restart=, 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 interval has passed. From that point on, the + restart logic is activated again. systemctl reset-failed 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. + + 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. + + 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. diff --git a/man/timesyncd.conf.xml b/man/timesyncd.conf.xml index 9554cbb378d..3fd11cea04c 100644 --- a/man/timesyncd.conf.xml +++ b/man/timesyncd.conf.xml @@ -73,7 +73,7 @@ the current server does not satisfy this limit, systemd-timesyncd will switch to a different server. - Takes a time value. The default unit is seconds, but other units may be specified, see + Takes a time span value. The default unit is seconds, but other units may be specified, see systemd.time5. Defaults to 5 seconds. @@ -85,8 +85,9 @@ minimum poll interval, and is adjusted within the specified limits in response to received packets. - Each setting takes a time value. The default unit is seconds, but other units may be specified, - see systemd.time5. + Each setting takes a time span value. The default unit is seconds, but other units may be + specified, see + systemd.time5. PollIntervalMinSec= defaults to 32 seconds and must not be smaller than 16 seconds. PollIntervalMaxSec= defaults to 34 min 8 s (2048 seconds) and must be larger than PollIntervalMinSec=. @@ -97,7 +98,7 @@ Specifies the minimum delay before subsequent attempts to contact a new NTP server are made. - Takes a time value. The default unit is seconds, but other units may be specified, see + Takes a time span value. The default unit is seconds, but other units may be specified, see systemd.time5. Defaults to 30 seconds and must not be smaller than 1 second. -- 2.47.3