diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 417840e6c2..2208b6a287 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -436,32 +436,30 @@ Requires= - Configures requirement dependencies on other - units. If this unit gets activated, the units listed here will - be activated as well. If one of the other units gets - deactivated or its activation fails, this unit will be - deactivated. This option may be specified more than once or - multiple space-separated units may be specified in one option - in which case requirement dependencies for all listed names - will be created. Note that requirement dependencies do not - influence the order in which services are started or stopped. - This has to be configured independently with the - After= or Before= - options. If a unit foo.service requires a - unit bar.service as configured with - Requires= and no ordering is configured - with After= or Before=, - then both units will be started simultaneously and without any - delay between them if foo.service is - activated. Often, it is a better choice to use - Wants= instead of - Requires= in order to achieve a system that - is more robust when dealing with failing services. + Configures requirement dependencies on other units. If this unit gets activated, the units + listed here will be activated as well. If one of the other units gets deactivated or its activation fails, this + unit will be deactivated. This option may be specified more than once or multiple space-separated units may be + specified in one option in which case requirement dependencies for all listed names will be created. Note that + requirement dependencies do not influence the order in which services are started or stopped. This has to be + configured independently with the After= or Before= options. If a unit + foo.service requires a unit bar.service as configured with + Requires= and no ordering is configured with After= or + Before=, then both units will be started simultaneously and without any delay between them + if foo.service is activated. Often, it is a better choice to use Wants= + instead of Requires= in order to achieve a system that is more robust when dealing with + failing services. - Note that dependencies of this type may also be - configured outside of the unit configuration file by adding a - symlink to a .requires/ directory - accompanying the unit file. For details, see + Note that this dependency type does not imply that the other unit always has to be in active state when + this unit is running. Specifically: failing condition checks (such as ConditionPathExists=, + ConditionPathExists=, … — see below) do not cause the start job of a unit with a + Requires= dependency on it to fail. Also, some unit types may deactivate on their own (for + example, a service process may decide to exit cleanly, or a device may be unplugged by the user), which is not + propagated to units having a Requires= dependency. Use the BindsTo= + dependency type together with After= to ensure that a unit may never be in active state + without a specific other unit also in active state (see below). + + Note that dependencies of this type may also be configured outside of the unit configuration file by + adding a symlink to a .requires/ directory accompanying the unit file. For details, see above. @@ -495,14 +493,21 @@ BindsTo= - Configures requirement dependencies, very - similar in style to Requires=, however in - addition to this behavior, it also declares that this unit is - stopped when any of the units listed suddenly disappears. - Units can suddenly, unexpectedly disappear if a service - terminates on its own choice, a device is unplugged or a mount - point unmounted without involvement of - systemd. + Configures requirement dependencies, very similar in style to + Requires=. However, this dependency type is stronger: in addition to the effect of + Requires= it declares that if the unit bound to is stopped, this unit will be stopped + too. This means a unit bound to another unit that suddenly enters inactive state will be stopped too. + Units can suddenly, unexpectedly enter inactive state for different reasons: the main process of a service unit + might terminate on its own choice, the backing device of a device unit might be unplugged or the mount point of + a mount unit might be unmounted without involvement of the system and service manager. + + When used in conjunction with After= on the same unit the behaviour of + BindsTo= is even stronger. In this case, the unit bound to strictly has to be in active + state for this unit to also be in active state. This not only means a unit bound to another unit that suddenly + enters inactive state, but also one that is bound to another unit that gets skipped due to a failed condition + check (such as ConditionPathExists=, ConditionPathIsSymbolicLink=, … — + see below) will be stopped, should it be running. Hence, in many cases it is best to combine + BindsTo= with After=. @@ -541,42 +546,26 @@ Before= After= - A space-separated list of unit names. - Configures ordering dependencies between units. If a unit - foo.service contains a setting - and both units are being - started, bar.service's start-up is - delayed until foo.service is started up. - Note that this setting is independent of and orthogonal to the - requirement dependencies as configured by - Requires=. It is a common pattern to - include a unit name in both the After= and - Requires= option, in which case the unit - listed will be started before the unit that is configured with - these options. This option may be specified more than once, in - which case ordering dependencies for all listed names are - created. After= is the inverse of - Before=, i.e. while - After= ensures that the configured unit is - started after the listed unit finished starting up, - Before= ensures the opposite, i.e. that the - configured unit is fully started up before the listed unit is - started. Note that when two units with an ordering dependency - between them are shut down, the inverse of the start-up order - is applied. i.e. if a unit is configured with - After= on another unit, the former is - stopped before the latter if both are shut down. Given two units - with any ordering dependency between them, if one unit is shut - down and the other is started up, the shutdown is ordered - before the start-up. It doesn't matter if the ordering - dependency is After= or - Before=. It also doesn't matter which of the - two is shut down, as long as one is shut down and the other is - started up. The shutdown is ordered before the start-up in all - cases. If two units have no ordering dependencies between them, - they are shut down or started up simultaneously, and no ordering - takes place. - + A space-separated list of unit names. Configures ordering dependencies between units. If a + unit foo.service contains a setting and both units are + being started, bar.service's start-up is delayed until foo.service is + started up. Note that this setting is independent of and orthogonal to the requirement dependencies as + configured by Requires=, Wants= or BindsTo=. It is a + common pattern to include a unit name in both the After= and Requires= + option, in which case the unit listed will be started before the unit that is configured with these + options. This option may be specified more than once, in which case ordering dependencies for all listed names + are created. After= is the inverse of Before=, i.e. while + After= ensures that the configured unit is started after the listed unit finished starting + up, Before= ensures the opposite, i.e. that the configured unit is fully started up before + the listed unit is started. Note that when two units with an ordering dependency between them are shut down, + the inverse of the start-up order is applied. i.e. if a unit is configured with After= on + another unit, the former is stopped before the latter if both are shut down. Given two units with any ordering + dependency between them, if one unit is shut down and the other is started up, the shutdown is ordered before + the start-up. It doesn't matter if the ordering dependency is After= or + Before=, in this case. It also doesn't matter which of the two is shut down, as long as one + is shut down and the other is started up. The shutdown is ordered before the start-up in all cases. If two + units have no ordering dependencies between them, they are shut down or started up simultaneously, and no + ordering takes place.