2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
9 SPDX-License-Identifier: LGPL-2.1+
12 <refentry id=
"systemd.unit">
15 <title>systemd.unit
</title>
16 <productname>systemd
</productname>
20 <refentrytitle>systemd.unit
</refentrytitle>
21 <manvolnum>5</manvolnum>
25 <refname>systemd.unit
</refname>
26 <refpurpose>Unit configuration
</refpurpose>
30 <para><filename><replaceable>service
</replaceable>.service
</filename>,
31 <filename><replaceable>socket
</replaceable>.socket
</filename>,
32 <filename><replaceable>device
</replaceable>.device
</filename>,
33 <filename><replaceable>mount
</replaceable>.mount
</filename>,
34 <filename><replaceable>automount
</replaceable>.automount
</filename>,
35 <filename><replaceable>swap
</replaceable>.swap
</filename>,
36 <filename><replaceable>target
</replaceable>.target
</filename>,
37 <filename><replaceable>path
</replaceable>.path
</filename>,
38 <filename><replaceable>timer
</replaceable>.timer
</filename>,
39 <filename><replaceable>slice
</replaceable>.slice
</filename>,
40 <filename><replaceable>scope
</replaceable>.scope
</filename></para>
43 <title>System Unit Search Path
</title>
45 <para><literallayout><filename>/etc/systemd/system.control/*
</filename>
46 <filename>/run/systemd/system.control/*
</filename>
47 <filename>/run/systemd/transient/*
</filename>
48 <filename>/run/systemd/generator.early/*
</filename>
49 <filename>/etc/systemd/system/*
</filename>
50 <filename>/etc/systemd/systemd.attached/*
</filename>
51 <filename>/run/systemd/system/*
</filename>
52 <filename>/run/systemd/systemd.attached/*
</filename>
53 <filename>/run/systemd/generator/*
</filename>
54 <filename>…
</filename>
55 <filename>/usr/lib/systemd/system/*
</filename>
56 <filename>/run/systemd/generator.late/*
</filename></literallayout></para>
60 <title>User Unit Search Path
</title>
61 <para><literallayout><filename>~/.config/systemd/user.control/*
</filename>
62 <filename>$XDG_RUNTIME_DIR/systemd/user.control/*
</filename>
63 <filename>$XDG_RUNTIME_DIR/systemd/transient/*
</filename>
64 <filename>$XDG_RUNTIME_DIR/systemd/generator.early/*
</filename>
65 <filename>~/.config/systemd/user/*
</filename>
66 <filename>/etc/systemd/user/*
</filename>
67 <filename>$XDG_RUNTIME_DIR/systemd/user/*
</filename>
68 <filename>/run/systemd/user/*
</filename>
69 <filename>$XDG_RUNTIME_DIR/systemd/generator/*
</filename>
70 <filename>~/.local/share/systemd/user/*
</filename>
71 <filename>…
</filename>
72 <filename>/usr/lib/systemd/user/*
</filename>
73 <filename>$XDG_RUNTIME_DIR/systemd/generator.late/*
</filename></literallayout></para>
79 <title>Description
</title>
81 <para>A unit file is a plain text ini-style file that encodes information about a service, a
82 socket, a device, a mount point, an automount point, a swap file or partition, a start-up
83 target, a watched file system path, a timer controlled and supervised by
84 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>, a
85 resource management slice or a group of externally created processes. See
86 <citerefentry><refentrytitle>systemd.syntax
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
87 for a general description of the syntax.
</para>
89 <para>This man page lists the common configuration options of all
90 the unit types. These options need to be configured in the [Unit]
91 or [Install] sections of the unit files.
</para>
93 <para>In addition to the generic [Unit] and [Install] sections
94 described here, each unit may have a type-specific section, e.g.
95 [Service] for a service unit. See the respective man pages for
97 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
98 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
99 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
100 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
101 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
102 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
103 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
104 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
105 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
106 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
107 <citerefentry><refentrytitle>systemd.scope
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
110 <para>Unit files are loaded from a set of paths determined during
111 compilation, described in the next section.
</para>
113 <para>Unit files can be parameterized by a single argument called the
"instance name". The unit
114 is then constructed based on a
"template file" which serves as the definition of multiple
115 services or other units. A template unit must have a single
<literal>@
</literal> at the end of
116 the name (right before the type suffix). The name of the full unit is formed by inserting the
117 instance name between
<literal>@
</literal> and the unit type suffix. In the unit file itself,
118 the instance parameter may be referred to using
<literal>%i
</literal> and other specifiers, see
121 <para>Unit files may contain additional options on top of those
122 listed here. If systemd encounters an unknown option, it will
123 write a warning log message but continue loading the unit. If an
124 option or section name is prefixed with
<option>X-
</option>, it is
125 ignored completely by systemd. Options within an ignored section
126 do not need the prefix. Applications may use this to include
127 additional information in the unit files.
</para>
129 <para>Units can be aliased (have an alternative name), by creating a symlink from the new name
130 to the existing name in one of the unit search paths. For example,
131 <filename>systemd-networkd.service
</filename> has the alias
132 <filename>dbus-org.freedesktop.network1.service
</filename>, created during installation as the
133 symlink
<filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service
</filename>. In
134 addition, unit files may specify aliases through the
<varname>Alias=
</varname> directive in the
135 [Install] section; those aliases are only effective when the unit is enabled. When the unit is
136 enabled, symlinks will be created for those names, and removed when the unit is disabled. For
137 example,
<filename>reboot.target
</filename> specifies
138 <varname>Alias=ctrl-alt-del.target
</varname>, so when enabled it will be invoked whenever
139 CTRL+ALT+DEL is pressed. Alias names may be used in commands like
<command>enable
</command>,
140 <command>disable
</command>,
<command>start
</command>,
<command>stop
</command>,
141 <command>status
</command>, …, and in unit dependency directives
<varname>Wants=
</varname>,
142 <varname>Requires=
</varname>,
<varname>Before=
</varname>,
<varname>After=
</varname>, …, with the
143 limitation that aliases specified through
<varname>Alias=
</varname> are only effective when the
144 unit is enabled. Aliases cannot be used with the
<command>preset
</command> command.
</para>
146 <para>Along with a unit file
<filename>foo.service
</filename>, the directory
147 <filename>foo.service.wants/
</filename> may exist. All unit files symlinked from such a
148 directory are implicitly added as dependencies of type
<varname>Wants=
</varname> to the unit.
149 This is useful to hook units into the start-up of other units, without having to modify their
150 unit files. For details about the semantics of
<varname>Wants=
</varname>, see below. The
151 preferred way to create symlinks in the
<filename>.wants/
</filename> directory of a unit file is
152 with the
<command>enable
</command> command of the
153 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
154 tool which reads information from the [Install] section of unit files (see below). A similar
155 functionality exists for
<varname>Requires=
</varname> type dependencies as well, the directory
156 suffix is
<filename>.requires/
</filename> in this case.
</para>
158 <para>Along with a unit file
<filename>foo.service
</filename>, a
"drop-in" directory
159 <filename>foo.service.d/
</filename> may exist. All files with the suffix
<literal>.conf
</literal> from this
160 directory will be parsed after the unit file itself is parsed. This is useful to alter or add configuration
161 settings for a unit, without having to modify unit files. Drop-in files must contain appropriate section
162 headers. For instantiated units, this logic will first look for the instance
<literal>.d/
</literal> subdirectory
163 (e.g.
<literal>foo@bar.service.d/
</literal>) and read its
<literal>.conf
</literal> files, followed by the template
164 <literal>.d/
</literal> subdirectory (e.g.
<literal>foo@.service.d/
</literal>) and the
<literal>.conf
</literal>
165 files there. Moreover for units names containing dashes (
<literal>-
</literal>), the set of directories generated by
166 truncating the unit name after all dashes is searched too. Specifically, for a unit name
167 <filename>foo-bar-baz.service
</filename> not only the regular drop-in directory
168 <filename>foo-bar-baz.service.d/
</filename> is searched but also both
<filename>foo-bar-.service.d/
</filename> and
169 <filename>foo-.service.d/
</filename>. This is useful for defining common drop-ins for a set of related units, whose
170 names begin with a common prefix. This scheme is particularly useful for mount, automount and slice units, whose
171 systematic naming structure is built around dashes as component separators. Note that equally named drop-in files
172 further down the prefix hierarchy override those further up,
173 i.e.
<filename>foo-bar-.service.d/
10-override.conf
</filename> overrides
174 <filename>foo-.service.d/
10-override.conf
</filename>.
</para>
176 <para>In addition to
<filename>/etc/systemd/system
</filename>, the drop-in
<literal>.d/
</literal>
177 directories for system services can be placed in
<filename>/usr/lib/systemd/system
</filename> or
178 <filename>/run/systemd/system
</filename> directories. Drop-in files in
<filename>/etc
</filename>
179 take precedence over those in
<filename>/run
</filename> which in turn take precedence over those
180 in
<filename>/usr/lib
</filename>. Drop-in files under any of these directories take precedence
181 over unit files wherever located. Multiple drop-in files with different names are applied in
182 lexicographic order, regardless of which of the directories they reside in.
</para>
184 <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want
185 people to use .d/ drop-ins instead. -->
187 <para>Note that while systemd offers a flexible dependency system
188 between units it is recommended to use this functionality only
189 sparingly and instead rely on techniques such as bus-based or
190 socket-based activation which make dependencies implicit,
191 resulting in a both simpler and more flexible system.
</para>
193 <para>As mentioned above, a unit may be instantiated from a template file. This allows creation
194 of multiple units from a single configuration file. If systemd looks for a unit configuration
195 file, it will first search for the literal unit name in the file system. If that yields no
196 success and the unit name contains an
<literal>@
</literal> character, systemd will look for a
197 unit template that shares the same name but with the instance string (i.e. the part between the
198 <literal>@
</literal> character and the suffix) removed. Example: if a service
199 <filename>getty@tty3.service
</filename> is requested and no file by that name is found, systemd
200 will look for
<filename>getty@.service
</filename> and instantiate a service from that
201 configuration file if it is found.
</para>
203 <para>To refer to the instance string from within the
204 configuration file you may use the special
<literal>%i
</literal>
205 specifier in many of the configuration options. See below for
208 <para>If a unit file is empty (i.e. has the file size
0) or is
209 symlinked to
<filename>/dev/null
</filename>, its configuration
210 will not be loaded and it appears with a load state of
211 <literal>masked
</literal>, and cannot be activated. Use this as an
212 effective way to fully disable a unit, making it impossible to
213 start it even manually.
</para>
215 <para>The unit file format is covered by the
217 url=
"https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
218 Stability Promise
</ulink>.
</para>
223 <title>String Escaping for Inclusion in Unit Names
</title>
225 <para>Sometimes it is useful to convert arbitrary strings into unit names. To facilitate this, a method of string
226 escaping is used, in order to map strings containing arbitrary byte values (except NUL) into valid unit names and
227 their restricted character set. A common special case are unit names that reflect paths to objects in the file
228 system hierarchy. Example: a device unit
<filename>dev-sda.device
</filename> refers to a device with the device
229 node
<filename noindex='true'
>/dev/sda
</filename> in the file system.
</para>
231 <para>The escaping algorithm operates as follows: given a string, any
<literal>/
</literal> character is replaced by
232 <literal>-
</literal>, and all other characters which are not ASCII alphanumerics or
<literal>_
</literal> are
233 replaced by C-style
<literal>\x2d
</literal> escapes. In addition,
<literal>.
</literal> is replaced with such a
234 C-style escape when it would appear as the first character in the escaped string.
</para>
236 <para>When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the
237 root directory
<literal>/
</literal> is encoded as single dash
<literal>-
</literal>. In addition, any leading,
238 trailing or duplicate
<literal>/
</literal> characters are removed from the string before transformation. Example:
239 <filename>/foo//bar/baz/
</filename> becomes
<literal>foo-bar-baz
</literal>.
</para>
241 <para>This escaping is fully reversible, as long as it is known whether the escaped string was a path (the
242 unescaping results are different for paths and non-path strings). The
243 <citerefentry><refentrytitle>systemd-escape
</refentrytitle><manvolnum>1</manvolnum></citerefentry> command may be
244 used to apply and reverse escaping on arbitrary strings. Use
<command>systemd-escape --path
</command> to escape
245 path strings, and
<command>systemd-escape
</command> without
<option>--path
</option> otherwise.
</para>
249 <title>Automatic dependencies
</title>
252 <title>Implicit Dependencies
</title>
254 <para>A number of unit dependencies are implicitly established, depending on unit type and
255 unit configuration. These implicit dependencies can make unit configuration file cleaner. For
256 the implicit dependencies in each unit type, please refer to section
"Implicit Dependencies"
257 in respective man pages.
</para>
259 <para>For example, service units with
<varname>Type=dbus
</varname> automatically acquire
260 dependencies of type
<varname>Requires=
</varname> and
<varname>After=
</varname> on
261 <filename>dbus.socket
</filename>. See
262 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
267 <title>Default Dependencies
</title>
269 <para>Default dependencies are similar to implicit dependencies, but can be turned on and off
270 by setting
<varname>DefaultDependencies=
</varname> to
<varname>yes
</varname> (the default) and
271 <varname>no
</varname>, while implicit dependencies are always in effect. See section
"Default
272 Dependencies" in respective man pages for the effect of enabling
273 <varname>DefaultDependencies=
</varname> in each unit types.
</para>
275 <para>For example, target units will complement all configured dependencies of type
276 <varname>Wants=
</varname> or
<varname>Requires=
</varname> with dependencies of type
277 <varname>After=
</varname> unless
<varname>DefaultDependencies=no
</varname> is set in the
279 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
280 for details. Note that this behavior can be turned off by setting
281 <varname>DefaultDependencies=no
</varname>.
</para>
286 <title>Unit File Load Path
</title>
288 <para>Unit files are loaded from a set of paths determined during
289 compilation, described in the two tables below. Unit files found
290 in directories listed earlier override files with the same name in
291 directories lower in the list.
</para>
293 <para>When the variable
<varname>$SYSTEMD_UNIT_PATH
</varname> is set,
294 the contents of this variable overrides the unit load path. If
295 <varname>$SYSTEMD_UNIT_PATH
</varname> ends with an empty component
296 (
<literal>:
</literal>), the usual unit load path will be appended
297 to the contents of the variable.
</para>
301 Load path when running in system mode (
<option>--system
</option>).
305 <colspec colname='path'
/>
306 <colspec colname='expl'
/>
310 <entry>Description
</entry>
315 <entry><filename>/etc/systemd/system.control
</filename></entry>
316 <entry morerows=
"1">Persistent and transient configuration created using the dbus API
</entry>
319 <entry><filename>/run/systemd/system.control
</filename></entry>
322 <entry><filename>/run/systemd/transient
</filename></entry>
323 <entry>Dynamic configuration for transient units
</entry>
326 <entry><filename>/run/systemd/generator.early
</filename></entry>
327 <entry>Generated units with high priority (see
<replaceable>early-dir
</replaceable> in
<citerefentry
328 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
331 <entry><filename>/etc/systemd/system
</filename></entry>
332 <entry>Local configuration
</entry>
335 <entry><filename>/run/systemd/system
</filename></entry>
336 <entry>Runtime units
</entry>
339 <entry><filename>/run/systemd/generator
</filename></entry>
340 <entry>Generated units with medium priority (see
<replaceable>normal-dir
</replaceable> in
<citerefentry
341 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
344 <entry><filename>/usr/local/lib/systemd/system
</filename></entry>
345 <entry morerows=
"1">Units of installed packages
</entry>
348 <entry><filename>/usr/lib/systemd/system
</filename></entry>
351 <entry><filename>/run/systemd/generator.late
</filename></entry>
352 <entry>Generated units with low priority (see
<replaceable>late-dir
</replaceable> in
<citerefentry
353 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
361 Load path when running in user mode (
<option>--user
</option>).
365 <colspec colname='path'
/>
366 <colspec colname='expl'
/>
370 <entry>Description
</entry>
375 <entry><filename>$XDG_CONFIG_HOME/systemd/user.control
</filename> or
<filename
376 >~/.config/systemd/user.control
</filename></entry>
377 <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>
380 <entry><filename>$XDG_RUNTIME_DIR/systemd/user.control
</filename></entry>
383 <entry><filename>/run/systemd/transient
</filename></entry>
384 <entry>Dynamic configuration for transient units
</entry>
387 <entry><filename>/run/systemd/generator.early
</filename></entry>
388 <entry>Generated units with high priority (see
<replaceable>early-dir
</replaceable> in
<citerefentry
389 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
392 <entry><filename>$XDG_CONFIG_HOME/systemd/user
</filename> or
<filename>$HOME/.config/systemd/user
</filename></entry>
393 <entry>User configuration (
<varname>$XDG_CONFIG_HOME
</varname> is used if set,
<filename>~/.config
</filename> otherwise)
</entry>
396 <entry><filename>/etc/systemd/user
</filename></entry>
397 <entry>Local configuration
</entry>
400 <entry><filename>$XDG_RUNTIME_DIR/systemd/user
</filename></entry>
401 <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)
</entry>
404 <entry><filename>/run/systemd/user
</filename></entry>
405 <entry>Runtime units
</entry>
408 <entry><filename>$XDG_RUNTIME_DIR/systemd/generator
</filename></entry>
409 <entry>Generated units with medium priority (see
<replaceable>normal-dir
</replaceable> in
<citerefentry
410 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
413 <entry><filename>$XDG_DATA_HOME/systemd/user
</filename> or
<filename>$HOME/.local/share/systemd/user
</filename></entry>
414 <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>
417 <entry><filename>$dir/systemd/user
</filename> for each
<varname noindex='true'
>$dir
</varname> in
<varname>$XDG_DATA_DIRS
</varname></entry>
418 <entry>Additional locations for installed user units, one for each entry in
<varname>$XDG_DATA_DIRS
</varname></entry>
421 <entry><filename>/usr/local/lib/systemd/user
</filename></entry>
422 <entry morerows=
"1">Units of packages that have been installed system-wide
</entry>
425 <entry><filename>/usr/lib/systemd/user
</filename></entry>
428 <entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late
</filename></entry>
429 <entry>Generated units with low priority (see
<replaceable>late-dir
</replaceable> in
<citerefentry
430 ><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
</entry>
436 <para>The set of load paths for the user manager instance may be augmented or
437 changed using various environment variables. And environment variables may in
438 turn be set using environment generators, see
439 <citerefentry><refentrytitle>systemd.environment-generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
440 In particular,
<varname>$XDG_DATA_HOME
</varname> and
441 <varname>$XDG_DATA_DIRS
</varname> may be easily set using
442 <citerefentry><refentrytitle>systemd-environment-d-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
443 Thus, directories listed here are just the defaults. To see the actual list that
444 would be used based on compilation options and current environment use
445 <programlisting>systemd-analyze --user unit-paths
</programlisting>
448 <para>Moreover, additional units might be loaded into systemd (
"linked") from
449 directories not on the unit load path. See the
<command>link
</command> command
451 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
456 <title>Unit Garbage Collection
</title>
458 <para>The system and service manager loads a unit's configuration automatically when a unit is referenced for the
459 first time. It will automatically unload the unit configuration and state again when the unit is not needed anymore
460 (
"garbage collection"). A unit may be referenced through a number of different mechanisms:
</para>
463 <listitem><para>Another loaded unit references it with a dependency such as
<varname>After=
</varname>,
464 <varname>Wants=
</varname>, …
</para></listitem>
466 <listitem><para>The unit is currently starting, running, reloading or stopping.
</para></listitem>
468 <listitem><para>The unit is currently in the
<constant>failed
</constant> state. (But see below.)
</para></listitem>
470 <listitem><para>A job for the unit is pending.
</para></listitem>
472 <listitem><para>The unit is pinned by an active IPC client program.
</para></listitem>
474 <listitem><para>The unit is a special
"perpetual" unit that is always active and loaded. Examples for perpetual
475 units are the root mount unit
<filename>-.mount
</filename> or the scope unit
<filename>init.scope
</filename> that
476 the service manager itself lives in.
</para></listitem>
478 <listitem><para>The unit has running processes associated with it.
</para></listitem>
481 <para>The garbage collection logic may be altered with the
<varname>CollectMode=
</varname> option, which allows
482 configuration whether automatic unloading of units that are in
<constant>failed
</constant> state is permissible,
485 <para>Note that when a unit's configuration and state is unloaded, all execution results, such as exit codes, exit
486 signals, resource consumption and other statistics are lost, except for what is stored in the log subsystem.
</para>
488 <para>Use
<command>systemctl daemon-reload
</command> or an equivalent command to reload unit configuration while
489 the unit is already loaded. In this case all configuration settings are flushed out and replaced with the new
490 configuration (which however might not be in effect immediately), however all runtime state is
491 saved/restored.
</para>
495 <title>[Unit] Section Options
</title>
497 <para>The unit file may include a [Unit] section, which carries
498 generic information about the unit that is not dependent on the
501 <variablelist class='unit-directives'
>
504 <term><varname>Description=
</varname></term>
505 <listitem><para>A human readable name for the unit. This is used by
506 <command>systemd
</command> (and other UIs) as the label for the unit, so this string should
507 identify the unit rather than describe it, despite the name.
<literal>Apache2 Web
508 Server
</literal> is a good example. Bad examples are
<literal>high-performance light-weight
509 HTTP server
</literal> (too generic) or
<literal>Apache2
</literal> (too specific and
510 meaningless for people who do not know Apache).
<command>systemd
</command> will use this
511 string as a noun in status messages (
<literal>Starting
512 <replaceable>description
</replaceable>...
</literal>,
<literal>Started
513 <replaceable>description
</replaceable>.
</literal>,
<literal>Reached target
514 <replaceable>description
</replaceable>.
</literal>,
<literal>Failed to start
515 <replaceable>description
</replaceable>.
</literal>), so it should be capitalized, and should
516 not be a full sentence or a phrase with a continous verb. Bad examples include
517 <literal>exiting the container
</literal> or
<literal>updating the database once per
518 day.
</literal>.
</para>
523 <term><varname>Documentation=
</varname></term>
524 <listitem><para>A space-separated list of URIs referencing
525 documentation for this unit or its configuration. Accepted are
526 only URIs of the types
<literal>http://
</literal>,
527 <literal>https://
</literal>,
<literal>file:
</literal>,
528 <literal>info:
</literal>,
<literal>man:
</literal>. For more
529 information about the syntax of these URIs, see
<citerefentry
530 project='man-pages'
><refentrytitle>uri
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
531 The URIs should be listed in order of relevance, starting with
532 the most relevant. It is a good idea to first reference
533 documentation that explains what the unit's purpose is,
534 followed by how it is configured, followed by any other
535 related documentation. This option may be specified more than
536 once, in which case the specified list of URIs is merged. If
537 the empty string is assigned to this option, the list is reset
538 and all prior assignments will have no
539 effect.
</para></listitem>
543 <term><varname>Requires=
</varname></term>
545 <listitem><para>Configures requirement dependencies on other units. If this unit gets activated, the units
546 listed here will be activated as well. If one of the other units fails to activate, and an ordering dependency
547 <varname>After=
</varname> on the failing unit is set, this unit will not be started. Besides, with or without
548 specifying
<varname>After=
</varname>, this unit will be stopped if one of the other units is explicitly
549 stopped. This option may be specified more than once or multiple space-separated units may be
550 specified in one option in which case requirement dependencies for all listed names will be created. Note that
551 requirement dependencies do not influence the order in which services are started or stopped. This has to be
552 configured independently with the
<varname>After=
</varname> or
<varname>Before=
</varname> options. If a unit
553 <filename>foo.service
</filename> requires a unit
<filename>bar.service
</filename> as configured with
554 <varname>Requires=
</varname> and no ordering is configured with
<varname>After=
</varname> or
555 <varname>Before=
</varname>, then both units will be started simultaneously and without any delay between them
556 if
<filename>foo.service
</filename> is activated. Often, it is a better choice to use
<varname>Wants=
</varname>
557 instead of
<varname>Requires=
</varname> in order to achieve a system that is more robust when dealing with
558 failing services.
</para>
560 <para>Note that this dependency type does not imply that the other unit always has to be in active state when
561 this unit is running. Specifically: failing condition checks (such as
<varname>ConditionPathExists=
</varname>,
562 <varname>ConditionPathIsSymbolicLink=
</varname>, … — see below) do not cause the start job of a unit with a
563 <varname>Requires=
</varname> dependency on it to fail. Also, some unit types may deactivate on their own (for
564 example, a service process may decide to exit cleanly, or a device may be unplugged by the user), which is not
565 propagated to units having a
<varname>Requires=
</varname> dependency. Use the
<varname>BindsTo=
</varname>
566 dependency type together with
<varname>After=
</varname> to ensure that a unit may never be in active state
567 without a specific other unit also in active state (see below).
</para>
569 <para>Note that dependencies of this type may also be configured outside of the unit configuration file by
570 adding a symlink to a
<filename>.requires/
</filename> directory accompanying the unit file. For details, see
571 above.
</para></listitem>
575 <term><varname>Requisite=
</varname></term>
577 <listitem><para>Similar to
<varname>Requires=
</varname>. However, if the units listed here
578 are not started already, they will not be started and the starting of this unit will fail
579 immediately.
<varname>Requisite=
</varname> does not imply an ordering dependency, even if
580 both units are started in the same transaction. Hence this setting should usually be
581 combined with
<varname>After=
</varname>, to ensure this unit is not started before the other
584 <para>When
<varname>Requisite=b.service
</varname> is used on
585 <filename>a.service
</filename>, this dependency will show as
586 <varname>RequisiteOf=a.service
</varname> in property listing of
587 <filename>b.service
</filename>.
<varname>RequisiteOf=
</varname>
588 dependency cannot be specified directly.
</para>
593 <term><varname>Wants=
</varname></term>
595 <listitem><para>A weaker version of
596 <varname>Requires=
</varname>. Units listed in this option will
597 be started if the configuring unit is. However, if the listed
598 units fail to start or cannot be added to the transaction,
599 this has no impact on the validity of the transaction as a
600 whole. This is the recommended way to hook start-up of one
601 unit to the start-up of another unit.
</para>
603 <para>Note that dependencies of this type may also be
604 configured outside of the unit configuration file by adding
605 symlinks to a
<filename>.wants/
</filename> directory
606 accompanying the unit file. For details, see
607 above.
</para></listitem>
611 <term><varname>BindsTo=
</varname></term>
613 <listitem><para>Configures requirement dependencies, very similar in style to
614 <varname>Requires=
</varname>. However, this dependency type is stronger: in addition to the effect of
615 <varname>Requires=
</varname> it declares that if the unit bound to is stopped, this unit will be stopped
616 too. This means a unit bound to another unit that suddenly enters inactive state will be stopped too.
617 Units can suddenly, unexpectedly enter inactive state for different reasons: the main process of a service unit
618 might terminate on its own choice, the backing device of a device unit might be unplugged or the mount point of
619 a mount unit might be unmounted without involvement of the system and service manager.
</para>
621 <para>When used in conjunction with
<varname>After=
</varname> on the same unit the behaviour of
622 <varname>BindsTo=
</varname> is even stronger. In this case, the unit bound to strictly has to be in active
623 state for this unit to also be in active state. This not only means a unit bound to another unit that suddenly
624 enters inactive state, but also one that is bound to another unit that gets skipped due to a failed condition
625 check (such as
<varname>ConditionPathExists=
</varname>,
<varname>ConditionPathIsSymbolicLink=
</varname>, … —
626 see below) will be stopped, should it be running. Hence, in many cases it is best to combine
627 <varname>BindsTo=
</varname> with
<varname>After=
</varname>.
</para>
629 <para>When
<varname>BindsTo=b.service
</varname> is used on
630 <filename>a.service
</filename>, this dependency will show as
631 <varname>BoundBy=a.service
</varname> in property listing of
632 <filename>b.service
</filename>.
<varname>BoundBy=
</varname>
633 dependency cannot be specified directly.
</para>
638 <term><varname>PartOf=
</varname></term>
640 <listitem><para>Configures dependencies similar to
641 <varname>Requires=
</varname>, but limited to stopping and
642 restarting of units. When systemd stops or restarts the units
643 listed here, the action is propagated to this unit. Note that
644 this is a one-way dependency — changes to this unit do not
645 affect the listed units.
</para>
647 <para>When
<varname>PartOf=b.service
</varname> is used on
648 <filename>a.service
</filename>, this dependency will show as
649 <varname>ConsistsOf=a.service
</varname> in property listing of
650 <filename>b.service
</filename>.
<varname>ConsistsOf=
</varname>
651 dependency cannot be specified directly.
</para>
656 <term><varname>Conflicts=
</varname></term>
658 <listitem><para>A space-separated list of unit names.
659 Configures negative requirement dependencies. If a unit has a
660 <varname>Conflicts=
</varname> setting on another unit,
661 starting the former will stop the latter and vice versa. Note
662 that this setting is independent of and orthogonal to the
663 <varname>After=
</varname> and
<varname>Before=
</varname>
664 ordering dependencies.
</para>
666 <para>If a unit A that conflicts with a unit B is scheduled to
667 be started at the same time as B, the transaction will either
668 fail (in case both are required parts of the transaction) or be
669 modified to be fixed (in case one or both jobs are not a
670 required part of the transaction). In the latter case, the job
671 that is not required will be removed, or in case both are
672 not required, the unit that conflicts will be started and the
673 unit that is conflicted is stopped.
</para></listitem>
677 <term><varname>Before=
</varname></term>
678 <term><varname>After=
</varname></term>
680 <listitem><para>These two settings expect a space-separated list of unit names. They configure ordering
681 dependencies between units. If a unit
<filename>foo.service
</filename> contains a setting
682 <option>Before=bar.service
</option> and both units are being started,
<filename>bar.service
</filename>'s
683 start-up is delayed until
<filename>foo.service
</filename> has finished starting up. Note that this setting is
684 independent of and orthogonal to the requirement dependencies as configured by
<varname>Requires=
</varname>,
685 <varname>Wants=
</varname> or
<varname>BindsTo=
</varname>. It is a common pattern to include a unit name in both
686 the
<varname>After=
</varname> and
<varname>Requires=
</varname> options, in which case the unit listed will be
687 started before the unit that is configured with these options. This option may be specified more than once, in
688 which case ordering dependencies for all listed names are created.
<varname>After=
</varname> is the inverse of
689 <varname>Before=
</varname>, i.e. while
<varname>After=
</varname> ensures that the configured unit is started
690 after the listed unit finished starting up,
<varname>Before=
</varname> ensures the opposite, that the
691 configured unit is fully started up before the listed unit is started. Note that when two units with an
692 ordering dependency between them are shut down, the inverse of the start-up order is applied. i.e. if a unit is
693 configured with
<varname>After=
</varname> on another unit, the former is stopped before the latter if both are
694 shut down. Given two units with any ordering dependency between them, if one unit is shut down and the other is
695 started up, the shutdown is ordered before the start-up. It doesn't matter if the ordering dependency is
696 <varname>After=
</varname> or
<varname>Before=
</varname>, in this case. It also doesn't matter which of the two
697 is shut down, as long as one is shut down and the other is started up. The shutdown is ordered before the
698 start-up in all cases. If two units have no ordering dependencies between them, they are shut down or started
699 up simultaneously, and no ordering takes place. It depends on the unit type when precisely a unit has finished
700 starting up. Most importantly, for service units start-up is considered completed for the purpose of
701 <varname>Before=
</varname>/
<varname>After=
</varname> when all its configured start-up commands have been
702 invoked and they either failed or reported start-up success.
</para></listitem>
706 <term><varname>OnFailure=
</varname></term>
708 <listitem><para>A space-separated list of one or more units
709 that are activated when this unit enters the
710 <literal>failed
</literal> state. A service unit using
711 <varname>Restart=
</varname> enters the failed state only after
712 the start limits are reached.
</para></listitem>
716 <term><varname>PropagatesReloadTo=
</varname></term>
717 <term><varname>ReloadPropagatedFrom=
</varname></term>
719 <listitem><para>A space-separated list of one or more units
720 where reload requests on this unit will be propagated to, or
721 reload requests on the other unit will be propagated to this
722 unit, respectively. Issuing a reload request on a unit will
723 automatically also enqueue a reload request on all units that
724 the reload request shall be propagated to via these two
725 settings.
</para></listitem>
729 <term><varname>JoinsNamespaceOf=
</varname></term>
731 <listitem><para>For units that start processes (such as service units), lists one or more other units
732 whose network and/or temporary file namespace to join. This only applies to unit types which support
733 the
<varname>PrivateNetwork=
</varname>,
<varname>NetworkNamespacePath=
</varname> and
734 <varname>PrivateTmp=
</varname> directives (see
735 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
736 details). If a unit that has this setting set is started, its processes will see the same
737 <filename>/tmp
</filename>,
<filename>/var/tmp
</filename> and network namespace as one listed unit
738 that is started. If multiple listed units are already started, it is not defined which namespace is
739 joined. Note that this setting only has an effect if
740 <varname>PrivateNetwork=
</varname>/
<varname>NetworkNamespacePath=
</varname> and/or
741 <varname>PrivateTmp=
</varname> is enabled for both the unit that joins the namespace and the unit
742 whose namespace is joined.
</para></listitem>
746 <term><varname>RequiresMountsFor=
</varname></term>
748 <listitem><para>Takes a space-separated list of absolute
749 paths. Automatically adds dependencies of type
750 <varname>Requires=
</varname> and
<varname>After=
</varname> for
751 all mount units required to access the specified path.
</para>
753 <para>Mount points marked with
<option>noauto
</option> are not
754 mounted automatically through
<filename>local-fs.target
</filename>,
755 but are still honored for the purposes of this option, i.e. they
756 will be pulled in by this unit.
</para></listitem>
760 <term><varname>OnFailureJobMode=
</varname></term>
762 <listitem><para>Takes a value of
763 <literal>fail
</literal>,
764 <literal>replace
</literal>,
765 <literal>replace-irreversibly
</literal>,
766 <literal>isolate
</literal>,
767 <literal>flush
</literal>,
768 <literal>ignore-dependencies
</literal> or
769 <literal>ignore-requirements
</literal>. Defaults to
770 <literal>replace
</literal>. Specifies how the units listed in
771 <varname>OnFailure=
</varname> will be enqueued. See
772 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
773 <option>--job-mode=
</option> option for details on the
774 possible values. If this is set to
<literal>isolate
</literal>,
775 only a single unit may be listed in
776 <varname>OnFailure=
</varname>..
</para></listitem>
780 <term><varname>IgnoreOnIsolate=
</varname></term>
782 <listitem><para>Takes a boolean argument. If
<option>true
</option>, this unit
783 will not be stopped when isolating another unit. Defaults to
784 <option>false
</option> for service, target, socket, busname, timer, and path
785 units, and
<option>true
</option> for slice, scope, device, swap, mount, and
786 automount units.
</para></listitem>
790 <term><varname>StopWhenUnneeded=
</varname></term>
792 <listitem><para>Takes a boolean argument. If
793 <option>true
</option>, this unit will be stopped when it is no
794 longer used. Note that, in order to minimize the work to be
795 executed, systemd will not stop units by default unless they
796 are conflicting with other units, or the user explicitly
797 requested their shut down. If this option is set, a unit will
798 be automatically cleaned up if no other active unit requires
799 it. Defaults to
<option>false
</option>.
</para></listitem>
803 <term><varname>RefuseManualStart=
</varname></term>
804 <term><varname>RefuseManualStop=
</varname></term>
806 <listitem><para>Takes a boolean argument. If
807 <option>true
</option>, this unit can only be activated or
808 deactivated indirectly. In this case, explicit start-up or
809 termination requested by the user is denied, however if it is
810 started or stopped as a dependency of another unit, start-up
811 or termination will succeed. This is mostly a safety feature
812 to ensure that the user does not accidentally activate units
813 that are not intended to be activated explicitly, and not
814 accidentally deactivate units that are not intended to be
815 deactivated. These options default to
816 <option>false
</option>.
</para></listitem>
820 <term><varname>AllowIsolate=
</varname></term>
822 <listitem><para>Takes a boolean argument. If
823 <option>true
</option>, this unit may be used with the
824 <command>systemctl isolate
</command> command. Otherwise, this
825 will be refused. It probably is a good idea to leave this
826 disabled except for target units that shall be used similar to
827 runlevels in SysV init systems, just as a precaution to avoid
828 unusable system states. This option defaults to
829 <option>false
</option>.
</para></listitem>
833 <term><varname>DefaultDependencies=
</varname></term>
835 <listitem><para>Takes a boolean argument. If
836 <option>true
</option>, (the default), a few default
837 dependencies will implicitly be created for the unit. The
838 actual dependencies created depend on the unit type. For
839 example, for service units, these dependencies ensure that the
840 service is started only after basic system initialization is
841 completed and is properly terminated on system shutdown. See
842 the respective man pages for details. Generally, only services
843 involved with early boot or late shutdown should set this
844 option to
<option>false
</option>. It is highly recommended to
845 leave this option enabled for the majority of common units. If
846 set to
<option>false
</option>, this option does not disable
847 all implicit dependencies, just non-essential
848 ones.
</para></listitem>
852 <term><varname>CollectMode=
</varname></term>
854 <listitem><para>Tweaks the
"garbage collection" algorithm for this unit. Takes one of
<option>inactive
</option>
855 or
<option>inactive-or-failed
</option>. If set to
<option>inactive
</option> the unit will be unloaded if it is
856 in the
<constant>inactive
</constant> state and is not referenced by clients, jobs or other units — however it
857 is not unloaded if it is in the
<constant>failed
</constant> state. In
<option>failed
</option> mode, failed
858 units are not unloaded until the user invoked
<command>systemctl reset-failed
</command> on them to reset the
859 <constant>failed
</constant> state, or an equivalent command. This behaviour is altered if this option is set to
860 <option>inactive-or-failed
</option>: in this case the unit is unloaded even if the unit is in a
861 <constant>failed
</constant> state, and thus an explicitly resetting of the
<constant>failed
</constant> state is
862 not necessary. Note that if this mode is used unit results (such as exit codes, exit signals, consumed
863 resources, …) are flushed out immediately after the unit completed, except for what is stored in the logging
864 subsystem. Defaults to
<option>inactive
</option>.
</para>
869 <term><varname>FailureAction=
</varname></term>
870 <term><varname>SuccessAction=
</varname></term>
872 <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive state.
873 Takes one of
<option>none
</option>,
<option>reboot
</option>,
<option>reboot-force
</option>,
874 <option>reboot-immediate
</option>,
<option>poweroff
</option>,
<option>poweroff-force
</option>,
875 <option>poweroff-immediate
</option>,
<option>exit
</option>, and
<option>exit-force
</option>. In system mode,
876 all options are allowed. In user mode, only
<option>none
</option>,
<option>exit
</option>, and
877 <option>exit-force
</option> are allowed. Both options default to
<option>none
</option>.
</para>
879 <para>If
<option>none
</option> is set, no action will be triggered.
<option>reboot
</option> causes a reboot
880 following the normal shutdown procedure (i.e. equivalent to
<command>systemctl reboot
</command>).
881 <option>reboot-force
</option> causes a forced reboot which will terminate all processes forcibly but should
882 cause no dirty file systems on reboot (i.e. equivalent to
<command>systemctl reboot -f
</command>) and
883 <option>reboot-immediate
</option> causes immediate execution of the
884 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which
885 might result in data loss (i.e. equivalent to
<command>systemctl reboot -ff
</command>). Similarly,
886 <option>poweroff
</option>,
<option>poweroff-force
</option>,
<option>poweroff-immediate
</option> have the effect
887 of powering down the system with similar semantics.
<option>exit
</option> causes the manager to exit following
888 the normal shutdown procedure, and
<option>exit-force
</option> causes it terminate without shutting down
889 services. When
<option>exit
</option> or
<option>exit-force
</option> is used by default the exit status of the
890 main process of the unit (if this applies) is returned from the service manager. However, this may be overriden
891 with
<varname>FailureActionExitStatus=
</varname>/
<varname>SuccessActionExitStatus=
</varname>, see
892 below.
</para></listitem>
896 <term><varname>FailureActionExitStatus=
</varname></term>
897 <term><varname>SuccessActionExitStatus=
</varname></term>
899 <listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a
900 system service) or service manager (in case of a user manager) when the
901 <varname>FailureAction=
</varname>/
<varname>SuccessAction=
</varname> are set to
<option>exit
</option> or
902 <option>exit-force
</option> and the action is triggered. By default the exit status of the main process of the
903 triggering unit (if this applies) is propagated. Takes a value in the range
0…
255 or the empty string to
904 request default behaviour.
</para></listitem>
908 <term><varname>JobTimeoutSec=
</varname></term>
909 <term><varname>JobRunningTimeoutSec=
</varname></term>
911 <listitem><para>When a job for this unit is queued, a timeout
<varname>JobTimeoutSec=
</varname> may be
912 configured. Similarly,
<varname>JobRunningTimeoutSec=
</varname> starts counting when the queued job is actually
913 started. If either time limit is reached, the job will be cancelled, the unit however will not change state or
914 even enter the
<literal>failed
</literal> mode. This value defaults to
<literal>infinity
</literal> (job timeouts
915 disabled), except for device units (
<varname>JobRunningTimeoutSec=
</varname> defaults to
916 <varname>DefaultTimeoutStartSec=
</varname>). NB: this timeout is independent from any unit-specific timeout
917 (for example, the timeout set with
<varname>TimeoutStartSec=
</varname> in service units) as the job timeout has
918 no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific
919 timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however
920 is useful to abort only the job waiting for the unit state to change.
</para>
925 <term><varname>JobTimeoutAction=
</varname></term>
926 <term><varname>JobTimeoutRebootArgument=
</varname></term>
928 <listitem><para><varname>JobTimeoutAction=
</varname> optionally configures an additional action to take when
929 the timeout is hit, see description of
<varname>JobTimeoutSec=
</varname> and
930 <varname>JobRunningTimeoutSec=
</varname> above. It takes the same values as
931 <varname>StartLimitAction=
</varname>. Defaults to
<option>none
</option>.
932 <varname>JobTimeoutRebootArgument=
</varname> configures an optional reboot string to pass to the
933 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call.
938 <term><varname>StartLimitIntervalSec=
<replaceable>interval
</replaceable></varname></term>
939 <term><varname>StartLimitBurst=
<replaceable>burst
</replaceable></varname></term>
941 <listitem><para>Configure unit start rate limiting. Units which are started more than
942 <replaceable>burst
</replaceable> times within an
<replaceable>interval
</replaceable> time interval are not
943 permitted to start any more. Use
<varname>StartLimitIntervalSec=
</varname> to configure the checking interval
944 (defaults to
<varname>DefaultStartLimitIntervalSec=
</varname> in manager configuration file, set it to
0 to
945 disable any kind of rate limiting). Use
<varname>StartLimitBurst=
</varname> to configure how many starts per
946 interval are allowed (defaults to
<varname>DefaultStartLimitBurst=
</varname> in manager configuration
947 file). These configuration options are particularly useful in conjunction with the service setting
948 <varname>Restart=
</varname> (see
949 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however,
950 they apply to all kinds of starts (including manual), not just those triggered by the
951 <varname>Restart=
</varname> logic. Note that units which are configured for
<varname>Restart=
</varname> and
952 which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted
953 manually at a later point, after the
<replaceable>interval
</replaceable> has passed. From this point on, the
954 restart logic is activated again. Note that
<command>systemctl reset-failed
</command> will cause the restart
955 rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit
956 and the start limit interferes with that. Note that this rate-limiting is enforced after any unit condition
957 checks are executed, and hence unit activations with failing conditions do not count towards this rate
958 limit. This setting does not apply to slice, target, device, and scope units, since they are unit types whose
959 activation may either never fail, or may succeed only a single time.
</para>
961 <para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are
962 flushed out too. This means that configuring start rate limiting for a unit that is not referenced continuously
963 has no effect.
</para></listitem>
967 <term><varname>StartLimitAction=
</varname></term>
969 <listitem><para>Configure an additional action to take if the rate limit configured with
970 <varname>StartLimitIntervalSec=
</varname> and
<varname>StartLimitBurst=
</varname> is hit. Takes the same
971 values as the setting
<varname>FailureAction=
</varname>/
<varname>SuccessAction=
</varname> settings and executes
972 the same actions. If
<option>none
</option> is set, hitting the rate limit will trigger no action besides that
973 the start will not be permitted. Defaults to
<option>none
</option>.
</para></listitem>
978 <term><varname>RebootArgument=
</varname></term>
979 <listitem><para>Configure the optional argument for the
980 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if
981 <varname>StartLimitAction=
</varname> or
<varname>FailureAction=
</varname> is a reboot action. This
982 works just like the optional argument to
<command>systemctl reboot
</command> command.
</para></listitem>
986 <term><varname>ConditionArchitecture=
</varname></term>
987 <term><varname>ConditionVirtualization=
</varname></term>
988 <term><varname>ConditionHost=
</varname></term>
989 <term><varname>ConditionKernelCommandLine=
</varname></term>
990 <term><varname>ConditionKernelVersion=
</varname></term>
991 <term><varname>ConditionSecurity=
</varname></term>
992 <term><varname>ConditionCapability=
</varname></term>
993 <term><varname>ConditionACPower=
</varname></term>
994 <term><varname>ConditionNeedsUpdate=
</varname></term>
995 <term><varname>ConditionFirstBoot=
</varname></term>
996 <term><varname>ConditionPathExists=
</varname></term>
997 <term><varname>ConditionPathExistsGlob=
</varname></term>
998 <term><varname>ConditionPathIsDirectory=
</varname></term>
999 <term><varname>ConditionPathIsSymbolicLink=
</varname></term>
1000 <term><varname>ConditionPathIsMountPoint=
</varname></term>
1001 <term><varname>ConditionPathIsReadWrite=
</varname></term>
1002 <term><varname>ConditionDirectoryNotEmpty=
</varname></term>
1003 <term><varname>ConditionFileNotEmpty=
</varname></term>
1004 <term><varname>ConditionFileIsExecutable=
</varname></term>
1005 <term><varname>ConditionUser=
</varname></term>
1006 <term><varname>ConditionGroup=
</varname></term>
1007 <term><varname>ConditionControlGroupController=
</varname></term>
1009 <!-- We do not document ConditionNull=
1010 here, as it is not particularly
1011 useful and probably just
1014 <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
1015 starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
1016 respected. A failing condition will not result in the unit being moved into the
<literal>failed
</literal>
1017 state. The condition is checked at the time the queued start job is to be executed. Use condition expressions
1018 in order to silently skip units that do not apply to the local running system, for example because the kernel
1019 or runtime environment doesn't require their functionality. Use the various
1020 <varname>AssertArchitecture=
</varname>,
<varname>AssertVirtualization=
</varname>, … options for a similar
1021 mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check
1022 (instead of being silently processed). For details about assertion conditions see below.
</para>
1024 <para><varname>ConditionArchitecture=
</varname> may be used to
1025 check whether the system is running on a specific
1026 architecture. Takes one of
1027 <varname>x86
</varname>,
1028 <varname>x86-
64</varname>,
1029 <varname>ppc
</varname>,
1030 <varname>ppc-le
</varname>,
1031 <varname>ppc64
</varname>,
1032 <varname>ppc64-le
</varname>,
1033 <varname>ia64
</varname>,
1034 <varname>parisc
</varname>,
1035 <varname>parisc64
</varname>,
1036 <varname>s390
</varname>,
1037 <varname>s390x
</varname>,
1038 <varname>sparc
</varname>,
1039 <varname>sparc64
</varname>,
1040 <varname>mips
</varname>,
1041 <varname>mips-le
</varname>,
1042 <varname>mips64
</varname>,
1043 <varname>mips64-le
</varname>,
1044 <varname>alpha
</varname>,
1045 <varname>arm
</varname>,
1046 <varname>arm-be
</varname>,
1047 <varname>arm64
</varname>,
1048 <varname>arm64-be
</varname>,
1049 <varname>sh
</varname>,
1050 <varname>sh64
</varname>,
1051 <varname>m68k
</varname>,
1052 <varname>tilegx
</varname>,
1053 <varname>cris
</varname>,
1054 <varname>arc
</varname>,
1055 <varname>arc-be
</varname> to test
1056 against a specific architecture. The architecture is
1057 determined from the information returned by
1058 <citerefentry project='man-pages'
><refentrytitle>uname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1059 and is thus subject to
1060 <citerefentry><refentrytitle>personality
</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
1061 Note that a
<varname>Personality=
</varname> setting in the
1062 same unit file has no effect on this condition. A special
1063 architecture name
<varname>native
</varname> is mapped to the
1064 architecture the system manager itself is compiled for. The
1065 test may be negated by prepending an exclamation mark.
</para>
1067 <para><varname>ConditionVirtualization=
</varname> may be used
1068 to check whether the system is executed in a virtualized
1069 environment and optionally test whether it is a specific
1070 implementation. Takes either boolean value to check if being
1071 executed in any virtualized environment, or one of
1072 <varname>vm
</varname> and
1073 <varname>container
</varname> to test against a generic type of
1074 virtualization solution, or one of
1075 <varname>qemu
</varname>,
1076 <varname>kvm
</varname>,
1077 <varname>zvm
</varname>,
1078 <varname>vmware
</varname>,
1079 <varname>microsoft
</varname>,
1080 <varname>oracle
</varname>,
1081 <varname>xen
</varname>,
1082 <varname>bochs
</varname>,
1083 <varname>uml
</varname>,
1084 <varname>bhyve
</varname>,
1085 <varname>qnx
</varname>,
1086 <varname>openvz
</varname>,
1087 <varname>lxc
</varname>,
1088 <varname>lxc-libvirt
</varname>,
1089 <varname>systemd-nspawn
</varname>,
1090 <varname>docker
</varname>,
1091 <varname>rkt
</varname>,
1092 <varname>acrn
</varname> to test
1093 against a specific implementation, or
1094 <varname>private-users
</varname> to check whether we are running in a user namespace. See
1095 <citerefentry><refentrytitle>systemd-detect-virt
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1096 for a full list of known virtualization technologies and their
1097 identifiers. If multiple virtualization technologies are
1098 nested, only the innermost is considered. The test may be
1099 negated by prepending an exclamation mark.
</para>
1101 <para><varname>ConditionHost=
</varname> may be used to match
1102 against the hostname or machine ID of the host. This either
1103 takes a hostname string (optionally with shell style globs)
1104 which is tested against the locally set hostname as returned
1106 <citerefentry><refentrytitle>gethostname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1107 or a machine ID formatted as string (see
1108 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1109 The test may be negated by prepending an exclamation
1112 <para><varname>ConditionKernelCommandLine=
</varname> may be
1113 used to check whether a specific kernel command line option is
1114 set (or if prefixed with the exclamation mark unset). The
1115 argument must either be a single word, or an assignment (i.e.
1116 two words, separated
<literal>=
</literal>). In the former case
1117 the kernel command line is searched for the word appearing as
1118 is, or as left hand side of an assignment. In the latter case,
1119 the exact assignment is looked for with right and left hand
1120 side matching.
</para>
1122 <para><varname>ConditionKernelVersion=
</varname> may be used to check whether the kernel version (as reported
1123 by
<command>uname -r
</command>) matches a certain expression (or if prefixed with the exclamation mark does not
1124 match it). The argument must be a single string. If the string starts with one of
<literal><</literal>,
1125 <literal><=
</literal>,
<literal>=
</literal>,
<literal>>=
</literal>,
<literal>></literal> a relative
1126 version comparison is done, otherwise the specified string is matched with shell-style globs.
</para>
1128 <para>Note that using the kernel version string is an unreliable way to determine which features are supported
1129 by a kernel, because of the widespread practice of backporting drivers, features, and fixes from newer upstream
1130 kernels into older versions provided by distributions. Hence, this check is inherently unportable and should
1131 not be used for units which may be used on different distributions.
</para>
1133 <para><varname>ConditionSecurity=
</varname> may be used to check
1134 whether the given security technology is enabled on the
1135 system. Currently, the recognized values are
1136 <varname>selinux
</varname>,
<varname>apparmor
</varname>,
1137 <varname>tomoyo
</varname>,
<varname>ima
</varname>,
1138 <varname>smack
</varname>,
<varname>audit
</varname> and
1139 <varname>uefi-secureboot
</varname>. The test may be negated by
1140 prepending an exclamation mark.
</para>
1142 <para><varname>ConditionCapability=
</varname> may be used to
1143 check whether the given capability exists in the capability
1144 bounding set of the service manager (i.e. this does not check
1145 whether capability is actually available in the permitted or
1147 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1148 for details). Pass a capability name such as
1149 <literal>CAP_MKNOD
</literal>, possibly prefixed with an
1150 exclamation mark to negate the check.
</para>
1152 <para><varname>ConditionACPower=
</varname> may be used to
1153 check whether the system has AC power, or is exclusively
1154 battery powered at the time of activation of the unit. This
1155 takes a boolean argument. If set to
<varname>true
</varname>,
1156 the condition will hold only if at least one AC connector of
1157 the system is connected to a power source, or if no AC
1158 connectors are known. Conversely, if set to
1159 <varname>false
</varname>, the condition will hold only if
1160 there is at least one AC connector known and all AC connectors
1161 are disconnected from a power source.
</para>
1163 <para><varname>ConditionNeedsUpdate=
</varname> takes one of
1164 <filename>/var
</filename> or
<filename>/etc
</filename> as
1165 argument, possibly prefixed with a
<literal>!
</literal> (for
1166 inverting the condition). This condition may be used to
1167 conditionalize units on whether the specified directory
1168 requires an update because
<filename>/usr
</filename>'s
1169 modification time is newer than the stamp file
1170 <filename>.updated
</filename> in the specified directory. This
1171 is useful to implement offline updates of the vendor operating
1172 system resources in
<filename>/usr
</filename> that require
1173 updating of
<filename>/etc
</filename> or
1174 <filename>/var
</filename> on the next following boot. Units
1175 making use of this condition should order themselves before
1176 <citerefentry><refentrytitle>systemd-update-done.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1177 to make sure they run before the stamp file's modification
1178 time gets reset indicating a completed update.
</para>
1180 <para><varname>ConditionFirstBoot=
</varname> takes a boolean argument. This condition may be used to
1181 conditionalize units on whether the system is booting up with an unpopulated
<filename>/etc
</filename>
1182 directory (specifically: an
<filename>/etc
</filename> with no
<filename>/etc/machine-id
</filename>). This may
1183 be used to populate
<filename>/etc
</filename> on the first boot after factory reset, or when a new system
1184 instance boots up for the first time.
</para>
1186 <para>With
<varname>ConditionPathExists=
</varname> a file
1187 existence condition is checked before a unit is started. If
1188 the specified absolute path name does not exist, the condition
1189 will fail. If the absolute path name passed to
1190 <varname>ConditionPathExists=
</varname> is prefixed with an
1191 exclamation mark (
<literal>!
</literal>), the test is negated,
1192 and the unit is only started if the path does not
1195 <para><varname>ConditionPathExistsGlob=
</varname> is similar
1196 to
<varname>ConditionPathExists=
</varname>, but checks for the
1197 existence of at least one file or directory matching the
1198 specified globbing pattern.
</para>
1200 <para><varname>ConditionPathIsDirectory=
</varname> is similar
1201 to
<varname>ConditionPathExists=
</varname> but verifies
1202 whether a certain path exists and is a directory.
</para>
1204 <para><varname>ConditionPathIsSymbolicLink=
</varname> is
1205 similar to
<varname>ConditionPathExists=
</varname> but
1206 verifies whether a certain path exists and is a symbolic
1209 <para><varname>ConditionPathIsMountPoint=
</varname> is similar
1210 to
<varname>ConditionPathExists=
</varname> but verifies
1211 whether a certain path exists and is a mount point.
</para>
1213 <para><varname>ConditionPathIsReadWrite=
</varname> is similar
1214 to
<varname>ConditionPathExists=
</varname> but verifies
1215 whether the underlying file system is readable and writable
1216 (i.e. not mounted read-only).
</para>
1218 <para><varname>ConditionDirectoryNotEmpty=
</varname> is
1219 similar to
<varname>ConditionPathExists=
</varname> but
1220 verifies whether a certain path exists and is a non-empty
1223 <para><varname>ConditionFileNotEmpty=
</varname> is similar to
1224 <varname>ConditionPathExists=
</varname> but verifies whether a
1225 certain path exists and refers to a regular file with a
1226 non-zero size.
</para>
1228 <para><varname>ConditionFileIsExecutable=
</varname> is similar
1229 to
<varname>ConditionPathExists=
</varname> but verifies
1230 whether a certain path exists, is a regular file and marked
1233 <para><varname>ConditionUser=
</varname> takes a numeric
1234 <literal>UID
</literal>, a UNIX user name, or the special value
1235 <literal>@system
</literal>. This condition may be used to check
1236 whether the service manager is running as the given user. The
1237 special value
<literal>@system
</literal> can be used to check
1238 if the user id is within the system user range. This option is not
1239 useful for system services, as the system manager exclusively
1240 runs as the root user, and thus the test result is constant.
</para>
1242 <para><varname>ConditionGroup=
</varname> is similar
1243 to
<varname>ConditionUser=
</varname> but verifies that the
1244 service manager's real or effective group, or any of its
1245 auxiliary groups match the specified group or GID. This setting
1246 does not have a special value
<literal>@system
</literal>.
</para>
1248 <para><varname>ConditionControlGroupController=
</varname> takes a
1249 cgroup controller name (eg.
<option>cpu
</option>), verifying that it is
1250 available for use on the system. For example, a particular controller
1251 may not be available if it was disabled on the kernel command line with
1252 <varname>cgroup_disable=controller
</varname>. Multiple controllers may
1253 be passed with a space separating them; in this case the condition will
1254 only pass if all listed controllers are available for use. Controllers
1255 unknown to systemd are ignored. Valid controllers are
1256 <option>cpu
</option>,
<option>cpuacct
</option>,
<option>io
</option>,
1257 <option>blkio
</option>,
<option>memory
</option>,
1258 <option>devices
</option>, and
<option>pids
</option>.
</para>
1260 <para>If multiple conditions are specified, the unit will be
1261 executed if all of them apply (i.e. a logical AND is applied).
1262 Condition checks can be prefixed with a pipe symbol (|) in
1263 which case a condition becomes a triggering condition. If at
1264 least one triggering condition is defined for a unit, then the
1265 unit will be executed if at least one of the triggering
1266 conditions apply and all of the non-triggering conditions. If
1267 you prefix an argument with the pipe symbol and an exclamation
1268 mark, the pipe symbol must be passed first, the exclamation
1270 <varname>ConditionPathIsSymbolicLink=
</varname>, all path
1271 checks follow symlinks. If any of these options is assigned
1272 the empty string, the list of conditions is reset completely,
1273 all previous condition settings (of any kind) will have no
1274 effect.
</para></listitem>
1278 <term><varname>AssertArchitecture=
</varname></term>
1279 <term><varname>AssertVirtualization=
</varname></term>
1280 <term><varname>AssertHost=
</varname></term>
1281 <term><varname>AssertKernelCommandLine=
</varname></term>
1282 <term><varname>AssertKernelVersion=
</varname></term>
1283 <term><varname>AssertSecurity=
</varname></term>
1284 <term><varname>AssertCapability=
</varname></term>
1285 <term><varname>AssertACPower=
</varname></term>
1286 <term><varname>AssertNeedsUpdate=
</varname></term>
1287 <term><varname>AssertFirstBoot=
</varname></term>
1288 <term><varname>AssertPathExists=
</varname></term>
1289 <term><varname>AssertPathExistsGlob=
</varname></term>
1290 <term><varname>AssertPathIsDirectory=
</varname></term>
1291 <term><varname>AssertPathIsSymbolicLink=
</varname></term>
1292 <term><varname>AssertPathIsMountPoint=
</varname></term>
1293 <term><varname>AssertPathIsReadWrite=
</varname></term>
1294 <term><varname>AssertDirectoryNotEmpty=
</varname></term>
1295 <term><varname>AssertFileNotEmpty=
</varname></term>
1296 <term><varname>AssertFileIsExecutable=
</varname></term>
1297 <term><varname>AssertUser=
</varname></term>
1298 <term><varname>AssertGroup=
</varname></term>
1299 <term><varname>AssertControlGroupController=
</varname></term>
1301 <listitem><para>Similar to the
<varname>ConditionArchitecture=
</varname>,
1302 <varname>ConditionVirtualization=
</varname>, …, condition settings described above, these settings add
1303 assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
1304 that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a
1305 configured assertion does not cause the unit to enter the
<literal>failed
</literal> state (or in fact result in
1306 any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that
1307 cannot operate when specific requirements are not met, and when this is something the administrator or user
1308 should look into.
</para>
1310 <para>Note that neither assertion nor condition expressions result in unit state changes. Also note that both
1311 are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were
1312 queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit
1313 dependencies.
</para></listitem>
1317 <term><varname>SourcePath=
</varname></term>
1318 <listitem><para>A path to a configuration file this unit has
1319 been generated from. This is primarily useful for
1320 implementation of generator tools that convert configuration
1321 from an external configuration file format into native unit
1322 files. This functionality should not be used in normal
1323 units.
</para></listitem>
1329 <title>Mapping of unit properties to their inverses
</title>
1331 <para>Unit settings that create a relationship with a second unit usually show up
1332 in properties of both units, for example in
<command>systemctl show
</command>
1333 output. In some cases the name of the property is the same as the name of the
1334 configuration setting, but not always. This table lists the properties
1335 that are shown on two units which are connected through some dependency, and shows
1336 which property on
"source" unit corresponds to which property on the
"target" unit.
1341 "Forward" and
"reverse" unit properties
1345 <colspec colname='forward'
/>
1346 <colspec colname='reverse'
/>
1347 <colspec colname='notes'
/>
1350 <entry>"Forward" property
</entry>
1351 <entry>"Reverse" property
</entry>
1352 <entry>Where used
</entry>
1357 <entry><varname>Before=
</varname></entry>
1358 <entry><varname>After=
</varname></entry>
1359 <entry morerows='
1' valign='middle'
>Both are unit file options
</entry>
1362 <entry><varname>After=
</varname></entry>
1363 <entry><varname>Before=
</varname></entry>
1366 <entry><varname>Requires=
</varname></entry>
1367 <entry><varname>RequiredBy=
</varname></entry>
1368 <entry>A unit file option; an option in the [Install] section
</entry>
1371 <entry><varname>Wants=
</varname></entry>
1372 <entry><varname>WantedBy=
</varname></entry>
1373 <entry>A unit file option; an option in the [Install] section
</entry>
1376 <entry><varname>PartOf=
</varname></entry>
1377 <entry><varname>ConsistsOf=
</varname></entry>
1378 <entry>A unit file option; an automatic property
</entry>
1381 <entry><varname>BindsTo=
</varname></entry>
1382 <entry><varname>BoundBy=
</varname></entry>
1383 <entry>A unit file option; an automatic property
</entry>
1386 <entry><varname>Requisite=
</varname></entry>
1387 <entry><varname>RequisiteOf=
</varname></entry>
1388 <entry>A unit file option; an automatic property
</entry>
1391 <entry><varname>Triggers=
</varname></entry>
1392 <entry><varname>TriggeredBy=
</varname></entry>
1393 <entry>Automatic properties, see notes below
</entry>
1396 <entry><varname>Conflicts=
</varname></entry>
1397 <entry><varname>ConflictedBy=
</varname></entry>
1398 <entry>A unit file option; an automatic property
</entry>
1401 <entry><varname>PropagatesReloadTo=
</varname></entry>
1402 <entry><varname>ReloadPropagatedFrom=
</varname></entry>
1403 <entry morerows='
1' valign='middle'
>Both are unit file options
</entry>
1406 <entry><varname>ReloadPropagatedFrom=
</varname></entry>
1407 <entry><varname>PropagatesReloadTo=
</varname></entry>
1410 <entry><varname>Following=
</varname></entry>
1412 <entry>An automatic property
</entry>
1418 <para>Note:
<varname>WantedBy=
</varname> and
<varname>RequiredBy=
</varname> are
1419 used in the [Install] section to create symlinks in
<filename>.wants/
</filename>
1420 and
<filename>.requires/
</filename> directories. They cannot be used directly as a
1421 unit configuration setting.
</para>
1423 <para>Note:
<varname>ConsistsOf=
</varname>,
<varname>BoundBy=
</varname>,
1424 <varname>RequisiteOf=
</varname>,
<varname>ConflictedBy=
</varname> are created
1425 implicitly along with their reverse and cannot be specified directly.
</para>
1427 <para>Note:
<varname>Triggers=
</varname> is created implicitly between a socket,
1428 path unit, or an automount unit, and the unit they activate. By default a unit
1429 with the same name is triggered, but this can be overridden using
1430 <varname>Sockets=
</varname>,
<varname>Service=
</varname>, and
<varname>Unit=
</varname>
1432 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1433 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1434 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1436 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1437 for details.
<varname>TriggersBy=
</varname> is created implicitly on the
1438 triggered unit.
</para>
1440 <para>Note:
<varname>Following=
</varname> is used to group device aliases and points to the
1441 "primary" device unit that systemd is using to track device state, usually corresponding to a
1442 sysfs path. It does not show up in the
"target" unit.
</para>
1446 <title>[Install] Section Options
</title>
1448 <para>Unit files may include an
<literal>[Install]
</literal> section, which carries installation information for
1449 the unit. This section is not interpreted by
1450 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
1451 used by the
<command>enable
</command> and
<command>disable
</command> commands of the
1452 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
1453 installation of a unit.
</para>
1455 <variablelist class='unit-directives'
>
1457 <term><varname>Alias=
</varname></term>
1459 <listitem><para>A space-separated list of additional names this unit shall be installed under. The names listed
1460 here must have the same suffix (i.e. type) as the unit filename. This option may be specified more than once,
1461 in which case all listed names are used. At installation time,
<command>systemctl enable
</command> will create
1462 symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this
1463 setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support
1464 aliasing.
</para></listitem>
1468 <term><varname>WantedBy=
</varname></term>
1469 <term><varname>RequiredBy=
</varname></term>
1471 <listitem><para>This option may be used more than once, or a
1472 space-separated list of unit names may be given. A symbolic
1473 link is created in the
<filename>.wants/
</filename> or
1474 <filename>.requires/
</filename> directory of each of the
1475 listed units when this unit is installed by
<command>systemctl
1476 enable
</command>. This has the effect that a dependency of
1477 type
<varname>Wants=
</varname> or
<varname>Requires=
</varname>
1478 is added from the listed unit to the current unit. The primary
1479 result is that the current unit will be started when the
1480 listed unit is started. See the description of
1481 <varname>Wants=
</varname> and
<varname>Requires=
</varname> in
1482 the [Unit] section for details.
</para>
1484 <para><command>WantedBy=foo.service
</command> in a service
1485 <filename>bar.service
</filename> is mostly equivalent to
1486 <command>Alias=foo.service.wants/bar.service
</command> in the
1487 same file. In case of template units,
<command>systemctl
1488 enable
</command> must be called with an instance name, and
1489 this instance will be added to the
1490 <filename>.wants/
</filename> or
1491 <filename>.requires/
</filename> list of the listed unit. E.g.
1492 <command>WantedBy=getty.target
</command> in a service
1493 <filename>getty@.service
</filename> will result in
1494 <command>systemctl enable getty@tty2.service
</command>
1496 <filename>getty.target.wants/getty@tty2.service
</filename>
1497 link to
<filename>getty@.service
</filename>.
1502 <term><varname>Also=
</varname></term>
1504 <listitem><para>Additional units to install/deinstall when
1505 this unit is installed/deinstalled. If the user requests
1506 installation/deinstallation of a unit with this option
1507 configured,
<command>systemctl enable
</command> and
1508 <command>systemctl disable
</command> will automatically
1509 install/uninstall units listed in this option as well.
</para>
1511 <para>This option may be used more than once, or a
1512 space-separated list of unit names may be
1513 given.
</para></listitem>
1517 <term><varname>DefaultInstance=
</varname></term>
1519 <listitem><para>In template unit files, this specifies for
1520 which instance the unit shall be enabled if the template is
1521 enabled without any explicitly set instance. This option has
1522 no effect in non-template unit files. The specified string
1523 must be usable as instance identifier.
</para></listitem>
1527 <para>The following specifiers are interpreted in the Install
1528 section: %n, %N, %p, %i, %j, %g, %G, %U, %u, %m, %H, %b, %v. For their
1529 meaning see the next section.
1534 <title>Specifiers
</title>
1536 <para>Many settings resolve specifiers which may be used to write
1537 generic unit files referring to runtime or unit parameters that
1538 are replaced when the unit files are loaded. Specifiers must be known
1539 and resolvable for the setting to be valid. The following
1540 specifiers are understood:
</para>
1543 <title>Specifiers available in unit files
</title>
1544 <tgroup cols='
3' align='left' colsep='
1' rowsep='
1'
>
1545 <colspec colname=
"spec" />
1546 <colspec colname=
"mean" />
1547 <colspec colname=
"detail" />
1550 <entry>Specifier
</entry>
1551 <entry>Meaning
</entry>
1552 <entry>Details
</entry>
1557 <entry><literal>%b
</literal></entry>
1558 <entry>Boot ID
</entry>
1559 <entry>The boot ID of the running system, formatted as string. See
<citerefentry><refentrytitle>random
</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.
</entry>
1562 <entry><literal>%C
</literal></entry>
1563 <entry>Cache directory root
</entry>
1564 <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>
1567 <entry><literal>%E
</literal></entry>
1568 <entry>Configuration directory root
</entry>
1569 <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>
1572 <entry><literal>%f
</literal></entry>
1573 <entry>Unescaped filename
</entry>
1574 <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>
1577 <entry><literal>%h
</literal></entry>
1578 <entry>User home directory
</entry>
1579 <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>
1582 <entry><literal>%H
</literal></entry>
1583 <entry>Host name
</entry>
1584 <entry>The hostname of the running system at the point in time the unit configuration is loaded.
</entry>
1587 <entry><literal>%i
</literal></entry>
1588 <entry>Instance name
</entry>
1589 <entry>For instantiated units this is the string between the first
<literal>@
</literal> character and the type suffix. Empty for non-instantiated units.
</entry>
1592 <entry><literal>%I
</literal></entry>
1593 <entry>Unescaped instance name
</entry>
1594 <entry>Same as
<literal>%i
</literal>, but with escaping undone.
</entry>
1597 <entry><literal>%j
</literal></entry>
1598 <entry>Final component of the prefix
</entry>
1599 <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>
1602 <entry><literal>%J
</literal></entry>
1603 <entry>Unescaped final component of the prefix
</entry>
1604 <entry>Same as
<literal>%j
</literal>, but with escaping undone.
</entry>
1607 <entry><literal>%L
</literal></entry>
1608 <entry>Log directory root
</entry>
1609 <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>
1612 <entry><literal>%m
</literal></entry>
1613 <entry>Machine ID
</entry>
1614 <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>
1617 <entry><literal>%n
</literal></entry>
1618 <entry>Full unit name
</entry>
1622 <entry><literal>%N
</literal></entry>
1623 <entry>Full unit name
</entry>
1624 <entry>Same as
<literal>%n
</literal>, but with the type suffix removed.
</entry>
1627 <entry><literal>%p
</literal></entry>
1628 <entry>Prefix name
</entry>
1629 <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>
1632 <entry><literal>%P
</literal></entry>
1633 <entry>Unescaped prefix name
</entry>
1634 <entry>Same as
<literal>%p
</literal>, but with escaping undone.
</entry>
1637 <entry><literal>%s
</literal></entry>
1638 <entry>User shell
</entry>
1639 <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>
1642 <entry><literal>%S
</literal></entry>
1643 <entry>State directory root
</entry>
1644 <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>
1647 <entry><literal>%t
</literal></entry>
1648 <entry>Runtime directory root
</entry>
1649 <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>
1652 <entry><literal>%T
</literal></entry>
1653 <entry>Directory for temporary files
</entry>
1654 <entry>This is either
<filename>/tmp
</filename> or the path
<literal>$TMPDIR
</literal>,
<literal>$TEMP
</literal> or
<literal>$TMP
</literal> are set to.
</entry>
1657 <entry><literal>%g
</literal></entry>
1658 <entry>User group
</entry>
1659 <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>
1662 <entry><literal>%G
</literal></entry>
1663 <entry>User GID
</entry>
1664 <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>
1667 <entry><literal>%u
</literal></entry>
1668 <entry>User name
</entry>
1669 <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>
1672 <entry><literal>%U
</literal></entry>
1673 <entry>User UID
</entry>
1674 <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>
1677 <entry><literal>%v
</literal></entry>
1678 <entry>Kernel release
</entry>
1679 <entry>Identical to
<command>uname -r
</command> output
</entry>
1682 <entry><literal>%V
</literal></entry>
1683 <entry>Directory for larger and persistent temporary files
</entry>
1684 <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>
1687 <entry><literal>%%
</literal></entry>
1688 <entry>Single percent sign
</entry>
1689 <entry>Use
<literal>%%
</literal> in place of
<literal>%
</literal> to specify a single percent sign.
</entry>
1697 <title>Examples
</title>
1700 <title>Allowing units to be enabled
</title>
1702 <para>The following snippet (highlighted) allows a unit (e.g.
1703 <filename>foo.service
</filename>) to be enabled via
1704 <command>systemctl enable
</command>:
</para>
1706 <programlisting>[Unit]
1710 ExecStart=/usr/sbin/foo-daemon
1712 <emphasis>[Install]
</emphasis>
1713 <emphasis>WantedBy=multi-user.target
</emphasis></programlisting>
1715 <para>After running
<command>systemctl enable
</command>, a
1717 <filename>/etc/systemd/system/multi-user.target.wants/foo.service
</filename>
1718 linking to the actual unit will be created. It tells systemd to
1719 pull in the unit when starting
1720 <filename>multi-user.target
</filename>. The inverse
1721 <command>systemctl disable
</command> will remove that symlink
1726 <title>Overriding vendor settings
</title>
1728 <para>There are two methods of overriding vendor settings in
1729 unit files: copying the unit file from
1730 <filename>/usr/lib/systemd/system
</filename> to
1731 <filename>/etc/systemd/system
</filename> and modifying the
1732 chosen settings. Alternatively, one can create a directory named
1733 <filename><replaceable>unit
</replaceable>.d/
</filename> within
1734 <filename>/etc/systemd/system
</filename> and place a drop-in
1735 file
<filename><replaceable>name
</replaceable>.conf
</filename>
1736 there that only changes the specific settings one is interested
1737 in. Note that multiple such drop-in files are read if
1738 present, processed in lexicographic order of their filename.
</para>
1740 <para>The advantage of the first method is that one easily
1741 overrides the complete unit, the vendor unit is not parsed at
1742 all anymore. It has the disadvantage that improvements to the
1743 unit file by the vendor are not automatically incorporated on
1746 <para>The advantage of the second method is that one only
1747 overrides the settings one specifically wants, where updates to
1748 the unit by the vendor automatically apply. This has the
1749 disadvantage that some future updates by the vendor might be
1750 incompatible with the local changes.
</para>
1752 <para>This also applies for user instances of systemd, but with
1753 different locations for the unit files. See the section on unit
1754 load paths for further details.
</para>
1756 <para>Suppose there is a vendor-supplied unit
1757 <filename>/usr/lib/systemd/system/httpd.service
</filename> with
1758 the following contents:
</para>
1760 <programlisting>[Unit]
1761 Description=Some HTTP server
1762 After=remote-fs.target sqldb.service
1763 Requires=sqldb.service
1764 AssertPathExists=/srv/webserver
1768 ExecStart=/usr/sbin/some-fancy-httpd-server
1772 WantedBy=multi-user.target
</programlisting>
1774 <para>Now one wants to change some settings as an administrator:
1775 firstly, in the local setup,
<filename>/srv/webserver
</filename>
1776 might not exist, because the HTTP server is configured to use
1777 <filename>/srv/www
</filename> instead. Secondly, the local
1778 configuration makes the HTTP server also depend on a memory
1779 cache service,
<filename>memcached.service
</filename>, that
1780 should be pulled in (
<varname>Requires=
</varname>) and also be
1781 ordered appropriately (
<varname>After=
</varname>). Thirdly, in
1782 order to harden the service a bit more, the administrator would
1783 like to set the
<varname>PrivateTmp=
</varname> setting (see
1784 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1785 for details). And lastly, the administrator would like to reset
1786 the niceness of the service to its default value of
0.
</para>
1788 <para>The first possibility is to copy the unit file to
1789 <filename>/etc/systemd/system/httpd.service
</filename> and
1790 change the chosen settings:
</para>
1792 <programlisting>[Unit]
1793 Description=Some HTTP server
1794 After=remote-fs.target sqldb.service
<emphasis>memcached.service
</emphasis>
1795 Requires=sqldb.service
<emphasis>memcached.service
</emphasis>
1796 AssertPathExists=
<emphasis>/srv/www
</emphasis>
1800 ExecStart=/usr/sbin/some-fancy-httpd-server
1801 <emphasis>Nice=
0</emphasis>
1802 <emphasis>PrivateTmp=yes
</emphasis>
1805 WantedBy=multi-user.target
</programlisting>
1807 <para>Alternatively, the administrator could create a drop-in
1809 <filename>/etc/systemd/system/httpd.service.d/local.conf
</filename>
1810 with the following contents:
</para>
1812 <programlisting>[Unit]
1813 After=memcached.service
1814 Requires=memcached.service
1815 # Reset all assertions and then re-add the condition we want
1817 AssertPathExists=/srv/www
1821 PrivateTmp=yes
</programlisting>
1823 <para>Note that for drop-in files, if one wants to remove
1824 entries from a setting that is parsed as a list (and is not a
1825 dependency), such as
<varname>AssertPathExists=
</varname> (or
1826 e.g.
<varname>ExecStart=
</varname> in service units), one needs
1827 to first clear the list before re-adding all entries except the
1828 one that is to be removed. Dependencies (
<varname>After=
</varname>, etc.)
1829 cannot be reset to an empty list, so dependencies can only be
1830 added in drop-ins. If you want to remove dependencies, you have
1831 to override the entire unit.
</para>
1837 <title>See Also
</title>
1839 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1840 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1841 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1842 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1843 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1844 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1845 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1846 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1847 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1848 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1849 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1850 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1851 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1852 <citerefentry><refentrytitle>systemd.scope
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1853 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1854 <citerefentry><refentrytitle>systemd.time
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1855 <citerefentry><refentrytitle>systemd-analyze
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1856 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1857 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1858 <citerefentry project='man-pages'
><refentrytitle>uname
</refentrytitle><manvolnum>1</manvolnum></citerefentry>