]> git.proxmox.com Git - systemd.git/blame - man/systemd.unit.xml
Merge tag 'upstream/229'
[systemd.git] / man / systemd.unit.xml
CommitLineData
db2df898 1<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
663996b3 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
e735f4d4 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
663996b3
MS
4<!ENTITY % entities SYSTEM "custom-entities.ent" >
5%entities;
6]>
7
8<!--
9 This file is part of systemd.
10
11 Copyright 2010 Lennart Poettering
12
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
17
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
22
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<refentry id="systemd.unit">
28
e735f4d4
MP
29 <refentryinfo>
30 <title>systemd.unit</title>
31 <productname>systemd</productname>
32
33 <authorgroup>
34 <author>
35 <contrib>Developer</contrib>
36 <firstname>Lennart</firstname>
37 <surname>Poettering</surname>
38 <email>lennart@poettering.net</email>
39 </author>
40 </authorgroup>
41 </refentryinfo>
42
43 <refmeta>
44 <refentrytitle>systemd.unit</refentrytitle>
45 <manvolnum>5</manvolnum>
46 </refmeta>
47
48 <refnamediv>
49 <refname>systemd.unit</refname>
50 <refpurpose>Unit configuration</refpurpose>
51 </refnamediv>
52
53 <refsynopsisdiv>
54 <para><filename><replaceable>service</replaceable>.service</filename>,
55 <filename><replaceable>socket</replaceable>.socket</filename>,
56 <filename><replaceable>device</replaceable>.device</filename>,
57 <filename><replaceable>mount</replaceable>.mount</filename>,
58 <filename><replaceable>automount</replaceable>.automount</filename>,
59 <filename><replaceable>swap</replaceable>.swap</filename>,
60 <filename><replaceable>target</replaceable>.target</filename>,
61 <filename><replaceable>path</replaceable>.path</filename>,
62 <filename><replaceable>timer</replaceable>.timer</filename>,
e735f4d4
MP
63 <filename><replaceable>slice</replaceable>.slice</filename>,
64 <filename><replaceable>scope</replaceable>.scope</filename></para>
65
66 <para><literallayout><filename>/etc/systemd/system/*</filename>
663996b3
MS
67<filename>/run/systemd/system/*</filename>
68<filename>/usr/lib/systemd/system/*</filename>
69<filename>...</filename>
e735f4d4 70 </literallayout></para>
663996b3 71
e735f4d4 72 <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename>
60f067b4 73<filename>$HOME/.config/systemd/user/*</filename>
14228c0d 74<filename>/etc/systemd/user/*</filename>
5eef597e 75<filename>$XDG_RUNTIME_DIR/systemd/user/*</filename>
663996b3 76<filename>/run/systemd/user/*</filename>
5eef597e
MP
77<filename>$XDG_DATA_HOME/systemd/user/*</filename>
78<filename>$HOME/.local/share/systemd/user/*</filename>
663996b3
MS
79<filename>/usr/lib/systemd/user/*</filename>
80<filename>...</filename>
e735f4d4
MP
81 </literallayout></para>
82 </refsynopsisdiv>
83
84 <refsect1>
85 <title>Description</title>
86
87 <para>A unit configuration file encodes information about a
88 service, a socket, a device, a mount point, an automount point, a
89 swap file or partition, a start-up target, a watched file system
90 path, a timer controlled and supervised by
91 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
db2df898 92 a resource management slice or
e735f4d4
MP
93 a group of externally created processes. The syntax is inspired by
94 <ulink
95 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
96 Desktop Entry Specification</ulink> <filename>.desktop</filename>
97 files, which are in turn inspired by Microsoft Windows
98 <filename>.ini</filename> files.</para>
99
100 <para>This man page lists the common configuration options of all
101 the unit types. These options need to be configured in the [Unit]
102 or [Install] sections of the unit files.</para>
103
104 <para>In addition to the generic [Unit] and [Install] sections
105 described here, each unit may have a type-specific section, e.g.
106 [Service] for a service unit. See the respective man pages for
107 more information:
108 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
109 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
110 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
111 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
112 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
113 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
114 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
115 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
116 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
db2df898 117 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e735f4d4
MP
118 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
119 </para>
120
121 <para>Various settings are allowed to be specified more than once,
122 in which case the interpretation depends on the setting. Often,
123 multiple settings form a list, and setting to an empty value
124 "resets", which means that previous assignments are ignored. When
125 this is allowed, it is mentioned in the description of the
126 setting. Note that using multiple assignments to the same value
127 makes the unit file incompatible with parsers for the XDG
128 <filename>.desktop</filename> file format.</para>
129
130 <para>Unit files are loaded from a set of paths determined during
131 compilation, described in the next section.</para>
132
133 <para>Unit files may contain additional options on top of those
134 listed here. If systemd encounters an unknown option, it will
135 write a warning log message but continue loading the unit. If an
136 option or section name is prefixed with <option>X-</option>, it is
137 ignored completely by systemd. Options within an ignored section
138 do not need the prefix. Applications may use this to include
139 additional information in the unit files.</para>
140
141 <para>Boolean arguments used in unit files can be written in
142 various formats. For positive settings the strings
143 <option>1</option>, <option>yes</option>, <option>true</option>
144 and <option>on</option> are equivalent. For negative settings, the
145 strings <option>0</option>, <option>no</option>,
146 <option>false</option> and <option>off</option> are
147 equivalent.</para>
148
149 <para>Time span values encoded in unit files can be written in
150 various formats. A stand-alone number specifies a time in seconds.
151 If suffixed with a time unit, the unit is honored. A concatenation
152 of multiple values with units is supported, in which case the
153 values are added up. Example: "50" refers to 50 seconds; "2min
154 200ms" refers to 2 minutes plus 200 milliseconds, i.e. 120200ms.
155 The following time units are understood: s, min, h, d, w, ms, us.
156 For details see
157 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
158
159 <para>Empty lines and lines starting with # or ; are
160 ignored. This may be used for commenting. Lines ending
161 in a backslash are concatenated with the following
162 line while reading and the backslash is replaced by a
163 space character. This may be used to wrap long lines.</para>
164
165 <para>Along with a unit file <filename>foo.service</filename>, the
166 directory <filename>foo.service.wants/</filename> may exist. All
167 unit files symlinked from such a directory are implicitly added as
168 dependencies of type <varname>Wants=</varname> to the unit. This
169 is useful to hook units into the start-up of other units, without
170 having to modify their unit files. For details about the semantics
171 of <varname>Wants=</varname>, see below. The preferred way to
172 create symlinks in the <filename>.wants/</filename> directory of a
173 unit file is with the <command>enable</command> command of the
174 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
175 tool which reads information from the [Install] section of unit
176 files (see below). A similar functionality exists for
177 <varname>Requires=</varname> type dependencies as well, the
178 directory suffix is <filename>.requires/</filename> in this
179 case.</para>
180
4c89c718
MP
181 <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
182 <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this
183 directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for
184 a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for
185 instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory and read its
186 <literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory and the
187 <literal>.conf</literal> files there. Also note that settings from the <literal>[Install]</literal> section are not
188 honoured in drop-in unit files, and have no effect.</para>
189
190 <para>In addition to <filename>/etc/systemd/system</filename>,
191 the drop-in <literal>.conf</literal> files for system services
192 can be placed in <filename>/usr/lib/systemd/system</filename> or
193 <filename>/run/systemd/system</filename> directories. Drop-in
194 files in <filename>/etc</filename> take precedence over those in
195 <filename>/run</filename> which in turn take precedence over
196 those in <filename>/usr/lib</filename>. Drop-in files under any of
197 these directories take precedence over unit files wherever located.
198 (Of course, since <filename>/run</filename> is temporary and
199 <filename>/usr/lib</filename> is for vendors, it is unlikely
200 drop-ins should be used in either of those places.)</para>
e735f4d4
MP
201 <!-- Note that we do not document .include here, as we
202 consider it mostly obsolete, and want people to
203 use .d/ drop-ins instead. -->
204
e735f4d4
MP
205 <para>Some unit names reflect paths existing in the file system
206 namespace. Example: a device unit
207 <filename>dev-sda.device</filename> refers to a device with the
208 device node <filename noindex='true'>/dev/sda</filename> in the
209 file system namespace. If this applies, a special way to escape
210 the path name is used, so that the result is usable as part of a
db2df898 211 filename. Basically, given a path, "/" is replaced by "-", and all
e735f4d4
MP
212 other characters which are not ASCII alphanumerics are replaced by
213 C-style "\x2d" escapes (except that "_" is never replaced and "."
214 is only replaced when it would be the first character in the
215 escaped path). The root directory "/" is encoded as single dash,
216 while otherwise the initial and ending "/" are removed from all
217 paths during transformation. This escaping is reversible. Properly
218 escaped paths can be generated using the
219 <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry>
220 command.</para>
221
222 <para>Optionally, units may be instantiated from a
223 template file at runtime. This allows creation of
224 multiple units from a single configuration file. If
225 systemd looks for a unit configuration file, it will
226 first search for the literal unit name in the
227 file system. If that yields no success and the unit
228 name contains an <literal>@</literal> character, systemd will look for a
229 unit template that shares the same name but with the
230 instance string (i.e. the part between the <literal>@</literal> character
231 and the suffix) removed. Example: if a service
232 <filename>getty@tty3.service</filename> is requested
233 and no file by that name is found, systemd will look
234 for <filename>getty@.service</filename> and
235 instantiate a service from that configuration file if
236 it is found.</para>
237
238 <para>To refer to the instance string from within the
239 configuration file you may use the special <literal>%i</literal>
240 specifier in many of the configuration options. See below for
241 details.</para>
242
243 <para>If a unit file is empty (i.e. has the file size 0) or is
244 symlinked to <filename>/dev/null</filename>, its configuration
245 will not be loaded and it appears with a load state of
246 <literal>masked</literal>, and cannot be activated. Use this as an
247 effective way to fully disable a unit, making it impossible to
248 start it even manually.</para>
249
250 <para>The unit file format is covered by the
251 <ulink
252 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
253 Stability Promise</ulink>.</para>
254
255 </refsect1>
256
db2df898
MP
257 <refsect1>
258 <title>Automatic Dependencies</title>
259
260 <para>Note that while systemd offers a flexible dependency system
261 between units it is recommended to use this functionality only
262 sparingly and instead rely on techniques such as bus-based or
263 socket-based activation which make dependencies implicit,
264 resulting in a both simpler and more flexible system.</para>
265
266 <para>A number of unit dependencies are automatically established,
267 depending on unit configuration. On top of that, for units with
268 <varname>DefaultDependencies=yes</varname> (the default) a couple
269 of additional dependencies are added. The precise effect of
270 <varname>DefaultDependencies=yes</varname> depends on the unit
271 type (see below).</para>
272
273 <para>If <varname>DefaultDependencies=yes</varname> is set, units
274 that are referenced by other units of type
275 <filename>.target</filename> via a <varname>Wants=</varname> or
276 <varname>Requires=</varname> dependency might automatically gain
277 an <varname>Before=</varname> dependency too. See
278 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>
279 for details.</para>
280 </refsect1>
281
e735f4d4 282 <refsect1>
d9dfd233 283 <title>Unit File Load Path</title>
e735f4d4
MP
284
285 <para>Unit files are loaded from a set of paths determined during
286 compilation, described in the two tables below. Unit files found
287 in directories listed earlier override files with the same name in
288 directories lower in the list.</para>
289
db2df898
MP
290 <para>When the variable <varname>$SYSTEMD_UNIT_PATH</varname> is set,
291 the contents of this variable overrides the unit load path. If
e735f4d4
MP
292 <varname>$SYSTEMD_UNIT_PATH</varname> ends with an empty component
293 (<literal>:</literal>), the usual unit load path will be appended
294 to the contents of the variable.</para>
295
296 <table>
297 <title>
298 Load path when running in system mode (<option>--system</option>).
299 </title>
300
301 <tgroup cols='2'>
302 <colspec colname='path' />
303 <colspec colname='expl' />
304 <thead>
305 <row>
306 <entry>Path</entry>
307 <entry>Description</entry>
308 </row>
309 </thead>
310 <tbody>
311 <row>
312 <entry><filename>/etc/systemd/system</filename></entry>
313 <entry>Local configuration</entry>
314 </row>
315 <row>
316 <entry><filename>/run/systemd/system</filename></entry>
317 <entry>Runtime units</entry>
318 </row>
319 <row>
320 <entry><filename>/usr/lib/systemd/system</filename></entry>
321 <entry>Units of installed packages</entry>
322 </row>
323 </tbody>
324 </tgroup>
325 </table>
326
327 <table>
328 <title>
329 Load path when running in user mode (<option>--user</option>).
330 </title>
331
332 <tgroup cols='2'>
333 <colspec colname='path' />
334 <colspec colname='expl' />
335 <thead>
336 <row>
337 <entry>Path</entry>
338 <entry>Description</entry>
339 </row>
340 </thead>
341 <tbody>
342 <row>
343 <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
344 <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
345 </row>
346 <row>
347 <entry><filename>$HOME/.config/systemd/user</filename></entry>
348 <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
349 </row>
350 <row>
351 <entry><filename>/etc/systemd/user</filename></entry>
352 <entry>Local configuration</entry>
353 </row>
354 <row>
355 <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry>
356 <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry>
357 </row>
358 <row>
359 <entry><filename>/run/systemd/user</filename></entry>
360 <entry>Runtime units</entry>
361 </row>
362 <row>
363 <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry>
364 <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry>
365 </row>
366 <row>
367 <entry><filename>$HOME/.local/share/systemd/user</filename></entry>
368 <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry>
369 </row>
370 <row>
371 <entry><filename>/usr/lib/systemd/user</filename></entry>
372 <entry>Units of packages that have been installed system-wide</entry>
373 </row>
374 </tbody>
375 </tgroup>
376 </table>
377
378 <para>Additional units might be loaded into systemd ("linked")
379 from directories not on the unit load path. See the
380 <command>link</command> command for
381 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
e3bff60a
MP
382 Also, some units are dynamically created via a
383 <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
e735f4d4
MP
384 </para>
385 </refsect1>
386
387 <refsect1>
388 <title>[Unit] Section Options</title>
389
db2df898 390 <para>The unit file may include a [Unit] section, which carries
e735f4d4
MP
391 generic information about the unit that is not dependent on the
392 type of unit:</para>
393
394 <variablelist class='unit-directives'>
395
396 <varlistentry>
397 <term><varname>Description=</varname></term>
398 <listitem><para>A free-form string describing the unit. This
399 is intended for use in UIs to show descriptive information
400 along with the unit name. The description should contain a
401 name that means something to the end user. <literal>Apache2
402 Web Server</literal> is a good example. Bad examples are
403 <literal>high-performance light-weight HTTP server</literal>
404 (too generic) or <literal>Apache2</literal> (too specific and
405 meaningless for people who do not know
406 Apache).</para></listitem>
407 </varlistentry>
408
409 <varlistentry>
410 <term><varname>Documentation=</varname></term>
411 <listitem><para>A space-separated list of URIs referencing
412 documentation for this unit or its configuration. Accepted are
413 only URIs of the types <literal>http://</literal>,
414 <literal>https://</literal>, <literal>file:</literal>,
415 <literal>info:</literal>, <literal>man:</literal>. For more
416 information about the syntax of these URIs, see <citerefentry
417 project='man-pages'><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
418 The URIs should be listed in order of relevance, starting with
419 the most relevant. It is a good idea to first reference
420 documentation that explains what the unit's purpose is,
421 followed by how it is configured, followed by any other
422 related documentation. This option may be specified more than
423 once, in which case the specified list of URIs is merged. If
424 the empty string is assigned to this option, the list is reset
425 and all prior assignments will have no
426 effect.</para></listitem>
427 </varlistentry>
428
429 <varlistentry>
430 <term><varname>Requires=</varname></term>
431
432 <listitem><para>Configures requirement dependencies on other
433 units. If this unit gets activated, the units listed here will
434 be activated as well. If one of the other units gets
435 deactivated or its activation fails, this unit will be
436 deactivated. This option may be specified more than once or
437 multiple space-separated units may be specified in one option
438 in which case requirement dependencies for all listed names
439 will be created. Note that requirement dependencies do not
440 influence the order in which services are started or stopped.
441 This has to be configured independently with the
442 <varname>After=</varname> or <varname>Before=</varname>
443 options. If a unit <filename>foo.service</filename> requires a
444 unit <filename>bar.service</filename> as configured with
445 <varname>Requires=</varname> and no ordering is configured
446 with <varname>After=</varname> or <varname>Before=</varname>,
447 then both units will be started simultaneously and without any
448 delay between them if <filename>foo.service</filename> is
db2df898 449 activated. Often, it is a better choice to use
e735f4d4
MP
450 <varname>Wants=</varname> instead of
451 <varname>Requires=</varname> in order to achieve a system that
452 is more robust when dealing with failing services.</para>
453
454 <para>Note that dependencies of this type may also be
455 configured outside of the unit configuration file by adding a
456 symlink to a <filename>.requires/</filename> directory
db2df898 457 accompanying the unit file. For details, see
e735f4d4
MP
458 above.</para></listitem>
459 </varlistentry>
460
e735f4d4
MP
461 <varlistentry>
462 <term><varname>Requisite=</varname></term>
e735f4d4 463
db2df898 464 <listitem><para>Similar to <varname>Requires=</varname>.
e735f4d4
MP
465 However, if the units listed here are not started already,
466 they will not be started and the transaction will fail
467 immediately. </para></listitem>
468 </varlistentry>
469
470 <varlistentry>
471 <term><varname>Wants=</varname></term>
472
473 <listitem><para>A weaker version of
474 <varname>Requires=</varname>. Units listed in this option will
475 be started if the configuring unit is. However, if the listed
476 units fail to start or cannot be added to the transaction,
477 this has no impact on the validity of the transaction as a
478 whole. This is the recommended way to hook start-up of one
479 unit to the start-up of another unit.</para>
480
481 <para>Note that dependencies of this type may also be
482 configured outside of the unit configuration file by adding
483 symlinks to a <filename>.wants/</filename> directory
484 accompanying the unit file. For details, see
485 above.</para></listitem>
486 </varlistentry>
487
488 <varlistentry>
489 <term><varname>BindsTo=</varname></term>
490
491 <listitem><para>Configures requirement dependencies, very
492 similar in style to <varname>Requires=</varname>, however in
493 addition to this behavior, it also declares that this unit is
494 stopped when any of the units listed suddenly disappears.
495 Units can suddenly, unexpectedly disappear if a service
496 terminates on its own choice, a device is unplugged or a mount
497 point unmounted without involvement of
498 systemd.</para></listitem>
499 </varlistentry>
500
501 <varlistentry>
502 <term><varname>PartOf=</varname></term>
503
504 <listitem><para>Configures dependencies similar to
505 <varname>Requires=</varname>, but limited to stopping and
506 restarting of units. When systemd stops or restarts the units
507 listed here, the action is propagated to this unit. Note that
508 this is a one-way dependency — changes to this unit do not
509 affect the listed units. </para></listitem>
510 </varlistentry>
511
512 <varlistentry>
513 <term><varname>Conflicts=</varname></term>
514
515 <listitem><para>A space-separated list of unit names.
516 Configures negative requirement dependencies. If a unit has a
517 <varname>Conflicts=</varname> setting on another unit,
518 starting the former will stop the latter and vice versa. Note
519 that this setting is independent of and orthogonal to the
520 <varname>After=</varname> and <varname>Before=</varname>
521 ordering dependencies.</para>
522
523 <para>If a unit A that conflicts with a unit B is scheduled to
524 be started at the same time as B, the transaction will either
525 fail (in case both are required part of the transaction) or be
526 modified to be fixed (in case one or both jobs are not a
527 required part of the transaction). In the latter case, the job
528 that is not the required will be removed, or in case both are
529 not required, the unit that conflicts will be started and the
530 unit that is conflicted is stopped.</para></listitem>
531 </varlistentry>
532
533 <varlistentry>
534 <term><varname>Before=</varname></term>
535 <term><varname>After=</varname></term>
536
537 <listitem><para>A space-separated list of unit names.
538 Configures ordering dependencies between units. If a unit
539 <filename>foo.service</filename> contains a setting
540 <option>Before=bar.service</option> and both units are being
541 started, <filename>bar.service</filename>'s start-up is
542 delayed until <filename>foo.service</filename> is started up.
543 Note that this setting is independent of and orthogonal to the
544 requirement dependencies as configured by
545 <varname>Requires=</varname>. It is a common pattern to
546 include a unit name in both the <varname>After=</varname> and
547 <varname>Requires=</varname> option, in which case the unit
548 listed will be started before the unit that is configured with
549 these options. This option may be specified more than once, in
550 which case ordering dependencies for all listed names are
551 created. <varname>After=</varname> is the inverse of
552 <varname>Before=</varname>, i.e. while
553 <varname>After=</varname> ensures that the configured unit is
554 started after the listed unit finished starting up,
555 <varname>Before=</varname> ensures the opposite, i.e. that the
556 configured unit is fully started up before the listed unit is
557 started. Note that when two units with an ordering dependency
558 between them are shut down, the inverse of the start-up order
559 is applied. i.e. if a unit is configured with
560 <varname>After=</varname> on another unit, the former is
561 stopped before the latter if both are shut down. If one unit
562 with an ordering dependency on another unit is shut down while
563 the latter is started up, the shut down is ordered before the
564 start-up regardless of whether the ordering dependency is
565 actually of type <varname>After=</varname> or
566 <varname>Before=</varname>. If two units have no ordering
567 dependencies between them, they are shut down or started up
568 simultaneously, and no ordering takes place.
569 </para></listitem>
570 </varlistentry>
571
572 <varlistentry>
573 <term><varname>OnFailure=</varname></term>
574
575 <listitem><para>A space-separated list of one or more units
576 that are activated when this unit enters the
577 <literal>failed</literal> state.</para></listitem>
578 </varlistentry>
579
580 <varlistentry>
581 <term><varname>PropagatesReloadTo=</varname></term>
582 <term><varname>ReloadPropagatedFrom=</varname></term>
583
584 <listitem><para>A space-separated list of one or more units
585 where reload requests on this unit will be propagated to, or
586 reload requests on the other unit will be propagated to this
587 unit, respectively. Issuing a reload request on a unit will
588 automatically also enqueue a reload request on all units that
589 the reload request shall be propagated to via these two
590 settings.</para></listitem>
591 </varlistentry>
592
593 <varlistentry>
594 <term><varname>JoinsNamespaceOf=</varname></term>
595
596 <listitem><para>For units that start processes (such as
597 service units), lists one or more other units whose network
598 and/or temporary file namespace to join. This only applies to
599 unit types which support the
600 <varname>PrivateNetwork=</varname> and
601 <varname>PrivateTmp=</varname> directives (see
602 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
603 for details). If a unit that has this setting set is started,
604 its processes will see the same <filename>/tmp</filename>,
605 <filename>/tmp/var</filename> and network namespace as one
606 listed unit that is started. If multiple listed units are
607 already started, it is not defined which namespace is joined.
608 Note that this setting only has an effect if
609 <varname>PrivateNetwork=</varname> and/or
610 <varname>PrivateTmp=</varname> is enabled for both the unit
611 that joins the namespace and the unit whose namespace is
612 joined.</para></listitem>
613 </varlistentry>
614
615 <varlistentry>
616 <term><varname>RequiresMountsFor=</varname></term>
617
618 <listitem><para>Takes a space-separated list of absolute
619 paths. Automatically adds dependencies of type
620 <varname>Requires=</varname> and <varname>After=</varname> for
621 all mount units required to access the specified path.</para>
622
623 <para>Mount points marked with <option>noauto</option> are not
624 mounted automatically and will be ignored for the purposes of
625 this option. If such a mount should be a requirement for this
626 unit, direct dependencies on the mount units may be added
627 (<varname>Requires=</varname> and <varname>After=</varname> or
628 some other combination). </para></listitem>
629 </varlistentry>
630
631 <varlistentry>
632 <term><varname>OnFailureJobMode=</varname></term>
633
634 <listitem><para>Takes a value of
635 <literal>fail</literal>,
636 <literal>replace</literal>,
637 <literal>replace-irreversibly</literal>,
638 <literal>isolate</literal>,
639 <literal>flush</literal>,
640 <literal>ignore-dependencies</literal> or
641 <literal>ignore-requirements</literal>. Defaults to
642 <literal>replace</literal>. Specifies how the units listed in
643 <varname>OnFailure=</varname> will be enqueued. See
644 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
645 <option>--job-mode=</option> option for details on the
646 possible values. If this is set to <literal>isolate</literal>,
647 only a single unit may be listed in
648 <varname>OnFailure=</varname>..</para></listitem>
649 </varlistentry>
650
651 <varlistentry>
652 <term><varname>IgnoreOnIsolate=</varname></term>
653
654 <listitem><para>Takes a boolean argument. If
655 <option>true</option>, this unit will not be stopped when
656 isolating another unit. Defaults to
657 <option>false</option>.</para></listitem>
658 </varlistentry>
659
e735f4d4
MP
660 <varlistentry>
661 <term><varname>StopWhenUnneeded=</varname></term>
662
663 <listitem><para>Takes a boolean argument. If
664 <option>true</option>, this unit will be stopped when it is no
db2df898 665 longer used. Note that, in order to minimize the work to be
e735f4d4
MP
666 executed, systemd will not stop units by default unless they
667 are conflicting with other units, or the user explicitly
668 requested their shut down. If this option is set, a unit will
669 be automatically cleaned up if no other active unit requires
670 it. Defaults to <option>false</option>.</para></listitem>
671 </varlistentry>
672
673 <varlistentry>
674 <term><varname>RefuseManualStart=</varname></term>
675 <term><varname>RefuseManualStop=</varname></term>
676
677 <listitem><para>Takes a boolean argument. If
678 <option>true</option>, this unit can only be activated or
679 deactivated indirectly. In this case, explicit start-up or
680 termination requested by the user is denied, however if it is
681 started or stopped as a dependency of another unit, start-up
682 or termination will succeed. This is mostly a safety feature
683 to ensure that the user does not accidentally activate units
684 that are not intended to be activated explicitly, and not
685 accidentally deactivate units that are not intended to be
686 deactivated. These options default to
687 <option>false</option>.</para></listitem>
688 </varlistentry>
689
690 <varlistentry>
691 <term><varname>AllowIsolate=</varname></term>
692
693 <listitem><para>Takes a boolean argument. If
694 <option>true</option>, this unit may be used with the
695 <command>systemctl isolate</command> command. Otherwise, this
696 will be refused. It probably is a good idea to leave this
697 disabled except for target units that shall be used similar to
698 runlevels in SysV init systems, just as a precaution to avoid
699 unusable system states. This option defaults to
700 <option>false</option>.</para></listitem>
701 </varlistentry>
702
703 <varlistentry>
704 <term><varname>DefaultDependencies=</varname></term>
705
706 <listitem><para>Takes a boolean argument. If
707 <option>true</option>, (the default), a few default
708 dependencies will implicitly be created for the unit. The
709 actual dependencies created depend on the unit type. For
710 example, for service units, these dependencies ensure that the
711 service is started only after basic system initialization is
712 completed and is properly terminated on system shutdown. See
713 the respective man pages for details. Generally, only services
714 involved with early boot or late shutdown should set this
715 option to <option>false</option>. It is highly recommended to
716 leave this option enabled for the majority of common units. If
717 set to <option>false</option>, this option does not disable
718 all implicit dependencies, just non-essential
719 ones.</para></listitem>
720 </varlistentry>
721
722 <varlistentry>
723 <term><varname>JobTimeoutSec=</varname></term>
724 <term><varname>JobTimeoutAction=</varname></term>
725 <term><varname>JobTimeoutRebootArgument=</varname></term>
726
4c89c718
MP
727 <listitem><para>When a job for this unit is queued, a time-out may be configured. If this time limit is
728 reached, the job will be cancelled, the unit however will not change state or even enter the
729 <literal>failed</literal> mode. This value defaults to <literal>infinity</literal> (job timeouts disabled),
730 except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the
731 timeout set with <varname>TimeoutStartSec=</varname> in service units) as the job timeout has no effect on the
732 unit itself, only on the job that might be pending for it. Or in other words: unit-specific timeouts are useful
733 to abort unit state changes, and revert them. The job timeout set with this option however is useful to abort
734 only the job waiting for the unit state to change.</para>
e735f4d4
MP
735
736 <para><varname>JobTimeoutAction=</varname>
737 optionally configures an additional
738 action to take when the time-out is
739 hit. It takes the same values as the
740 per-service
741 <varname>StartLimitAction=</varname>
742 setting, see
743 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
744 for details. Defaults to
745 <option>none</option>. <varname>JobTimeoutRebootArgument=</varname>
746 configures an optional reboot string
747 to pass to the
748 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
749 system call.</para></listitem>
750 </varlistentry>
751
4c89c718
MP
752 <varlistentry>
753 <term><varname>StartLimitInterval=</varname></term>
754 <term><varname>StartLimitBurst=</varname></term>
755
756 <listitem><para>Configure unit start rate limiting. By default, units which are started more than 5 times
757 within 10 seconds are not permitted to start any more times until the 10 second interval ends. With these two
758 options, this rate limiting may be modified. Use <varname>StartLimitInterval=</varname> to configure the
759 checking interval (defaults to <varname>DefaultStartLimitInterval=</varname> in manager configuration file, set
760 to 0 to disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many
761 starts per interval are allowed (defaults to <varname>DefaultStartLimitBurst=</varname> in manager
762 configuration file). These configuration options are particularly useful in conjunction with the service
763 setting <varname>Restart=</varname> (see
764 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however,
765 they apply to all kinds of starts (including manual), not just those triggered by the
766 <varname>Restart=</varname> logic. Note that units which are configured for <varname>Restart=</varname> and
767 which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted
768 manually at a later point, from which point on, the restart logic is again activated. Note that
769 <command>systemctl reset-failed</command> will cause the restart rate counter for a service to be flushed,
770 which is useful if the administrator wants to manually start a unit and the start limit interferes with
771 that.</para></listitem>
772 </varlistentry>
773
774 <varlistentry>
775 <term><varname>StartLimitAction=</varname></term>
776
777 <listitem><para>Configure the action to take if the rate limit configured with
778 <varname>StartLimitInterval=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of
779 <option>none</option>, <option>reboot</option>, <option>reboot-force</option>,
780 <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option> or
781 <option>poweroff-immediate</option>. If <option>none</option> is set, hitting the rate limit will trigger no
782 action besides that the start will not be permitted. <option>reboot</option> causes a reboot following the
783 normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>).
784 <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should
785 cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and
786 <option>reboot-immediate</option> causes immediate execution of the
787 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which
788 might result in data loss. Similarly, <option>poweroff</option>, <option>poweroff-force</option>,
789 <option>poweroff-immediate</option> have the effect of powering down the system with similar
790 semantics. Defaults to <option>none</option>.</para></listitem>
791 </varlistentry>
792
793 <varlistentry>
794 <term><varname>RebootArgument=</varname></term>
795 <listitem><para>Configure the optional argument for the
796 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if
797 <varname>StartLimitAction=</varname> or a service's <varname>FailureAction=</varname> is a reboot action. This
798 works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem>
799 </varlistentry>
800
e735f4d4
MP
801 <varlistentry>
802 <term><varname>ConditionArchitecture=</varname></term>
803 <term><varname>ConditionVirtualization=</varname></term>
804 <term><varname>ConditionHost=</varname></term>
805 <term><varname>ConditionKernelCommandLine=</varname></term>
806 <term><varname>ConditionSecurity=</varname></term>
807 <term><varname>ConditionCapability=</varname></term>
808 <term><varname>ConditionACPower=</varname></term>
809 <term><varname>ConditionNeedsUpdate=</varname></term>
810 <term><varname>ConditionFirstBoot=</varname></term>
811 <term><varname>ConditionPathExists=</varname></term>
812 <term><varname>ConditionPathExistsGlob=</varname></term>
813 <term><varname>ConditionPathIsDirectory=</varname></term>
814 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
815 <term><varname>ConditionPathIsMountPoint=</varname></term>
816 <term><varname>ConditionPathIsReadWrite=</varname></term>
817 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
818 <term><varname>ConditionFileNotEmpty=</varname></term>
819 <term><varname>ConditionFileIsExecutable=</varname></term>
820
db2df898
MP
821 <!-- We do not document ConditionNull=
822 here, as it is not particularly
e735f4d4
MP
823 useful and probably just
824 confusing. -->
825
4c89c718
MP
826 <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
827 starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
828 respected. A failing condition will not result in the unit being moved into a failure state. The condition is
829 checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip
830 units that do not apply to the local running system, for example because the kernel or runtime environment
831 doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>,
832 <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure
833 state and logs about the failed check (see below).</para>
e735f4d4
MP
834
835 <para><varname>ConditionArchitecture=</varname> may be used to
836 check whether the system is running on a specific
837 architecture. Takes one of
838 <varname>x86</varname>,
839 <varname>x86-64</varname>,
840 <varname>ppc</varname>,
841 <varname>ppc-le</varname>,
842 <varname>ppc64</varname>,
843 <varname>ppc64-le</varname>,
844 <varname>ia64</varname>,
845 <varname>parisc</varname>,
846 <varname>parisc64</varname>,
847 <varname>s390</varname>,
848 <varname>s390x</varname>,
849 <varname>sparc</varname>,
850 <varname>sparc64</varname>,
851 <varname>mips</varname>,
852 <varname>mips-le</varname>,
853 <varname>mips64</varname>,
854 <varname>mips64-le</varname>,
855 <varname>alpha</varname>,
856 <varname>arm</varname>,
857 <varname>arm-be</varname>,
858 <varname>arm64</varname>,
859 <varname>arm64-be</varname>,
860 <varname>sh</varname>,
861 <varname>sh64</varname>,
862 <varname>m86k</varname>,
863 <varname>tilegx</varname>,
864 <varname>cris</varname> to test
865 against a specific architecture. The architecture is
866 determined from the information returned by
e3bff60a 867 <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
e735f4d4
MP
868 and is thus subject to
869 <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
870 Note that a <varname>Personality=</varname> setting in the
871 same unit file has no effect on this condition. A special
872 architecture name <varname>native</varname> is mapped to the
873 architecture the system manager itself is compiled for. The
874 test may be negated by prepending an exclamation mark.</para>
875
876 <para><varname>ConditionVirtualization=</varname> may be used
877 to check whether the system is executed in a virtualized
878 environment and optionally test whether it is a specific
879 implementation. Takes either boolean value to check if being
880 executed in any virtualized environment, or one of
881 <varname>vm</varname> and
882 <varname>container</varname> to test against a generic type of
883 virtualization solution, or one of
884 <varname>qemu</varname>,
885 <varname>kvm</varname>,
886 <varname>zvm</varname>,
887 <varname>vmware</varname>,
888 <varname>microsoft</varname>,
889 <varname>oracle</varname>,
890 <varname>xen</varname>,
891 <varname>bochs</varname>,
892 <varname>uml</varname>,
893 <varname>openvz</varname>,
894 <varname>lxc</varname>,
895 <varname>lxc-libvirt</varname>,
896 <varname>systemd-nspawn</varname>,
db2df898
MP
897 <varname>docker</varname>,
898 <varname>rkt</varname> to test
e735f4d4
MP
899 against a specific implementation. See
900 <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry>
901 for a full list of known virtualization technologies and their
902 identifiers. If multiple virtualization technologies are
903 nested, only the innermost is considered. The test may be
904 negated by prepending an exclamation mark.</para>
905
906 <para><varname>ConditionHost=</varname> may be used to match
907 against the hostname or machine ID of the host. This either
908 takes a hostname string (optionally with shell style globs)
909 which is tested against the locally set hostname as returned
910 by
911 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
912 or a machine ID formatted as string (see
913 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
914 The test may be negated by prepending an exclamation
915 mark.</para>
916
917 <para><varname>ConditionKernelCommandLine=</varname> may be
918 used to check whether a specific kernel command line option is
919 set (or if prefixed with the exclamation mark unset). The
920 argument must either be a single word, or an assignment (i.e.
921 two words, separated <literal>=</literal>). In the former case
922 the kernel command line is searched for the word appearing as
923 is, or as left hand side of an assignment. In the latter case,
924 the exact assignment is looked for with right and left hand
925 side matching.</para>
926
927 <para><varname>ConditionSecurity=</varname> may be used to
928 check whether the given security module is enabled on the
4c89c718 929 system. Currently, the recognized values are
e735f4d4
MP
930 <varname>selinux</varname>,
931 <varname>apparmor</varname>,
932 <varname>ima</varname>,
933 <varname>smack</varname> and
934 <varname>audit</varname>. The test may be negated by
935 prepending an exclamation mark.</para>
936
937 <para><varname>ConditionCapability=</varname> may be used to
938 check whether the given capability exists in the capability
939 bounding set of the service manager (i.e. this does not check
940 whether capability is actually available in the permitted or
941 effective sets, see
942 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
943 for details). Pass a capability name such as
944 <literal>CAP_MKNOD</literal>, possibly prefixed with an
945 exclamation mark to negate the check.</para>
946
947 <para><varname>ConditionACPower=</varname> may be used to
948 check whether the system has AC power, or is exclusively
949 battery powered at the time of activation of the unit. This
950 takes a boolean argument. If set to <varname>true</varname>,
951 the condition will hold only if at least one AC connector of
952 the system is connected to a power source, or if no AC
953 connectors are known. Conversely, if set to
954 <varname>false</varname>, the condition will hold only if
955 there is at least one AC connector known and all AC connectors
956 are disconnected from a power source.</para>
957
958 <para><varname>ConditionNeedsUpdate=</varname> takes one of
959 <filename>/var</filename> or <filename>/etc</filename> as
960 argument, possibly prefixed with a <literal>!</literal> (for
961 inverting the condition). This condition may be used to
962 conditionalize units on whether the specified directory
963 requires an update because <filename>/usr</filename>'s
964 modification time is newer than the stamp file
965 <filename>.updated</filename> in the specified directory. This
966 is useful to implement offline updates of the vendor operating
967 system resources in <filename>/usr</filename> that require
968 updating of <filename>/etc</filename> or
969 <filename>/var</filename> on the next following boot. Units
970 making use of this condition should order themselves before
971 <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
4c89c718 972 to make sure they run before the stamp file's modification
e735f4d4
MP
973 time gets reset indicating a completed update.</para>
974
975 <para><varname>ConditionFirstBoot=</varname> takes a boolean
976 argument. This condition may be used to conditionalize units
977 on whether the system is booting up with an unpopulated
978 <filename>/etc</filename> directory. This may be used to
979 populate <filename>/etc</filename> on the first boot after
980 factory reset, or when a new system instances boots up for the
981 first time.</para>
982
983 <para>With <varname>ConditionPathExists=</varname> a file
984 existence condition is checked before a unit is started. If
985 the specified absolute path name does not exist, the condition
986 will fail. If the absolute path name passed to
987 <varname>ConditionPathExists=</varname> is prefixed with an
988 exclamation mark (<literal>!</literal>), the test is negated,
989 and the unit is only started if the path does not
990 exist.</para>
991
992 <para><varname>ConditionPathExistsGlob=</varname> is similar
993 to <varname>ConditionPathExists=</varname>, but checks for the
994 existence of at least one file or directory matching the
995 specified globbing pattern.</para>
996
997 <para><varname>ConditionPathIsDirectory=</varname> is similar
998 to <varname>ConditionPathExists=</varname> but verifies
999 whether a certain path exists and is a directory.</para>
1000
1001 <para><varname>ConditionPathIsSymbolicLink=</varname> is
1002 similar to <varname>ConditionPathExists=</varname> but
1003 verifies whether a certain path exists and is a symbolic
1004 link.</para>
1005
1006 <para><varname>ConditionPathIsMountPoint=</varname> is similar
1007 to <varname>ConditionPathExists=</varname> but verifies
1008 whether a certain path exists and is a mount point.</para>
1009
1010 <para><varname>ConditionPathIsReadWrite=</varname> is similar
1011 to <varname>ConditionPathExists=</varname> but verifies
1012 whether the underlying file system is readable and writable
1013 (i.e. not mounted read-only).</para>
1014
1015 <para><varname>ConditionDirectoryNotEmpty=</varname> is
1016 similar to <varname>ConditionPathExists=</varname> but
1017 verifies whether a certain path exists and is a non-empty
1018 directory.</para>
1019
1020 <para><varname>ConditionFileNotEmpty=</varname> is similar to
1021 <varname>ConditionPathExists=</varname> but verifies whether a
1022 certain path exists and refers to a regular file with a
1023 non-zero size.</para>
1024
1025 <para><varname>ConditionFileIsExecutable=</varname> is similar
1026 to <varname>ConditionPathExists=</varname> but verifies
1027 whether a certain path exists, is a regular file and marked
1028 executable.</para>
1029
1030 <para>If multiple conditions are specified, the unit will be
1031 executed if all of them apply (i.e. a logical AND is applied).
1032 Condition checks can be prefixed with a pipe symbol (|) in
1033 which case a condition becomes a triggering condition. If at
1034 least one triggering condition is defined for a unit, then the
1035 unit will be executed if at least one of the triggering
1036 conditions apply and all of the non-triggering conditions. If
1037 you prefix an argument with the pipe symbol and an exclamation
1038 mark, the pipe symbol must be passed first, the exclamation
1039 second. Except for
1040 <varname>ConditionPathIsSymbolicLink=</varname>, all path
1041 checks follow symlinks. If any of these options is assigned
1042 the empty string, the list of conditions is reset completely,
1043 all previous condition settings (of any kind) will have no
1044 effect.</para></listitem>
1045 </varlistentry>
1046
1047 <varlistentry>
1048 <term><varname>AssertArchitecture=</varname></term>
1049 <term><varname>AssertVirtualization=</varname></term>
1050 <term><varname>AssertHost=</varname></term>
1051 <term><varname>AssertKernelCommandLine=</varname></term>
1052 <term><varname>AssertSecurity=</varname></term>
1053 <term><varname>AssertCapability=</varname></term>
1054 <term><varname>AssertACPower=</varname></term>
1055 <term><varname>AssertNeedsUpdate=</varname></term>
1056 <term><varname>AssertFirstBoot=</varname></term>
1057 <term><varname>AssertPathExists=</varname></term>
1058 <term><varname>AssertPathExistsGlob=</varname></term>
1059 <term><varname>AssertPathIsDirectory=</varname></term>
1060 <term><varname>AssertPathIsSymbolicLink=</varname></term>
1061 <term><varname>AssertPathIsMountPoint=</varname></term>
1062 <term><varname>AssertPathIsReadWrite=</varname></term>
1063 <term><varname>AssertDirectoryNotEmpty=</varname></term>
1064 <term><varname>AssertFileNotEmpty=</varname></term>
1065 <term><varname>AssertFileIsExecutable=</varname></term>
1066
4c89c718
MP
1067 <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
1068 <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add
1069 assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
1070 that is not met results in failure of the start job (which means this is logged loudly). Use assertion
1071 expressions for units that cannot operate when specific requirements are not met, and when this is something
1072 the administrator or user should look into.</para></listitem>
e735f4d4
MP
1073 </varlistentry>
1074
1075 <varlistentry>
1076 <term><varname>SourcePath=</varname></term>
1077 <listitem><para>A path to a configuration file this unit has
1078 been generated from. This is primarily useful for
1079 implementation of generator tools that convert configuration
1080 from an external configuration file format into native unit
1081 files. This functionality should not be used in normal
1082 units.</para></listitem>
1083 </varlistentry>
6300502b 1084
e735f4d4
MP
1085 </variablelist>
1086
1087 </refsect1>
1088
1089 <refsect1>
1090 <title>[Install] Section Options</title>
1091
4c89c718
MP
1092 <para>Unit files may include an <literal>[Install]</literal> section, which carries installation information for
1093 the unit. This section is not interpreted by
1094 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
1095 used by the <command>enable</command> and <command>disable</command> commands of the
1096 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
1097 installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in
1098 <filename>.d/*.conf</filename> unit file drop-ins (see above).</para>
e735f4d4
MP
1099
1100 <variablelist class='unit-directives'>
1101 <varlistentry>
1102 <term><varname>Alias=</varname></term>
1103
1104 <listitem><para>A space-separated list of additional names
1105 this unit shall be installed under. The names listed here must
1106 have the same suffix (i.e. type) as the unit file name. This
1107 option may be specified more than once, in which case all
1108 listed names are used. At installation time,
1109 <command>systemctl enable</command> will create symlinks from
1110 these names to the unit filename.</para></listitem>
1111 </varlistentry>
1112
1113 <varlistentry>
1114 <term><varname>WantedBy=</varname></term>
1115 <term><varname>RequiredBy=</varname></term>
1116
1117 <listitem><para>This option may be used more than once, or a
1118 space-separated list of unit names may be given. A symbolic
1119 link is created in the <filename>.wants/</filename> or
1120 <filename>.requires/</filename> directory of each of the
1121 listed units when this unit is installed by <command>systemctl
1122 enable</command>. This has the effect that a dependency of
1123 type <varname>Wants=</varname> or <varname>Requires=</varname>
1124 is added from the listed unit to the current unit. The primary
1125 result is that the current unit will be started when the
1126 listed unit is started. See the description of
1127 <varname>Wants=</varname> and <varname>Requires=</varname> in
1128 the [Unit] section for details.</para>
1129
1130 <para><command>WantedBy=foo.service</command> in a service
1131 <filename>bar.service</filename> is mostly equivalent to
1132 <command>Alias=foo.service.wants/bar.service</command> in the
1133 same file. In case of template units, <command>systemctl
1134 enable</command> must be called with an instance name, and
1135 this instance will be added to the
1136 <filename>.wants/</filename> or
1137 <filename>.requires/</filename> list of the listed unit. E.g.
1138 <command>WantedBy=getty.target</command> in a service
1139 <filename>getty@.service</filename> will result in
1140 <command>systemctl enable getty@tty2.service</command>
1141 creating a
1142 <filename>getty.target.wants/getty@tty2.service</filename>
1143 link to <filename>getty@.service</filename>.
1144 </para></listitem>
1145 </varlistentry>
1146
1147 <varlistentry>
1148 <term><varname>Also=</varname></term>
1149
1150 <listitem><para>Additional units to install/deinstall when
1151 this unit is installed/deinstalled. If the user requests
1152 installation/deinstallation of a unit with this option
1153 configured, <command>systemctl enable</command> and
1154 <command>systemctl disable</command> will automatically
1155 install/uninstall units listed in this option as well.</para>
1156
1157 <para>This option may be used more than once, or a
1158 space-separated list of unit names may be
1159 given.</para></listitem>
1160 </varlistentry>
1161
1162 <varlistentry>
1163 <term><varname>DefaultInstance=</varname></term>
1164
1165 <listitem><para>In template unit files, this specifies for
1166 which instance the unit shall be enabled if the template is
1167 enabled without any explicitly set instance. This option has
1168 no effect in non-template unit files. The specified string
1169 must be usable as instance identifier.</para></listitem>
1170 </varlistentry>
1171 </variablelist>
1172
1173 <para>The following specifiers are interpreted in the Install
1174 section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning
1175 see the next section.
1176 </para>
1177 </refsect1>
1178
1179 <refsect1>
1180 <title>Specifiers</title>
1181
1182 <para>Many settings resolve specifiers which may be used to write
1183 generic unit files referring to runtime or unit parameters that
1184 are replaced when the unit files are loaded. The following
1185 specifiers are understood:</para>
1186
1187 <table>
1188 <title>Specifiers available in unit files</title>
1189 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1190 <colspec colname="spec" />
1191 <colspec colname="mean" />
1192 <colspec colname="detail" />
1193 <thead>
1194 <row>
1195 <entry>Specifier</entry>
1196 <entry>Meaning</entry>
1197 <entry>Details</entry>
1198 </row>
1199 </thead>
1200 <tbody>
1201 <row>
1202 <entry><literal>%n</literal></entry>
1203 <entry>Full unit name</entry>
1204 <entry></entry>
1205 </row>
1206 <row>
1207 <entry><literal>%N</literal></entry>
1208 <entry>Unescaped full unit name</entry>
1209 <entry>Same as <literal>%n</literal>, but with escaping undone</entry>
1210 </row>
1211 <row>
1212 <entry><literal>%p</literal></entry>
1213 <entry>Prefix name</entry>
1214 <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry>
1215 </row>
1216 <row>
1217 <entry><literal>%P</literal></entry>
1218 <entry>Unescaped prefix name</entry>
1219 <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
1220 </row>
1221 <row>
1222 <entry><literal>%i</literal></entry>
1223 <entry>Instance name</entry>
1224 <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry>
1225 </row>
1226 <row>
1227 <entry><literal>%I</literal></entry>
1228 <entry>Unescaped instance name</entry>
1229 <entry>Same as <literal>%i</literal>, but with escaping undone</entry>
1230 </row>
1231 <row>
1232 <entry><literal>%f</literal></entry>
1233 <entry>Unescaped filename</entry>
1234 <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry>
1235 </row>
1236 <row>
1237 <entry><literal>%c</literal></entry>
1238 <entry>Control group path of the unit</entry>
1239 <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry>
1240 </row>
1241 <row>
1242 <entry><literal>%r</literal></entry>
1243 <entry>Control group path of the slice the unit is placed in</entry>
1244 <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry>
1245 </row>
1246 <row>
1247 <entry><literal>%R</literal></entry>
1248 <entry>Root control group path below which slices and units are placed</entry>
1249 <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry>
1250 </row>
1251 <row>
1252 <entry><literal>%t</literal></entry>
1253 <entry>Runtime directory</entry>
1254 <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>
1255 </row>
1256 <row>
1257 <entry><literal>%u</literal></entry>
1258 <entry>User name</entry>
db2df898 1259 <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
e735f4d4
MP
1260 </row>
1261 <row>
1262 <entry><literal>%U</literal></entry>
1263 <entry>User UID</entry>
db2df898 1264 <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry>
e735f4d4
MP
1265 </row>
1266 <row>
1267 <entry><literal>%h</literal></entry>
1268 <entry>User home directory</entry>
db2df898 1269 <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry>
e735f4d4
MP
1270 </row>
1271 <row>
1272 <entry><literal>%s</literal></entry>
1273 <entry>User shell</entry>
db2df898 1274 <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>
e735f4d4
MP
1275 </row>
1276 <row>
1277 <entry><literal>%m</literal></entry>
1278 <entry>Machine ID</entry>
1279 <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>
1280 </row>
1281 <row>
1282 <entry><literal>%b</literal></entry>
1283 <entry>Boot ID</entry>
1284 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1285 </row>
1286 <row>
1287 <entry><literal>%H</literal></entry>
1288 <entry>Host name</entry>
e3bff60a 1289 <entry>The hostname of the running system at the point in time the unit configuration is loaded.</entry>
e735f4d4
MP
1290 </row>
1291 <row>
1292 <entry><literal>%v</literal></entry>
1293 <entry>Kernel release</entry>
1294 <entry>Identical to <command>uname -r</command> output</entry>
1295 </row>
1296 <row>
1297 <entry><literal>%%</literal></entry>
1298 <entry>Single percent sign</entry>
1299 <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry>
1300 </row>
1301 </tbody>
1302 </tgroup>
1303 </table>
1304
1305 <para>Please note that specifiers <literal>%U</literal>,
1306 <literal>%h</literal>, <literal>%s</literal> are mostly useless
1307 when systemd is running in system mode. PID 1 cannot query the
1308 user account database for information, so the specifiers only work
1309 as shortcuts for things which are already specified in a different
1310 way in the unit file. They are fully functional when systemd is
1311 running in <option>--user</option> mode.</para>
1312 </refsect1>
1313
1314 <refsect1>
1315 <title>Examples</title>
1316
1317 <example>
1318 <title>Allowing units to be enabled</title>
1319
1320 <para>The following snippet (highlighted) allows a unit (e.g.
1321 <filename>foo.service</filename>) to be enabled via
1322 <command>systemctl enable</command>:</para>
1323
1324 <programlisting>[Unit]
1325Description=Foo
1326
1327[Service]
1328ExecStart=/usr/sbin/foo-daemon
1329
1330<emphasis>[Install]</emphasis>
1331<emphasis>WantedBy=multi-user.target</emphasis></programlisting>
1332
1333 <para>After running <command>systemctl enable</command>, a
1334 symlink
1335 <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename>
1336 linking to the actual unit will be created. It tells systemd to
1337 pull in the unit when starting
1338 <filename>multi-user.target</filename>. The inverse
1339 <command>systemctl disable</command> will remove that symlink
1340 again.</para>
1341 </example>
1342
1343 <example>
1344 <title>Overriding vendor settings</title>
1345
1346 <para>There are two methods of overriding vendor settings in
1347 unit files: copying the unit file from
1348 <filename>/usr/lib/systemd/system</filename> to
1349 <filename>/etc/systemd/system</filename> and modifying the
1350 chosen settings. Alternatively, one can create a directory named
1351 <filename><replaceable>unit</replaceable>.d/</filename> within
1352 <filename>/etc/systemd/system</filename> and place a drop-in
1353 file <filename><replaceable>name</replaceable>.conf</filename>
1354 there that only changes the specific settings one is interested
1355 in. Note that multiple such drop-in files are read if
1356 present.</para>
1357
1358 <para>The advantage of the first method is that one easily
1359 overrides the complete unit, the vendor unit is not parsed at
1360 all anymore. It has the disadvantage that improvements to the
1361 unit file by the vendor are not automatically incorporated on
1362 updates.</para>
1363
1364 <para>The advantage of the second method is that one only
1365 overrides the settings one specifically wants, where updates to
1366 the unit by the vendor automatically apply. This has the
1367 disadvantage that some future updates by the vendor might be
1368 incompatible with the local changes.</para>
1369
1370 <para>Note that for drop-in files, if one wants to remove
1371 entries from a setting that is parsed as a list (and is not a
1372 dependency), such as <varname>ConditionPathExists=</varname> (or
1373 e.g. <varname>ExecStart=</varname> in service units), one needs
1374 to first clear the list before re-adding all entries except the
1375 one that is to be removed. See below for an example.</para>
1376
1377 <para>This also applies for user instances of systemd, but with
1378 different locations for the unit files. See the section on unit
1379 load paths for further details.</para>
1380
1381 <para>Suppose there is a vendor-supplied unit
1382 <filename>/usr/lib/systemd/system/httpd.service</filename> with
1383 the following contents:</para>
1384
1385 <programlisting>[Unit]
1386Description=Some HTTP server
1387After=remote-fs.target sqldb.service
1388Requires=sqldb.service
1389AssertPathExists=/srv/webserver
1390
1391[Service]
1392Type=notify
1393ExecStart=/usr/sbin/some-fancy-httpd-server
1394Nice=5
1395
1396[Install]
1397WantedBy=multi-user.target</programlisting>
1398
1399 <para>Now one wants to change some settings as an administrator:
1400 firstly, in the local setup, <filename>/srv/webserver</filename>
1401 might not exist, because the HTTP server is configured to use
1402 <filename>/srv/www</filename> instead. Secondly, the local
1403 configuration makes the HTTP server also depend on a memory
1404 cache service, <filename>memcached.service</filename>, that
1405 should be pulled in (<varname>Requires=</varname>) and also be
1406 ordered appropriately (<varname>After=</varname>). Thirdly, in
1407 order to harden the service a bit more, the administrator would
1408 like to set the <varname>PrivateTmp=</varname> setting (see
1409 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1410 for details). And lastly, the administrator would like to reset
1411 the niceness of the service to its default value of 0.</para>
1412
1413 <para>The first possibility is to copy the unit file to
1414 <filename>/etc/systemd/system/httpd.service</filename> and
1415 change the chosen settings:</para>
1416
1417 <programlisting>[Unit]
1418Description=Some HTTP server
1419After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis>
1420Requires=sqldb.service <emphasis>memcached.service</emphasis>
1421AssertPathExists=<emphasis>/srv/www</emphasis>
1422
1423[Service]
1424Type=notify
1425ExecStart=/usr/sbin/some-fancy-httpd-server
1426<emphasis>Nice=0</emphasis>
1427<emphasis>PrivateTmp=yes</emphasis>
1428
1429[Install]
1430WantedBy=multi-user.target</programlisting>
1431
1432 <para>Alternatively, the administrator could create a drop-in
1433 file
1434 <filename>/etc/systemd/system/httpd.service.d/local.conf</filename>
1435 with the following contents:</para>
1436
1437 <programlisting>[Unit]
1438After=memcached.service
1439Requires=memcached.service
1440# Reset all assertions and then re-add the condition we want
1441AssertPathExists=
1442AssertPathExists=/srv/www
1443
1444[Service]
1445Nice=0
1446PrivateTmp=yes</programlisting>
1447
1448 <para>Note that dependencies (<varname>After=</varname>, etc.)
1449 cannot be reset to an empty list, so dependencies can only be
1450 added in drop-ins. If you want to remove dependencies, you have
1451 to override the entire unit.</para>
4c89c718 1452
e735f4d4
MP
1453 </example>
1454 </refsect1>
1455
1456 <refsect1>
1457 <title>See Also</title>
1458 <para>
1459 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1460 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1461 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1462 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1463 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1464 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1465 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1466 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1467 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1468 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1469 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1470 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e735f4d4
MP
1471 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1472 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1473 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1474 <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1475 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1476 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
e3bff60a 1477 <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e735f4d4
MP
1478 </para>
1479 </refsect1>
663996b3
MS
1480
1481</refentry>