HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/systemd.unit.xml
Git blob: 54d24961893748d6aa56d22aa57bf37d61254735
Lines 2001–2862 of 2,862
<literal>de</literal>,
<literal>pse</literal>,
<literal>tsc</literal>,
<literal>msr</literal>,
<literal>pae</literal>,
<literal>mce</literal>,
<literal>cx8</literal>,
<literal>apic</literal>,
<literal>sep</literal>,
<literal>mtrr</literal>,
<literal>pge</literal>,
<literal>mca</literal>,
<literal>cmov</literal>,
<literal>pat</literal>,
<literal>pse36</literal>,
<literal>clflush</literal>,
<literal>mmx</literal>,
<literal>fxsr</literal>,
<literal>sse</literal>,
<literal>sse2</literal>,
<literal>ht</literal>,
<literal>pni</literal>,
<literal>pclmul</literal>,
<literal>monitor</literal>,
<literal>ssse3</literal>,
<literal>fma3</literal>,
<literal>cx16</literal>,
<literal>sse4_1</literal>,
<literal>sse4_2</literal>,
<literal>movbe</literal>,
<literal>popcnt</literal>,
<literal>aes</literal>,
<literal>xsave</literal>,
<literal>osxsave</literal>,
<literal>avx</literal>,
<literal>f16c</literal>,
<literal>rdrand</literal>,
<literal>bmi1</literal>,
<literal>avx2</literal>,
<literal>bmi2</literal>,
<literal>rdseed</literal>,
<literal>adx</literal>,
<literal>sha_ni</literal>,
<literal>syscall</literal>,
<literal>rdtscp</literal>,
<literal>lm</literal>,
<literal>lahf_lm</literal>,
<literal>abm</literal>,
<literal>constant_tsc</literal>.</para>
<para>On arm64, valid values are the corresponding arm64 feature names,
such as
<literal>asimd</literal>,
<literal>paca</literal>,
<literal>pacg</literal>,
<literal>bti</literal>,
<literal>mte</literal>,
among others. For the full list, see the documentation on
<ulink url="https://docs.kernel.org/arch/arm64/elf_hwcaps.html">ARM64 ELF hwcaps</ulink>.</para>
<para>To avoid ambiguities in mixed-architecture fleets, the value can be prefixed
with the architecture name using the form <literal>ARCH.FEATURE</literal>. If the
architecture prefix does not match the running system, the condition evaluates
to false. For example, one can specify <literal>arm64.bti</literal> on arm64
systems to check if <literal>bti</literal> is supported. In this example,
<literal>ConditionCPUFeature=arm64.bti</literal> and
<literal>ConditionCPUFeature=bti</literal> are functionally equivalent.
See <varname>ConditionArchitecture=</varname> for valid architecture names.</para>
<para>On architectures other than x86 and arm64, it is assumed that the CPU does not support the given feature.</para>
<xi:include href="version-info.xml" xpointer="v248"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ConditionOSRelease=</varname></term>
<listitem><para>Verify that a specific <literal>key=value</literal> pair is set in the host's
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>Other than exact string matching (with <literal>=</literal> and <literal>!=</literal>),
relative comparisons are supported for versioned parameters (e.g. <literal>VERSION_ID</literal>;
with <literal><</literal>, <literal><=</literal>, <literal>==</literal>,
<literal><></literal>, <literal>>=</literal>, <literal>></literal>), and shell-style
wildcard comparisons (<literal>*</literal>, <literal>?</literal>, <literal>[]</literal>) are
supported with the <literal>$=</literal> (match) and <literal>!$=</literal> (non-match).</para>
<para>If the given key is not found in the file, the match is done against an empty value.</para>
<xi:include href="version-info.xml" xpointer="v249"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ConditionMachineTag=</varname></term>
<listitem><para><varname>ConditionMachineTag=</varname> may be used to match against the tags
assigned to the local machine. Machine tags are short labels that classify and group machines for
management purposes; they are configured in the <varname>TAGS=</varname> field of
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
may be queried and changed with the <command>tags</command> command of
<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
argument is a single tag pattern, which is compared against each of the configured tags using
shell-style globbing (<literal>*</literal>, <literal>?</literal>, <literal>[]</literal>). The
condition is satisfied if at least one of the configured tags matches the pattern. The test may be
negated by prepending an exclamation mark, in which case it is satisfied if none of the configured
tags matches.</para>
<para>Tags may be parameterized with a value in the form
<literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>; the
<literal>=</literal> and the value are part of the tag and thus part of the string the pattern is
matched against. Hence <literal>ConditionMachineTag=role=webserver</literal> matches the tag
<literal>role=webserver</literal> exactly, <literal>ConditionMachineTag=role=*</literal> matches any
value assigned to the <literal>role</literal> key, and <literal>ConditionMachineTag=role</literal>
(without <literal>=</literal>) does <emphasis>not</emphasis> match <literal>role=webserver</literal>.
See
<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the precise syntax of machine tags.</para>
<xi:include href="version-info.xml" xpointer="v261"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ConditionMemoryPressure=</varname></term>
<term><varname>ConditionCPUPressure=</varname></term>
<term><varname>ConditionIOPressure=</varname></term>
<listitem><para>Verify that the overall system (memory, CPU or IO) pressure is below or equal to a threshold.
This setting takes a threshold value as argument. It can be specified as a simple percentage value,
suffixed with <literal>%</literal>, in which case the pressure will be measured as an average over the last
five minutes before the attempt to start the unit is performed.
Alternatively, the average timespan can also be specified using <literal>/</literal> as a separator, for
example: <literal>10%/1min</literal>. The supported timespans match what the kernel provides, and are
limited to <literal>10sec</literal>, <literal>1min</literal> and <literal>5min</literal>. The
<literal>full</literal> PSI will be checked first, and if not found <literal>some</literal> will be
checked. For more details, see the documentation on <ulink
url="https://docs.kernel.org/accounting/psi.html">PSI (Pressure Stall Information)
</ulink>.</para>
<para>Optionally, the threshold value can be prefixed with the slice unit under which the pressure will be checked,
followed by a <literal>:</literal>. If the slice unit is not specified, the overall system pressure will be measured,
instead of a particular cgroup's.</para>
<xi:include href="version-info.xml" xpointer="v250"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ConditionKernelModuleLoaded=</varname></term>
<listitem><para>Test whether the specified kernel module has been loaded and is already fully
initialized.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>AssertArchitecture=</varname></term>
<term><varname>AssertVirtualization=</varname></term>
<term><varname>AssertHost=</varname></term>
<term><varname>AssertFraction=</varname></term>
<term><varname>AssertKernelCommandLine=</varname></term>
<term><varname>AssertKernelVersion=</varname></term>
<term><varname>AssertVersion=</varname></term>
<term><varname>AssertCredential=</varname></term>
<term><varname>AssertEnvironment=</varname></term>
<term><varname>AssertSecurity=</varname></term>
<term><varname>AssertCapability=</varname></term>
<term><varname>AssertACPower=</varname></term>
<term><varname>AssertNeedsUpdate=</varname></term>
<term><varname>AssertFirstBoot=</varname></term>
<term><varname>AssertPathExists=</varname></term>
<term><varname>AssertPathExistsGlob=</varname></term>
<term><varname>AssertPathIsDirectory=</varname></term>
<term><varname>AssertPathIsSymbolicLink=</varname></term>
<term><varname>AssertPathIsMountPoint=</varname></term>
<term><varname>AssertPathIsReadWrite=</varname></term>
<term><varname>AssertPathIsEncrypted=</varname></term>
<term><varname>AssertPathIsSocket=</varname></term>
<term><varname>AssertDirectoryNotEmpty=</varname></term>
<term><varname>AssertFileNotEmpty=</varname></term>
<term><varname>AssertFileIsExecutable=</varname></term>
<term><varname>AssertUser=</varname></term>
<term><varname>AssertGroup=</varname></term>
<term><varname>AssertControlGroupController=</varname></term>
<term><varname>AssertMemory=</varname></term>
<term><varname>AssertCPUs=</varname></term>
<term><varname>AssertCPUFeature=</varname></term>
<term><varname>AssertOSRelease=</varname></term>
<term><varname>AssertMachineTag=</varname></term>
<term><varname>AssertMemoryPressure=</varname></term>
<term><varname>AssertCPUPressure=</varname></term>
<term><varname>AssertIOPressure=</varname></term>
<term><varname>AssertKernelModuleLoaded=</varname></term>
<listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
<varname>ConditionVirtualization=</varname>, …, 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). Note that hitting a configured assertion does not cause the unit to enter the
<literal>failed</literal> 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.</para>
<xi:include href="version-info.xml" xpointer="v218"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</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 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='4'>
<colspec colname='forward' />
<colspec colname='reverse' />
<colspec colname='fuse' />
<colspec colname='ruse' />
<thead>
<row>
<entry>"Forward" property</entry>
<entry>"Reverse" property</entry>
<entry namest='fuse' nameend='ruse' valign='middle'>Where used</entry>
</row>
</thead>
<tbody>
<row>
<entry><varname>Before=</varname></entry>
<entry><varname>After=</varname></entry>
<entry morerows='1' namest='fuse' nameend='ruse' valign='middle'>[Unit] section</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>[Unit] section</entry>
<entry>[Install] section</entry>
</row>
<row>
<entry><varname>Wants=</varname></entry>
<entry><varname>WantedBy=</varname></entry>
<entry>[Unit] section</entry>
<entry>[Install] section</entry>
</row>
<row>
<entry><varname>Upholds=</varname></entry>
<entry><varname>UpheldBy=</varname></entry>
<entry>[Unit] section</entry>
<entry>[Install] section</entry>
</row>
<row>
<entry><varname>PartOf=</varname></entry>
<entry><varname>ConsistsOf=</varname></entry>
<entry>[Unit] section</entry>
<entry>an automatic property</entry>
</row>
<row>
<entry><varname>BindsTo=</varname></entry>
<entry><varname>BoundBy=</varname></entry>
<entry>[Unit] section</entry>
<entry>an automatic property</entry>
</row>
<row>
<entry><varname>Requisite=</varname></entry>
<entry><varname>RequisiteOf=</varname></entry>
<entry>[Unit] section</entry>
<entry>an automatic property</entry>
</row>
<row>
<entry><varname>Conflicts=</varname></entry>
<entry><varname>ConflictedBy=</varname></entry>
<entry>[Unit] section</entry>
<entry>an automatic property</entry>
</row>
<row>
<entry><varname>Triggers=</varname></entry>
<entry><varname>TriggeredBy=</varname></entry>
<entry namest='fuse' nameend='ruse' valign='middle'>Automatic properties, see notes below</entry>
</row>
<row>
<entry><varname>PropagatesReloadTo=</varname></entry>
<entry><varname>ReloadPropagatedFrom=</varname></entry>
<entry morerows='1' namest='fuse' nameend='ruse' valign='middle'>[Unit] section</entry>
</row>
<row>
<entry><varname>ReloadPropagatedFrom=</varname></entry>
<entry><varname>PropagatesReloadTo=</varname></entry>
</row>
<row>
<entry><varname>PropagatesStopTo=</varname></entry>
<entry><varname>StopPropagatedFrom=</varname></entry>
<entry morerows='1' namest='fuse' nameend='ruse' valign='middle'>[Unit] section</entry>
</row>
<row>
<entry><varname>StopPropagatedFrom=</varname></entry>
<entry><varname>PropagatesStopTo=</varname></entry>
</row>
<row>
<entry><varname>Following=</varname></entry>
<entry>n/a</entry>
<entry>An automatic property</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Note: <varname>WantedBy=</varname>, <varname>RequiredBy=</varname>, and <varname>UpheldBy=</varname>
are used in the [Install] section to create symlinks in <filename>.wants/</filename>,
<filename>.requires/</filename>, and <filename>.upholds/</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 reverses 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 overridden 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>TriggeredBy=</varname> is created implicitly on the
triggered unit.</para>
<para>Note: <varname>Following=</varname> is used to group device aliases and points to the
"primary" device unit that systemd is using to track device state, usually corresponding to a
sysfs path. It does not show up in the "target" unit.</para>
</refsect1>
<refsect1>
<title>[Install] Section Options</title>
<para>Unit files may include an [Install] section, which carries installation information for
the unit. This section is not interpreted by
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
used by the <command>enable</command> and <command>disable</command> commands of the
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
installation of a unit.</para>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>Alias=</varname></term>
<listitem><para>A space-separated list of additional names this unit shall be installed under. The names listed
here must have the same suffix (i.e. type) as the unit filename. This option may be specified more than once,
in which case all listed names are used. At installation time, <command>systemctl enable</command> will create
symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this
setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support
aliasing.</para>
<xi:include href="version-info.xml" xpointer="v201"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>WantedBy=</varname></term>
<term><varname>RequiredBy=</varname></term>
<term><varname>UpheldBy=</varname></term>
<listitem><para>This option may be used more than once, or a space-separated list of unit names may
be given. A symbolic link is created in the <filename>.wants/</filename>, <filename>.requires/</filename>,
or <filename>.upholds/</filename> directory of each of the listed units when this unit is installed
by <command>systemctl enable</command>. This has the effect of a dependency of type
<varname>Wants=</varname>, <varname>Requires=</varname>, or <varname>Upholds=</varname> being added
from the listed unit to the current unit. See the description of the mentioned dependency types
in the [Unit] section for details.</para>
<para>In case of template units listing non template units, the listing unit must have
<varname>DefaultInstance=</varname> set, or <command>systemctl enable</command> must be called with
an instance name. The instance (default or specified) will be added to the
<filename>.wants/</filename>, <filename>.requires/</filename>, or <filename>.upholds/</filename>
list of the listed unit. For example, <command>WantedBy=getty.target</command> in a service
<filename>getty@.service</filename> will result in <command>systemctl enable getty@tty2.service</command>
creating a <filename>getty.target.wants/getty@tty2.service</filename> link to
<filename>getty@.service</filename>. This also applies to listing specific instances of templated
units: this specific instance will gain the dependency. A template unit may also list a template
unit, in which case a generic dependency will be added where each instance of the listing unit will
have a dependency on an instance of the listed template with the same instance value. For example,
<command>WantedBy=container@.target</command> in a service <filename>monitor@.service</filename> will
result in <command>systemctl enable monitor@.service</command> creating a
<filename>container@.target.wants/monitor@.service</filename> link to
<filename>monitor@.service</filename>, which applies to all instances of
<filename>container@.target</filename>.</para>
<xi:include href="version-info.xml" xpointer="v201"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>Also=</varname></term>
<listitem><para>Additional units to install/deinstall when
this unit is installed/deinstalled. If the user requests
installation/deinstallation of a unit with this option
configured, <command>systemctl enable</command> and
<command>systemctl disable</command> will automatically
install/uninstall units listed in this option as well.</para>
<para>This option may be used more than once, or a
space-separated list of unit names may be
given.</para>
<xi:include href="version-info.xml" xpointer="v201"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>DefaultInstance=</varname></term>
<listitem><para>In template unit files, this specifies for
which instance the unit shall be enabled if the template is
enabled without any explicitly set instance. This option has
no effect in non-template unit files. The specified string
must be usable as instance identifier.</para>
<xi:include href="version-info.xml" xpointer="v215"/></listitem>
</varlistentry>
</variablelist>
<para>The following specifiers are interpreted in the Install section:
%a, %b, %B, %g, %G, %H, %i, %j, %l, %m, %n, %N, %o, %p, %u, %U, %v, %w, %W, %%.
For their meaning see the next section.</para>
</refsect1>
<refsect1>
<title>Specifiers</title>
<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. Specifiers must be known
and resolvable for the setting to be valid. The following
specifiers are understood:</para>
<table class='specifiers'>
<title>Specifiers available in unit files</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<colspec colname="spec" />
<colspec colname="mean" />
<colspec colname="detail" />
<thead>
<row>
<entry>Specifier</entry>
<entry>Meaning</entry>
<entry>Details</entry>
</row>
</thead>
<tbody>
<row>
<!-- We do not use the common definition from standard-specifiers.xml here since it includes a
reference onto our own man page, which would make the rendered version self-referential. -->
<entry><literal>%a</literal></entry>
<entry>Architecture</entry>
<entry>A short string identifying the architecture of the local system. A string such as <constant>x86</constant>, <constant>x86-64</constant> or <constant>arm64</constant>. See the architectures defined for <varname>ConditionArchitecture=</varname> above for a full list.</entry>
</row>
<xi:include href="standard-specifiers.xml" xpointer="A"/>
<xi:include href="standard-specifiers.xml" xpointer="b"/>
<xi:include href="standard-specifiers.xml" xpointer="B"/>
<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>
</row>
<row>
<entry><literal>%d</literal></entry>
<entry>Credentials directory</entry>
<entry>This is the value of the <literal>$CREDENTIALS_DIRECTORY</literal> environment variable if available. See section "Credentials" in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
</row>
<xi:include href="standard-specifiers.xml" xpointer="D"/>
<row>
<entry><literal>%E</literal></entry>
<entry>Configuration directory root</entry>
<entry>This is either <filename>/etc/</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to (for user managers).</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>
</row>
<row>
<entry><literal>%g</literal></entry>
<entry>User group</entry>
<entry>This is the name of the group running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
</row>
<row>
<entry><literal>%G</literal></entry>
<entry>User GID</entry>
<entry>This is the numeric GID 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 <emphasis>user running the service manager instance</emphasis>. In case of the system manager this resolves to <literal>/root</literal>.
Note that this setting is <emphasis>not</emphasis> influenced by the <varname>User=</varname> setting configurable in the [Service] section of the service unit.</entry>
</row>
<row>
<!-- We do not use the common definition from standard-specifiers.xml here since we want a
slightly more verbose explanation here, referring to the reload cycle. -->
<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>%i</literal></entry>
<entry>Instance name</entry>
<entry>For instantiated units this is the string between the first <literal>@</literal> character and the type suffix. Empty for non-instantiated units.</entry>
</row>
<row>
<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>%j</literal></entry>
<entry>Final component of the prefix</entry>
<entry>This is the string between the last <literal>-</literal> and the end of the prefix name. If there is no <literal>-</literal>, this is the same as <literal>%p</literal>.</entry>
</row>
<row>
<entry><literal>%J</literal></entry>
<entry>Unescaped final component of the prefix</entry>
<entry>Same as <literal>%j</literal>, but with escaping undone.</entry>
</row>
<row>
<entry><literal>%l</literal></entry>
<!-- We do not use the common definition from standard-specifiers.xml here since we want a
slightly more verbose explanation here, referring to the reload cycle. -->
<entry>Short host name</entry>
<entry>The hostname of the running system at the point in time the unit configuration is loaded, truncated at the first dot to remove any domain component.</entry>
</row>
<row>
<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 <varname>$XDG_STATE_HOME</varname> resolves to with <filename index="false">/log</filename> appended (for user managers).</entry>
</row>
<xi:include href="standard-specifiers.xml" xpointer="m"/>
<xi:include href="standard-specifiers.xml" xpointer="M"/>
<row>
<entry><literal>%n</literal></entry>
<entry>Full unit name</entry>
<entry></entry>
</row>
<row>
<entry><literal>%N</literal></entry>
<entry>Full unit name</entry>
<entry>Same as <literal>%n</literal>, but with the type suffix removed.</entry>
</row>
<xi:include href="standard-specifiers.xml" xpointer="o"/>
<row>
<entry><literal>%p</literal></entry>
<entry>Prefix name</entry>
<entry>For instantiated units, this refers to the string before the first <literal>@</literal> character of the unit name. For non-instantiated units, same as <literal>%N</literal>.</entry>
</row>
<row>
<entry><literal>%P</literal></entry>
<entry>Unescaped prefix name</entry>
<entry>Same as <literal>%p</literal>, but with escaping undone.</entry>
</row>
<row>
<!-- We do not use the common definition from standard-specifiers.xml here since we want a
slightly more verbose explanation here, referring to the reload cycle. -->
<entry><literal>%q</literal></entry>
<entry>Pretty host name</entry>
<entry>The pretty hostname of the running system at the point in time the unit configuration is loaded, as read from the <varname>PRETTY_HOSTNAME=</varname> field of <filename>/etc/machine-info</filename>. If not set, resolves to the short hostname. See <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</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.</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 <varname>$XDG_STATE_HOME</varname> resolves to (for user managers).</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>
</row>
<xi:include href="standard-specifiers.xml" xpointer="T"/>
<row>
<entry><literal>%u</literal></entry>
<entry>User name</entry>
<entry>This is the name of the <emphasis>user running the service manager instance</emphasis>. In case of the system manager this resolves to <literal>root</literal>.
Note that this setting is <emphasis>not</emphasis> influenced by the <varname>User=</varname> setting configurable in the [Service] section of the service unit.</entry>
</row>
<row>
<entry><literal>%U</literal></entry>
<entry>User UID</entry>
<entry>This is the numeric UID of the <emphasis>user running the service manager instance</emphasis>. In case of the system manager this resolves to <literal>0</literal>.
Note that this setting is <emphasis>not</emphasis> influenced by the <varname>User=</varname> setting configurable in the [Service] section of the service unit.</entry>
</row>
<xi:include href="standard-specifiers.xml" xpointer="v"/>
<xi:include href="standard-specifiers.xml" xpointer="V"/>
<xi:include href="standard-specifiers.xml" xpointer="w"/>
<xi:include href="standard-specifiers.xml" xpointer="W"/>
<row>
<entry><literal>%y</literal></entry>
<entry>The path to the fragment</entry>
<entry>This is the path where the main part of the unit file is located. For linked unit files, the real path outside of the unit search directories is used. For units that do not have a fragment file, this specifier will raise an error.</entry>
</row>
<row>
<entry><literal>%Y</literal></entry>
<entry>The directory of the fragment</entry>
<entry>This is the directory part of <literal>%y</literal>.</entry>
</row>
<xi:include href="standard-specifiers.xml" xpointer="percent"/>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Allowing units to be enabled</title>
<para>The following snippet (highlighted) allows a unit (e.g.
<filename>foo.service</filename>) to be enabled via
<command>systemctl enable</command>:</para>
<programlisting>[Unit]
Description=Foo
[Service]
ExecStart=/usr/sbin/foo-daemon
<emphasis>[Install]</emphasis>
<emphasis>WantedBy=multi-user.target</emphasis></programlisting>
<para>After running <command>systemctl enable</command>, a
symlink
<filename index="false">/etc/systemd/system/multi-user.target.wants/foo.service</filename>
linking to the actual unit will be created. It tells systemd to
pull in the unit when starting
<filename>multi-user.target</filename>. The inverse
<command>systemctl disable</command> will remove that symlink
again.</para>
</example>
<example>
<title>Overriding vendor settings</title>
<para>There are two methods of overriding vendor settings in
unit files: copying the unit file from
<filename>/usr/lib/systemd/system</filename> to
<filename>/etc/systemd/system</filename> and modifying the
chosen settings. Alternatively, one can create a directory named
<filename><replaceable>unit</replaceable>.d/</filename> within
<filename>/etc/systemd/system</filename> and place a drop-in
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, 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
all anymore. It has the disadvantage that improvements to the
unit file by the vendor are not automatically incorporated on
updates.</para>
<para>The advantage of the second method is that one only
overrides the settings one specifically wants, where updates to
the unit by the vendor automatically apply. This has the
disadvantage that some future updates by the vendor might be
incompatible with the local changes.</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>
<para>Suppose there is a vendor-supplied unit
<filename>/usr/lib/systemd/system/httpd.service</filename> with
the following contents:</para>
<programlisting>[Unit]
Description=Some HTTP Server
After=remote-fs.target sqldb.service
Requires=sqldb.service
AssertPathExists=/srv/webserver
[Service]
Type=notify
ExecStart=/usr/sbin/some-fancy-httpd-server
Nice=5
[Install]
WantedBy=multi-user.target</programlisting>
<para>Now one wants to change some settings as an administrator:
firstly, in the local setup, <filename>/srv/webserver</filename>
might not exist, because the HTTP server is configured to use
<filename>/srv/www</filename> instead. Secondly, the local
configuration makes the HTTP server also depend on a memory
cache service, <filename>memcached.service</filename>, that
should be pulled in (<varname>Requires=</varname>) and also be
ordered appropriately (<varname>After=</varname>). Thirdly, in
order to harden the service a bit more, the administrator would
like to set the <varname>PrivateTmp=</varname> setting (see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details). And lastly, the administrator would like to reset
the niceness of the service to its default value of 0.</para>
<para>The first possibility is to copy the unit file to
<filename>/etc/systemd/system/httpd.service</filename> and
change the chosen settings:</para>
<programlisting>[Unit]
Description=Some HTTP Server
After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis>
Requires=sqldb.service <emphasis>memcached.service</emphasis>
AssertPathExists=<emphasis>/srv/www</emphasis>
[Service]
Type=notify
ExecStart=/usr/sbin/some-fancy-httpd-server
<emphasis>Nice=0</emphasis>
<emphasis>PrivateTmp=yes</emphasis>
[Install]
WantedBy=multi-user.target</programlisting>
<para>Alternatively, the administrator could create a drop-in
file
<filename>/etc/systemd/system/httpd.service.d/local.conf</filename>
with the following contents:</para>
<programlisting>[Unit]
After=memcached.service
Requires=memcached.service
# Reset all assertions and then re-add the condition we want
AssertPathExists=
AssertPathExists=/srv/www
[Service]
Nice=0
PrivateTmp=yes</programlisting>
<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>
</example>
<example>
<title>Top level drop-ins with template units</title>
<para>Top level per-type drop-ins can be used to change some aspect of
all units of a particular type. For example, by creating the
<filename index='false'>/etc/systemd/system/service.d/</filename>
directory with a drop-in file, the contents of the drop-in file can be
applied to all service units. We can take this further by having the
top-level drop-in instantiate a secondary helper unit. Consider for
example the following set of units and drop-in files where we install
an <varname>OnFailure=</varname> dependency for all service units.</para>
<para>
<filename index='false'>/etc/systemd/system/failure-handler@.service</filename>:</para>
<programlisting>[Unit]
Description=My Failure Handler For %i
[Service]
Type=oneshot
# Perform some special action for when %i exits unexpectedly.
ExecStart=/usr/sbin/myfailurehandler %i
</programlisting>
<para>We can then add an instance of
<filename index='false'>failure-handler@.service</filename> as an
<varname>OnFailure=</varname> dependency for all service units.</para>
<para>
<filename index='false'>/etc/systemd/system/service.d/10-all.conf</filename>:</para>
<programlisting>[Unit]
OnFailure=failure-handler@%N.service
</programlisting>
<para>Now, after running <command>systemctl daemon-reload</command> all
services will have acquired an <varname>OnFailure=</varname> dependency on
<filename index='false'>failure-handler@%N.service</filename>. The
template instance units will also have gained the dependency which results
in the creation of a recursive dependency chain. systemd will try to detect
these recursive dependency chains where a template unit directly and
recursively depends on itself and will remove such dependencies
automatically if it finds them. If systemd does not detect the recursive
dependency chain, we can break the chain ourselves by disabling the drop-in
for the template instance units via a symlink to
<filename index='false'>/dev/null</filename>:</para>
<programlisting>
<command>mkdir /etc/systemd/system/failure-handler@.service.d/</command>
<command>ln -s /dev/null /etc/systemd/system/failure-handler@.service.d/10-all.conf</command>
<command>systemctl daemon-reload</command>
</programlisting>
<para>This ensures that if a <filename index='false'>failure-handler@.service</filename> instance fails it will not trigger an instance named
<filename index='false'>failure-handler@failure-handler.service</filename>.</para>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>