<colspec colname='expl' />
<thead>
<row>
- <entry>Path</entry>
- <entry>Description</entry>
+ <entry>Path</entry>
+ <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
- <entry><filename>/etc/systemd/system</filename></entry>
- <entry>Local configuration</entry>
+ <entry><filename>/etc/systemd/system</filename></entry>
+ <entry>Local configuration</entry>
</row>
<row>
- <entry><filename>/run/systemd/system</filename></entry>
- <entry>Runtime units</entry>
+ <entry><filename>/run/systemd/system</filename></entry>
+ <entry>Runtime units</entry>
</row>
<row>
- <entry><filename>/usr/lib/systemd/system</filename></entry>
- <entry>Units of installed packages</entry>
+ <entry><filename>/usr/lib/systemd/system</filename></entry>
+ <entry>Units of installed packages</entry>
</row>
</tbody>
</tgroup>
<colspec colname='expl' />
<thead>
<row>
- <entry>Path</entry>
- <entry>Description</entry>
+ <entry>Path</entry>
+ <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
- <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
- <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
+ <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
+ <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
</row>
<row>
- <entry><filename>$HOME/.config/systemd/user</filename></entry>
- <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
+ <entry><filename>$HOME/.config/systemd/user</filename></entry>
+ <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
</row>
<row>
- <entry><filename>/etc/systemd/user</filename></entry>
- <entry>Local configuration</entry>
+ <entry><filename>/etc/systemd/user</filename></entry>
+ <entry>Local configuration</entry>
</row>
<row>
- <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry>
- <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry>
+ <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry>
+ <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry>
</row>
<row>
- <entry><filename>/run/systemd/user</filename></entry>
- <entry>Runtime units</entry>
+ <entry><filename>/run/systemd/user</filename></entry>
+ <entry>Runtime units</entry>
</row>
<row>
- <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry>
- <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry>
+ <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry>
+ <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry>
</row>
<row>
- <entry><filename>$HOME/.local/share/systemd/user</filename></entry>
- <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry>
+ <entry><filename>$HOME/.local/share/systemd/user</filename></entry>
+ <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry>
</row>
<row>
- <entry><filename>/usr/lib/systemd/user</filename></entry>
- <entry>Units of packages that have been installed system-wide</entry>
+ <entry><filename>/usr/lib/systemd/user</filename></entry>
+ <entry>Units of packages that have been installed system-wide</entry>
</row>
</tbody>
</tgroup>
<listitem><para>Similar to <varname>Requires=</varname>.
However, if the units listed here are not started already,
they will not be started and the transaction will fail
- immediately. </para></listitem>
+ immediately.</para>
+
+ <para>When <varname>Requisite=b.service</varname> is used on
+ <filename>a.service</filename>, this dependency will show as
+ <varname>RequisiteOf=a.service</varname> in property listing of
+ <filename>b.service</filename>. <varname>RequisiteOf=</varname>
+ dependency cannot be specified directly.</para>
+ </listitem>
</varlistentry>
<varlistentry>
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>
+ <varname>BindsTo=</varname> with <varname>After=</varname>.</para>
+
+ <para>When <varname>BindsTo=b.service</varname> is used on
+ <filename>a.service</filename>, this dependency will show as
+ <varname>BoundBy=a.service</varname> in property listing of
+ <filename>b.service</filename>. <varname>BoundBy=</varname>
+ dependency cannot be specified directly.</para>
+ </listitem>
</varlistentry>
<varlistentry>
restarting of units. When systemd stops or restarts the units
listed here, the action is propagated to this unit. Note that
this is a one-way dependency — changes to this unit do not
- affect the listed units. </para></listitem>
+ affect the listed units.</para>
+
+ <para>When <varname>PartOf=b.service</varname> is used on
+ <filename>a.service</filename>, this dependency will show as
+ <varname>ConsistsOf=a.service</varname> in property listing of
+ <filename>b.service</filename>. <varname>ConsistsOf=</varname>
+ dependency cannot be specified directly.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<listitem><para>A space-separated list of one or more units
that are activated when this unit enters the
- <literal>failed</literal> state.</para></listitem>
+ <literal>failed</literal> state. A service unit using
+ <varname>Restart=</varname> enters the failed state only after
+ the start limits are reached.</para></listitem>
</varlistentry>
<varlistentry>
semantics. Defaults to <option>none</option>.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>FailureAction=</varname></term>
+ <term><varname>SuccessAction=</varname></term>
+ <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive
+ state. Takes the same values as the setting <varname>StartLimitAction=</varname> setting and executes the same
+ actions (see
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Both options
+ default to <option>none</option>.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>RebootArgument=</varname></term>
<listitem><para>Configure the optional argument for the
<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if
- <varname>StartLimitAction=</varname> or a service's <varname>FailureAction=</varname> is a reboot action. This
+ <varname>StartLimitAction=</varname> or <varname>FailureAction=</varname> is a reboot action. This
works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem>
</varlistentry>
files. This functionality should not be used in normal
units.</para></listitem>
</varlistentry>
-
</variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Mapping of unit properties to their inverses</title>
+
+ <para>Unit settings that create a relationship with a second unit usually show up
+ in properties of both units, for example in <command>systemctl show</command>
+ output. In some cases the name of the property is the same as the name of the
+ configuration setting, but not always. This table lists the pairs of properties
+ that are shown on two units which are connected through some dependency, and shows
+ which property on "source" unit corresponds to which property on the "target" unit.
+ </para>
+ <table>
+ <title>
+ "Forward" and "reverse" unit properties
+ </title>
+
+ <tgroup cols='2'>
+ <colspec colname='forward' />
+ <colspec colname='reverse' />
+ <colspec colname='notes' />
+ <thead>
+ <row>
+ <entry>"Forward" property</entry>
+ <entry>"Reverse" property</entry>
+ <entry>Where used</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><varname>Before=</varname></entry>
+ <entry><varname>After=</varname></entry>
+ <entry morerows='1' valign='middle'>Both are unit file options</entry>
+ </row>
+ <row>
+ <entry><varname>After=</varname></entry>
+ <entry><varname>Before=</varname></entry>
+ </row>
+ <row>
+ <entry><varname>Requires=</varname></entry>
+ <entry><varname>RequiredBy=</varname></entry>
+ <entry>A unit file option; an option in the [Install] section</entry>
+ </row>
+ <row>
+ <entry><varname>Wants=</varname></entry>
+ <entry><varname>WantedBy=</varname></entry>
+ <entry>A unit file option; an option in the [Install] section</entry>
+ </row>
+ <row>
+ <entry><varname>PartOf=</varname></entry>
+ <entry><varname>ConsistsOf=</varname></entry>
+ <entry>A unit file option; an automatic property</entry>
+ </row>
+ <row>
+ <entry><varname>BindsTo=</varname></entry>
+ <entry><varname>BoundBy=</varname></entry>
+ <entry>A unit file option; an automatic property</entry>
+ </row>
+ <row>
+ <entry><varname>Requisite=</varname></entry>
+ <entry><varname>RequisiteOf=</varname></entry>
+ <entry>A unit file option; an automatic property</entry>
+ </row>
+ <row>
+ <entry><varname>Triggers=</varname></entry>
+ <entry><varname>TriggeredBy=</varname></entry>
+ <entry>Automatic properties, see notes below</entry>
+ </row>
+ <row>
+ <entry><varname>Conflicts=</varname></entry>
+ <entry><varname>ConflictedBy=</varname></entry>
+ <entry>A unit file option; an automatic property</entry>
+ </row>
+ <row>
+ <entry><varname>PropagatesReloadTo=</varname></entry>
+ <entry><varname>ReloadPropagatedFrom=</varname></entry>
+ <entry morerows='1' valign='middle'>Both are unit file options</entry>
+ </row>
+ <row>
+ <entry><varname>ReloadPropagatedFrom=</varname></entry>
+ <entry><varname>PropagatesReloadTo=</varname></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Note: <varname>WantedBy=</varname> and <varname>RequiredBy=</varname> are
+ used in the [Install] section to create symlinks in <filename>.wants/</filename>
+ and <filename>.requires/</filename> directories. They cannot be used directly as a
+ unit configuration setting.</para>
+
+ <para>Note: <varname>ConsistsOf=</varname>, <varname>BoundBy=</varname>,
+ <varname>RequisiteOf=</varname>, <varname>ConflictedBy=</varname> are created
+ implicitly along with their reverse and cannot be specified directly.</para>
+
+ <para>Note: <varname>Triggers=</varname> is created implicitly between a socket,
+ path unit, or an automount unit, and the unit they activate. By default a unit
+ with the same name is triggered, but this can be overriden using
+ <varname>Sockets=</varname>, <varname>Service=</varname>, and <varname>Unit=</varname>
+ settings. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ and
+ <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. <varname>TriggersBy=</varname> is created implicitly on the
+ triggered unit.</para>
</refsect1>
<refsect1>
<para>Many settings resolve specifiers which may be used to write
generic unit files referring to runtime or unit parameters that
- are replaced when the unit files are loaded. The following
+ are replaced when the unit files are loaded. Specifiers must be known
+ and resolvable for the setting to be valid. The following
specifiers are understood:</para>
<table>
<colspec colname="detail" />
<thead>
<row>
- <entry>Specifier</entry>
- <entry>Meaning</entry>
- <entry>Details</entry>
+ <entry>Specifier</entry>
+ <entry>Meaning</entry>
+ <entry>Details</entry>
</row>
</thead>
<tbody>
<row>
- <entry><literal>%n</literal></entry>
- <entry>Full unit name</entry>
- <entry></entry>
+ <entry><literal>%n</literal></entry>
+ <entry>Full unit name</entry>
+ <entry></entry>
</row>
<row>
- <entry><literal>%N</literal></entry>
- <entry>Unescaped full unit name</entry>
- <entry>Same as <literal>%n</literal>, but with escaping undone. This undoes the escaping used when generating unit names from arbitrary strings (see above). </entry>
+ <entry><literal>%N</literal></entry>
+ <entry>Unescaped full unit name</entry>
+ <entry>Same as <literal>%n</literal>, but with escaping undone. This undoes the escaping used when generating unit names from arbitrary strings (see above). </entry>
</row>
<row>
- <entry><literal>%p</literal></entry>
- <entry>Prefix name</entry>
- <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry>
+ <entry><literal>%p</literal></entry>
+ <entry>Prefix name</entry>
+ <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry>
</row>
<row>
- <entry><literal>%P</literal></entry>
- <entry>Unescaped prefix name</entry>
- <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
+ <entry><literal>%P</literal></entry>
+ <entry>Unescaped prefix name</entry>
+ <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
</row>
<row>
- <entry><literal>%i</literal></entry>
- <entry>Instance name</entry>
- <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry>
+ <entry><literal>%i</literal></entry>
+ <entry>Instance name</entry>
+ <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry>
</row>
<row>
- <entry><literal>%I</literal></entry>
- <entry>Unescaped instance name</entry>
- <entry>Same as <literal>%i</literal>, but with escaping undone</entry>
+ <entry><literal>%I</literal></entry>
+ <entry>Unescaped instance name</entry>
+ <entry>Same as <literal>%i</literal>, but with escaping undone</entry>
</row>
<row>
- <entry><literal>%f</literal></entry>
- <entry>Unescaped filename</entry>
- <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>. This implements unescaping according to the rules for escaping absolute file system paths discussed above.</entry>
+ <entry><literal>%f</literal></entry>
+ <entry>Unescaped filename</entry>
+ <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>. This implements unescaping according to the rules for escaping absolute file system paths discussed above.</entry>
</row>
<row>
- <entry><literal>%t</literal></entry>
- <entry>Runtime directory root</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>
+ <entry><literal>%t</literal></entry>
+ <entry>Runtime directory root</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>
</row>
<row>
- <entry><literal>%S</literal></entry>
- <entry>State directory root </entry>
- <entry>This is either <filename>/var/lib</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to (for user managers).</entry>
+ <entry><literal>%S</literal></entry>
+ <entry>State directory root</entry>
+ <entry>This is either <filename>/var/lib</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to (for user managers).</entry>
</row>
<row>
- <entry><literal>%C</literal></entry>
- <entry>Cache directory root </entry>
- <entry>This is either <filename>/var/cache</filename> (for the system manager) or the path <literal>$XDG_CACHE_HOME</literal> resolves to (for user managers).</entry>
+ <entry><literal>%C</literal></entry>
+ <entry>Cache directory root</entry>
+ <entry>This is either <filename>/var/cache</filename> (for the system manager) or the path <literal>$XDG_CACHE_HOME</literal> resolves to (for user managers).</entry>
</row>
<row>
- <entry><literal>%L</literal></entry>
- <entry>Logs directory root </entry>
- <entry>This is either <filename>/var/log</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to with <filename>/log</filename> appended (for user managers).</entry>
+ <entry><literal>%L</literal></entry>
+ <entry>Log directory root</entry>
+ <entry>This is either <filename>/var/log</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to with <filename noindex='true'>/log</filename> appended (for user managers).</entry>
</row>
<row>
- <entry><literal>%u</literal></entry>
- <entry>User name</entry>
- <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
+ <entry><literal>%u</literal></entry>
+ <entry>User name</entry>
+ <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
</row>
<row>
- <entry><literal>%U</literal></entry>
- <entry>User UID</entry>
- <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry>
+ <entry><literal>%U</literal></entry>
+ <entry>User UID</entry>
+ <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry>
</row>
<row>
- <entry><literal>%h</literal></entry>
- <entry>User home directory</entry>
- <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry>
+ <entry><literal>%h</literal></entry>
+ <entry>User home directory</entry>
+ <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry>
</row>
<row>
- <entry><literal>%s</literal></entry>
- <entry>User shell</entry>
- <entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to <literal>/bin/sh</literal>.</entry>
+ <entry><literal>%s</literal></entry>
+ <entry>User shell</entry>
+ <entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to <literal>/bin/sh</literal>.</entry>
</row>
<row>
- <entry><literal>%m</literal></entry>
- <entry>Machine ID</entry>
- <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+ <entry><literal>%m</literal></entry>
+ <entry>Machine ID</entry>
+ <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
</row>
<row>
- <entry><literal>%b</literal></entry>
- <entry>Boot ID</entry>
- <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
+ <entry><literal>%b</literal></entry>
+ <entry>Boot ID</entry>
+ <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
</row>
<row>
- <entry><literal>%H</literal></entry>
- <entry>Host name</entry>
- <entry>The hostname of the running system at the point in time the unit configuration is loaded.</entry>
+ <entry><literal>%H</literal></entry>
+ <entry>Host name</entry>
+ <entry>The hostname of the running system at the point in time the unit configuration is loaded.</entry>
</row>
<row>
- <entry><literal>%v</literal></entry>
- <entry>Kernel release</entry>
- <entry>Identical to <command>uname -r</command> output</entry>
+ <entry><literal>%v</literal></entry>
+ <entry>Kernel release</entry>
+ <entry>Identical to <command>uname -r</command> output</entry>
</row>
<row>
- <entry><literal>%%</literal></entry>
- <entry>Single percent sign</entry>
- <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry>
+ <entry><literal>%%</literal></entry>
+ <entry>Single percent sign</entry>
+ <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry>
</row>
</tbody>
</tgroup>
</table>
-
</refsect1>
<refsect1>
disadvantage that some future updates by the vendor might be
incompatible with the local changes.</para>
- <para>Note that for drop-in files, if one wants to remove
- entries from a setting that is parsed as a list (and is not a
- dependency), such as <varname>ConditionPathExists=</varname> (or
- e.g. <varname>ExecStart=</varname> in service units), one needs
- to first clear the list before re-adding all entries except the
- one that is to be removed. See below for an example.</para>
-
<para>This also applies for user instances of systemd, but with
different locations for the unit files. See the section on unit
load paths for further details.</para>
Nice=0
PrivateTmp=yes</programlisting>
- <para>Note that dependencies (<varname>After=</varname>, etc.)
+ <para>Note that for drop-in files, if one wants to remove
+ entries from a setting that is parsed as a list (and is not a
+ dependency), such as <varname>AssertPathExists=</varname> (or
+ e.g. <varname>ExecStart=</varname> in service units), one needs
+ to first clear the list before re-adding all entries except the
+ one that is to be removed. Dependencies (<varname>After=</varname>, etc.)
cannot be reset to an empty list, so dependencies can only be
added in drop-ins. If you want to remove dependencies, you have
to override the entire unit.</para>
projects / thirdparty / systemd.git / blobdiff