1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2010 Lennart Poettering
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.
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.
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/>.
27 <refentry id=
"systemd.unit">
30 <title>systemd.unit
</title>
31 <productname>systemd
</productname>
35 <contrib>Developer
</contrib>
36 <firstname>Lennart
</firstname>
37 <surname>Poettering
</surname>
38 <email>lennart@poettering.net
</email>
44 <refentrytitle>systemd.unit
</refentrytitle>
45 <manvolnum>5</manvolnum>
49 <refname>systemd.unit
</refname>
50 <refpurpose>Unit configuration
</refpurpose>
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>,
63 <filename><replaceable>slice
</replaceable>.slice
</filename>,
64 <filename><replaceable>scope
</replaceable>.scope
</filename></para>
66 <para><literallayout><filename>/etc/systemd/system/*
</filename>
67 <filename>/run/systemd/system/*
</filename>
68 <filename>/usr/lib/systemd/system/*
</filename>
69 <filename>...
</filename>
70 </literallayout></para>
72 <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*
</filename>
73 <filename>$HOME/.config/systemd/user/*
</filename>
74 <filename>/etc/systemd/user/*
</filename>
75 <filename>$XDG_RUNTIME_DIR/systemd/user/*
</filename>
76 <filename>/run/systemd/user/*
</filename>
77 <filename>$XDG_DATA_HOME/systemd/user/*
</filename>
78 <filename>$HOME/.local/share/systemd/user/*
</filename>
79 <filename>/usr/lib/systemd/user/*
</filename>
80 <filename>...
</filename>
81 </literallayout></para>
85 <title>Description
</title>
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>,
92 a resource management slice or
93 a group of externally created processes. The syntax is inspired by
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>
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>
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
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>,
117 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
118 <citerefentry><refentrytitle>systemd.scope
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
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>
130 <para>Unit files are loaded from a set of paths determined during
131 compilation, described in the next section.
</para>
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>
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
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.
157 <citerefentry><refentrytitle>systemd.time
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
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>
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
181 <para>Along with a unit file
<filename>foo.service
</filename>, a
182 directory
<filename>foo.service.d/
</filename> may exist. All files
183 with the suffix
<literal>.conf
</literal> from this directory will
184 be parsed after the file itself is parsed. This is useful to alter
185 or add configuration settings to a unit, without having to modify
186 their unit files. Make sure that the file that is included has the
187 appropriate section headers before any directive. Note that, for
188 instanced units, this logic will first look for the instance
189 <literal>.d/
</literal> subdirectory and read its
190 <literal>.conf
</literal> files, followed by the template
191 <literal>.d/
</literal> subdirectory and reads its
192 <literal>.conf
</literal> files.
</para>
194 <para>In addition to
<filename>/etc/systemd/system
</filename>,
195 the drop-in
<literal>.conf
</literal> files for system services
196 can be placed in
<filename>/usr/lib/systemd/system
</filename> or
197 <filename>/run/systemd/system
</filename> directories. Drop-in
198 files in
<filename>/etc
</filename> take precedence over those in
199 <filename>/run
</filename> which in turn take precedence over
200 those in
<filename>/usr/lib
</filename>. Drop-in files under any of
201 these directories take precedence over unit files wherever located.
202 (Of course, since
<filename>/run
</filename> is temporary and
203 <filename>/usr/lib
</filename> is for vendors, it is unlikely
204 drop-ins should be used in either of those places.)
</para>
205 <!-- Note that we do not document .include here, as we
206 consider it mostly obsolete, and want people to
207 use .d/ drop-ins instead. -->
209 <para>Some unit names reflect paths existing in the file system
210 namespace. Example: a device unit
211 <filename>dev-sda.device
</filename> refers to a device with the
212 device node
<filename noindex='true'
>/dev/sda
</filename> in the
213 file system namespace. If this applies, a special way to escape
214 the path name is used, so that the result is usable as part of a
215 filename. Basically, given a path,
"/" is replaced by
"-", and all
216 other characters which are not ASCII alphanumerics are replaced by
217 C-style
"\x2d" escapes (except that
"_" is never replaced and
"."
218 is only replaced when it would be the first character in the
219 escaped path). The root directory
"/" is encoded as single dash,
220 while otherwise the initial and ending
"/" are removed from all
221 paths during transformation. This escaping is reversible. Properly
222 escaped paths can be generated using the
223 <citerefentry><refentrytitle>systemd-escape
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
226 <para>Optionally, units may be instantiated from a
227 template file at runtime. This allows creation of
228 multiple units from a single configuration file. If
229 systemd looks for a unit configuration file, it will
230 first search for the literal unit name in the
231 file system. If that yields no success and the unit
232 name contains an
<literal>@
</literal> character, systemd will look for a
233 unit template that shares the same name but with the
234 instance string (i.e. the part between the
<literal>@
</literal> character
235 and the suffix) removed. Example: if a service
236 <filename>getty@tty3.service
</filename> is requested
237 and no file by that name is found, systemd will look
238 for
<filename>getty@.service
</filename> and
239 instantiate a service from that configuration file if
242 <para>To refer to the instance string from within the
243 configuration file you may use the special
<literal>%i
</literal>
244 specifier in many of the configuration options. See below for
247 <para>If a unit file is empty (i.e. has the file size
0) or is
248 symlinked to
<filename>/dev/null
</filename>, its configuration
249 will not be loaded and it appears with a load state of
250 <literal>masked
</literal>, and cannot be activated. Use this as an
251 effective way to fully disable a unit, making it impossible to
252 start it even manually.
</para>
254 <para>The unit file format is covered by the
256 url=
"http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
257 Stability Promise
</ulink>.
</para>
262 <title>Automatic Dependencies
</title>
264 <para>Note that while systemd offers a flexible dependency system
265 between units it is recommended to use this functionality only
266 sparingly and instead rely on techniques such as bus-based or
267 socket-based activation which make dependencies implicit,
268 resulting in a both simpler and more flexible system.
</para>
270 <para>A number of unit dependencies are automatically established,
271 depending on unit configuration. On top of that, for units with
272 <varname>DefaultDependencies=yes
</varname> (the default) a couple
273 of additional dependencies are added. The precise effect of
274 <varname>DefaultDependencies=yes
</varname> depends on the unit
275 type (see below).
</para>
277 <para>If
<varname>DefaultDependencies=yes
</varname> is set, units
278 that are referenced by other units of type
279 <filename>.target
</filename> via a
<varname>Wants=
</varname> or
280 <varname>Requires=
</varname> dependency might automatically gain
281 an
<varname>Before=
</varname> dependency too. See
282 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
287 <title>Unit File Load Path
</title>
289 <para>Unit files are loaded from a set of paths determined during
290 compilation, described in the two tables below. Unit files found
291 in directories listed earlier override files with the same name in
292 directories lower in the list.
</para>
294 <para>When the variable
<varname>$SYSTEMD_UNIT_PATH
</varname> is set,
295 the contents of this variable overrides the unit load path. If
296 <varname>$SYSTEMD_UNIT_PATH
</varname> ends with an empty component
297 (
<literal>:
</literal>), the usual unit load path will be appended
298 to the contents of the variable.
</para>
302 Load path when running in system mode (
<option>--system
</option>).
306 <colspec colname='path'
/>
307 <colspec colname='expl'
/>
311 <entry>Description
</entry>
316 <entry><filename>/etc/systemd/system
</filename></entry>
317 <entry>Local configuration
</entry>
320 <entry><filename>/run/systemd/system
</filename></entry>
321 <entry>Runtime units
</entry>
324 <entry><filename>/usr/lib/systemd/system
</filename></entry>
325 <entry>Units of installed packages
</entry>
333 Load path when running in user mode (
<option>--user
</option>).
337 <colspec colname='path'
/>
338 <colspec colname='expl'
/>
342 <entry>Description
</entry>
347 <entry><filename>$XDG_CONFIG_HOME/systemd/user
</filename></entry>
348 <entry>User configuration (only used when $XDG_CONFIG_HOME is set)
</entry>
351 <entry><filename>$HOME/.config/systemd/user
</filename></entry>
352 <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)
</entry>
355 <entry><filename>/etc/systemd/user
</filename></entry>
356 <entry>Local configuration
</entry>
359 <entry><filename>$XDG_RUNTIME_DIR/systemd/user
</filename></entry>
360 <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)
</entry>
363 <entry><filename>/run/systemd/user
</filename></entry>
364 <entry>Runtime units
</entry>
367 <entry><filename>$XDG_DATA_HOME/systemd/user
</filename></entry>
368 <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)
</entry>
371 <entry><filename>$HOME/.local/share/systemd/user
</filename></entry>
372 <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)
</entry>
375 <entry><filename>/usr/lib/systemd/user
</filename></entry>
376 <entry>Units of packages that have been installed system-wide
</entry>
382 <para>Additional units might be loaded into systemd (
"linked")
383 from directories not on the unit load path. See the
384 <command>link
</command> command for
385 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
386 Also, some units are dynamically created via a
387 <citerefentry><refentrytitle>systemd.generator
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
392 <title>[Unit] Section Options
</title>
394 <para>The unit file may include a [Unit] section, which carries
395 generic information about the unit that is not dependent on the
398 <variablelist class='unit-directives'
>
401 <term><varname>Description=
</varname></term>
402 <listitem><para>A free-form string describing the unit. This
403 is intended for use in UIs to show descriptive information
404 along with the unit name. The description should contain a
405 name that means something to the end user.
<literal>Apache2
406 Web Server
</literal> is a good example. Bad examples are
407 <literal>high-performance light-weight HTTP server
</literal>
408 (too generic) or
<literal>Apache2
</literal> (too specific and
409 meaningless for people who do not know
410 Apache).
</para></listitem>
414 <term><varname>Documentation=
</varname></term>
415 <listitem><para>A space-separated list of URIs referencing
416 documentation for this unit or its configuration. Accepted are
417 only URIs of the types
<literal>http://
</literal>,
418 <literal>https://
</literal>,
<literal>file:
</literal>,
419 <literal>info:
</literal>,
<literal>man:
</literal>. For more
420 information about the syntax of these URIs, see
<citerefentry
421 project='man-pages'
><refentrytitle>uri
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
422 The URIs should be listed in order of relevance, starting with
423 the most relevant. It is a good idea to first reference
424 documentation that explains what the unit's purpose is,
425 followed by how it is configured, followed by any other
426 related documentation. This option may be specified more than
427 once, in which case the specified list of URIs is merged. If
428 the empty string is assigned to this option, the list is reset
429 and all prior assignments will have no
430 effect.
</para></listitem>
434 <term><varname>Requires=
</varname></term>
436 <listitem><para>Configures requirement dependencies on other
437 units. If this unit gets activated, the units listed here will
438 be activated as well. If one of the other units gets
439 deactivated or its activation fails, this unit will be
440 deactivated. This option may be specified more than once or
441 multiple space-separated units may be specified in one option
442 in which case requirement dependencies for all listed names
443 will be created. Note that requirement dependencies do not
444 influence the order in which services are started or stopped.
445 This has to be configured independently with the
446 <varname>After=
</varname> or
<varname>Before=
</varname>
447 options. If a unit
<filename>foo.service
</filename> requires a
448 unit
<filename>bar.service
</filename> as configured with
449 <varname>Requires=
</varname> and no ordering is configured
450 with
<varname>After=
</varname> or
<varname>Before=
</varname>,
451 then both units will be started simultaneously and without any
452 delay between them if
<filename>foo.service
</filename> is
453 activated. Often, it is a better choice to use
454 <varname>Wants=
</varname> instead of
455 <varname>Requires=
</varname> in order to achieve a system that
456 is more robust when dealing with failing services.
</para>
458 <para>Note that dependencies of this type may also be
459 configured outside of the unit configuration file by adding a
460 symlink to a
<filename>.requires/
</filename> directory
461 accompanying the unit file. For details, see
462 above.
</para></listitem>
466 <term><varname>Requisite=
</varname></term>
468 <listitem><para>Similar to
<varname>Requires=
</varname>.
469 However, if the units listed here are not started already,
470 they will not be started and the transaction will fail
471 immediately.
</para></listitem>
475 <term><varname>Wants=
</varname></term>
477 <listitem><para>A weaker version of
478 <varname>Requires=
</varname>. Units listed in this option will
479 be started if the configuring unit is. However, if the listed
480 units fail to start or cannot be added to the transaction,
481 this has no impact on the validity of the transaction as a
482 whole. This is the recommended way to hook start-up of one
483 unit to the start-up of another unit.
</para>
485 <para>Note that dependencies of this type may also be
486 configured outside of the unit configuration file by adding
487 symlinks to a
<filename>.wants/
</filename> directory
488 accompanying the unit file. For details, see
489 above.
</para></listitem>
493 <term><varname>BindsTo=
</varname></term>
495 <listitem><para>Configures requirement dependencies, very
496 similar in style to
<varname>Requires=
</varname>, however in
497 addition to this behavior, it also declares that this unit is
498 stopped when any of the units listed suddenly disappears.
499 Units can suddenly, unexpectedly disappear if a service
500 terminates on its own choice, a device is unplugged or a mount
501 point unmounted without involvement of
502 systemd.
</para></listitem>
506 <term><varname>PartOf=
</varname></term>
508 <listitem><para>Configures dependencies similar to
509 <varname>Requires=
</varname>, but limited to stopping and
510 restarting of units. When systemd stops or restarts the units
511 listed here, the action is propagated to this unit. Note that
512 this is a one-way dependency — changes to this unit do not
513 affect the listed units.
</para></listitem>
517 <term><varname>Conflicts=
</varname></term>
519 <listitem><para>A space-separated list of unit names.
520 Configures negative requirement dependencies. If a unit has a
521 <varname>Conflicts=
</varname> setting on another unit,
522 starting the former will stop the latter and vice versa. Note
523 that this setting is independent of and orthogonal to the
524 <varname>After=
</varname> and
<varname>Before=
</varname>
525 ordering dependencies.
</para>
527 <para>If a unit A that conflicts with a unit B is scheduled to
528 be started at the same time as B, the transaction will either
529 fail (in case both are required part of the transaction) or be
530 modified to be fixed (in case one or both jobs are not a
531 required part of the transaction). In the latter case, the job
532 that is not the required will be removed, or in case both are
533 not required, the unit that conflicts will be started and the
534 unit that is conflicted is stopped.
</para></listitem>
538 <term><varname>Before=
</varname></term>
539 <term><varname>After=
</varname></term>
541 <listitem><para>A space-separated list of unit names.
542 Configures ordering dependencies between units. If a unit
543 <filename>foo.service
</filename> contains a setting
544 <option>Before=bar.service
</option> and both units are being
545 started,
<filename>bar.service
</filename>'s start-up is
546 delayed until
<filename>foo.service
</filename> is started up.
547 Note that this setting is independent of and orthogonal to the
548 requirement dependencies as configured by
549 <varname>Requires=
</varname>. It is a common pattern to
550 include a unit name in both the
<varname>After=
</varname> and
551 <varname>Requires=
</varname> option, in which case the unit
552 listed will be started before the unit that is configured with
553 these options. This option may be specified more than once, in
554 which case ordering dependencies for all listed names are
555 created.
<varname>After=
</varname> is the inverse of
556 <varname>Before=
</varname>, i.e. while
557 <varname>After=
</varname> ensures that the configured unit is
558 started after the listed unit finished starting up,
559 <varname>Before=
</varname> ensures the opposite, i.e. that the
560 configured unit is fully started up before the listed unit is
561 started. Note that when two units with an ordering dependency
562 between them are shut down, the inverse of the start-up order
563 is applied. i.e. if a unit is configured with
564 <varname>After=
</varname> on another unit, the former is
565 stopped before the latter if both are shut down. If one unit
566 with an ordering dependency on another unit is shut down while
567 the latter is started up, the shut down is ordered before the
568 start-up regardless of whether the ordering dependency is
569 actually of type
<varname>After=
</varname> or
570 <varname>Before=
</varname>. If two units have no ordering
571 dependencies between them, they are shut down or started up
572 simultaneously, and no ordering takes place.
577 <term><varname>OnFailure=
</varname></term>
579 <listitem><para>A space-separated list of one or more units
580 that are activated when this unit enters the
581 <literal>failed
</literal> state.
</para></listitem>
585 <term><varname>PropagatesReloadTo=
</varname></term>
586 <term><varname>ReloadPropagatedFrom=
</varname></term>
588 <listitem><para>A space-separated list of one or more units
589 where reload requests on this unit will be propagated to, or
590 reload requests on the other unit will be propagated to this
591 unit, respectively. Issuing a reload request on a unit will
592 automatically also enqueue a reload request on all units that
593 the reload request shall be propagated to via these two
594 settings.
</para></listitem>
598 <term><varname>JoinsNamespaceOf=
</varname></term>
600 <listitem><para>For units that start processes (such as
601 service units), lists one or more other units whose network
602 and/or temporary file namespace to join. This only applies to
603 unit types which support the
604 <varname>PrivateNetwork=
</varname> and
605 <varname>PrivateTmp=
</varname> directives (see
606 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
607 for details). If a unit that has this setting set is started,
608 its processes will see the same
<filename>/tmp
</filename>,
609 <filename>/tmp/var
</filename> and network namespace as one
610 listed unit that is started. If multiple listed units are
611 already started, it is not defined which namespace is joined.
612 Note that this setting only has an effect if
613 <varname>PrivateNetwork=
</varname> and/or
614 <varname>PrivateTmp=
</varname> is enabled for both the unit
615 that joins the namespace and the unit whose namespace is
616 joined.
</para></listitem>
620 <term><varname>RequiresMountsFor=
</varname></term>
622 <listitem><para>Takes a space-separated list of absolute
623 paths. Automatically adds dependencies of type
624 <varname>Requires=
</varname> and
<varname>After=
</varname> for
625 all mount units required to access the specified path.
</para>
627 <para>Mount points marked with
<option>noauto
</option> are not
628 mounted automatically and will be ignored for the purposes of
629 this option. If such a mount should be a requirement for this
630 unit, direct dependencies on the mount units may be added
631 (
<varname>Requires=
</varname> and
<varname>After=
</varname> or
632 some other combination).
</para></listitem>
636 <term><varname>OnFailureJobMode=
</varname></term>
638 <listitem><para>Takes a value of
639 <literal>fail
</literal>,
640 <literal>replace
</literal>,
641 <literal>replace-irreversibly
</literal>,
642 <literal>isolate
</literal>,
643 <literal>flush
</literal>,
644 <literal>ignore-dependencies
</literal> or
645 <literal>ignore-requirements
</literal>. Defaults to
646 <literal>replace
</literal>. Specifies how the units listed in
647 <varname>OnFailure=
</varname> will be enqueued. See
648 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
649 <option>--job-mode=
</option> option for details on the
650 possible values. If this is set to
<literal>isolate
</literal>,
651 only a single unit may be listed in
652 <varname>OnFailure=
</varname>..
</para></listitem>
656 <term><varname>IgnoreOnIsolate=
</varname></term>
658 <listitem><para>Takes a boolean argument. If
659 <option>true
</option>, this unit will not be stopped when
660 isolating another unit. Defaults to
661 <option>false
</option>.
</para></listitem>
665 <term><varname>StopWhenUnneeded=
</varname></term>
667 <listitem><para>Takes a boolean argument. If
668 <option>true
</option>, this unit will be stopped when it is no
669 longer used. Note that, in order to minimize the work to be
670 executed, systemd will not stop units by default unless they
671 are conflicting with other units, or the user explicitly
672 requested their shut down. If this option is set, a unit will
673 be automatically cleaned up if no other active unit requires
674 it. Defaults to
<option>false
</option>.
</para></listitem>
678 <term><varname>RefuseManualStart=
</varname></term>
679 <term><varname>RefuseManualStop=
</varname></term>
681 <listitem><para>Takes a boolean argument. If
682 <option>true
</option>, this unit can only be activated or
683 deactivated indirectly. In this case, explicit start-up or
684 termination requested by the user is denied, however if it is
685 started or stopped as a dependency of another unit, start-up
686 or termination will succeed. This is mostly a safety feature
687 to ensure that the user does not accidentally activate units
688 that are not intended to be activated explicitly, and not
689 accidentally deactivate units that are not intended to be
690 deactivated. These options default to
691 <option>false
</option>.
</para></listitem>
695 <term><varname>AllowIsolate=
</varname></term>
697 <listitem><para>Takes a boolean argument. If
698 <option>true
</option>, this unit may be used with the
699 <command>systemctl isolate
</command> command. Otherwise, this
700 will be refused. It probably is a good idea to leave this
701 disabled except for target units that shall be used similar to
702 runlevels in SysV init systems, just as a precaution to avoid
703 unusable system states. This option defaults to
704 <option>false
</option>.
</para></listitem>
708 <term><varname>DefaultDependencies=
</varname></term>
710 <listitem><para>Takes a boolean argument. If
711 <option>true
</option>, (the default), a few default
712 dependencies will implicitly be created for the unit. The
713 actual dependencies created depend on the unit type. For
714 example, for service units, these dependencies ensure that the
715 service is started only after basic system initialization is
716 completed and is properly terminated on system shutdown. See
717 the respective man pages for details. Generally, only services
718 involved with early boot or late shutdown should set this
719 option to
<option>false
</option>. It is highly recommended to
720 leave this option enabled for the majority of common units. If
721 set to
<option>false
</option>, this option does not disable
722 all implicit dependencies, just non-essential
723 ones.
</para></listitem>
727 <term><varname>JobTimeoutSec=
</varname></term>
728 <term><varname>JobTimeoutAction=
</varname></term>
729 <term><varname>JobTimeoutRebootArgument=
</varname></term>
731 <listitem><para>When a job for this unit is queued, a time-out
732 may be configured. If this time limit is reached, the job will
733 be cancelled, the unit however will not change state or even
734 enter the
<literal>failed
</literal> mode. This value defaults
735 to
0 (job timeouts disabled), except for device units. NB:
736 this timeout is independent from any unit-specific timeout
737 (for example, the timeout set with
738 <varname>TimeoutStartSec=
</varname> in service units) as the
739 job timeout has no effect on the unit itself, only on the job
740 that might be pending for it. Or in other words: unit-specific
741 timeouts are useful to abort unit state changes, and revert
742 them. The job timeout set with this option however is useful
743 to abort only the job waiting for the unit state to
746 <para><varname>JobTimeoutAction=
</varname>
747 optionally configures an additional
748 action to take when the time-out is
749 hit. It takes the same values as the
751 <varname>StartLimitAction=
</varname>
753 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
754 for details. Defaults to
755 <option>none
</option>.
<varname>JobTimeoutRebootArgument=
</varname>
756 configures an optional reboot string
758 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
759 system call.
</para></listitem>
763 <term><varname>ConditionArchitecture=
</varname></term>
764 <term><varname>ConditionVirtualization=
</varname></term>
765 <term><varname>ConditionHost=
</varname></term>
766 <term><varname>ConditionKernelCommandLine=
</varname></term>
767 <term><varname>ConditionSecurity=
</varname></term>
768 <term><varname>ConditionCapability=
</varname></term>
769 <term><varname>ConditionACPower=
</varname></term>
770 <term><varname>ConditionNeedsUpdate=
</varname></term>
771 <term><varname>ConditionFirstBoot=
</varname></term>
772 <term><varname>ConditionPathExists=
</varname></term>
773 <term><varname>ConditionPathExistsGlob=
</varname></term>
774 <term><varname>ConditionPathIsDirectory=
</varname></term>
775 <term><varname>ConditionPathIsSymbolicLink=
</varname></term>
776 <term><varname>ConditionPathIsMountPoint=
</varname></term>
777 <term><varname>ConditionPathIsReadWrite=
</varname></term>
778 <term><varname>ConditionDirectoryNotEmpty=
</varname></term>
779 <term><varname>ConditionFileNotEmpty=
</varname></term>
780 <term><varname>ConditionFileIsExecutable=
</varname></term>
782 <!-- We do not document ConditionNull=
783 here, as it is not particularly
784 useful and probably just
787 <listitem><para>Before starting a unit verify that the
788 specified condition is true. If it is not true, the starting
789 of the unit will be skipped, however all ordering dependencies
790 of it are still respected. A failing condition will not result
791 in the unit being moved into a failure state. The condition is
792 checked at the time the queued start job is to be
795 <para><varname>ConditionArchitecture=
</varname> may be used to
796 check whether the system is running on a specific
797 architecture. Takes one of
798 <varname>x86
</varname>,
799 <varname>x86-
64</varname>,
800 <varname>ppc
</varname>,
801 <varname>ppc-le
</varname>,
802 <varname>ppc64
</varname>,
803 <varname>ppc64-le
</varname>,
804 <varname>ia64
</varname>,
805 <varname>parisc
</varname>,
806 <varname>parisc64
</varname>,
807 <varname>s390
</varname>,
808 <varname>s390x
</varname>,
809 <varname>sparc
</varname>,
810 <varname>sparc64
</varname>,
811 <varname>mips
</varname>,
812 <varname>mips-le
</varname>,
813 <varname>mips64
</varname>,
814 <varname>mips64-le
</varname>,
815 <varname>alpha
</varname>,
816 <varname>arm
</varname>,
817 <varname>arm-be
</varname>,
818 <varname>arm64
</varname>,
819 <varname>arm64-be
</varname>,
820 <varname>sh
</varname>,
821 <varname>sh64
</varname>,
822 <varname>m86k
</varname>,
823 <varname>tilegx
</varname>,
824 <varname>cris
</varname> to test
825 against a specific architecture. The architecture is
826 determined from the information returned by
827 <citerefentry project='man-pages'
><refentrytitle>uname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
828 and is thus subject to
829 <citerefentry><refentrytitle>personality
</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
830 Note that a
<varname>Personality=
</varname> setting in the
831 same unit file has no effect on this condition. A special
832 architecture name
<varname>native
</varname> is mapped to the
833 architecture the system manager itself is compiled for. The
834 test may be negated by prepending an exclamation mark.
</para>
836 <para><varname>ConditionVirtualization=
</varname> may be used
837 to check whether the system is executed in a virtualized
838 environment and optionally test whether it is a specific
839 implementation. Takes either boolean value to check if being
840 executed in any virtualized environment, or one of
841 <varname>vm
</varname> and
842 <varname>container
</varname> to test against a generic type of
843 virtualization solution, or one of
844 <varname>qemu
</varname>,
845 <varname>kvm
</varname>,
846 <varname>zvm
</varname>,
847 <varname>vmware
</varname>,
848 <varname>microsoft
</varname>,
849 <varname>oracle
</varname>,
850 <varname>xen
</varname>,
851 <varname>bochs
</varname>,
852 <varname>uml
</varname>,
853 <varname>openvz
</varname>,
854 <varname>lxc
</varname>,
855 <varname>lxc-libvirt
</varname>,
856 <varname>systemd-nspawn
</varname>,
857 <varname>docker
</varname>,
858 <varname>rkt
</varname> to test
859 against a specific implementation. See
860 <citerefentry><refentrytitle>systemd-detect-virt
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
861 for a full list of known virtualization technologies and their
862 identifiers. If multiple virtualization technologies are
863 nested, only the innermost is considered. The test may be
864 negated by prepending an exclamation mark.
</para>
866 <para><varname>ConditionHost=
</varname> may be used to match
867 against the hostname or machine ID of the host. This either
868 takes a hostname string (optionally with shell style globs)
869 which is tested against the locally set hostname as returned
871 <citerefentry><refentrytitle>gethostname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
872 or a machine ID formatted as string (see
873 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
874 The test may be negated by prepending an exclamation
877 <para><varname>ConditionKernelCommandLine=
</varname> may be
878 used to check whether a specific kernel command line option is
879 set (or if prefixed with the exclamation mark unset). The
880 argument must either be a single word, or an assignment (i.e.
881 two words, separated
<literal>=
</literal>). In the former case
882 the kernel command line is searched for the word appearing as
883 is, or as left hand side of an assignment. In the latter case,
884 the exact assignment is looked for with right and left hand
885 side matching.
</para>
887 <para><varname>ConditionSecurity=
</varname> may be used to
888 check whether the given security module is enabled on the
889 system. Currently, the recognized values values are
890 <varname>selinux
</varname>,
891 <varname>apparmor
</varname>,
892 <varname>ima
</varname>,
893 <varname>smack
</varname> and
894 <varname>audit
</varname>. The test may be negated by
895 prepending an exclamation mark.
</para>
897 <para><varname>ConditionCapability=
</varname> may be used to
898 check whether the given capability exists in the capability
899 bounding set of the service manager (i.e. this does not check
900 whether capability is actually available in the permitted or
902 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
903 for details). Pass a capability name such as
904 <literal>CAP_MKNOD
</literal>, possibly prefixed with an
905 exclamation mark to negate the check.
</para>
907 <para><varname>ConditionACPower=
</varname> may be used to
908 check whether the system has AC power, or is exclusively
909 battery powered at the time of activation of the unit. This
910 takes a boolean argument. If set to
<varname>true
</varname>,
911 the condition will hold only if at least one AC connector of
912 the system is connected to a power source, or if no AC
913 connectors are known. Conversely, if set to
914 <varname>false
</varname>, the condition will hold only if
915 there is at least one AC connector known and all AC connectors
916 are disconnected from a power source.
</para>
918 <para><varname>ConditionNeedsUpdate=
</varname> takes one of
919 <filename>/var
</filename> or
<filename>/etc
</filename> as
920 argument, possibly prefixed with a
<literal>!
</literal> (for
921 inverting the condition). This condition may be used to
922 conditionalize units on whether the specified directory
923 requires an update because
<filename>/usr
</filename>'s
924 modification time is newer than the stamp file
925 <filename>.updated
</filename> in the specified directory. This
926 is useful to implement offline updates of the vendor operating
927 system resources in
<filename>/usr
</filename> that require
928 updating of
<filename>/etc
</filename> or
929 <filename>/var
</filename> on the next following boot. Units
930 making use of this condition should order themselves before
931 <citerefentry><refentrytitle>systemd-update-done.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
932 to make sure they run before the stamp files's modification
933 time gets reset indicating a completed update.
</para>
935 <para><varname>ConditionFirstBoot=
</varname> takes a boolean
936 argument. This condition may be used to conditionalize units
937 on whether the system is booting up with an unpopulated
938 <filename>/etc
</filename> directory. This may be used to
939 populate
<filename>/etc
</filename> on the first boot after
940 factory reset, or when a new system instances boots up for the
943 <para>With
<varname>ConditionPathExists=
</varname> a file
944 existence condition is checked before a unit is started. If
945 the specified absolute path name does not exist, the condition
946 will fail. If the absolute path name passed to
947 <varname>ConditionPathExists=
</varname> is prefixed with an
948 exclamation mark (
<literal>!
</literal>), the test is negated,
949 and the unit is only started if the path does not
952 <para><varname>ConditionPathExistsGlob=
</varname> is similar
953 to
<varname>ConditionPathExists=
</varname>, but checks for the
954 existence of at least one file or directory matching the
955 specified globbing pattern.
</para>
957 <para><varname>ConditionPathIsDirectory=
</varname> is similar
958 to
<varname>ConditionPathExists=
</varname> but verifies
959 whether a certain path exists and is a directory.
</para>
961 <para><varname>ConditionPathIsSymbolicLink=
</varname> is
962 similar to
<varname>ConditionPathExists=
</varname> but
963 verifies whether a certain path exists and is a symbolic
966 <para><varname>ConditionPathIsMountPoint=
</varname> is similar
967 to
<varname>ConditionPathExists=
</varname> but verifies
968 whether a certain path exists and is a mount point.
</para>
970 <para><varname>ConditionPathIsReadWrite=
</varname> is similar
971 to
<varname>ConditionPathExists=
</varname> but verifies
972 whether the underlying file system is readable and writable
973 (i.e. not mounted read-only).
</para>
975 <para><varname>ConditionDirectoryNotEmpty=
</varname> is
976 similar to
<varname>ConditionPathExists=
</varname> but
977 verifies whether a certain path exists and is a non-empty
980 <para><varname>ConditionFileNotEmpty=
</varname> is similar to
981 <varname>ConditionPathExists=
</varname> but verifies whether a
982 certain path exists and refers to a regular file with a
983 non-zero size.
</para>
985 <para><varname>ConditionFileIsExecutable=
</varname> is similar
986 to
<varname>ConditionPathExists=
</varname> but verifies
987 whether a certain path exists, is a regular file and marked
990 <para>If multiple conditions are specified, the unit will be
991 executed if all of them apply (i.e. a logical AND is applied).
992 Condition checks can be prefixed with a pipe symbol (|) in
993 which case a condition becomes a triggering condition. If at
994 least one triggering condition is defined for a unit, then the
995 unit will be executed if at least one of the triggering
996 conditions apply and all of the non-triggering conditions. If
997 you prefix an argument with the pipe symbol and an exclamation
998 mark, the pipe symbol must be passed first, the exclamation
1000 <varname>ConditionPathIsSymbolicLink=
</varname>, all path
1001 checks follow symlinks. If any of these options is assigned
1002 the empty string, the list of conditions is reset completely,
1003 all previous condition settings (of any kind) will have no
1004 effect.
</para></listitem>
1008 <term><varname>AssertArchitecture=
</varname></term>
1009 <term><varname>AssertVirtualization=
</varname></term>
1010 <term><varname>AssertHost=
</varname></term>
1011 <term><varname>AssertKernelCommandLine=
</varname></term>
1012 <term><varname>AssertSecurity=
</varname></term>
1013 <term><varname>AssertCapability=
</varname></term>
1014 <term><varname>AssertACPower=
</varname></term>
1015 <term><varname>AssertNeedsUpdate=
</varname></term>
1016 <term><varname>AssertFirstBoot=
</varname></term>
1017 <term><varname>AssertPathExists=
</varname></term>
1018 <term><varname>AssertPathExistsGlob=
</varname></term>
1019 <term><varname>AssertPathIsDirectory=
</varname></term>
1020 <term><varname>AssertPathIsSymbolicLink=
</varname></term>
1021 <term><varname>AssertPathIsMountPoint=
</varname></term>
1022 <term><varname>AssertPathIsReadWrite=
</varname></term>
1023 <term><varname>AssertDirectoryNotEmpty=
</varname></term>
1024 <term><varname>AssertFileNotEmpty=
</varname></term>
1025 <term><varname>AssertFileIsExecutable=
</varname></term>
1027 <listitem><para>Similar to the
1028 <varname>ConditionArchitecture=
</varname>,
1029 <varname>ConditionVirtualization=
</varname>, etc., condition
1030 settings described above, these settings add assertion checks
1031 to the start-up of the unit. However, unlike the conditions
1032 settings, any assertion setting that is not met results in
1033 failure of the start job it was triggered
1034 by.
</para></listitem>
1038 <term><varname>SourcePath=
</varname></term>
1039 <listitem><para>A path to a configuration file this unit has
1040 been generated from. This is primarily useful for
1041 implementation of generator tools that convert configuration
1042 from an external configuration file format into native unit
1043 files. This functionality should not be used in normal
1044 units.
</para></listitem>
1052 <title>[Install] Section Options
</title>
1054 <para>Unit file may include an
<literal>[Install]
</literal>
1055 section, which carries installation information for the unit. This
1056 section is not interpreted by
1057 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1058 during runtime. It is used exclusively by the
1059 <command>enable
</command> and
<command>disable
</command> commands
1061 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1062 tool during installation of a unit:
</para>
1064 <variablelist class='unit-directives'
>
1066 <term><varname>Alias=
</varname></term>
1068 <listitem><para>A space-separated list of additional names
1069 this unit shall be installed under. The names listed here must
1070 have the same suffix (i.e. type) as the unit file name. This
1071 option may be specified more than once, in which case all
1072 listed names are used. At installation time,
1073 <command>systemctl enable
</command> will create symlinks from
1074 these names to the unit filename.
</para></listitem>
1078 <term><varname>WantedBy=
</varname></term>
1079 <term><varname>RequiredBy=
</varname></term>
1081 <listitem><para>This option may be used more than once, or a
1082 space-separated list of unit names may be given. A symbolic
1083 link is created in the
<filename>.wants/
</filename> or
1084 <filename>.requires/
</filename> directory of each of the
1085 listed units when this unit is installed by
<command>systemctl
1086 enable
</command>. This has the effect that a dependency of
1087 type
<varname>Wants=
</varname> or
<varname>Requires=
</varname>
1088 is added from the listed unit to the current unit. The primary
1089 result is that the current unit will be started when the
1090 listed unit is started. See the description of
1091 <varname>Wants=
</varname> and
<varname>Requires=
</varname> in
1092 the [Unit] section for details.
</para>
1094 <para><command>WantedBy=foo.service
</command> in a service
1095 <filename>bar.service
</filename> is mostly equivalent to
1096 <command>Alias=foo.service.wants/bar.service
</command> in the
1097 same file. In case of template units,
<command>systemctl
1098 enable
</command> must be called with an instance name, and
1099 this instance will be added to the
1100 <filename>.wants/
</filename> or
1101 <filename>.requires/
</filename> list of the listed unit. E.g.
1102 <command>WantedBy=getty.target
</command> in a service
1103 <filename>getty@.service
</filename> will result in
1104 <command>systemctl enable getty@tty2.service
</command>
1106 <filename>getty.target.wants/getty@tty2.service
</filename>
1107 link to
<filename>getty@.service
</filename>.
1112 <term><varname>Also=
</varname></term>
1114 <listitem><para>Additional units to install/deinstall when
1115 this unit is installed/deinstalled. If the user requests
1116 installation/deinstallation of a unit with this option
1117 configured,
<command>systemctl enable
</command> and
1118 <command>systemctl disable
</command> will automatically
1119 install/uninstall units listed in this option as well.
</para>
1121 <para>This option may be used more than once, or a
1122 space-separated list of unit names may be
1123 given.
</para></listitem>
1127 <term><varname>DefaultInstance=
</varname></term>
1129 <listitem><para>In template unit files, this specifies for
1130 which instance the unit shall be enabled if the template is
1131 enabled without any explicitly set instance. This option has
1132 no effect in non-template unit files. The specified string
1133 must be usable as instance identifier.
</para></listitem>
1137 <para>The following specifiers are interpreted in the Install
1138 section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning
1139 see the next section.
1144 <title>Specifiers
</title>
1146 <para>Many settings resolve specifiers which may be used to write
1147 generic unit files referring to runtime or unit parameters that
1148 are replaced when the unit files are loaded. The following
1149 specifiers are understood:
</para>
1152 <title>Specifiers available in unit files
</title>
1153 <tgroup cols='
3' align='left' colsep='
1' rowsep='
1'
>
1154 <colspec colname=
"spec" />
1155 <colspec colname=
"mean" />
1156 <colspec colname=
"detail" />
1159 <entry>Specifier
</entry>
1160 <entry>Meaning
</entry>
1161 <entry>Details
</entry>
1166 <entry><literal>%n
</literal></entry>
1167 <entry>Full unit name
</entry>
1171 <entry><literal>%N
</literal></entry>
1172 <entry>Unescaped full unit name
</entry>
1173 <entry>Same as
<literal>%n
</literal>, but with escaping undone
</entry>
1176 <entry><literal>%p
</literal></entry>
1177 <entry>Prefix name
</entry>
1178 <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>
1181 <entry><literal>%P
</literal></entry>
1182 <entry>Unescaped prefix name
</entry>
1183 <entry>Same as
<literal>%p
</literal>, but with escaping undone
</entry>
1186 <entry><literal>%i
</literal></entry>
1187 <entry>Instance name
</entry>
1188 <entry>For instantiated units: this is the string between the
<literal>@
</literal> character and the suffix of the unit name.
</entry>
1191 <entry><literal>%I
</literal></entry>
1192 <entry>Unescaped instance name
</entry>
1193 <entry>Same as
<literal>%i
</literal>, but with escaping undone
</entry>
1196 <entry><literal>%f
</literal></entry>
1197 <entry>Unescaped filename
</entry>
1198 <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>
1201 <entry><literal>%c
</literal></entry>
1202 <entry>Control group path of the unit
</entry>
1203 <entry>This path does not include the
<filename>/sys/fs/cgroup/systemd/
</filename> prefix.
</entry>
1206 <entry><literal>%r
</literal></entry>
1207 <entry>Control group path of the slice the unit is placed in
</entry>
1208 <entry>This usually maps to the parent cgroup path of
<literal>%c
</literal>.
</entry>
1211 <entry><literal>%R
</literal></entry>
1212 <entry>Root control group path below which slices and units are placed
</entry>
1213 <entry>For system instances, this resolves to
<filename>/
</filename>, except in containers, where this maps to the container's root control group path.
</entry>
1216 <entry><literal>%t
</literal></entry>
1217 <entry>Runtime directory
</entry>
1218 <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>
1221 <entry><literal>%u
</literal></entry>
1222 <entry>User name
</entry>
1223 <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>
1226 <entry><literal>%U
</literal></entry>
1227 <entry>User UID
</entry>
1228 <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>
1231 <entry><literal>%h
</literal></entry>
1232 <entry>User home directory
</entry>
1233 <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>
1236 <entry><literal>%s
</literal></entry>
1237 <entry>User shell
</entry>
1238 <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>
1241 <entry><literal>%m
</literal></entry>
1242 <entry>Machine ID
</entry>
1243 <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>
1246 <entry><literal>%b
</literal></entry>
1247 <entry>Boot ID
</entry>
1248 <entry>The boot ID of the running system, formatted as string. See
<citerefentry><refentrytitle>random
</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.
</entry>
1251 <entry><literal>%H
</literal></entry>
1252 <entry>Host name
</entry>
1253 <entry>The hostname of the running system at the point in time the unit configuration is loaded.
</entry>
1256 <entry><literal>%v
</literal></entry>
1257 <entry>Kernel release
</entry>
1258 <entry>Identical to
<command>uname -r
</command> output
</entry>
1261 <entry><literal>%%
</literal></entry>
1262 <entry>Single percent sign
</entry>
1263 <entry>Use
<literal>%%
</literal> in place of
<literal>%
</literal> to specify a single percent sign.
</entry>
1269 <para>Please note that specifiers
<literal>%U
</literal>,
1270 <literal>%h
</literal>,
<literal>%s
</literal> are mostly useless
1271 when systemd is running in system mode. PID
1 cannot query the
1272 user account database for information, so the specifiers only work
1273 as shortcuts for things which are already specified in a different
1274 way in the unit file. They are fully functional when systemd is
1275 running in
<option>--user
</option> mode.
</para>
1279 <title>Examples
</title>
1282 <title>Allowing units to be enabled
</title>
1284 <para>The following snippet (highlighted) allows a unit (e.g.
1285 <filename>foo.service
</filename>) to be enabled via
1286 <command>systemctl enable
</command>:
</para>
1288 <programlisting>[Unit]
1292 ExecStart=/usr/sbin/foo-daemon
1294 <emphasis>[Install]
</emphasis>
1295 <emphasis>WantedBy=multi-user.target
</emphasis></programlisting>
1297 <para>After running
<command>systemctl enable
</command>, a
1299 <filename>/etc/systemd/system/multi-user.target.wants/foo.service
</filename>
1300 linking to the actual unit will be created. It tells systemd to
1301 pull in the unit when starting
1302 <filename>multi-user.target
</filename>. The inverse
1303 <command>systemctl disable
</command> will remove that symlink
1308 <title>Overriding vendor settings
</title>
1310 <para>There are two methods of overriding vendor settings in
1311 unit files: copying the unit file from
1312 <filename>/usr/lib/systemd/system
</filename> to
1313 <filename>/etc/systemd/system
</filename> and modifying the
1314 chosen settings. Alternatively, one can create a directory named
1315 <filename><replaceable>unit
</replaceable>.d/
</filename> within
1316 <filename>/etc/systemd/system
</filename> and place a drop-in
1317 file
<filename><replaceable>name
</replaceable>.conf
</filename>
1318 there that only changes the specific settings one is interested
1319 in. Note that multiple such drop-in files are read if
1322 <para>The advantage of the first method is that one easily
1323 overrides the complete unit, the vendor unit is not parsed at
1324 all anymore. It has the disadvantage that improvements to the
1325 unit file by the vendor are not automatically incorporated on
1328 <para>The advantage of the second method is that one only
1329 overrides the settings one specifically wants, where updates to
1330 the unit by the vendor automatically apply. This has the
1331 disadvantage that some future updates by the vendor might be
1332 incompatible with the local changes.
</para>
1334 <para>Note that for drop-in files, if one wants to remove
1335 entries from a setting that is parsed as a list (and is not a
1336 dependency), such as
<varname>ConditionPathExists=
</varname> (or
1337 e.g.
<varname>ExecStart=
</varname> in service units), one needs
1338 to first clear the list before re-adding all entries except the
1339 one that is to be removed. See below for an example.
</para>
1341 <para>This also applies for user instances of systemd, but with
1342 different locations for the unit files. See the section on unit
1343 load paths for further details.
</para>
1345 <para>Suppose there is a vendor-supplied unit
1346 <filename>/usr/lib/systemd/system/httpd.service
</filename> with
1347 the following contents:
</para>
1349 <programlisting>[Unit]
1350 Description=Some HTTP server
1351 After=remote-fs.target sqldb.service
1352 Requires=sqldb.service
1353 AssertPathExists=/srv/webserver
1357 ExecStart=/usr/sbin/some-fancy-httpd-server
1361 WantedBy=multi-user.target
</programlisting>
1363 <para>Now one wants to change some settings as an administrator:
1364 firstly, in the local setup,
<filename>/srv/webserver
</filename>
1365 might not exist, because the HTTP server is configured to use
1366 <filename>/srv/www
</filename> instead. Secondly, the local
1367 configuration makes the HTTP server also depend on a memory
1368 cache service,
<filename>memcached.service
</filename>, that
1369 should be pulled in (
<varname>Requires=
</varname>) and also be
1370 ordered appropriately (
<varname>After=
</varname>). Thirdly, in
1371 order to harden the service a bit more, the administrator would
1372 like to set the
<varname>PrivateTmp=
</varname> setting (see
1373 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1374 for details). And lastly, the administrator would like to reset
1375 the niceness of the service to its default value of
0.
</para>
1377 <para>The first possibility is to copy the unit file to
1378 <filename>/etc/systemd/system/httpd.service
</filename> and
1379 change the chosen settings:
</para>
1381 <programlisting>[Unit]
1382 Description=Some HTTP server
1383 After=remote-fs.target sqldb.service
<emphasis>memcached.service
</emphasis>
1384 Requires=sqldb.service
<emphasis>memcached.service
</emphasis>
1385 AssertPathExists=
<emphasis>/srv/www
</emphasis>
1389 ExecStart=/usr/sbin/some-fancy-httpd-server
1390 <emphasis>Nice=
0</emphasis>
1391 <emphasis>PrivateTmp=yes
</emphasis>
1394 WantedBy=multi-user.target
</programlisting>
1396 <para>Alternatively, the administrator could create a drop-in
1398 <filename>/etc/systemd/system/httpd.service.d/local.conf
</filename>
1399 with the following contents:
</para>
1401 <programlisting>[Unit]
1402 After=memcached.service
1403 Requires=memcached.service
1404 # Reset all assertions and then re-add the condition we want
1406 AssertPathExists=/srv/www
1410 PrivateTmp=yes
</programlisting>
1412 <para>Note that dependencies (
<varname>After=
</varname>, etc.)
1413 cannot be reset to an empty list, so dependencies can only be
1414 added in drop-ins. If you want to remove dependencies, you have
1415 to override the entire unit.
</para>
1421 <title>See Also
</title>
1423 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1424 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1425 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1426 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1427 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1428 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1429 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1430 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1431 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1432 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1433 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1434 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1435 <citerefentry><refentrytitle>systemd.scope
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1436 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1437 <citerefentry><refentrytitle>systemd.time
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1438 <citerefentry><refentrytitle>systemd-analyze
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1439 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1440 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1441 <citerefentry project='man-pages'
><refentrytitle>uname
</refentrytitle><manvolnum>1</manvolnum></citerefentry>