template <literal>.d/</literal> subdirectory and reads
its <literal>.conf</literal> files.</para>
+ <!-- Note that we do not document .include here, as we
+ consider it mostly obsolete, and want people to
+ use .d/ drop-ins instead. -->
+
<para>Note that while systemd offers a flexible
dependency system between units it is recommended to
use this functionality only sparingly and instead rely
the file system namespace. If this applies, a special
way to escape the path name is used, so that the
result is usable as part of a filename. Basically,
- given a path, "/" is replaced by "-", and all
- unprintable characters and the "-" are replaced by
- C-style "\x2d" escapes. The root directory "/" is
- encoded as single dash, while otherwise the initial
- and ending "/" is removed from all paths during
- transformation. This escaping is reversible.</para>
+ given a path, "/" is replaced by "-" and all other
+ characters which are not ASCII alphanumerics are
+ replaced by C-style "\x2d" escapes (except that "_"
+ is never replaced and "." is only replaced when it
+ would be the first character in the escaped path).
+ The root directory "/" is encoded as single dash,
+ while otherwise the initial and ending "/" are removed
+ from all paths during transformation. This escaping
+ is reversible. Properly escaped paths can be generated
+ using the <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ command.</para>
<para>Optionally, units may be instantiated from a
template file at runtime. This allows creation of
<para>When systemd is running in user mode
(<option>--user</option>) and the variable
- <varname>$SYSTEMD_UNIT_PATH</varname> is set, this
+ <varname>$SYSTEMD_UNIT_PATH</varname> is set, the
contents of this variable overrides the unit load
path. If <varname>$SYSTEMD_UNIT_PATH</varname> ends
with an empty component (<literal>:</literal>), the
<varlistentry>
<term><varname>JobTimeoutSec=</varname></term>
-
- <listitem><para>When clients are
- waiting for a job of this unit to
- complete, time out after the specified
- time. If this time limit is reached,
- the job will be cancelled, the unit
- however will not change state or even
- enter the <literal>failed</literal>
- mode. This value defaults to 0 (job
- timeouts disabled), except for device
+ <term><varname>JobTimeoutAction=</varname></term>
+ <term><varname>JobTimeoutRebootArgument=</varname></term>
+
+ <listitem><para>When a job for this
+ unit is queued a time-out may be
+ configured. If this time limit is
+ reached, the job will be cancelled,
+ the unit however will not change state
+ or even enter the
+ <literal>failed</literal> mode. This
+ value defaults to 0 (job timeouts
+ disabled), except for device
units. NB: this timeout is independent
from any unit-specific timeout (for
example, the timeout set with
- <varname>Timeout=</varname> in service
+ <varname>StartTimeoutSec=</varname> in service
units) as the job timeout has no
effect on the unit itself, only on the
job that might be pending for it. Or
timeout set with this option however
is useful to abort only the job
waiting for the unit state to
- change.</para></listitem>
+ change.</para>
+
+ <para><varname>JobTimeoutAction=</varname>
+ optionally configures an additional
+ action to take when the time-out is
+ hit. It takes the same values as the
+ per-service
+ <varname>StartLimitAction=</varname>
+ setting, see
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. Defaults to
+ <option>none</option>. <varname>JobTimeoutRebootArgument=</varname>
+ configures an optional reboot string
+ to pass to the
+ <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ system call.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ConditionDirectoryNotEmpty=</varname></term>
<term><varname>ConditionFileNotEmpty=</varname></term>
<term><varname>ConditionFileIsExecutable=</varname></term>
- <term><varname>ConditionNull=</varname></term>
+
+ <!-- We don't document ConditionNull=
+ here as it is not particularly
+ useful and probably just
+ confusing. -->
<listitem><para>Before starting a unit
verify that the specified condition is
<para><varname>ConditionSecurity=</varname>
may be used to check whether the given
security module is enabled on the
- system. Currently the recognized values
- values are <varname>selinux</varname>,
+ system. Currently the recognized
+ values values are
+ <varname>selinux</varname>,
<varname>apparmor</varname>,
- <varname>ima</varname> and
- <varname>smack</varname>.
- The test may be negated by prepending
- an exclamation
- mark.</para>
+ <varname>ima</varname>,
+ <varname>smack</varname> and
+ <varname>audit</varname>. The test may
+ be negated by prepending an
+ exclamation mark.</para>
<para><varname>ConditionCapability=</varname>
may be used to check whether the given
exists, is a regular file and marked
executable.</para>
- <para>Finally,
- <varname>ConditionNull=</varname> may
- be used to add a constant condition
- check value to the unit. It takes a
- boolean argument. If set to
- <varname>false</varname>, the condition
- will always fail, otherwise
- succeed.</para>
-
<para>If multiple conditions are
specified, the unit will be executed if
all of them apply (i.e. a logical AND
have no effect.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>AssertArchitecture=</varname></term>
+ <term><varname>AssertVirtualization=</varname></term>
+ <term><varname>AssertHost=</varname></term>
+ <term><varname>AssertKernelCommandLine=</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>AssertDirectoryNotEmpty=</varname></term>
+ <term><varname>AssertFileNotEmpty=</varname></term>
+ <term><varname>AssertFileIsExecutable=</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 it was triggered by.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>SourcePath=</varname></term>
<listitem><para>A path to a
</tbody>
</tgroup>
</table>
+
+ <para>Please note that specifiers
+ <literal>%U</literal>, <literal>%h</literal>,
+ <literal>%s</literal> are mostly useless when systemd
+ is running in system mode. PID 1 cannot query the
+ user account database for information, so the
+ specifiers only work as shortcuts for things which are
+ already specified in a different way in the unit
+ file. They are fully functional when systemd is
+ running in <option>--user</option> mode.</para>
+ </refsect1>
+
+ <refsect1>
+ <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>/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.</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>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>
+
+ <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
+ exit, 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.service</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 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>
</refsect1>
<refsect1>
<citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-verify</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>
~ianmdlvl / elogind.git / blobdiff