1 <?xml version='
1.0'
?> <!--*-nxml-*-->
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>snapshot
</replaceable>.snapshot
</filename>,
64 <filename><replaceable>slice
</replaceable>.slice
</filename>,
65 <filename><replaceable>scope
</replaceable>.scope
</filename></para>
67 <para><literallayout><filename>/etc/systemd/system/*
</filename>
68 <filename>/run/systemd/system/*
</filename>
69 <filename>/usr/lib/systemd/system/*
</filename>
70 <filename>...
</filename>
71 </literallayout></para>
73 <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*
</filename>
74 <filename>$HOME/.config/systemd/user/*
</filename>
75 <filename>/etc/systemd/user/*
</filename>
76 <filename>$XDG_RUNTIME_DIR/systemd/user/*
</filename>
77 <filename>/run/systemd/user/*
</filename>
78 <filename>$XDG_DATA_HOME/systemd/user/*
</filename>
79 <filename>$HOME/.local/share/systemd/user/*
</filename>
80 <filename>/usr/lib/systemd/user/*
</filename>
81 <filename>...
</filename>
82 </literallayout></para>
86 <title>Description
</title>
88 <para>A unit configuration file encodes information about a
89 service, a socket, a device, a mount point, an automount point, a
90 swap file or partition, a start-up target, a watched file system
91 path, a timer controlled and supervised by
92 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
93 a temporary system state snapshot, a resource management slice or
94 a group of externally created processes. The syntax is inspired by
96 url=
"http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
97 Desktop Entry Specification
</ulink> <filename>.desktop
</filename>
98 files, which are in turn inspired by Microsoft Windows
99 <filename>.ini
</filename> files.
</para>
101 <para>This man page lists the common configuration options of all
102 the unit types. These options need to be configured in the [Unit]
103 or [Install] sections of the unit files.
</para>
105 <para>In addition to the generic [Unit] and [Install] sections
106 described here, each unit may have a type-specific section, e.g.
107 [Service] for a service unit. See the respective man pages for
109 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
110 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
111 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
112 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
113 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
114 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
115 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
116 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
117 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
118 <citerefentry><refentrytitle>systemd.snapshot
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
119 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
120 <citerefentry><refentrytitle>systemd.scope
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
123 <para>Various settings are allowed to be specified more than once,
124 in which case the interpretation depends on the setting. Often,
125 multiple settings form a list, and setting to an empty value
126 "resets", which means that previous assignments are ignored. When
127 this is allowed, it is mentioned in the description of the
128 setting. Note that using multiple assignments to the same value
129 makes the unit file incompatible with parsers for the XDG
130 <filename>.desktop
</filename> file format.
</para>
132 <para>Unit files are loaded from a set of paths determined during
133 compilation, described in the next section.
</para>
135 <para>Unit files may contain additional options on top of those
136 listed here. If systemd encounters an unknown option, it will
137 write a warning log message but continue loading the unit. If an
138 option or section name is prefixed with
<option>X-
</option>, it is
139 ignored completely by systemd. Options within an ignored section
140 do not need the prefix. Applications may use this to include
141 additional information in the unit files.
</para>
143 <para>Boolean arguments used in unit files can be written in
144 various formats. For positive settings the strings
145 <option>1</option>,
<option>yes
</option>,
<option>true
</option>
146 and
<option>on
</option> are equivalent. For negative settings, the
147 strings
<option>0</option>,
<option>no
</option>,
148 <option>false
</option> and
<option>off
</option> are
151 <para>Time span values encoded in unit files can be written in
152 various formats. A stand-alone number specifies a time in seconds.
153 If suffixed with a time unit, the unit is honored. A concatenation
154 of multiple values with units is supported, in which case the
155 values are added up. Example:
"50" refers to
50 seconds;
"2min
156 200ms" refers to
2 minutes plus
200 milliseconds, i.e.
120200ms.
157 The following time units are understood: s, min, h, d, w, ms, us.
159 <citerefentry><refentrytitle>systemd.time
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
161 <para>Empty lines and lines starting with # or ; are
162 ignored. This may be used for commenting. Lines ending
163 in a backslash are concatenated with the following
164 line while reading and the backslash is replaced by a
165 space character. This may be used to wrap long lines.
</para>
167 <para>Along with a unit file
<filename>foo.service
</filename>, the
168 directory
<filename>foo.service.wants/
</filename> may exist. All
169 unit files symlinked from such a directory are implicitly added as
170 dependencies of type
<varname>Wants=
</varname> to the unit. This
171 is useful to hook units into the start-up of other units, without
172 having to modify their unit files. For details about the semantics
173 of
<varname>Wants=
</varname>, see below. The preferred way to
174 create symlinks in the
<filename>.wants/
</filename> directory of a
175 unit file is with the
<command>enable
</command> command of the
176 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
177 tool which reads information from the [Install] section of unit
178 files (see below). A similar functionality exists for
179 <varname>Requires=
</varname> type dependencies as well, the
180 directory suffix is
<filename>.requires/
</filename> in this
183 <para>Along with a unit file
<filename>foo.service
</filename>, a
184 directory
<filename>foo.service.d/
</filename> may exist. All files
185 with the suffix
<literal>.conf
</literal> from this directory will
186 be parsed after the file itself is parsed. This is useful to alter
187 or add configuration settings to a unit, without having to modify
188 their unit files. Make sure that the file that is included has the
189 appropriate section headers before any directive. Note that for
190 instanced units this logic will first look for the instance
191 <literal>.d/
</literal> subdirectory and read its
192 <literal>.conf
</literal> files, followed by the template
193 <literal>.d/
</literal> subdirectory and reads its
194 <literal>.conf
</literal> files.
</para>
196 <!-- Note that we do not document .include here, as we
197 consider it mostly obsolete, and want people to
198 use .d/ drop-ins instead. -->
200 <para>Note that while systemd offers a flexible dependency system
201 between units it is recommended to use this functionality only
202 sparingly and instead rely on techniques such as bus-based or
203 socket-based activation which make dependencies implicit,
204 resulting in a both simpler and more flexible system.
</para>
206 <para>Some unit names reflect paths existing in the file system
207 namespace. Example: a device unit
208 <filename>dev-sda.device
</filename> refers to a device with the
209 device node
<filename noindex='true'
>/dev/sda
</filename> in the
210 file system namespace. If this applies, a special way to escape
211 the path name is used, so that the result is usable as part of a
212 filename. Basically, given a path,
"/" is replaced by
"-" and all
213 other characters which are not ASCII alphanumerics are replaced by
214 C-style
"\x2d" escapes (except that
"_" is never replaced and
"."
215 is only replaced when it would be the first character in the
216 escaped path). The root directory
"/" is encoded as single dash,
217 while otherwise the initial and ending
"/" are removed from all
218 paths during transformation. This escaping is reversible. Properly
219 escaped paths can be generated using the
220 <citerefentry><refentrytitle>systemd-escape
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
223 <para>Optionally, units may be instantiated from a
224 template file at runtime. This allows creation of
225 multiple units from a single configuration file. If
226 systemd looks for a unit configuration file, it will
227 first search for the literal unit name in the
228 file system. If that yields no success and the unit
229 name contains an
<literal>@
</literal> character, systemd will look for a
230 unit template that shares the same name but with the
231 instance string (i.e. the part between the
<literal>@
</literal> character
232 and the suffix) removed. Example: if a service
233 <filename>getty@tty3.service
</filename> is requested
234 and no file by that name is found, systemd will look
235 for
<filename>getty@.service
</filename> and
236 instantiate a service from that configuration file if
239 <para>To refer to the instance string from within the
240 configuration file you may use the special
<literal>%i
</literal>
241 specifier in many of the configuration options. See below for
244 <para>If a unit file is empty (i.e. has the file size
0) or is
245 symlinked to
<filename>/dev/null
</filename>, its configuration
246 will not be loaded and it appears with a load state of
247 <literal>masked
</literal>, and cannot be activated. Use this as an
248 effective way to fully disable a unit, making it impossible to
249 start it even manually.
</para>
251 <para>The unit file format is covered by the
253 url=
"http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
254 Stability Promise
</ulink>.
</para>
259 <title>Unit Load Path
</title>
261 <para>Unit files are loaded from a set of paths determined during
262 compilation, described in the two tables below. Unit files found
263 in directories listed earlier override files with the same name in
264 directories lower in the list.
</para>
266 <para>When systemd is running in user mode
267 (
<option>--user
</option>) and the variable
268 <varname>$SYSTEMD_UNIT_PATH
</varname> is set, the contents of this
269 variable overrides the unit load path. If
270 <varname>$SYSTEMD_UNIT_PATH
</varname> ends with an empty component
271 (
<literal>:
</literal>), the usual unit load path will be appended
272 to the contents of the variable.
</para>
276 Load path when running in system mode (
<option>--system
</option>).
280 <colspec colname='path'
/>
281 <colspec colname='expl'
/>
285 <entry>Description
</entry>
290 <entry><filename>/etc/systemd/system
</filename></entry>
291 <entry>Local configuration
</entry>
294 <entry><filename>/run/systemd/system
</filename></entry>
295 <entry>Runtime units
</entry>
298 <entry><filename>/usr/lib/systemd/system
</filename></entry>
299 <entry>Units of installed packages
</entry>
307 Load path when running in user mode (
<option>--user
</option>).
311 <colspec colname='path'
/>
312 <colspec colname='expl'
/>
316 <entry>Description
</entry>
321 <entry><filename>$XDG_CONFIG_HOME/systemd/user
</filename></entry>
322 <entry>User configuration (only used when $XDG_CONFIG_HOME is set)
</entry>
325 <entry><filename>$HOME/.config/systemd/user
</filename></entry>
326 <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)
</entry>
329 <entry><filename>/etc/systemd/user
</filename></entry>
330 <entry>Local configuration
</entry>
333 <entry><filename>$XDG_RUNTIME_DIR/systemd/user
</filename></entry>
334 <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)
</entry>
337 <entry><filename>/run/systemd/user
</filename></entry>
338 <entry>Runtime units
</entry>
341 <entry><filename>$XDG_DATA_HOME/systemd/user
</filename></entry>
342 <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)
</entry>
345 <entry><filename>$HOME/.local/share/systemd/user
</filename></entry>
346 <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)
</entry>
349 <entry><filename>/usr/lib/systemd/user
</filename></entry>
350 <entry>Units of packages that have been installed system-wide
</entry>
356 <para>Additional units might be loaded into systemd (
"linked")
357 from directories not on the unit load path. See the
358 <command>link
</command> command for
359 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
360 Also, some units are dynamically created via generators
<ulink
361 url=
"http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators
</ulink>.
366 <title>[Unit] Section Options
</title>
368 <para>Unit file may include a [Unit] section, which carries
369 generic information about the unit that is not dependent on the
372 <variablelist class='unit-directives'
>
375 <term><varname>Description=
</varname></term>
376 <listitem><para>A free-form string describing the unit. This
377 is intended for use in UIs to show descriptive information
378 along with the unit name. The description should contain a
379 name that means something to the end user.
<literal>Apache2
380 Web Server
</literal> is a good example. Bad examples are
381 <literal>high-performance light-weight HTTP server
</literal>
382 (too generic) or
<literal>Apache2
</literal> (too specific and
383 meaningless for people who do not know
384 Apache).
</para></listitem>
388 <term><varname>Documentation=
</varname></term>
389 <listitem><para>A space-separated list of URIs referencing
390 documentation for this unit or its configuration. Accepted are
391 only URIs of the types
<literal>http://
</literal>,
392 <literal>https://
</literal>,
<literal>file:
</literal>,
393 <literal>info:
</literal>,
<literal>man:
</literal>. For more
394 information about the syntax of these URIs, see
<citerefentry
395 project='man-pages'
><refentrytitle>uri
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
396 The URIs should be listed in order of relevance, starting with
397 the most relevant. It is a good idea to first reference
398 documentation that explains what the unit's purpose is,
399 followed by how it is configured, followed by any other
400 related documentation. This option may be specified more than
401 once, in which case the specified list of URIs is merged. If
402 the empty string is assigned to this option, the list is reset
403 and all prior assignments will have no
404 effect.
</para></listitem>
408 <term><varname>Requires=
</varname></term>
410 <listitem><para>Configures requirement dependencies on other
411 units. If this unit gets activated, the units listed here will
412 be activated as well. If one of the other units gets
413 deactivated or its activation fails, this unit will be
414 deactivated. This option may be specified more than once or
415 multiple space-separated units may be specified in one option
416 in which case requirement dependencies for all listed names
417 will be created. Note that requirement dependencies do not
418 influence the order in which services are started or stopped.
419 This has to be configured independently with the
420 <varname>After=
</varname> or
<varname>Before=
</varname>
421 options. If a unit
<filename>foo.service
</filename> requires a
422 unit
<filename>bar.service
</filename> as configured with
423 <varname>Requires=
</varname> and no ordering is configured
424 with
<varname>After=
</varname> or
<varname>Before=
</varname>,
425 then both units will be started simultaneously and without any
426 delay between them if
<filename>foo.service
</filename> is
427 activated. Often it is a better choice to use
428 <varname>Wants=
</varname> instead of
429 <varname>Requires=
</varname> in order to achieve a system that
430 is more robust when dealing with failing services.
</para>
432 <para>Note that dependencies of this type may also be
433 configured outside of the unit configuration file by adding a
434 symlink to a
<filename>.requires/
</filename> directory
435 accompanying the unit file. For details see
436 above.
</para></listitem>
440 <term><varname>RequiresOverridable=
</varname></term>
442 <listitem><para>Similar to
<varname>Requires=
</varname>.
443 Dependencies listed in
<varname>RequiresOverridable=
</varname>
444 which cannot be fulfilled or fail to start are ignored if the
445 startup was explicitly requested by the user. If the start-up
446 was pulled in indirectly by some dependency or automatic
447 start-up of units that is not requested by the user, this
448 dependency must be fulfilled and otherwise the transaction
449 fails. Hence, this option may be used to configure
450 dependencies that are normally honored unless the user
451 explicitly starts up the unit, in which case whether they
452 failed or not is irrelevant.
</para></listitem>
456 <term><varname>Requisite=
</varname></term>
457 <term><varname>RequisiteOverridable=
</varname></term>
459 <listitem><para>Similar to
<varname>Requires=
</varname> and
460 <varname>RequiresOverridable=
</varname>, respectively.
461 However, if the units listed here are not started already,
462 they will not be started and the transaction will fail
463 immediately.
</para></listitem>
467 <term><varname>Wants=
</varname></term>
469 <listitem><para>A weaker version of
470 <varname>Requires=
</varname>. Units listed in this option will
471 be started if the configuring unit is. However, if the listed
472 units fail to start or cannot be added to the transaction,
473 this has no impact on the validity of the transaction as a
474 whole. This is the recommended way to hook start-up of one
475 unit to the start-up of another unit.
</para>
477 <para>Note that dependencies of this type may also be
478 configured outside of the unit configuration file by adding
479 symlinks to a
<filename>.wants/
</filename> directory
480 accompanying the unit file. For details, see
481 above.
</para></listitem>
485 <term><varname>BindsTo=
</varname></term>
487 <listitem><para>Configures requirement dependencies, very
488 similar in style to
<varname>Requires=
</varname>, however in
489 addition to this behavior, it also declares that this unit is
490 stopped when any of the units listed suddenly disappears.
491 Units can suddenly, unexpectedly disappear if a service
492 terminates on its own choice, a device is unplugged or a mount
493 point unmounted without involvement of
494 systemd.
</para></listitem>
498 <term><varname>PartOf=
</varname></term>
500 <listitem><para>Configures dependencies similar to
501 <varname>Requires=
</varname>, but limited to stopping and
502 restarting of units. When systemd stops or restarts the units
503 listed here, the action is propagated to this unit. Note that
504 this is a one-way dependency — changes to this unit do not
505 affect the listed units.
</para></listitem>
509 <term><varname>Conflicts=
</varname></term>
511 <listitem><para>A space-separated list of unit names.
512 Configures negative requirement dependencies. If a unit has a
513 <varname>Conflicts=
</varname> setting on another unit,
514 starting the former will stop the latter and vice versa. Note
515 that this setting is independent of and orthogonal to the
516 <varname>After=
</varname> and
<varname>Before=
</varname>
517 ordering dependencies.
</para>
519 <para>If a unit A that conflicts with a unit B is scheduled to
520 be started at the same time as B, the transaction will either
521 fail (in case both are required part of the transaction) or be
522 modified to be fixed (in case one or both jobs are not a
523 required part of the transaction). In the latter case, the job
524 that is not the required will be removed, or in case both are
525 not required, the unit that conflicts will be started and the
526 unit that is conflicted is stopped.
</para></listitem>
530 <term><varname>Before=
</varname></term>
531 <term><varname>After=
</varname></term>
533 <listitem><para>A space-separated list of unit names.
534 Configures ordering dependencies between units. If a unit
535 <filename>foo.service
</filename> contains a setting
536 <option>Before=bar.service
</option> and both units are being
537 started,
<filename>bar.service
</filename>'s start-up is
538 delayed until
<filename>foo.service
</filename> is started up.
539 Note that this setting is independent of and orthogonal to the
540 requirement dependencies as configured by
541 <varname>Requires=
</varname>. It is a common pattern to
542 include a unit name in both the
<varname>After=
</varname> and
543 <varname>Requires=
</varname> option, in which case the unit
544 listed will be started before the unit that is configured with
545 these options. This option may be specified more than once, in
546 which case ordering dependencies for all listed names are
547 created.
<varname>After=
</varname> is the inverse of
548 <varname>Before=
</varname>, i.e. while
549 <varname>After=
</varname> ensures that the configured unit is
550 started after the listed unit finished starting up,
551 <varname>Before=
</varname> ensures the opposite, i.e. that the
552 configured unit is fully started up before the listed unit is
553 started. Note that when two units with an ordering dependency
554 between them are shut down, the inverse of the start-up order
555 is applied. i.e. if a unit is configured with
556 <varname>After=
</varname> on another unit, the former is
557 stopped before the latter if both are shut down. If one unit
558 with an ordering dependency on another unit is shut down while
559 the latter is started up, the shut down is ordered before the
560 start-up regardless of whether the ordering dependency is
561 actually of type
<varname>After=
</varname> or
562 <varname>Before=
</varname>. If two units have no ordering
563 dependencies between them, they are shut down or started up
564 simultaneously, and no ordering takes place.
569 <term><varname>OnFailure=
</varname></term>
571 <listitem><para>A space-separated list of one or more units
572 that are activated when this unit enters the
573 <literal>failed
</literal> state.
</para></listitem>
577 <term><varname>PropagatesReloadTo=
</varname></term>
578 <term><varname>ReloadPropagatedFrom=
</varname></term>
580 <listitem><para>A space-separated list of one or more units
581 where reload requests on this unit will be propagated to, or
582 reload requests on the other unit will be propagated to this
583 unit, respectively. Issuing a reload request on a unit will
584 automatically also enqueue a reload request on all units that
585 the reload request shall be propagated to via these two
586 settings.
</para></listitem>
590 <term><varname>JoinsNamespaceOf=
</varname></term>
592 <listitem><para>For units that start processes (such as
593 service units), lists one or more other units whose network
594 and/or temporary file namespace to join. This only applies to
595 unit types which support the
596 <varname>PrivateNetwork=
</varname> and
597 <varname>PrivateTmp=
</varname> directives (see
598 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
599 for details). If a unit that has this setting set is started,
600 its processes will see the same
<filename>/tmp
</filename>,
601 <filename>/tmp/var
</filename> and network namespace as one
602 listed unit that is started. If multiple listed units are
603 already started, it is not defined which namespace is joined.
604 Note that this setting only has an effect if
605 <varname>PrivateNetwork=
</varname> and/or
606 <varname>PrivateTmp=
</varname> is enabled for both the unit
607 that joins the namespace and the unit whose namespace is
608 joined.
</para></listitem>
612 <term><varname>RequiresMountsFor=
</varname></term>
614 <listitem><para>Takes a space-separated list of absolute
615 paths. Automatically adds dependencies of type
616 <varname>Requires=
</varname> and
<varname>After=
</varname> for
617 all mount units required to access the specified path.
</para>
619 <para>Mount points marked with
<option>noauto
</option> are not
620 mounted automatically and will be ignored for the purposes of
621 this option. If such a mount should be a requirement for this
622 unit, direct dependencies on the mount units may be added
623 (
<varname>Requires=
</varname> and
<varname>After=
</varname> or
624 some other combination).
</para></listitem>
628 <term><varname>OnFailureJobMode=
</varname></term>
630 <listitem><para>Takes a value of
631 <literal>fail
</literal>,
632 <literal>replace
</literal>,
633 <literal>replace-irreversibly
</literal>,
634 <literal>isolate
</literal>,
635 <literal>flush
</literal>,
636 <literal>ignore-dependencies
</literal> or
637 <literal>ignore-requirements
</literal>. Defaults to
638 <literal>replace
</literal>. Specifies how the units listed in
639 <varname>OnFailure=
</varname> will be enqueued. See
640 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
641 <option>--job-mode=
</option> option for details on the
642 possible values. If this is set to
<literal>isolate
</literal>,
643 only a single unit may be listed in
644 <varname>OnFailure=
</varname>..
</para></listitem>
648 <term><varname>IgnoreOnIsolate=
</varname></term>
650 <listitem><para>Takes a boolean argument. If
651 <option>true
</option>, this unit will not be stopped when
652 isolating another unit. Defaults to
653 <option>false
</option>.
</para></listitem>
657 <term><varname>IgnoreOnSnapshot=
</varname></term>
659 <listitem><para>Takes a boolean argument. If
660 <option>true
</option>, this unit will not be included in
661 snapshots. Defaults to
<option>true
</option> for device and
662 snapshot units,
<option>false
</option> for the
663 others.
</para></listitem>
667 <term><varname>StopWhenUnneeded=
</varname></term>
669 <listitem><para>Takes a boolean argument. If
670 <option>true
</option>, this unit will be stopped when it is no
671 longer used. Note that in order to minimize the work to be
672 executed, systemd will not stop units by default unless they
673 are conflicting with other units, or the user explicitly
674 requested their shut down. If this option is set, a unit will
675 be automatically cleaned up if no other active unit requires
676 it. Defaults to
<option>false
</option>.
</para></listitem>
680 <term><varname>RefuseManualStart=
</varname></term>
681 <term><varname>RefuseManualStop=
</varname></term>
683 <listitem><para>Takes a boolean argument. If
684 <option>true
</option>, this unit can only be activated or
685 deactivated indirectly. In this case, explicit start-up or
686 termination requested by the user is denied, however if it is
687 started or stopped as a dependency of another unit, start-up
688 or termination will succeed. This is mostly a safety feature
689 to ensure that the user does not accidentally activate units
690 that are not intended to be activated explicitly, and not
691 accidentally deactivate units that are not intended to be
692 deactivated. These options default to
693 <option>false
</option>.
</para></listitem>
697 <term><varname>AllowIsolate=
</varname></term>
699 <listitem><para>Takes a boolean argument. If
700 <option>true
</option>, this unit may be used with the
701 <command>systemctl isolate
</command> command. Otherwise, this
702 will be refused. It probably is a good idea to leave this
703 disabled except for target units that shall be used similar to
704 runlevels in SysV init systems, just as a precaution to avoid
705 unusable system states. This option defaults to
706 <option>false
</option>.
</para></listitem>
710 <term><varname>DefaultDependencies=
</varname></term>
712 <listitem><para>Takes a boolean argument. If
713 <option>true
</option>, (the default), a few default
714 dependencies will implicitly be created for the unit. The
715 actual dependencies created depend on the unit type. For
716 example, for service units, these dependencies ensure that the
717 service is started only after basic system initialization is
718 completed and is properly terminated on system shutdown. See
719 the respective man pages for details. Generally, only services
720 involved with early boot or late shutdown should set this
721 option to
<option>false
</option>. It is highly recommended to
722 leave this option enabled for the majority of common units. If
723 set to
<option>false
</option>, this option does not disable
724 all implicit dependencies, just non-essential
725 ones.
</para></listitem>
729 <term><varname>JobTimeoutSec=
</varname></term>
730 <term><varname>JobTimeoutAction=
</varname></term>
731 <term><varname>JobTimeoutRebootArgument=
</varname></term>
733 <listitem><para>When a job for this unit is queued a time-out
734 may be configured. If this time limit is reached, the job will
735 be cancelled, the unit however will not change state or even
736 enter the
<literal>failed
</literal> mode. This value defaults
737 to
0 (job timeouts disabled), except for device units. NB:
738 this timeout is independent from any unit-specific timeout
739 (for example, the timeout set with
740 <varname>StartTimeoutSec=
</varname> in service units) as the
741 job timeout has no effect on the unit itself, only on the job
742 that might be pending for it. Or in other words: unit-specific
743 timeouts are useful to abort unit state changes, and revert
744 them. The job timeout set with this option however is useful
745 to abort only the job waiting for the unit state to
748 <para><varname>JobTimeoutAction=
</varname>
749 optionally configures an additional
750 action to take when the time-out is
751 hit. It takes the same values as the
753 <varname>StartLimitAction=
</varname>
755 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
756 for details. Defaults to
757 <option>none
</option>.
<varname>JobTimeoutRebootArgument=
</varname>
758 configures an optional reboot string
760 <citerefentry><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
761 system call.
</para></listitem>
765 <term><varname>ConditionArchitecture=
</varname></term>
766 <term><varname>ConditionVirtualization=
</varname></term>
767 <term><varname>ConditionHost=
</varname></term>
768 <term><varname>ConditionKernelCommandLine=
</varname></term>
769 <term><varname>ConditionSecurity=
</varname></term>
770 <term><varname>ConditionCapability=
</varname></term>
771 <term><varname>ConditionACPower=
</varname></term>
772 <term><varname>ConditionNeedsUpdate=
</varname></term>
773 <term><varname>ConditionFirstBoot=
</varname></term>
774 <term><varname>ConditionPathExists=
</varname></term>
775 <term><varname>ConditionPathExistsGlob=
</varname></term>
776 <term><varname>ConditionPathIsDirectory=
</varname></term>
777 <term><varname>ConditionPathIsSymbolicLink=
</varname></term>
778 <term><varname>ConditionPathIsMountPoint=
</varname></term>
779 <term><varname>ConditionPathIsReadWrite=
</varname></term>
780 <term><varname>ConditionDirectoryNotEmpty=
</varname></term>
781 <term><varname>ConditionFileNotEmpty=
</varname></term>
782 <term><varname>ConditionFileIsExecutable=
</varname></term>
784 <!-- We don't document ConditionNull=
785 here as it is not particularly
786 useful and probably just
789 <listitem><para>Before starting a unit verify that the
790 specified condition is true. If it is not true, the starting
791 of the unit will be skipped, however all ordering dependencies
792 of it are still respected. A failing condition will not result
793 in the unit being moved into a failure state. The condition is
794 checked at the time the queued start job is to be
797 <para><varname>ConditionArchitecture=
</varname> may be used to
798 check whether the system is running on a specific
799 architecture. Takes one of
800 <varname>x86
</varname>,
801 <varname>x86-
64</varname>,
802 <varname>ppc
</varname>,
803 <varname>ppc-le
</varname>,
804 <varname>ppc64
</varname>,
805 <varname>ppc64-le
</varname>,
806 <varname>ia64
</varname>,
807 <varname>parisc
</varname>,
808 <varname>parisc64
</varname>,
809 <varname>s390
</varname>,
810 <varname>s390x
</varname>,
811 <varname>sparc
</varname>,
812 <varname>sparc64
</varname>,
813 <varname>mips
</varname>,
814 <varname>mips-le
</varname>,
815 <varname>mips64
</varname>,
816 <varname>mips64-le
</varname>,
817 <varname>alpha
</varname>,
818 <varname>arm
</varname>,
819 <varname>arm-be
</varname>,
820 <varname>arm64
</varname>,
821 <varname>arm64-be
</varname>,
822 <varname>sh
</varname>,
823 <varname>sh64
</varname>,
824 <varname>m86k
</varname>,
825 <varname>tilegx
</varname>,
826 <varname>cris
</varname> to test
827 against a specific architecture. The architecture is
828 determined from the information returned by
829 <citerefentry><refentrytitle>uname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
830 and is thus subject to
831 <citerefentry><refentrytitle>personality
</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
832 Note that a
<varname>Personality=
</varname> setting in the
833 same unit file has no effect on this condition. A special
834 architecture name
<varname>native
</varname> is mapped to the
835 architecture the system manager itself is compiled for. The
836 test may be negated by prepending an exclamation mark.
</para>
838 <para><varname>ConditionVirtualization=
</varname> may be used
839 to check whether the system is executed in a virtualized
840 environment and optionally test whether it is a specific
841 implementation. Takes either boolean value to check if being
842 executed in any virtualized environment, or one of
843 <varname>vm
</varname> and
844 <varname>container
</varname> to test against a generic type of
845 virtualization solution, or one of
846 <varname>qemu
</varname>,
847 <varname>kvm
</varname>,
848 <varname>zvm
</varname>,
849 <varname>vmware
</varname>,
850 <varname>microsoft
</varname>,
851 <varname>oracle
</varname>,
852 <varname>xen
</varname>,
853 <varname>bochs
</varname>,
854 <varname>uml
</varname>,
855 <varname>openvz
</varname>,
856 <varname>lxc
</varname>,
857 <varname>lxc-libvirt
</varname>,
858 <varname>systemd-nspawn
</varname>,
859 <varname>docker
</varname> to test
860 against a specific implementation. See
861 <citerefentry><refentrytitle>systemd-detect-virt
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
862 for a full list of known virtualization technologies and their
863 identifiers. If multiple virtualization technologies are
864 nested, only the innermost is considered. The test may be
865 negated by prepending an exclamation mark.
</para>
867 <para><varname>ConditionHost=
</varname> may be used to match
868 against the hostname or machine ID of the host. This either
869 takes a hostname string (optionally with shell style globs)
870 which is tested against the locally set hostname as returned
872 <citerefentry><refentrytitle>gethostname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
873 or a machine ID formatted as string (see
874 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
875 The test may be negated by prepending an exclamation
878 <para><varname>ConditionKernelCommandLine=
</varname> may be
879 used to check whether a specific kernel command line option is
880 set (or if prefixed with the exclamation mark unset). The
881 argument must either be a single word, or an assignment (i.e.
882 two words, separated
<literal>=
</literal>). In the former case
883 the kernel command line is searched for the word appearing as
884 is, or as left hand side of an assignment. In the latter case,
885 the exact assignment is looked for with right and left hand
886 side matching.
</para>
888 <para><varname>ConditionSecurity=
</varname> may be used to
889 check whether the given security module is enabled on the
890 system. Currently the recognized values values are
891 <varname>selinux
</varname>,
892 <varname>apparmor
</varname>,
893 <varname>ima
</varname>,
894 <varname>smack
</varname> and
895 <varname>audit
</varname>. The test may be negated by
896 prepending an exclamation mark.
</para>
898 <para><varname>ConditionCapability=
</varname> may be used to
899 check whether the given capability exists in the capability
900 bounding set of the service manager (i.e. this does not check
901 whether capability is actually available in the permitted or
903 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
904 for details). Pass a capability name such as
905 <literal>CAP_MKNOD
</literal>, possibly prefixed with an
906 exclamation mark to negate the check.
</para>
908 <para><varname>ConditionACPower=
</varname> may be used to
909 check whether the system has AC power, or is exclusively
910 battery powered at the time of activation of the unit. This
911 takes a boolean argument. If set to
<varname>true
</varname>,
912 the condition will hold only if at least one AC connector of
913 the system is connected to a power source, or if no AC
914 connectors are known. Conversely, if set to
915 <varname>false
</varname>, the condition will hold only if
916 there is at least one AC connector known and all AC connectors
917 are disconnected from a power source.
</para>
919 <para><varname>ConditionNeedsUpdate=
</varname> takes one of
920 <filename>/var
</filename> or
<filename>/etc
</filename> as
921 argument, possibly prefixed with a
<literal>!
</literal> (for
922 inverting the condition). This condition may be used to
923 conditionalize units on whether the specified directory
924 requires an update because
<filename>/usr
</filename>'s
925 modification time is newer than the stamp file
926 <filename>.updated
</filename> in the specified directory. This
927 is useful to implement offline updates of the vendor operating
928 system resources in
<filename>/usr
</filename> that require
929 updating of
<filename>/etc
</filename> or
930 <filename>/var
</filename> on the next following boot. Units
931 making use of this condition should order themselves before
932 <citerefentry><refentrytitle>systemd-update-done.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
933 to make sure they run before the stamp files's modification
934 time gets reset indicating a completed update.
</para>
936 <para><varname>ConditionFirstBoot=
</varname> takes a boolean
937 argument. This condition may be used to conditionalize units
938 on whether the system is booting up with an unpopulated
939 <filename>/etc
</filename> directory. This may be used to
940 populate
<filename>/etc
</filename> on the first boot after
941 factory reset, or when a new system instances boots up for the
944 <para>With
<varname>ConditionPathExists=
</varname> a file
945 existence condition is checked before a unit is started. If
946 the specified absolute path name does not exist, the condition
947 will fail. If the absolute path name passed to
948 <varname>ConditionPathExists=
</varname> is prefixed with an
949 exclamation mark (
<literal>!
</literal>), the test is negated,
950 and the unit is only started if the path does not
953 <para><varname>ConditionPathExistsGlob=
</varname> is similar
954 to
<varname>ConditionPathExists=
</varname>, but checks for the
955 existence of at least one file or directory matching the
956 specified globbing pattern.
</para>
958 <para><varname>ConditionPathIsDirectory=
</varname> is similar
959 to
<varname>ConditionPathExists=
</varname> but verifies
960 whether a certain path exists and is a directory.
</para>
962 <para><varname>ConditionPathIsSymbolicLink=
</varname> is
963 similar to
<varname>ConditionPathExists=
</varname> but
964 verifies whether a certain path exists and is a symbolic
967 <para><varname>ConditionPathIsMountPoint=
</varname> is similar
968 to
<varname>ConditionPathExists=
</varname> but verifies
969 whether a certain path exists and is a mount point.
</para>
971 <para><varname>ConditionPathIsReadWrite=
</varname> is similar
972 to
<varname>ConditionPathExists=
</varname> but verifies
973 whether the underlying file system is readable and writable
974 (i.e. not mounted read-only).
</para>
976 <para><varname>ConditionDirectoryNotEmpty=
</varname> is
977 similar to
<varname>ConditionPathExists=
</varname> but
978 verifies whether a certain path exists and is a non-empty
981 <para><varname>ConditionFileNotEmpty=
</varname> is similar to
982 <varname>ConditionPathExists=
</varname> but verifies whether a
983 certain path exists and refers to a regular file with a
984 non-zero size.
</para>
986 <para><varname>ConditionFileIsExecutable=
</varname> is similar
987 to
<varname>ConditionPathExists=
</varname> but verifies
988 whether a certain path exists, is a regular file and marked
991 <para>If multiple conditions are specified, the unit will be
992 executed if all of them apply (i.e. a logical AND is applied).
993 Condition checks can be prefixed with a pipe symbol (|) in
994 which case a condition becomes a triggering condition. If at
995 least one triggering condition is defined for a unit, then the
996 unit will be executed if at least one of the triggering
997 conditions apply and all of the non-triggering conditions. If
998 you prefix an argument with the pipe symbol and an exclamation
999 mark, the pipe symbol must be passed first, the exclamation
1001 <varname>ConditionPathIsSymbolicLink=
</varname>, all path
1002 checks follow symlinks. If any of these options is assigned
1003 the empty string, the list of conditions is reset completely,
1004 all previous condition settings (of any kind) will have no
1005 effect.
</para></listitem>
1009 <term><varname>AssertArchitecture=
</varname></term>
1010 <term><varname>AssertVirtualization=
</varname></term>
1011 <term><varname>AssertHost=
</varname></term>
1012 <term><varname>AssertKernelCommandLine=
</varname></term>
1013 <term><varname>AssertSecurity=
</varname></term>
1014 <term><varname>AssertCapability=
</varname></term>
1015 <term><varname>AssertACPower=
</varname></term>
1016 <term><varname>AssertNeedsUpdate=
</varname></term>
1017 <term><varname>AssertFirstBoot=
</varname></term>
1018 <term><varname>AssertPathExists=
</varname></term>
1019 <term><varname>AssertPathExistsGlob=
</varname></term>
1020 <term><varname>AssertPathIsDirectory=
</varname></term>
1021 <term><varname>AssertPathIsSymbolicLink=
</varname></term>
1022 <term><varname>AssertPathIsMountPoint=
</varname></term>
1023 <term><varname>AssertPathIsReadWrite=
</varname></term>
1024 <term><varname>AssertDirectoryNotEmpty=
</varname></term>
1025 <term><varname>AssertFileNotEmpty=
</varname></term>
1026 <term><varname>AssertFileIsExecutable=
</varname></term>
1028 <listitem><para>Similar to the
1029 <varname>ConditionArchitecture=
</varname>,
1030 <varname>ConditionVirtualization=
</varname>, ... condition
1031 settings described above these settings add assertion checks
1032 to the start-up of the unit. However, unlike the conditions
1033 settings any assertion setting that is not met results in
1034 failure of the start job it was triggered
1035 by.
</para></listitem>
1039 <term><varname>SourcePath=
</varname></term>
1040 <listitem><para>A path to a configuration file this unit has
1041 been generated from. This is primarily useful for
1042 implementation of generator tools that convert configuration
1043 from an external configuration file format into native unit
1044 files. This functionality should not be used in normal
1045 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 configured user of the unit, or (if none is set) the user running the systemd instance.
</entry>
1226 <entry><literal>%U
</literal></entry>
1227 <entry>User UID
</entry>
1228 <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.
</entry>
1231 <entry><literal>%h
</literal></entry>
1232 <entry>User home directory
</entry>
1233 <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to
<literal>%U
</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.
</entry>
1236 <entry><literal>%s
</literal></entry>
1237 <entry>User shell
</entry>
1238 <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to
<literal>%U
</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.
</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 configuation 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>
1420 <title>See Also
</title>
1422 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1423 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1424 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1425 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1426 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1427 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1428 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1429 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1430 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1431 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1432 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1433 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1434 <citerefentry><refentrytitle>systemd.snapshot
</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><refentrytitle>uname
</refentrytitle><manvolnum>1</manvolnum></citerefentry>