2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
7 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
9 <refentry id=
"systemd.unit">
12 <title>systemd.unit
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>systemd.unit
</refentrytitle>
18 <manvolnum>5</manvolnum>
22 <refname>systemd.unit
</refname>
23 <refpurpose>Unit configuration
</refpurpose>
27 <para><filename><replaceable>service
</replaceable>.service
</filename>,
28 <filename><replaceable>socket
</replaceable>.socket
</filename>,
29 <filename><replaceable>device
</replaceable>.device
</filename>,
30 <filename><replaceable>mount
</replaceable>.mount
</filename>,
31 <filename><replaceable>automount
</replaceable>.automount
</filename>,
32 <filename><replaceable>swap
</replaceable>.swap
</filename>,
33 <filename><replaceable>target
</replaceable>.target
</filename>,
34 <filename><replaceable>path
</replaceable>.path
</filename>,
35 <filename><replaceable>timer
</replaceable>.timer
</filename>,
36 <filename><replaceable>slice
</replaceable>.slice
</filename>,
37 <filename><replaceable>scope
</replaceable>.scope
</filename></para>
40 <title>System Unit Search Path
</title>
42 <para><literallayout><filename>/etc/systemd/system.control/*
</filename>
43 <filename>/run/systemd/system.control/*
</filename>
44 <filename>/run/systemd/transient/*
</filename>
45 <filename>/run/systemd/generator.early/*
</filename>
46 <filename>/etc/systemd/system/*
</filename>
47 <filename>/etc/systemd/systemd.attached/*
</filename>
48 <filename>/run/systemd/system/*
</filename>
49 <filename>/run/systemd/systemd.attached/*
</filename>
50 <filename>/run/systemd/generator/*
</filename>
51 <filename>…
</filename>
52 <filename>/usr/lib/systemd/system/*
</filename>
53 <filename>/run/systemd/generator.late/*
</filename></literallayout></para>
57 <title>User Unit Search Path
</title>
58 <para><literallayout><filename>~/.config/systemd/user.control/*
</filename>
59 <filename>$XDG_RUNTIME_DIR/systemd/user.control/*
</filename>
60 <filename>$XDG_RUNTIME_DIR/systemd/transient/*
</filename>
61 <filename>$XDG_RUNTIME_DIR/systemd/generator.early/*
</filename>
62 <filename>~/.config/systemd/user/*
</filename>
63 <filename>/etc/systemd/user/*
</filename>
64 <filename>$XDG_RUNTIME_DIR/systemd/user/*
</filename>
65 <filename>/run/systemd/user/*
</filename>
66 <filename>$XDG_RUNTIME_DIR/systemd/generator/*
</filename>
67 <filename>~/.local/share/systemd/user/*
</filename>
68 <filename>…
</filename>
69 <filename>/usr/lib/systemd/user/*
</filename>
70 <filename>$XDG_RUNTIME_DIR/systemd/generator.late/*
</filename></literallayout></para>
76 <title>Description
</title>
78 <para>A unit file is a plain text ini-style file that encodes information about a service, a
79 socket, a device, a mount point, an automount point, a swap file or partition, a start-up
80 target, a watched file system path, a timer controlled and supervised by
81 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>, a
82 resource management slice or a group of externally created processes. See
83 <citerefentry><refentrytitle>systemd.syntax
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
84 for a general description of the syntax.
</para>
86 <para>This man page lists the common configuration options of all
87 the unit types. These options need to be configured in the [Unit]
88 or [Install] sections of the unit files.
</para>
90 <para>In addition to the generic [Unit] and [Install] sections
91 described here, each unit may have a type-specific section, e.g.
92 [Service] for a service unit. See the respective man pages for
94 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
95 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
96 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
97 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
98 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
99 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
100 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
101 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
102 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
103 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
104 <citerefentry><refentrytitle>systemd.scope
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
107 <para>Unit files are loaded from a set of paths determined during
108 compilation, described in the next section.
</para>
110 <para>Unit files can be parameterized by a single argument called the
"instance name". The unit
111 is then constructed based on a
"template file" which serves as the definition of multiple
112 services or other units. A template unit must have a single
<literal>@
</literal> at the end of
113 the name (right before the type suffix). The name of the full unit is formed by inserting the
114 instance name between
<literal>@
</literal> and the unit type suffix. In the unit file itself,
115 the instance parameter may be referred to using
<literal>%i
</literal> and other specifiers, see
118 <para>Unit files may contain additional options on top of those
119 listed here. If systemd encounters an unknown option, it will
120 write a warning log message but continue loading the unit. If an
121 option or section name is prefixed with
<option>X-
</option>, it is
122 ignored completely by systemd. Options within an ignored section
123 do not need the prefix. Applications may use this to include
124 additional information in the unit files.
</para>
126 <para>Units can be aliased (have an alternative name), by creating a symlink from the new name
127 to the existing name in one of the unit search paths. For example,
128 <filename>systemd-networkd.service
</filename> has the alias
129 <filename>dbus-org.freedesktop.network1.service
</filename>, created during installation as the
130 symlink
<filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service
</filename>. In
131 addition, unit files may specify aliases through the
<varname>Alias=
</varname> directive in the
132 [Install] section; those aliases are only effective when the unit is enabled. When the unit is
133 enabled, symlinks will be created for those names, and removed when the unit is disabled. For
134 example,
<filename>reboot.target
</filename> specifies
135 <varname>Alias=ctrl-alt-del.target
</varname>, so when enabled it will be invoked whenever
136 CTRL+ALT+DEL is pressed. Alias names may be used in commands like
<command>enable
</command>,
137 <command>disable
</command>,
<command>start
</command>,
<command>stop
</command>,
138 <command>status
</command>, …, and in unit dependency directives
<varname>Wants=
</varname>,
139 <varname>Requires=
</varname>,
<varname>Before=
</varname>,
<varname>After=
</varname>, …, with the
140 limitation that aliases specified through
<varname>Alias=
</varname> are only effective when the
141 unit is enabled. Aliases cannot be used with the
<command>preset
</command> command.
</para>
143 <para>Along with a unit file
<filename>foo.service
</filename>, the directory
144 <filename>foo.service.wants/
</filename> may exist. All unit files symlinked from such a
145 directory are implicitly added as dependencies of type
<varname>Wants=
</varname> to the unit.
146 This is useful to hook units into the start-up of other units, without having to modify their
147 unit files. For details about the semantics of
<varname>Wants=
</varname>, see below. The
148 preferred way to create symlinks in the
<filename>.wants/
</filename> directory of a unit file is
149 with the
<command>enable
</command> command of the
150 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
151 tool which reads information from the [Install] section of unit files (see below). A similar
152 functionality exists for
<varname>Requires=
</varname> type dependencies as well, the directory
153 suffix is
<filename>.requires/
</filename> in this case.
</para>
155 <para>Along with a unit file
<filename>foo.service
</filename>, a
"drop-in" directory
156 <filename>foo.service.d/
</filename> may exist. All files with the suffix
<literal>.conf
</literal> from this
157 directory will be parsed after the unit file itself is parsed. This is useful to alter or add configuration
158 settings for a unit, without having to modify unit files. Drop-in files must contain appropriate section
159 headers. For instantiated units, this logic will first look for the instance
<literal>.d/
</literal> subdirectory
160 (e.g.
<literal>foo@bar.service.d/
</literal>) and read its
<literal>.conf
</literal> files, followed by the template
161 <literal>.d/
</literal> subdirectory (e.g.
<literal>foo@.service.d/
</literal>) and the
<literal>.conf
</literal>
162 files there. Moreover for units names containing dashes (
<literal>-
</literal>), the set of directories generated by
163 truncating the unit name after all dashes is searched too. Specifically, for a unit name
164 <filename>foo-bar-baz.service
</filename> not only the regular drop-in directory
165 <filename>foo-bar-baz.service.d/
</filename> is searched but also both
<filename>foo-bar-.service.d/
</filename> and
166 <filename>foo-.service.d/
</filename>. This is useful for defining common drop-ins for a set of related units, whose
167 names begin with a common prefix. This scheme is particularly useful for mount, automount and slice units, whose
168 systematic naming structure is built around dashes as component separators. Note that equally named drop-in files
169 further down the prefix hierarchy override those further up,
170 i.e.
<filename>foo-bar-.service.d/
10-override.conf
</filename> overrides
171 <filename>foo-.service.d/
10-override.conf
</filename>.
</para>
173 <para>In addition to
<filename>/etc/systemd/system
</filename>, the drop-in
<literal>.d/
</literal>
174 directories for system services can be placed in
<filename>/usr/lib/systemd/system
</filename> or
175 <filename>/run/systemd/system
</filename> directories. Drop-in files in
<filename>/etc
</filename>
176 take precedence over those in
<filename>/run
</filename> which in turn take precedence over those
177 in
<filename>/usr/lib
</filename>. Drop-in files under any of these directories take precedence
178 over unit files wherever located. Multiple drop-in files with different names are applied in
179 lexicographic order, regardless of which of the directories they reside in.
</para>
181 <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want
182 people to use .d/ drop-ins instead. -->
184 <para>Note that while systemd offers a flexible dependency system
185 between units it is recommended to use this functionality only
186 sparingly and instead rely on techniques such as bus-based or
187 socket-based activation which make dependencies implicit,
188 resulting in a both simpler and more flexible system.
</para>
190 <para>As mentioned above, a unit may be instantiated from a template file. This allows creation
191 of multiple units from a single configuration file. If systemd looks for a unit configuration
192 file, it will first search for the literal unit name in the file system. If that yields no
193 success and the unit name contains an
<literal>@
</literal> character, systemd will look for a
194 unit template that shares the same name but with the instance string (i.e. the part between the
195 <literal>@
</literal> character and the suffix) removed. Example: if a service
196 <filename>getty@tty3.service
</filename> is requested and no file by that name is found, systemd
197 will look for
<filename>getty@.service
</filename> and instantiate a service from that
198 configuration file if it is found.
</para>
200 <para>To refer to the instance string from within the
201 configuration file you may use the special
<literal>%i
</literal>
202 specifier in many of the configuration options. See below for
205 <para>If a unit file is empty (i.e. has the file size
0) or is
206 symlinked to
<filename>/dev/null
</filename>, its configuration
207 will not be loaded and it appears with a load state of
208 <literal>masked
</literal>, and cannot be activated. Use this as an
209 effective way to fully disable a unit, making it impossible to
210 start it even manually.
</para>
212 <para>The unit file format is covered by the
214 url=
"https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
215 Stability Promise
</ulink>.
</para>
220 <title>String Escaping for Inclusion in Unit Names
</title>
222 <para>Sometimes it is useful to convert arbitrary strings into unit names. To facilitate this, a method of string
223 escaping is used, in order to map strings containing arbitrary byte values (except NUL) into valid unit names and
224 their restricted character set. A common special case are unit names that reflect paths to objects in the file
225 system hierarchy. Example: a device unit
<filename>dev-sda.device
</filename> refers to a device with the device
226 node
<filename noindex='true'
>/dev/sda
</filename> in the file system.
</para>
228 <para>The escaping algorithm operates as follows: given a string, any
<literal>/
</literal> character is replaced by
229 <literal>-
</literal>, and all other characters which are not ASCII alphanumerics or
<literal>_
</literal> are
230 replaced by C-style
<literal>\x2d
</literal> escapes. In addition,
<literal>.
</literal> is replaced with such a
231 C-style escape when it would appear as the first character in the escaped string.
</para>
233 <para>When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the
234 root directory
<literal>/
</literal> is encoded as single dash
<literal>-
</literal>. In addition, any leading,
235 trailing or duplicate
<literal>/
</literal> characters are removed from the string before transformation. Example:
236 <filename>/foo//bar/baz/
</filename> becomes
<literal>foo-bar-baz
</literal>.
</para>
238 <para>This escaping is fully reversible, as long as it is known whether the escaped string was a path (the
239 unescaping results are different for paths and non-path strings). The
240 <citerefentry><refentrytitle>systemd-escape
</refentrytitle><manvolnum>1</manvolnum></citerefentry> command may be
241 used to apply and reverse escaping on arbitrary strings. Use
<command>systemd-escape --path
</command> to escape
242 path strings, and
<command>systemd-escape
</command> without
<option>--path
</option> otherwise.
</para>
246 <title>Automatic dependencies
</title>
249 <title>Implicit Dependencies
</title>
251 <para>A number of unit dependencies are implicitly established, depending on unit type and
252 unit configuration. These implicit dependencies can make unit configuration file cleaner. For
253 the implicit dependencies in each unit type, please refer to section
"Implicit Dependencies"
254 in respective man pages.
</para>
256 <para>For example, service units with
<varname>Type=dbus
</varname> automatically acquire
257 dependencies of type
<varname>Requires=
</varname> and
<varname>After=
</varname> on
258 <filename>dbus.socket
</filename>. See
259 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
264 <title>Default Dependencies
</title>
266 <para>Default dependencies are similar to implicit dependencies, but can be turned on and off
267 by setting
<varname>DefaultDependencies=
</varname> to
<varname>yes
</varname> (the default) and
268 <varname>no
</varname>, while implicit dependencies are always in effect. See section
"Default
269 Dependencies" in respective man pages for the effect of enabling
270 <varname>DefaultDependencies=
</varname> in each unit types.
</para>
272 <para>For example, target units will complement all configured dependencies of type
273 <varname>Wants=
</varname> or
<varname>Requires=
</varname> with dependencies of type
274 <varname>After=
</varname> unless
<varname>DefaultDependencies=no
</varname> is set in the
276 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
277 for details. Note that this behavior can be turned off by setting
278 <varname>DefaultDependencies=no
</varname>.
</para>
283 <title>Unit File Load Path
</title>
285 <para>Unit files are loaded from a set of paths determined during
286 compilation, described in the two tables below. Unit files found
287 in directories listed earlier override files with the same name in
288 directories lower in the list.
</para>
290 <para>When the variable
<varname>$SYSTEMD_UNIT_PATH
</varname> is set,
291 the contents of this variable overrides the unit load path. If
292 <varname>$SYSTEMD_UNIT_PATH
</varname> ends with an empty component
293 (
<literal>:
</literal>), the usual unit load path will be appended
294 to the contents of the variable.
</para>
298 Load path when running in system mode (
<option>--system
</option>).
302 <colspec colname='path'
/>
303 <colspec colname='expl'
/>
307 <entry>Description
</entry>
312 <entry><filename>/etc/systemd/system.control
</filename></entry>
313 <entry morerows=
"1">Persistent and transient configuration created using the dbus API
</entry>
316 <entry><filename>/run/systemd/system.control
</filename></entry>
319 <entry><filename>/run/systemd/transient
</filename></entry>
320 <entry>Dynamic configuration for transient units
</entry>
323 <entry><filename>/run/systemd/generator.early
</filename></entry>
324 <entry>Generated units with high priority (see
<replaceable>early-dir
</replaceable> in
<citerefentry
325 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
328 <entry><filename>/etc/systemd/system
</filename></entry>
329 <entry>Local configuration
</entry>
332 <entry><filename>/run/systemd/system
</filename></entry>
333 <entry>Runtime units
</entry>
336 <entry><filename>/run/systemd/generator
</filename></entry>
337 <entry>Generated units with medium priority (see
<replaceable>normal-dir
</replaceable> in
<citerefentry
338 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
341 <entry><filename>/usr/local/lib/systemd/system
</filename></entry>
342 <entry morerows=
"1">Units of installed packages
</entry>
345 <entry><filename>/usr/lib/systemd/system
</filename></entry>
348 <entry><filename>/run/systemd/generator.late
</filename></entry>
349 <entry>Generated units with low priority (see
<replaceable>late-dir
</replaceable> in
<citerefentry
350 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
358 Load path when running in user mode (
<option>--user
</option>).
362 <colspec colname='path'
/>
363 <colspec colname='expl'
/>
367 <entry>Description
</entry>
372 <entry><filename>$XDG_CONFIG_HOME/systemd/user.control
</filename> or
<filename
373 >~/.config/systemd/user.control
</filename></entry>
374 <entry morerows=
"1">Persistent and transient configuration created using the dbus API (
<varname>$XDG_CONFIG_HOME
</varname> is used if set,
<filename>~/.config
</filename> otherwise)
</entry>
377 <entry><filename>$XDG_RUNTIME_DIR/systemd/user.control
</filename></entry>
380 <entry><filename>/run/systemd/transient
</filename></entry>
381 <entry>Dynamic configuration for transient units
</entry>
384 <entry><filename>/run/systemd/generator.early
</filename></entry>
385 <entry>Generated units with high priority (see
<replaceable>early-dir
</replaceable> in
<citerefentry
386 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
389 <entry><filename>$XDG_CONFIG_HOME/systemd/user
</filename> or
<filename>$HOME/.config/systemd/user
</filename></entry>
390 <entry>User configuration (
<varname>$XDG_CONFIG_HOME
</varname> is used if set,
<filename>~/.config
</filename> otherwise)
</entry>
393 <entry><filename>/etc/systemd/user
</filename></entry>
394 <entry>Local configuration
</entry>
397 <entry><filename>$XDG_RUNTIME_DIR/systemd/user
</filename></entry>
398 <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)
</entry>
401 <entry><filename>/run/systemd/user
</filename></entry>
402 <entry>Runtime units
</entry>
405 <entry><filename>$XDG_RUNTIME_DIR/systemd/generator
</filename></entry>
406 <entry>Generated units with medium priority (see
<replaceable>normal-dir
</replaceable> in
<citerefentry
407 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
410 <entry><filename>$XDG_DATA_HOME/systemd/user
</filename> or
<filename>$HOME/.local/share/systemd/user
</filename></entry>
411 <entry>Units of packages that have been installed in the home directory (
<varname>$XDG_DATA_HOME
</varname> is used if set,
<filename>~/.local/share
</filename> otherwise)
</entry>
414 <entry><filename>$dir/systemd/user
</filename> for each
<varname noindex='true'
>$dir
</varname> in
<varname>$XDG_DATA_DIRS
</varname></entry>
415 <entry>Additional locations for installed user units, one for each entry in
<varname>$XDG_DATA_DIRS
</varname></entry>
418 <entry><filename>/usr/local/lib/systemd/user
</filename></entry>
419 <entry morerows=
"1">Units of packages that have been installed system-wide
</entry>
422 <entry><filename>/usr/lib/systemd/user
</filename></entry>
425 <entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late
</filename></entry>
426 <entry>Generated units with low priority (see
<replaceable>late-dir
</replaceable> in
<citerefentry
427 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
433 <para>The set of load paths for the user manager instance may be augmented or
434 changed using various environment variables. And environment variables may in
435 turn be set using environment generators, see
436 <citerefentry><refentrytitle>systemd.environment-generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
437 In particular,
<varname>$XDG_DATA_HOME
</varname> and
438 <varname>$XDG_DATA_DIRS
</varname> may be easily set using
439 <citerefentry><refentrytitle>systemd-environment-d-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
440 Thus, directories listed here are just the defaults. To see the actual list that
441 would be used based on compilation options and current environment use
442 <programlisting>systemd-analyze --user unit-paths
</programlisting>
445 <para>Moreover, additional units might be loaded into systemd (
"linked") from
446 directories not on the unit load path. See the
<command>link
</command> command
448 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
453 <title>Unit Garbage Collection
</title>
455 <para>The system and service manager loads a unit's configuration automatically when a unit is referenced for the
456 first time. It will automatically unload the unit configuration and state again when the unit is not needed anymore
457 (
"garbage collection"). A unit may be referenced through a number of different mechanisms:
</para>
460 <listitem><para>Another loaded unit references it with a dependency such as
<varname>After=
</varname>,
461 <varname>Wants=
</varname>, …
</para></listitem>
463 <listitem><para>The unit is currently starting, running, reloading or stopping.
</para></listitem>
465 <listitem><para>The unit is currently in the
<constant>failed
</constant> state. (But see below.)
</para></listitem>
467 <listitem><para>A job for the unit is pending.
</para></listitem>
469 <listitem><para>The unit is pinned by an active IPC client program.
</para></listitem>
471 <listitem><para>The unit is a special
"perpetual" unit that is always active and loaded. Examples for perpetual
472 units are the root mount unit
<filename>-.mount
</filename> or the scope unit
<filename>init.scope
</filename> that
473 the service manager itself lives in.
</para></listitem>
475 <listitem><para>The unit has running processes associated with it.
</para></listitem>
478 <para>The garbage collection logic may be altered with the
<varname>CollectMode=
</varname> option, which allows
479 configuration whether automatic unloading of units that are in
<constant>failed
</constant> state is permissible,
482 <para>Note that when a unit's configuration and state is unloaded, all execution results, such as exit codes, exit
483 signals, resource consumption and other statistics are lost, except for what is stored in the log subsystem.
</para>
485 <para>Use
<command>systemctl daemon-reload
</command> or an equivalent command to reload unit configuration while
486 the unit is already loaded. In this case all configuration settings are flushed out and replaced with the new
487 configuration (which however might not be in effect immediately), however all runtime state is
488 saved/restored.
</para>
492 <title>[Unit] Section Options
</title>
494 <para>The unit file may include a [Unit] section, which carries
495 generic information about the unit that is not dependent on the
498 <variablelist class='unit-directives'
>
501 <term><varname>Description=
</varname></term>
502 <listitem><para>A human readable name for the unit. This is used by
503 <command>systemd
</command> (and other UIs) as the label for the unit, so this string should
504 identify the unit rather than describe it, despite the name.
<literal>Apache2 Web
505 Server
</literal> is a good example. Bad examples are
<literal>high-performance light-weight
506 HTTP server
</literal> (too generic) or
<literal>Apache2
</literal> (too specific and
507 meaningless for people who do not know Apache).
<command>systemd
</command> will use this
508 string as a noun in status messages (
<literal>Starting
509 <replaceable>description
</replaceable>...
</literal>,
<literal>Started
510 <replaceable>description
</replaceable>.
</literal>,
<literal>Reached target
511 <replaceable>description
</replaceable>.
</literal>,
<literal>Failed to start
512 <replaceable>description
</replaceable>.
</literal>), so it should be capitalized, and should
513 not be a full sentence or a phrase with a continous verb. Bad examples include
514 <literal>exiting the container
</literal> or
<literal>updating the database once per
515 day.
</literal>.
</para>
520 <term><varname>Documentation=
</varname></term>
521 <listitem><para>A space-separated list of URIs referencing
522 documentation for this unit or its configuration. Accepted are
523 only URIs of the types
<literal>http://
</literal>,
524 <literal>https://
</literal>,
<literal>file:
</literal>,
525 <literal>info:
</literal>,
<literal>man:
</literal>. For more
526 information about the syntax of these URIs, see
<citerefentry
527 project='man-pages'
><refentrytitle>uri
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
528 The URIs should be listed in order of relevance, starting with
529 the most relevant. It is a good idea to first reference
530 documentation that explains what the unit's purpose is,
531 followed by how it is configured, followed by any other
532 related documentation. This option may be specified more than
533 once, in which case the specified list of URIs is merged. If
534 the empty string is assigned to this option, the list is reset
535 and all prior assignments will have no
536 effect.
</para></listitem>
540 <term><varname>Requires=
</varname></term>
542 <listitem><para>Configures requirement dependencies on other units. If this unit gets activated, the units
543 listed here will be activated as well. If one of the other units fails to activate, and an ordering dependency
544 <varname>After=
</varname> on the failing unit is set, this unit will not be started. Besides, with or without
545 specifying
<varname>After=
</varname>, this unit will be stopped if one of the other units is explicitly
546 stopped. This option may be specified more than once or multiple space-separated units may be
547 specified in one option in which case requirement dependencies for all listed names will be created. Note that
548 requirement dependencies do not influence the order in which services are started or stopped. This has to be
549 configured independently with the
<varname>After=
</varname> or
<varname>Before=
</varname> options. If a unit
550 <filename>foo.service
</filename> requires a unit
<filename>bar.service
</filename> as configured with
551 <varname>Requires=
</varname> and no ordering is configured with
<varname>After=
</varname> or
552 <varname>Before=
</varname>, then both units will be started simultaneously and without any delay between them
553 if
<filename>foo.service
</filename> is activated. Often, it is a better choice to use
<varname>Wants=
</varname>
554 instead of
<varname>Requires=
</varname> in order to achieve a system that is more robust when dealing with
555 failing services.
</para>
557 <para>Note that this dependency type does not imply that the other unit always has to be in active state when
558 this unit is running. Specifically: failing condition checks (such as
<varname>ConditionPathExists=
</varname>,
559 <varname>ConditionPathIsSymbolicLink=
</varname>, … — see below) do not cause the start job of a unit with a
560 <varname>Requires=
</varname> dependency on it to fail. Also, some unit types may deactivate on their own (for
561 example, a service process may decide to exit cleanly, or a device may be unplugged by the user), which is not
562 propagated to units having a
<varname>Requires=
</varname> dependency. Use the
<varname>BindsTo=
</varname>
563 dependency type together with
<varname>After=
</varname> to ensure that a unit may never be in active state
564 without a specific other unit also in active state (see below).
</para>
566 <para>Note that dependencies of this type may also be configured outside of the unit configuration file by
567 adding a symlink to a
<filename>.requires/
</filename> directory accompanying the unit file. For details, see
568 above.
</para></listitem>
572 <term><varname>Requisite=
</varname></term>
574 <listitem><para>Similar to
<varname>Requires=
</varname>. However, if the units listed here
575 are not started already, they will not be started and the starting of this unit will fail
576 immediately.
<varname>Requisite=
</varname> does not imply an ordering dependency, even if
577 both units are started in the same transaction. Hence this setting should usually be
578 combined with
<varname>After=
</varname>, to ensure this unit is not started before the other
581 <para>When
<varname>Requisite=b.service
</varname> is used on
582 <filename>a.service
</filename>, this dependency will show as
583 <varname>RequisiteOf=a.service
</varname> in property listing of
584 <filename>b.service
</filename>.
<varname>RequisiteOf=
</varname>
585 dependency cannot be specified directly.
</para>
590 <term><varname>Wants=
</varname></term>
592 <listitem><para>A weaker version of
593 <varname>Requires=
</varname>. Units listed in this option will
594 be started if the configuring unit is. However, if the listed
595 units fail to start or cannot be added to the transaction,
596 this has no impact on the validity of the transaction as a
597 whole. This is the recommended way to hook start-up of one
598 unit to the start-up of another unit.
</para>
600 <para>Note that dependencies of this type may also be
601 configured outside of the unit configuration file by adding
602 symlinks to a
<filename>.wants/
</filename> directory
603 accompanying the unit file. For details, see
604 above.
</para></listitem>
608 <term><varname>BindsTo=
</varname></term>
610 <listitem><para>Configures requirement dependencies, very similar in style to
611 <varname>Requires=
</varname>. However, this dependency type is stronger: in addition to the effect of
612 <varname>Requires=
</varname> it declares that if the unit bound to is stopped, this unit will be stopped
613 too. This means a unit bound to another unit that suddenly enters inactive state will be stopped too.
614 Units can suddenly, unexpectedly enter inactive state for different reasons: the main process of a service unit
615 might terminate on its own choice, the backing device of a device unit might be unplugged or the mount point of
616 a mount unit might be unmounted without involvement of the system and service manager.
</para>
618 <para>When used in conjunction with
<varname>After=
</varname> on the same unit the behaviour of
619 <varname>BindsTo=
</varname> is even stronger. In this case, the unit bound to strictly has to be in active
620 state for this unit to also be in active state. This not only means a unit bound to another unit that suddenly
621 enters inactive state, but also one that is bound to another unit that gets skipped due to a failed condition
622 check (such as
<varname>ConditionPathExists=
</varname>,
<varname>ConditionPathIsSymbolicLink=
</varname>, … —
623 see below) will be stopped, should it be running. Hence, in many cases it is best to combine
624 <varname>BindsTo=
</varname> with
<varname>After=
</varname>.
</para>
626 <para>When
<varname>BindsTo=b.service
</varname> is used on
627 <filename>a.service
</filename>, this dependency will show as
628 <varname>BoundBy=a.service
</varname> in property listing of
629 <filename>b.service
</filename>.
<varname>BoundBy=
</varname>
630 dependency cannot be specified directly.
</para>
635 <term><varname>PartOf=
</varname></term>
637 <listitem><para>Configures dependencies similar to
638 <varname>Requires=
</varname>, but limited to stopping and
639 restarting of units. When systemd stops or restarts the units
640 listed here, the action is propagated to this unit. Note that
641 this is a one-way dependency — changes to this unit do not
642 affect the listed units.
</para>
644 <para>When
<varname>PartOf=b.service
</varname> is used on
645 <filename>a.service
</filename>, this dependency will show as
646 <varname>ConsistsOf=a.service
</varname> in property listing of
647 <filename>b.service
</filename>.
<varname>ConsistsOf=
</varname>
648 dependency cannot be specified directly.
</para>
653 <term><varname>Conflicts=
</varname></term>
655 <listitem><para>A space-separated list of unit names.
656 Configures negative requirement dependencies. If a unit has a
657 <varname>Conflicts=
</varname> setting on another unit,
658 starting the former will stop the latter and vice versa. Note
659 that this setting is independent of and orthogonal to the
660 <varname>After=
</varname> and
<varname>Before=
</varname>
661 ordering dependencies.
</para>
663 <para>If a unit A that conflicts with a unit B is scheduled to
664 be started at the same time as B, the transaction will either
665 fail (in case both are required parts of the transaction) or be
666 modified to be fixed (in case one or both jobs are not a
667 required part of the transaction). In the latter case, the job
668 that is not required will be removed, or in case both are
669 not required, the unit that conflicts will be started and the
670 unit that is conflicted is stopped.
</para></listitem>
674 <term><varname>Before=
</varname></term>
675 <term><varname>After=
</varname></term>
677 <listitem><para>These two settings expect a space-separated list of unit names. They configure ordering
678 dependencies between units. If a unit
<filename>foo.service
</filename> contains a setting
679 <option>Before=bar.service
</option> and both units are being started,
<filename>bar.service
</filename>'s
680 start-up is delayed until
<filename>foo.service
</filename> has finished starting up. Note that this setting is
681 independent of and orthogonal to the requirement dependencies as configured by
<varname>Requires=
</varname>,
682 <varname>Wants=
</varname> or
<varname>BindsTo=
</varname>. It is a common pattern to include a unit name in both
683 the
<varname>After=
</varname> and
<varname>Requires=
</varname> options, in which case the unit listed will be
684 started before the unit that is configured with these options. This option may be specified more than once, in
685 which case ordering dependencies for all listed names are created.
<varname>After=
</varname> is the inverse of
686 <varname>Before=
</varname>, i.e. while
<varname>After=
</varname> ensures that the configured unit is started
687 after the listed unit finished starting up,
<varname>Before=
</varname> ensures the opposite, that the
688 configured unit is fully started up before the listed unit is started. Note that when two units with an
689 ordering dependency between them are shut down, the inverse of the start-up order is applied. i.e. if a unit is
690 configured with
<varname>After=
</varname> on another unit, the former is stopped before the latter if both are
691 shut down. Given two units with any ordering dependency between them, if one unit is shut down and the other is
692 started up, the shutdown is ordered before the start-up. It doesn't matter if the ordering dependency is
693 <varname>After=
</varname> or
<varname>Before=
</varname>, in this case. It also doesn't matter which of the two
694 is shut down, as long as one is shut down and the other is started up. The shutdown is ordered before the
695 start-up in all cases. If two units have no ordering dependencies between them, they are shut down or started
696 up simultaneously, and no ordering takes place. It depends on the unit type when precisely a unit has finished
697 starting up. Most importantly, for service units start-up is considered completed for the purpose of
698 <varname>Before=
</varname>/
<varname>After=
</varname> when all its configured start-up commands have been
699 invoked and they either failed or reported start-up success.
</para></listitem>
703 <term><varname>OnFailure=
</varname></term>
705 <listitem><para>A space-separated list of one or more units
706 that are activated when this unit enters the
707 <literal>failed
</literal> state. A service unit using
708 <varname>Restart=
</varname> enters the failed state only after
709 the start limits are reached.
</para></listitem>
713 <term><varname>PropagatesReloadTo=
</varname></term>
714 <term><varname>ReloadPropagatedFrom=
</varname></term>
716 <listitem><para>A space-separated list of one or more units
717 where reload requests on this unit will be propagated to, or
718 reload requests on the other unit will be propagated to this
719 unit, respectively. Issuing a reload request on a unit will
720 automatically also enqueue a reload request on all units that
721 the reload request shall be propagated to via these two
722 settings.
</para></listitem>
726 <term><varname>JoinsNamespaceOf=
</varname></term>
728 <listitem><para>For units that start processes (such as service units), lists one or more other units
729 whose network and/or temporary file namespace to join. This only applies to unit types which support
730 the
<varname>PrivateNetwork=
</varname>,
<varname>NetworkNamespacePath=
</varname> and
731 <varname>PrivateTmp=
</varname> directives (see
732 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
733 details). If a unit that has this setting set is started, its processes will see the same
734 <filename>/tmp
</filename>,
<filename>/var/tmp
</filename> and network namespace as one listed unit
735 that is started. If multiple listed units are already started, it is not defined which namespace is
736 joined. Note that this setting only has an effect if
737 <varname>PrivateNetwork=
</varname>/
<varname>NetworkNamespacePath=
</varname> and/or
738 <varname>PrivateTmp=
</varname> is enabled for both the unit that joins the namespace and the unit
739 whose namespace is joined.
</para></listitem>
743 <term><varname>RequiresMountsFor=
</varname></term>
745 <listitem><para>Takes a space-separated list of absolute
746 paths. Automatically adds dependencies of type
747 <varname>Requires=
</varname> and
<varname>After=
</varname> for
748 all mount units required to access the specified path.
</para>
750 <para>Mount points marked with
<option>noauto
</option> are not
751 mounted automatically through
<filename>local-fs.target
</filename>,
752 but are still honored for the purposes of this option, i.e. they
753 will be pulled in by this unit.
</para></listitem>
757 <term><varname>OnFailureJobMode=
</varname></term>
759 <listitem><para>Takes a value of
760 <literal>fail
</literal>,
761 <literal>replace
</literal>,
762 <literal>replace-irreversibly
</literal>,
763 <literal>isolate
</literal>,
764 <literal>flush
</literal>,
765 <literal>ignore-dependencies
</literal> or
766 <literal>ignore-requirements
</literal>. Defaults to
767 <literal>replace
</literal>. Specifies how the units listed in
768 <varname>OnFailure=
</varname> will be enqueued. See
769 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
770 <option>--job-mode=
</option> option for details on the
771 possible values. If this is set to
<literal>isolate
</literal>,
772 only a single unit may be listed in
773 <varname>OnFailure=
</varname>..
</para></listitem>
777 <term><varname>IgnoreOnIsolate=
</varname></term>
779 <listitem><para>Takes a boolean argument. If
<option>true
</option>, this unit
780 will not be stopped when isolating another unit. Defaults to
781 <option>false
</option> for service, target, socket, busname, timer, and path
782 units, and
<option>true
</option> for slice, scope, device, swap, mount, and
783 automount units.
</para></listitem>
787 <term><varname>StopWhenUnneeded=
</varname></term>
789 <listitem><para>Takes a boolean argument. If
790 <option>true
</option>, this unit will be stopped when it is no
791 longer used. Note that, in order to minimize the work to be
792 executed, systemd will not stop units by default unless they
793 are conflicting with other units, or the user explicitly
794 requested their shut down. If this option is set, a unit will
795 be automatically cleaned up if no other active unit requires
796 it. Defaults to
<option>false
</option>.
</para></listitem>
800 <term><varname>RefuseManualStart=
</varname></term>
801 <term><varname>RefuseManualStop=
</varname></term>
803 <listitem><para>Takes a boolean argument. If
804 <option>true
</option>, this unit can only be activated or
805 deactivated indirectly. In this case, explicit start-up or
806 termination requested by the user is denied, however if it is
807 started or stopped as a dependency of another unit, start-up
808 or termination will succeed. This is mostly a safety feature
809 to ensure that the user does not accidentally activate units
810 that are not intended to be activated explicitly, and not
811 accidentally deactivate units that are not intended to be
812 deactivated. These options default to
813 <option>false
</option>.
</para></listitem>
817 <term><varname>AllowIsolate=
</varname></term>
819 <listitem><para>Takes a boolean argument. If
820 <option>true
</option>, this unit may be used with the
821 <command>systemctl isolate
</command> command. Otherwise, this
822 will be refused. It probably is a good idea to leave this
823 disabled except for target units that shall be used similar to
824 runlevels in SysV init systems, just as a precaution to avoid
825 unusable system states. This option defaults to
826 <option>false
</option>.
</para></listitem>
830 <term><varname>DefaultDependencies=
</varname></term>
832 <listitem><para>Takes a boolean argument. If
833 <option>true
</option>, (the default), a few default
834 dependencies will implicitly be created for the unit. The
835 actual dependencies created depend on the unit type. For
836 example, for service units, these dependencies ensure that the
837 service is started only after basic system initialization is
838 completed and is properly terminated on system shutdown. See
839 the respective man pages for details. Generally, only services
840 involved with early boot or late shutdown should set this
841 option to
<option>false
</option>. It is highly recommended to
842 leave this option enabled for the majority of common units. If
843 set to
<option>false
</option>, this option does not disable
844 all implicit dependencies, just non-essential
845 ones.
</para></listitem>
849 <term><varname>CollectMode=
</varname></term>
851 <listitem><para>Tweaks the
"garbage collection" algorithm for this unit. Takes one of
<option>inactive
</option>
852 or
<option>inactive-or-failed
</option>. If set to
<option>inactive
</option> the unit will be unloaded if it is
853 in the
<constant>inactive
</constant> state and is not referenced by clients, jobs or other units — however it
854 is not unloaded if it is in the
<constant>failed
</constant> state. In
<option>failed
</option> mode, failed
855 units are not unloaded until the user invoked
<command>systemctl reset-failed
</command> on them to reset the
856 <constant>failed
</constant> state, or an equivalent command. This behaviour is altered if this option is set to
857 <option>inactive-or-failed
</option>: in this case the unit is unloaded even if the unit is in a
858 <constant>failed
</constant> state, and thus an explicitly resetting of the
<constant>failed
</constant> state is
859 not necessary. Note that if this mode is used unit results (such as exit codes, exit signals, consumed
860 resources, …) are flushed out immediately after the unit completed, except for what is stored in the logging
861 subsystem. Defaults to
<option>inactive
</option>.
</para>
866 <term><varname>FailureAction=
</varname></term>
867 <term><varname>SuccessAction=
</varname></term>
869 <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive state.
870 Takes one of
<option>none
</option>,
<option>reboot
</option>,
<option>reboot-force
</option>,
871 <option>reboot-immediate
</option>,
<option>poweroff
</option>,
<option>poweroff-force
</option>,
872 <option>poweroff-immediate
</option>,
<option>exit
</option>, and
<option>exit-force
</option>. In system mode,
873 all options are allowed. In user mode, only
<option>none
</option>,
<option>exit
</option>, and
874 <option>exit-force
</option> are allowed. Both options default to
<option>none
</option>.
</para>
876 <para>If
<option>none
</option> is set, no action will be triggered.
<option>reboot
</option> causes a reboot
877 following the normal shutdown procedure (i.e. equivalent to
<command>systemctl reboot
</command>).
878 <option>reboot-force
</option> causes a forced reboot which will terminate all processes forcibly but should
879 cause no dirty file systems on reboot (i.e. equivalent to
<command>systemctl reboot -f
</command>) and
880 <option>reboot-immediate
</option> causes immediate execution of the
881 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which
882 might result in data loss (i.e. equivalent to
<command>systemctl reboot -ff
</command>). Similarly,
883 <option>poweroff
</option>,
<option>poweroff-force
</option>,
<option>poweroff-immediate
</option> have the effect
884 of powering down the system with similar semantics.
<option>exit
</option> causes the manager to exit following
885 the normal shutdown procedure, and
<option>exit-force
</option> causes it terminate without shutting down
886 services. When
<option>exit
</option> or
<option>exit-force
</option> is used by default the exit status of the
887 main process of the unit (if this applies) is returned from the service manager. However, this may be overriden
888 with
<varname>FailureActionExitStatus=
</varname>/
<varname>SuccessActionExitStatus=
</varname>, see
889 below.
</para></listitem>
893 <term><varname>FailureActionExitStatus=
</varname></term>
894 <term><varname>SuccessActionExitStatus=
</varname></term>
896 <listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a
897 system service) or service manager (in case of a user manager) when the
898 <varname>FailureAction=
</varname>/
<varname>SuccessAction=
</varname> are set to
<option>exit
</option> or
899 <option>exit-force
</option> and the action is triggered. By default the exit status of the main process of the
900 triggering unit (if this applies) is propagated. Takes a value in the range
0…
255 or the empty string to
901 request default behaviour.
</para></listitem>
905 <term><varname>JobTimeoutSec=
</varname></term>
906 <term><varname>JobRunningTimeoutSec=
</varname></term>
908 <listitem><para>When a job for this unit is queued, a timeout
<varname>JobTimeoutSec=
</varname> may be
909 configured. Similarly,
<varname>JobRunningTimeoutSec=
</varname> starts counting when the queued job is actually
910 started. If either time limit is reached, the job will be cancelled, the unit however will not change state or
911 even enter the
<literal>failed
</literal> mode. This value defaults to
<literal>infinity
</literal> (job timeouts
912 disabled), except for device units (
<varname>JobRunningTimeoutSec=
</varname> defaults to
913 <varname>DefaultTimeoutStartSec=
</varname>). NB: this timeout is independent from any unit-specific timeout
914 (for example, the timeout set with
<varname>TimeoutStartSec=
</varname> in service units) as the job timeout has
915 no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific
916 timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however
917 is useful to abort only the job waiting for the unit state to change.
</para>
922 <term><varname>JobTimeoutAction=
</varname></term>
923 <term><varname>JobTimeoutRebootArgument=
</varname></term>
925 <listitem><para><varname>JobTimeoutAction=
</varname> optionally configures an additional action to take when
926 the timeout is hit, see description of
<varname>JobTimeoutSec=
</varname> and
927 <varname>JobRunningTimeoutSec=
</varname> above. It takes the same values as
928 <varname>StartLimitAction=
</varname>. Defaults to
<option>none
</option>.
929 <varname>JobTimeoutRebootArgument=
</varname> configures an optional reboot string to pass to the
930 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call.
935 <term><varname>StartLimitIntervalSec=
<replaceable>interval
</replaceable></varname></term>
936 <term><varname>StartLimitBurst=
<replaceable>burst
</replaceable></varname></term>
938 <listitem><para>Configure unit start rate limiting. Units which are started more than
939 <replaceable>burst
</replaceable> times within an
<replaceable>interval
</replaceable> time interval are not
940 permitted to start any more. Use
<varname>StartLimitIntervalSec=
</varname> to configure the checking interval
941 (defaults to
<varname>DefaultStartLimitIntervalSec=
</varname> in manager configuration file, set it to
0 to
942 disable any kind of rate limiting). Use
<varname>StartLimitBurst=
</varname> to configure how many starts per
943 interval are allowed (defaults to
<varname>DefaultStartLimitBurst=
</varname> in manager configuration
944 file). These configuration options are particularly useful in conjunction with the service setting
945 <varname>Restart=
</varname> (see
946 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however,
947 they apply to all kinds of starts (including manual), not just those triggered by the
948 <varname>Restart=
</varname> logic. Note that units which are configured for
<varname>Restart=
</varname> and
949 which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted
950 manually at a later point, after the
<replaceable>interval
</replaceable> has passed. From this point on, the
951 restart logic is activated again. Note that
<command>systemctl reset-failed
</command> will cause the restart
952 rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit
953 and the start limit interferes with that. Note that this rate-limiting is enforced after any unit condition
954 checks are executed, and hence unit activations with failing conditions do not count towards this rate
955 limit. This setting does not apply to slice, target, device, and scope units, since they are unit types whose
956 activation may either never fail, or may succeed only a single time.
</para>
958 <para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are
959 flushed out too. This means that configuring start rate limiting for a unit that is not referenced continuously
960 has no effect.
</para></listitem>
964 <term><varname>StartLimitAction=
</varname></term>
966 <listitem><para>Configure an additional action to take if the rate limit configured with
967 <varname>StartLimitIntervalSec=
</varname> and
<varname>StartLimitBurst=
</varname> is hit. Takes the same
968 values as the setting
<varname>FailureAction=
</varname>/
<varname>SuccessAction=
</varname> settings and executes
969 the same actions. If
<option>none
</option> is set, hitting the rate limit will trigger no action besides that
970 the start will not be permitted. Defaults to
<option>none
</option>.
</para></listitem>
975 <term><varname>RebootArgument=
</varname></term>
976 <listitem><para>Configure the optional argument for the
977 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if
978 <varname>StartLimitAction=
</varname> or
<varname>FailureAction=
</varname> is a reboot action. This
979 works just like the optional argument to
<command>systemctl reboot
</command> command.
</para></listitem>
983 <term><varname>ConditionArchitecture=
</varname></term>
984 <term><varname>ConditionVirtualization=
</varname></term>
985 <term><varname>ConditionHost=
</varname></term>
986 <term><varname>ConditionKernelCommandLine=
</varname></term>
987 <term><varname>ConditionKernelVersion=
</varname></term>
988 <term><varname>ConditionSecurity=
</varname></term>
989 <term><varname>ConditionCapability=
</varname></term>
990 <term><varname>ConditionACPower=
</varname></term>
991 <term><varname>ConditionNeedsUpdate=
</varname></term>
992 <term><varname>ConditionFirstBoot=
</varname></term>
993 <term><varname>ConditionPathExists=
</varname></term>
994 <term><varname>ConditionPathExistsGlob=
</varname></term>
995 <term><varname>ConditionPathIsDirectory=
</varname></term>
996 <term><varname>ConditionPathIsSymbolicLink=
</varname></term>
997 <term><varname>ConditionPathIsMountPoint=
</varname></term>
998 <term><varname>ConditionPathIsReadWrite=
</varname></term>
999 <term><varname>ConditionDirectoryNotEmpty=
</varname></term>
1000 <term><varname>ConditionFileNotEmpty=
</varname></term>
1001 <term><varname>ConditionFileIsExecutable=
</varname></term>
1002 <term><varname>ConditionUser=
</varname></term>
1003 <term><varname>ConditionGroup=
</varname></term>
1004 <term><varname>ConditionControlGroupController=
</varname></term>
1006 <!-- We do not document ConditionNull=
1007 here, as it is not particularly
1008 useful and probably just
1011 <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
1012 starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
1013 respected. A failing condition will not result in the unit being moved into the
<literal>failed
</literal>
1014 state. The condition is checked at the time the queued start job is to be executed. Use condition expressions
1015 in order to silently skip units that do not apply to the local running system, for example because the kernel
1016 or runtime environment doesn't require their functionality. Use the various
1017 <varname>AssertArchitecture=
</varname>,
<varname>AssertVirtualization=
</varname>, … options for a similar
1018 mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check
1019 (instead of being silently processed). For details about assertion conditions see below.
</para>
1021 <para><varname>ConditionArchitecture=
</varname> may be used to
1022 check whether the system is running on a specific
1023 architecture. Takes one of
1024 <literal>x86
</literal>,
1025 <literal>x86-
64</literal>,
1026 <literal>ppc
</literal>,
1027 <literal>ppc-le
</literal>,
1028 <literal>ppc64
</literal>,
1029 <literal>ppc64-le
</literal>,
1030 <literal>ia64
</literal>,
1031 <literal>parisc
</literal>,
1032 <literal>parisc64
</literal>,
1033 <literal>s390
</literal>,
1034 <literal>s390x
</literal>,
1035 <literal>sparc
</literal>,
1036 <literal>sparc64
</literal>,
1037 <literal>mips
</literal>,
1038 <literal>mips-le
</literal>,
1039 <literal>mips64
</literal>,
1040 <literal>mips64-le
</literal>,
1041 <literal>alpha
</literal>,
1042 <literal>arm
</literal>,
1043 <literal>arm-be
</literal>,
1044 <literal>arm64
</literal>,
1045 <literal>arm64-be
</literal>,
1046 <literal>sh
</literal>,
1047 <literal>sh64
</literal>,
1048 <literal>m68k
</literal>,
1049 <literal>tilegx
</literal>,
1050 <literal>cris
</literal>,
1051 <literal>arc
</literal>,
1052 <literal>arc-be
</literal> to test
1053 against a specific architecture. The architecture is
1054 determined from the information returned by
1055 <citerefentry project='man-pages'
><refentrytitle>uname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1056 and is thus subject to
1057 <citerefentry><refentrytitle>personality
</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
1058 Note that a
<varname>Personality=
</varname> setting in the
1059 same unit file has no effect on this condition. A special
1060 architecture name
<literal>native
</literal> is mapped to the
1061 architecture the system manager itself is compiled for. The
1062 test may be negated by prepending an exclamation mark.
</para>
1064 <para><varname>ConditionVirtualization=
</varname> may be used
1065 to check whether the system is executed in a virtualized
1066 environment and optionally test whether it is a specific
1067 implementation. Takes either boolean value to check if being
1068 executed in any virtualized environment, or one of
1069 <literal>vm
</literal> and
1070 <literal>container
</literal> to test against a generic type of
1071 virtualization solution, or one of
1072 <literal>qemu
</literal>,
1073 <literal>kvm
</literal>,
1074 <literal>zvm
</literal>,
1075 <literal>vmware
</literal>,
1076 <literal>microsoft
</literal>,
1077 <literal>oracle
</literal>,
1078 <literal>xen
</literal>,
1079 <literal>bochs
</literal>,
1080 <literal>uml
</literal>,
1081 <literal>bhyve
</literal>,
1082 <literal>qnx
</literal>,
1083 <literal>openvz
</literal>,
1084 <literal>lxc
</literal>,
1085 <literal>lxc-libvirt
</literal>,
1086 <literal>systemd-nspawn
</literal>,
1087 <literal>docker
</literal>,
1088 <literal>rkt
</literal>,
1089 <literal>wsl
</literal>,
1090 <literal>acrn
</literal> to test
1091 against a specific implementation, or
1092 <literal>private-users
</literal> to check whether we are running in a user namespace. See
1093 <citerefentry><refentrytitle>systemd-detect-virt
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1094 for a full list of known virtualization technologies and their
1095 identifiers. If multiple virtualization technologies are
1096 nested, only the innermost is considered. The test may be
1097 negated by prepending an exclamation mark.
</para>
1099 <para><varname>ConditionHost=
</varname> may be used to match
1100 against the hostname or machine ID of the host. This either
1101 takes a hostname string (optionally with shell style globs)
1102 which is tested against the locally set hostname as returned
1104 <citerefentry><refentrytitle>gethostname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1105 or a machine ID formatted as string (see
1106 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1107 The test may be negated by prepending an exclamation
1110 <para><varname>ConditionKernelCommandLine=
</varname> may be
1111 used to check whether a specific kernel command line option is
1112 set (or if prefixed with the exclamation mark unset). The
1113 argument must either be a single word, or an assignment (i.e.
1114 two words, separated
<literal>=
</literal>). In the former case
1115 the kernel command line is searched for the word appearing as
1116 is, or as left hand side of an assignment. In the latter case,
1117 the exact assignment is looked for with right and left hand
1118 side matching.
</para>
1120 <para><varname>ConditionKernelVersion=
</varname> may be used to check whether the kernel version (as reported
1121 by
<command>uname -r
</command>) matches a certain expression (or if prefixed with the exclamation mark does not
1122 match it). The argument must be a single string. If the string starts with one of
<literal><</literal>,
1123 <literal><=
</literal>,
<literal>=
</literal>,
<literal>>=
</literal>,
<literal>></literal> a relative
1124 version comparison is done, otherwise the specified string is matched with shell-style globs.
</para>
1126 <para>Note that using the kernel version string is an unreliable way to determine which features are supported
1127 by a kernel, because of the widespread practice of backporting drivers, features, and fixes from newer upstream
1128 kernels into older versions provided by distributions. Hence, this check is inherently unportable and should
1129 not be used for units which may be used on different distributions.
</para>
1131 <para><varname>ConditionSecurity=
</varname> may be used to check
1132 whether the given security technology is enabled on the
1133 system. Currently, the recognized values are
1134 <literal>selinux
</literal>,
<literal>apparmor
</literal>,
1135 <literal>tomoyo
</literal>,
<literal>ima
</literal>,
1136 <literal>smack
</literal>,
<literal>audit
</literal> and
1137 <literal>uefi-secureboot
</literal>. The test may be negated by
1138 prepending an exclamation mark.
</para>
1140 <para><varname>ConditionCapability=
</varname> may be used to
1141 check whether the given capability exists in the capability
1142 bounding set of the service manager (i.e. this does not check
1143 whether capability is actually available in the permitted or
1145 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1146 for details). Pass a capability name such as
1147 <literal>CAP_MKNOD
</literal>, possibly prefixed with an
1148 exclamation mark to negate the check.
</para>
1150 <para><varname>ConditionACPower=
</varname> may be used to
1151 check whether the system has AC power, or is exclusively
1152 battery powered at the time of activation of the unit. This
1153 takes a boolean argument. If set to
<literal>true
</literal>,
1154 the condition will hold only if at least one AC connector of
1155 the system is connected to a power source, or if no AC
1156 connectors are known. Conversely, if set to
1157 <literal>false
</literal>, the condition will hold only if
1158 there is at least one AC connector known and all AC connectors
1159 are disconnected from a power source.
</para>
1161 <para><varname>ConditionNeedsUpdate=
</varname> takes one of
1162 <filename>/var
</filename> or
<filename>/etc
</filename> as
1163 argument, possibly prefixed with a
<literal>!
</literal> (for
1164 inverting the condition). This condition may be used to
1165 conditionalize units on whether the specified directory
1166 requires an update because
<filename>/usr
</filename>'s
1167 modification time is newer than the stamp file
1168 <filename>.updated
</filename> in the specified directory. This
1169 is useful to implement offline updates of the vendor operating
1170 system resources in
<filename>/usr
</filename> that require
1171 updating of
<filename>/etc
</filename> or
1172 <filename>/var
</filename> on the next following boot. Units
1173 making use of this condition should order themselves before
1174 <citerefentry><refentrytitle>systemd-update-done.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1175 to make sure they run before the stamp file's modification
1176 time gets reset indicating a completed update.
</para>
1178 <para><varname>ConditionFirstBoot=
</varname> takes a boolean argument. This condition may be used to
1179 conditionalize units on whether the system is booting up with an unpopulated
<filename>/etc
</filename>
1180 directory (specifically: an
<filename>/etc
</filename> with no
<filename>/etc/machine-id
</filename>). This may
1181 be used to populate
<filename>/etc
</filename> on the first boot after factory reset, or when a new system
1182 instance boots up for the first time.
</para>
1184 <para>With
<varname>ConditionPathExists=
</varname> a file
1185 existence condition is checked before a unit is started. If
1186 the specified absolute path name does not exist, the condition
1187 will fail. If the absolute path name passed to
1188 <varname>ConditionPathExists=
</varname> is prefixed with an
1189 exclamation mark (
<literal>!
</literal>), the test is negated,
1190 and the unit is only started if the path does not
1193 <para><varname>ConditionPathExistsGlob=
</varname> is similar
1194 to
<varname>ConditionPathExists=
</varname>, but checks for the
1195 existence of at least one file or directory matching the
1196 specified globbing pattern.
</para>
1198 <para><varname>ConditionPathIsDirectory=
</varname> is similar
1199 to
<varname>ConditionPathExists=
</varname> but verifies
1200 whether a certain path exists and is a directory.
</para>
1202 <para><varname>ConditionPathIsSymbolicLink=
</varname> is
1203 similar to
<varname>ConditionPathExists=
</varname> but
1204 verifies whether a certain path exists and is a symbolic
1207 <para><varname>ConditionPathIsMountPoint=
</varname> is similar
1208 to
<varname>ConditionPathExists=
</varname> but verifies
1209 whether a certain path exists and is a mount point.
</para>
1211 <para><varname>ConditionPathIsReadWrite=
</varname> is similar
1212 to
<varname>ConditionPathExists=
</varname> but verifies
1213 whether the underlying file system is readable and writable
1214 (i.e. not mounted read-only).
</para>
1216 <para><varname>ConditionDirectoryNotEmpty=
</varname> is
1217 similar to
<varname>ConditionPathExists=
</varname> but
1218 verifies whether a certain path exists and is a non-empty
1221 <para><varname>ConditionFileNotEmpty=
</varname> is similar to
1222 <varname>ConditionPathExists=
</varname> but verifies whether a
1223 certain path exists and refers to a regular file with a
1224 non-zero size.
</para>
1226 <para><varname>ConditionFileIsExecutable=
</varname> is similar
1227 to
<varname>ConditionPathExists=
</varname> but verifies
1228 whether a certain path exists, is a regular file and marked
1231 <para><varname>ConditionUser=
</varname> takes a numeric
1232 <literal>UID
</literal>, a UNIX user name, or the special value
1233 <literal>@system
</literal>. This condition may be used to check
1234 whether the service manager is running as the given user. The
1235 special value
<literal>@system
</literal> can be used to check
1236 if the user id is within the system user range. This option is not
1237 useful for system services, as the system manager exclusively
1238 runs as the root user, and thus the test result is constant.
</para>
1240 <para><varname>ConditionGroup=
</varname> is similar
1241 to
<varname>ConditionUser=
</varname> but verifies that the
1242 service manager's real or effective group, or any of its
1243 auxiliary groups match the specified group or GID. This setting
1244 does not have a special value
<literal>@system
</literal>.
</para>
1246 <para><varname>ConditionControlGroupController=
</varname> takes a
1247 cgroup controller name (eg.
<literal>cpu
</literal>), verifying that it is
1248 available for use on the system. For example, a particular controller
1249 may not be available if it was disabled on the kernel command line with
1250 <varname>cgroup_disable=controller
</varname>. Multiple controllers may
1251 be passed with a space separating them; in this case the condition will
1252 only pass if all listed controllers are available for use. Controllers
1253 unknown to systemd are ignored. Valid controllers are
1254 <literal>cpu
</literal>,
<literal>cpuacct
</literal>,
<literal>io
</literal>,
1255 <literal>blkio
</literal>,
<literal>memory
</literal>,
1256 <literal>devices
</literal>, and
<literal>pids
</literal>.
</para>
1258 <para>If multiple conditions are specified, the unit will be
1259 executed if all of them apply (i.e. a logical AND is applied).
1260 Condition checks can be prefixed with a pipe symbol (|) in
1261 which case a condition becomes a triggering condition. If at
1262 least one triggering condition is defined for a unit, then the
1263 unit will be executed if at least one of the triggering
1264 conditions apply and all of the non-triggering conditions. If
1265 you prefix an argument with the pipe symbol and an exclamation
1266 mark, the pipe symbol must be passed first, the exclamation
1268 <varname>ConditionPathIsSymbolicLink=
</varname>, all path
1269 checks follow symlinks. If any of these options is assigned
1270 the empty string, the list of conditions is reset completely,
1271 all previous condition settings (of any kind) will have no
1272 effect.
</para></listitem>
1276 <term><varname>AssertArchitecture=
</varname></term>
1277 <term><varname>AssertVirtualization=
</varname></term>
1278 <term><varname>AssertHost=
</varname></term>
1279 <term><varname>AssertKernelCommandLine=
</varname></term>
1280 <term><varname>AssertKernelVersion=
</varname></term>
1281 <term><varname>AssertSecurity=
</varname></term>
1282 <term><varname>AssertCapability=
</varname></term>
1283 <term><varname>AssertACPower=
</varname></term>
1284 <term><varname>AssertNeedsUpdate=
</varname></term>
1285 <term><varname>AssertFirstBoot=
</varname></term>
1286 <term><varname>AssertPathExists=
</varname></term>
1287 <term><varname>AssertPathExistsGlob=
</varname></term>
1288 <term><varname>AssertPathIsDirectory=
</varname></term>
1289 <term><varname>AssertPathIsSymbolicLink=
</varname></term>
1290 <term><varname>AssertPathIsMountPoint=
</varname></term>
1291 <term><varname>AssertPathIsReadWrite=
</varname></term>
1292 <term><varname>AssertDirectoryNotEmpty=
</varname></term>
1293 <term><varname>AssertFileNotEmpty=
</varname></term>
1294 <term><varname>AssertFileIsExecutable=
</varname></term>
1295 <term><varname>AssertUser=
</varname></term>
1296 <term><varname>AssertGroup=
</varname></term>
1297 <term><varname>AssertControlGroupController=
</varname></term>
1299 <listitem><para>Similar to the
<varname>ConditionArchitecture=
</varname>,
1300 <varname>ConditionVirtualization=
</varname>, …, condition settings described above, these settings add
1301 assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
1302 that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a
1303 configured assertion does not cause the unit to enter the
<literal>failed
</literal> state (or in fact result in
1304 any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that
1305 cannot operate when specific requirements are not met, and when this is something the administrator or user
1306 should look into.
</para>
1308 <para>Note that neither assertion nor condition expressions result in unit state changes. Also note that both
1309 are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were
1310 queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit
1311 dependencies.
</para></listitem>
1315 <term><varname>SourcePath=
</varname></term>
1316 <listitem><para>A path to a configuration file this unit has
1317 been generated from. This is primarily useful for
1318 implementation of generator tools that convert configuration
1319 from an external configuration file format into native unit
1320 files. This functionality should not be used in normal
1321 units.
</para></listitem>
1327 <title>Mapping of unit properties to their inverses
</title>
1329 <para>Unit settings that create a relationship with a second unit usually show up
1330 in properties of both units, for example in
<command>systemctl show
</command>
1331 output. In some cases the name of the property is the same as the name of the
1332 configuration setting, but not always. This table lists the properties
1333 that are shown on two units which are connected through some dependency, and shows
1334 which property on
"source" unit corresponds to which property on the
"target" unit.
1339 "Forward" and
"reverse" unit properties
1343 <colspec colname='forward'
/>
1344 <colspec colname='reverse'
/>
1345 <colspec colname='notes'
/>
1348 <entry>"Forward" property
</entry>
1349 <entry>"Reverse" property
</entry>
1350 <entry>Where used
</entry>
1355 <entry><varname>Before=
</varname></entry>
1356 <entry><varname>After=
</varname></entry>
1357 <entry morerows='
1' valign='middle'
>Both are unit file options
</entry>
1360 <entry><varname>After=
</varname></entry>
1361 <entry><varname>Before=
</varname></entry>
1364 <entry><varname>Requires=
</varname></entry>
1365 <entry><varname>RequiredBy=
</varname></entry>
1366 <entry>A unit file option; an option in the [Install] section
</entry>
1369 <entry><varname>Wants=
</varname></entry>
1370 <entry><varname>WantedBy=
</varname></entry>
1371 <entry>A unit file option; an option in the [Install] section
</entry>
1374 <entry><varname>PartOf=
</varname></entry>
1375 <entry><varname>ConsistsOf=
</varname></entry>
1376 <entry>A unit file option; an automatic property
</entry>
1379 <entry><varname>BindsTo=
</varname></entry>
1380 <entry><varname>BoundBy=
</varname></entry>
1381 <entry>A unit file option; an automatic property
</entry>
1384 <entry><varname>Requisite=
</varname></entry>
1385 <entry><varname>RequisiteOf=
</varname></entry>
1386 <entry>A unit file option; an automatic property
</entry>
1389 <entry><varname>Triggers=
</varname></entry>
1390 <entry><varname>TriggeredBy=
</varname></entry>
1391 <entry>Automatic properties, see notes below
</entry>
1394 <entry><varname>Conflicts=
</varname></entry>
1395 <entry><varname>ConflictedBy=
</varname></entry>
1396 <entry>A unit file option; an automatic property
</entry>
1399 <entry><varname>PropagatesReloadTo=
</varname></entry>
1400 <entry><varname>ReloadPropagatedFrom=
</varname></entry>
1401 <entry morerows='
1' valign='middle'
>Both are unit file options
</entry>
1404 <entry><varname>ReloadPropagatedFrom=
</varname></entry>
1405 <entry><varname>PropagatesReloadTo=
</varname></entry>
1408 <entry><varname>Following=
</varname></entry>
1410 <entry>An automatic property
</entry>
1416 <para>Note:
<varname>WantedBy=
</varname> and
<varname>RequiredBy=
</varname> are
1417 used in the [Install] section to create symlinks in
<filename>.wants/
</filename>
1418 and
<filename>.requires/
</filename> directories. They cannot be used directly as a
1419 unit configuration setting.
</para>
1421 <para>Note:
<varname>ConsistsOf=
</varname>,
<varname>BoundBy=
</varname>,
1422 <varname>RequisiteOf=
</varname>,
<varname>ConflictedBy=
</varname> are created
1423 implicitly along with their reverse and cannot be specified directly.
</para>
1425 <para>Note:
<varname>Triggers=
</varname> is created implicitly between a socket,
1426 path unit, or an automount unit, and the unit they activate. By default a unit
1427 with the same name is triggered, but this can be overridden using
1428 <varname>Sockets=
</varname>,
<varname>Service=
</varname>, and
<varname>Unit=
</varname>
1430 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1431 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1432 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1434 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1435 for details.
<varname>TriggersBy=
</varname> is created implicitly on the
1436 triggered unit.
</para>
1438 <para>Note:
<varname>Following=
</varname> is used to group device aliases and points to the
1439 "primary" device unit that systemd is using to track device state, usually corresponding to a
1440 sysfs path. It does not show up in the
"target" unit.
</para>
1444 <title>[Install] Section Options
</title>
1446 <para>Unit files may include an
<literal>[Install]
</literal> section, which carries installation information for
1447 the unit. This section is not interpreted by
1448 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
1449 used by the
<command>enable
</command> and
<command>disable
</command> commands of the
1450 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
1451 installation of a unit.
</para>
1453 <variablelist class='unit-directives'
>
1455 <term><varname>Alias=
</varname></term>
1457 <listitem><para>A space-separated list of additional names this unit shall be installed under. The names listed
1458 here must have the same suffix (i.e. type) as the unit filename. This option may be specified more than once,
1459 in which case all listed names are used. At installation time,
<command>systemctl enable
</command> will create
1460 symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this
1461 setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support
1462 aliasing.
</para></listitem>
1466 <term><varname>WantedBy=
</varname></term>
1467 <term><varname>RequiredBy=
</varname></term>
1469 <listitem><para>This option may be used more than once, or a
1470 space-separated list of unit names may be given. A symbolic
1471 link is created in the
<filename>.wants/
</filename> or
1472 <filename>.requires/
</filename> directory of each of the
1473 listed units when this unit is installed by
<command>systemctl
1474 enable
</command>. This has the effect that a dependency of
1475 type
<varname>Wants=
</varname> or
<varname>Requires=
</varname>
1476 is added from the listed unit to the current unit. The primary
1477 result is that the current unit will be started when the
1478 listed unit is started. See the description of
1479 <varname>Wants=
</varname> and
<varname>Requires=
</varname> in
1480 the [Unit] section for details.
</para>
1482 <para><command>WantedBy=foo.service
</command> in a service
1483 <filename>bar.service
</filename> is mostly equivalent to
1484 <command>Alias=foo.service.wants/bar.service
</command> in the
1485 same file. In case of template units,
<command>systemctl
1486 enable
</command> must be called with an instance name, and
1487 this instance will be added to the
1488 <filename>.wants/
</filename> or
1489 <filename>.requires/
</filename> list of the listed unit. E.g.
1490 <command>WantedBy=getty.target
</command> in a service
1491 <filename>getty@.service
</filename> will result in
1492 <command>systemctl enable getty@tty2.service
</command>
1494 <filename>getty.target.wants/getty@tty2.service
</filename>
1495 link to
<filename>getty@.service
</filename>.
1500 <term><varname>Also=
</varname></term>
1502 <listitem><para>Additional units to install/deinstall when
1503 this unit is installed/deinstalled. If the user requests
1504 installation/deinstallation of a unit with this option
1505 configured,
<command>systemctl enable
</command> and
1506 <command>systemctl disable
</command> will automatically
1507 install/uninstall units listed in this option as well.
</para>
1509 <para>This option may be used more than once, or a
1510 space-separated list of unit names may be
1511 given.
</para></listitem>
1515 <term><varname>DefaultInstance=
</varname></term>
1517 <listitem><para>In template unit files, this specifies for
1518 which instance the unit shall be enabled if the template is
1519 enabled without any explicitly set instance. This option has
1520 no effect in non-template unit files. The specified string
1521 must be usable as instance identifier.
</para></listitem>
1525 <para>The following specifiers are interpreted in the Install
1526 section: %n, %N, %p, %i, %j, %g, %G, %U, %u, %m, %H, %b, %v. For their
1527 meaning see the next section.
1532 <title>Specifiers
</title>
1534 <para>Many settings resolve specifiers which may be used to write
1535 generic unit files referring to runtime or unit parameters that
1536 are replaced when the unit files are loaded. Specifiers must be known
1537 and resolvable for the setting to be valid. The following
1538 specifiers are understood:
</para>
1541 <title>Specifiers available in unit files
</title>
1542 <tgroup cols='
3' align='left' colsep='
1' rowsep='
1'
>
1543 <colspec colname=
"spec" />
1544 <colspec colname=
"mean" />
1545 <colspec colname=
"detail" />
1548 <entry>Specifier
</entry>
1549 <entry>Meaning
</entry>
1550 <entry>Details
</entry>
1555 <entry><literal>%b
</literal></entry>
1556 <entry>Boot ID
</entry>
1557 <entry>The boot ID of the running system, formatted as string. See
<citerefentry><refentrytitle>random
</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.
</entry>
1560 <entry><literal>%C
</literal></entry>
1561 <entry>Cache directory root
</entry>
1562 <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>
1565 <entry><literal>%E
</literal></entry>
1566 <entry>Configuration directory root
</entry>
1567 <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>
1570 <entry><literal>%f
</literal></entry>
1571 <entry>Unescaped filename
</entry>
1572 <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>
1575 <entry><literal>%h
</literal></entry>
1576 <entry>User home directory
</entry>
1577 <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to
<literal>/root
</literal>.
</entry>
1580 <entry><literal>%H
</literal></entry>
1581 <entry>Host name
</entry>
1582 <entry>The hostname of the running system at the point in time the unit configuration is loaded.
</entry>
1585 <entry><literal>%i
</literal></entry>
1586 <entry>Instance name
</entry>
1587 <entry>For instantiated units this is the string between the first
<literal>@
</literal> character and the type suffix. Empty for non-instantiated units.
</entry>
1590 <entry><literal>%I
</literal></entry>
1591 <entry>Unescaped instance name
</entry>
1592 <entry>Same as
<literal>%i
</literal>, but with escaping undone.
</entry>
1595 <entry><literal>%j
</literal></entry>
1596 <entry>Final component of the prefix
</entry>
1597 <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>
1600 <entry><literal>%J
</literal></entry>
1601 <entry>Unescaped final component of the prefix
</entry>
1602 <entry>Same as
<literal>%j
</literal>, but with escaping undone.
</entry>
1605 <entry><literal>%L
</literal></entry>
1606 <entry>Log directory root
</entry>
1607 <entry>This is either
<filename>/var/log
</filename> (for the system manager) or the path
<literal>$XDG_CONFIG_HOME
</literal> resolves to with
<filename noindex='true'
>/log
</filename> appended (for user managers).
</entry>
1610 <entry><literal>%m
</literal></entry>
1611 <entry>Machine ID
</entry>
1612 <entry>The machine ID of the running system, formatted as string. See
<citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.
</entry>
1615 <entry><literal>%n
</literal></entry>
1616 <entry>Full unit name
</entry>
1620 <entry><literal>%N
</literal></entry>
1621 <entry>Full unit name
</entry>
1622 <entry>Same as
<literal>%n
</literal>, but with the type suffix removed.
</entry>
1625 <entry><literal>%p
</literal></entry>
1626 <entry>Prefix name
</entry>
1627 <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>
1630 <entry><literal>%P
</literal></entry>
1631 <entry>Unescaped prefix name
</entry>
1632 <entry>Same as
<literal>%p
</literal>, but with escaping undone.
</entry>
1635 <entry><literal>%s
</literal></entry>
1636 <entry>User shell
</entry>
1637 <entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to
<literal>/bin/sh
</literal>.
</entry>
1640 <entry><literal>%S
</literal></entry>
1641 <entry>State directory root
</entry>
1642 <entry>This is either
<filename>/var/lib
</filename> (for the system manager) or the path
<literal>$XDG_CONFIG_HOME
</literal> resolves to (for user managers).
</entry>
1645 <entry><literal>%t
</literal></entry>
1646 <entry>Runtime directory root
</entry>
1647 <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>
1650 <entry><literal>%T
</literal></entry>
1651 <entry>Directory for temporary files
</entry>
1652 <entry>This is either
<filename>/tmp
</filename> or the path
<literal>$TMPDIR
</literal>,
<literal>$TEMP
</literal> or
<literal>$TMP
</literal> are set to.
</entry>
1655 <entry><literal>%g
</literal></entry>
1656 <entry>User group
</entry>
1657 <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>
1660 <entry><literal>%G
</literal></entry>
1661 <entry>User GID
</entry>
1662 <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>
1665 <entry><literal>%u
</literal></entry>
1666 <entry>User name
</entry>
1667 <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to
<literal>root
</literal>.
</entry>
1670 <entry><literal>%U
</literal></entry>
1671 <entry>User UID
</entry>
1672 <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to
<literal>0</literal>.
</entry>
1675 <entry><literal>%v
</literal></entry>
1676 <entry>Kernel release
</entry>
1677 <entry>Identical to
<command>uname -r
</command> output
</entry>
1680 <entry><literal>%V
</literal></entry>
1681 <entry>Directory for larger and persistent temporary files
</entry>
1682 <entry>This is either
<filename>/var/tmp
</filename> or the path
<literal>$TMPDIR
</literal>,
<literal>$TEMP
</literal> or
<literal>$TMP
</literal> are set to.
</entry>
1685 <entry><literal>%%
</literal></entry>
1686 <entry>Single percent sign
</entry>
1687 <entry>Use
<literal>%%
</literal> in place of
<literal>%
</literal> to specify a single percent sign.
</entry>
1695 <title>Examples
</title>
1698 <title>Allowing units to be enabled
</title>
1700 <para>The following snippet (highlighted) allows a unit (e.g.
1701 <filename>foo.service
</filename>) to be enabled via
1702 <command>systemctl enable
</command>:
</para>
1704 <programlisting>[Unit]
1708 ExecStart=/usr/sbin/foo-daemon
1710 <emphasis>[Install]
</emphasis>
1711 <emphasis>WantedBy=multi-user.target
</emphasis></programlisting>
1713 <para>After running
<command>systemctl enable
</command>, a
1715 <filename>/etc/systemd/system/multi-user.target.wants/foo.service
</filename>
1716 linking to the actual unit will be created. It tells systemd to
1717 pull in the unit when starting
1718 <filename>multi-user.target
</filename>. The inverse
1719 <command>systemctl disable
</command> will remove that symlink
1724 <title>Overriding vendor settings
</title>
1726 <para>There are two methods of overriding vendor settings in
1727 unit files: copying the unit file from
1728 <filename>/usr/lib/systemd/system
</filename> to
1729 <filename>/etc/systemd/system
</filename> and modifying the
1730 chosen settings. Alternatively, one can create a directory named
1731 <filename><replaceable>unit
</replaceable>.d/
</filename> within
1732 <filename>/etc/systemd/system
</filename> and place a drop-in
1733 file
<filename><replaceable>name
</replaceable>.conf
</filename>
1734 there that only changes the specific settings one is interested
1735 in. Note that multiple such drop-in files are read if
1736 present, processed in lexicographic order of their filename.
</para>
1738 <para>The advantage of the first method is that one easily
1739 overrides the complete unit, the vendor unit is not parsed at
1740 all anymore. It has the disadvantage that improvements to the
1741 unit file by the vendor are not automatically incorporated on
1744 <para>The advantage of the second method is that one only
1745 overrides the settings one specifically wants, where updates to
1746 the unit by the vendor automatically apply. This has the
1747 disadvantage that some future updates by the vendor might be
1748 incompatible with the local changes.
</para>
1750 <para>This also applies for user instances of systemd, but with
1751 different locations for the unit files. See the section on unit
1752 load paths for further details.
</para>
1754 <para>Suppose there is a vendor-supplied unit
1755 <filename>/usr/lib/systemd/system/httpd.service
</filename> with
1756 the following contents:
</para>
1758 <programlisting>[Unit]
1759 Description=Some HTTP server
1760 After=remote-fs.target sqldb.service
1761 Requires=sqldb.service
1762 AssertPathExists=/srv/webserver
1766 ExecStart=/usr/sbin/some-fancy-httpd-server
1770 WantedBy=multi-user.target
</programlisting>
1772 <para>Now one wants to change some settings as an administrator:
1773 firstly, in the local setup,
<filename>/srv/webserver
</filename>
1774 might not exist, because the HTTP server is configured to use
1775 <filename>/srv/www
</filename> instead. Secondly, the local
1776 configuration makes the HTTP server also depend on a memory
1777 cache service,
<filename>memcached.service
</filename>, that
1778 should be pulled in (
<varname>Requires=
</varname>) and also be
1779 ordered appropriately (
<varname>After=
</varname>). Thirdly, in
1780 order to harden the service a bit more, the administrator would
1781 like to set the
<varname>PrivateTmp=
</varname> setting (see
1782 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1783 for details). And lastly, the administrator would like to reset
1784 the niceness of the service to its default value of
0.
</para>
1786 <para>The first possibility is to copy the unit file to
1787 <filename>/etc/systemd/system/httpd.service
</filename> and
1788 change the chosen settings:
</para>
1790 <programlisting>[Unit]
1791 Description=Some HTTP server
1792 After=remote-fs.target sqldb.service
<emphasis>memcached.service
</emphasis>
1793 Requires=sqldb.service
<emphasis>memcached.service
</emphasis>
1794 AssertPathExists=
<emphasis>/srv/www
</emphasis>
1798 ExecStart=/usr/sbin/some-fancy-httpd-server
1799 <emphasis>Nice=
0</emphasis>
1800 <emphasis>PrivateTmp=yes
</emphasis>
1803 WantedBy=multi-user.target
</programlisting>
1805 <para>Alternatively, the administrator could create a drop-in
1807 <filename>/etc/systemd/system/httpd.service.d/local.conf
</filename>
1808 with the following contents:
</para>
1810 <programlisting>[Unit]
1811 After=memcached.service
1812 Requires=memcached.service
1813 # Reset all assertions and then re-add the condition we want
1815 AssertPathExists=/srv/www
1819 PrivateTmp=yes
</programlisting>
1821 <para>Note that for drop-in files, if one wants to remove
1822 entries from a setting that is parsed as a list (and is not a
1823 dependency), such as
<varname>AssertPathExists=
</varname> (or
1824 e.g.
<varname>ExecStart=
</varname> in service units), one needs
1825 to first clear the list before re-adding all entries except the
1826 one that is to be removed. Dependencies (
<varname>After=
</varname>, etc.)
1827 cannot be reset to an empty list, so dependencies can only be
1828 added in drop-ins. If you want to remove dependencies, you have
1829 to override the entire unit.
</para>
1835 <title>See Also
</title>
1837 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1838 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1839 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1840 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1841 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1842 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1843 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1844 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1845 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1846 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1847 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1848 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1849 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1850 <citerefentry><refentrytitle>systemd.scope
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1851 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1852 <citerefentry><refentrytitle>systemd.time
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1853 <citerefentry><refentrytitle>systemd-analyze
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1854 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1855 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1856 <citerefentry project='man-pages'
><refentrytitle>uname
</refentrytitle><manvolnum>1</manvolnum></citerefentry>