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