diff options
Diffstat (limited to 'man/systemd.unit.xml')
| -rw-r--r-- | man/systemd.unit.xml | 166 |
1 files changed, 66 insertions, 100 deletions
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 40c4cfd854..44841ac7dd 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -203,7 +203,8 @@ <filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these directories take precedence - over unit files wherever located.</para> + over unit files wherever located. Multiple drop-in files with different names are applied in + lexicographic order, regardless of which of the directories they reside in.</para> <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want people to use .d/ drop-ins instead. --> @@ -255,7 +256,7 @@ <para>The unit file format is covered by the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + url="https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface Stability Promise</ulink>.</para> </refsect1> @@ -435,32 +436,30 @@ <varlistentry> <term><varname>Requires=</varname></term> - <listitem><para>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 - <varname>After=</varname> or <varname>Before=</varname> - options. If a unit <filename>foo.service</filename> requires a - unit <filename>bar.service</filename> as configured with - <varname>Requires=</varname> and no ordering is configured - with <varname>After=</varname> or <varname>Before=</varname>, - then both units will be started simultaneously and without any - delay between them if <filename>foo.service</filename> is - activated. Often, it is a better choice to use - <varname>Wants=</varname> instead of - <varname>Requires=</varname> in order to achieve a system that - is more robust when dealing with failing services.</para> - - <para>Note that dependencies of this type may also be - configured outside of the unit configuration file by adding a - symlink to a <filename>.requires/</filename> directory - accompanying the unit file. For details, see + <listitem><para>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 <varname>After=</varname> or <varname>Before=</varname> options. If a unit + <filename>foo.service</filename> requires a unit <filename>bar.service</filename> as configured with + <varname>Requires=</varname> and no ordering is configured with <varname>After=</varname> or + <varname>Before=</varname>, then both units will be started simultaneously and without any delay between them + if <filename>foo.service</filename> is activated. Often, it is a better choice to use <varname>Wants=</varname> + instead of <varname>Requires=</varname> in order to achieve a system that is more robust when dealing with + failing services.</para> + + <para>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 <varname>ConditionPathExists=</varname>, + <varname>ConditionPathExists=</varname>, … — see below) do not cause the start job of a unit with a + <varname>Requires=</varname> 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 <varname>Requires=</varname> dependency. Use the <varname>BindsTo=</varname> + dependency type together with <varname>After=</varname> to ensure that a unit may never be in active state + without a specific other unit also in active state (see below).</para> + + <para>Note that dependencies of this type may also be configured outside of the unit configuration file by + adding a symlink to a <filename>.requires/</filename> directory accompanying the unit file. For details, see above.</para></listitem> </varlistentry> @@ -494,14 +493,21 @@ <varlistentry> <term><varname>BindsTo=</varname></term> - <listitem><para>Configures requirement dependencies, very - similar in style to <varname>Requires=</varname>, 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.</para></listitem> + <listitem><para>Configures requirement dependencies, very similar in style to + <varname>Requires=</varname>. However, this dependency type is stronger: in addition to the effect of + <varname>Requires=</varname> 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.</para> + + <para>When used in conjunction with <varname>After=</varname> on the same unit the behaviour of + <varname>BindsTo=</varname> 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 <varname>ConditionPathExists=</varname>, <varname>ConditionPathIsSymbolicLink=</varname>, … — + see below) will be stopped, should it be running. Hence, in many cases it is best to combine + <varname>BindsTo=</varname> with <varname>After=</varname>.</para></listitem> </varlistentry> <varlistentry> @@ -540,42 +546,26 @@ <term><varname>Before=</varname></term> <term><varname>After=</varname></term> - <listitem><para>A space-separated list of unit names. - Configures ordering dependencies between units. If a unit - <filename>foo.service</filename> contains a setting - <option>Before=bar.service</option> and both units are being - started, <filename>bar.service</filename>'s start-up is - delayed until <filename>foo.service</filename> is started up. - Note that this setting is independent of and orthogonal to the - requirement dependencies as configured by - <varname>Requires=</varname>. It is a common pattern to - include a unit name in both the <varname>After=</varname> and - <varname>Requires=</varname> 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. <varname>After=</varname> is the inverse of - <varname>Before=</varname>, i.e. while - <varname>After=</varname> ensures that the configured unit is - started after the listed unit finished starting up, - <varname>Before=</varname> 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 - <varname>After=</varname> 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 <varname>After=</varname> or - <varname>Before=</varname>. 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. - </para></listitem> + <listitem><para>A space-separated list of unit names. Configures ordering dependencies between units. If a + unit <filename>foo.service</filename> contains a setting <option>Before=bar.service</option> and both units are + being started, <filename>bar.service</filename>'s start-up is delayed until <filename>foo.service</filename> is + started up. Note that this setting is independent of and orthogonal to the requirement dependencies as + configured by <varname>Requires=</varname>, <varname>Wants=</varname> or <varname>BindsTo=</varname>. It is a + common pattern to include a unit name in both the <varname>After=</varname> and <varname>Requires=</varname> + 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. <varname>After=</varname> is the inverse of <varname>Before=</varname>, i.e. while + <varname>After=</varname> ensures that the configured unit is started after the listed unit finished starting + up, <varname>Before=</varname> 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 <varname>After=</varname> 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 <varname>After=</varname> or + <varname>Before=</varname>, 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. </para></listitem> </varlistentry> <varlistentry> @@ -630,11 +620,9 @@ all mount units required to access the specified path.</para> <para>Mount points marked with <option>noauto</option> are not - mounted automatically and will be ignored for the purposes of - this option. If such a mount should be a requirement for this - unit, direct dependencies on the mount units may be added - (<varname>Requires=</varname> and <varname>After=</varname> or - some other combination). </para></listitem> + mounted automatically through <filename>local-fs.target</filename>, + but are still honored for the purposes of this option, i.e. they + will be pulled in by this unit.</para></listitem> </varlistentry> <varlistentry> @@ -1246,21 +1234,6 @@ <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>.</entry> </row> <row> - <entry><literal>%c</literal></entry> - <entry>Control group path of the unit</entry> - <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry> - </row> - <row> - <entry><literal>%r</literal></entry> - <entry>Control group path of the slice the unit is placed in</entry> - <entry>This usually maps to the parent control group path of <literal>%c</literal>.</entry> - </row> - <row> - <entry><literal>%R</literal></entry> - <entry>Root control group path below which slices and units are placed</entry> - <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry> - </row> - <row> <entry><literal>%t</literal></entry> <entry>Runtime directory</entry> <entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry> @@ -1314,13 +1287,6 @@ </tgroup> </table> - <para>Please note that specifiers <literal>%U</literal>, - <literal>%h</literal>, <literal>%s</literal> are mostly useless - when systemd is running in system mode. PID 1 cannot query the - user account database for information, so the specifiers only work - as shortcuts for things which are already specified in a different - way in the unit file. They are fully functional when systemd is - running in <option>--user</option> mode.</para> </refsect1> <refsect1> @@ -1365,7 +1331,7 @@ ExecStart=/usr/sbin/foo-daemon file <filename><replaceable>name</replaceable>.conf</filename> there that only changes the specific settings one is interested in. Note that multiple such drop-in files are read if - present.</para> + present, processed in lexicographic order of their filename.</para> <para>The advantage of the first method is that one easily overrides the complete unit, the vendor unit is not parsed at |