From: Lennart Poettering Date: Mon, 29 Oct 2018 19:07:22 +0000 (+0100) Subject: man: don't claim that AssertXYZ= expressions failing had an effect on unit state X-Git-Tag: v240~441^2~5 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=53bd20ea065fdd881a9308ace9b2dc96bd0b1c8d;p=thirdparty%2Fsystemd.git man: don't claim that AssertXYZ= expressions failing had an effect on unit state In the documentation for ConditionXYZ= we claimed that AssertXYZ= would have an effect on unit state (which is wrong), while at the documentation for AssertXYZ= we said it only has an effect on the job, but not the unit (which is right). Let's fix this contradiction, and only claim the latter. Also, fix a couple of other things (for example, stop talking about a "failure state", but let's just expressly called it "the 'failed' state", as that's the actual name of that state. Finally, let's emphasize again when the conditions/assertions are executed, and that they hence are not useful to conditionalize deps. Fixes: #10433 --- diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 467b905f14e..ed7a91ecf2f 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -990,12 +990,13 @@ 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 AssertArchitecture=, - AssertVirtualization=, … options for a similar mechanism that puts the unit in a failure - state and logs about the failed check (see below). + respected. A failing condition will not result in the unit being moved into the failed + 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 their functionality. Use the various + AssertArchitecture=, AssertVirtualization=, … options for a similar + mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check + (instead of being silently processed). For details about assertion conditions see below. ConditionArchitecture= may be used to check whether the system is running on a specific @@ -1276,9 +1277,16 @@ Similar to the ConditionArchitecture=, ConditionVirtualization=, …, 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. + that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a + configured assertion does not cause the unit to enter the failed state (or in fact result in + any state change of the unit), it affects only the job queued for it. 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. + + Note that neither assertion nor condition expressions result in unit state changes. Also note that both + are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were + queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit + dependencies.