HALF ECHO LEARN / REFERENCE COLLECTION

v262.2

man/systemd.unit.xml

165,445 bytesGit mode 100644Download original fileLGPL-2.1-or-later

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>&lt;</literal>, <literal>&lt;=</literal>, <literal>==</literal>,
          <literal>&lt;&gt;</literal>, <literal>&gt;=</literal>, <literal>&gt;</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>