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>$HOME/.config/systemd/user/*</filename>
74 <filename>/etc/systemd/user/*</filename>
75 <filename>/run/systemd/user/*</filename>
76 <filename>/usr/lib/systemd/user/*</filename>
77 <filename>...</filename>
78 </literallayout></para>
82 <title>Description</title>
84 <para>A unit configuration file encodes information
85 about a service, a socket, a device, a mount point, an
86 automount point, a swap file or partition, a start-up
87 target, a watched file system path, a timer controlled
89 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
90 a temporary system state snapshot, a resource
91 management slice or a group of externally created
92 processes. The syntax is inspired by <ulink
93 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
94 Desktop Entry Specification</ulink>
95 <filename>.desktop</filename> files, which are in turn
96 inspired by Microsoft Windows
97 <filename>.ini</filename> files.</para>
99 <para>This man page lists the common configuration
100 options of all the unit types. These options need to
101 be configured in the [Unit] or [Install]
102 sections of the unit files.</para>
104 <para>In addition to the generic [Unit] and [Install]
105 sections described here, each unit may have a
106 type-specific section, e.g. [Service] for a service
107 unit. See the respective man pages for more
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>Unit files are loaded from a set of paths
124 determined during compilation, described in the next section.
127 <para>Unit files may contain additional options on top
128 of those listed here. If systemd encounters an unknown
129 option, it will write a warning log message but
130 continue loading the unit. If an option is prefixed
131 with <option>X-</option>, it is ignored completely by
132 systemd. Applications may use this to include
133 additional information in the unit files.</para>
135 <para>Boolean arguments used in unit files can be
136 written in various formats. For positive settings the
137 strings <option>1</option>, <option>yes</option>,
138 <option>true</option> and <option>on</option> are
139 equivalent. For negative settings, the strings
140 <option>0</option>, <option>no</option>,
141 <option>false</option> and <option>off</option> are
144 <para>Time span values encoded in unit files can be
145 written in various formats. A stand-alone number
146 specifies a time in seconds. If suffixed with a time
147 unit, the unit is honored. A concatenation of multiple
148 values with units is supported, in which case the
149 values are added up. Example: "50" refers to 50
150 seconds; "2min 200ms" refers to 2 minutes plus 200
151 milliseconds, i.e. 120200ms. The following time units
152 are understood: s, min, h, d, w, ms, us. For details
154 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
156 <para>Empty lines and lines starting with # or ; are
157 ignored. This may be used for commenting. Lines ending
158 in a backslash are concatenated with the following
159 line while reading and the backslash is replaced by a
160 space character. This may be used to wrap long lines.</para>
162 <para>Along with a unit file
163 <filename>foo.service</filename>, the directory
164 <filename>foo.service.wants/</filename> may exist. All
165 unit files symlinked from such a directory are
166 implicitly added as dependencies of type
167 <varname>Wanted=</varname> to the unit. This is useful
168 to hook units into the start-up of other units,
169 without having to modify their unit files. For details
170 about the semantics of <varname>Wanted=</varname>, see
171 below. The preferred way to create symlinks in the
172 <filename>.wants/</filename> directory of a unit file
173 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]
176 section of unit files (see below). A similar
177 functionality exists for <varname>Requires=</varname>
178 type dependencies as well, the directory suffix is
179 <filename>.requires/</filename> in this case.</para>
181 <para>Along with a unit file
182 <filename>foo.service</filename>, a directory
183 <filename>foo.service.d/</filename> may exist. All
184 files with the suffix <literal>.conf</literal> from
185 this directory will be parsed after the file itself is
186 parsed. This is useful to alter or add configuration
187 settings to a unit, without having to modify their
188 unit files. Make sure that the file that is included
189 has the appropriate section headers before any
192 <para>If a line starts with <option>.include</option>
193 followed by a filename, the specified file will be
194 parsed at this point. Make sure that the file that is
195 included has the appropriate section headers before
196 any directives.</para>
198 <para>Note that while systemd offers a flexible
199 dependency system between units it is recommended to
200 use this functionality only sparingly and instead rely
201 on techniques such as bus-based or socket-based
202 activation which make dependencies implicit, resulting
203 in a both simpler and more flexible system.</para>
205 <para>Some unit names reflect paths existing in the
206 file system namespace. Example: a device unit
207 <filename>dev-sda.device</filename> refers to a device
208 with the device node <filename noindex='true'>/dev/sda</filename> in
209 the file system namespace. If this applies, a special
210 way to escape the path name is used, so that the
211 result is usable as part of a filename. Basically,
212 given a path, "/" is replaced by "-", and all
213 unprintable characters and the "-" are replaced by
214 C-style "\x20" escapes. The root directory "/" is
215 encoded as single dash, while otherwise the initial
216 and ending "/" is removed from all paths during
217 transformation. This escaping is reversible.</para>
219 <para>Optionally, units may be instantiated from a
220 template file at runtime. This allows creation of
221 multiple units from a single configuration file. If
222 systemd looks for a unit configuration file, it will
223 first search for the literal unit name in the
224 filesystem. If that yields no success and the unit
225 name contains an <literal>@</literal> character, systemd will look for a
226 unit template that shares the same name but with the
227 instance string (i.e. the part between the <literal>@</literal> character
228 and the suffix) removed. Example: if a service
229 <filename>getty@tty3.service</filename> is requested
230 and no file by that name is found, systemd will look
231 for <filename>getty@.service</filename> and
232 instantiate a service from that configuration file if
235 <para>To refer to the instance string from
236 within the configuration file you may use the special
237 <literal>%i</literal> specifier in many of the
238 configuration options. See below for details.</para>
240 <para>If a unit file is empty (i.e. has the file size
241 0) or is symlinked to <filename>/dev/null</filename>,
242 its configuration will not be loaded and it appears
243 with a load state of <literal>masked</literal>, and
244 cannot be activated. Use this as an effective way to
245 fully disable a unit, making it impossible to start it
246 even manually.</para>
248 <para>The unit file format is covered by the
250 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
251 Stability Promise</ulink>.</para>
256 <title>Unit Load Path</title>
258 <para>Unit files are loaded from a set of paths
259 determined during compilation, described in the two
260 tables below. Unit files found in directories listed
261 earlier override files with the same name in
262 directories lower in the list.</para>
264 <para>When systemd is running in user mode
265 (<option>--user</option>) and the variable
266 <varname>$SYSTEMD_UNIT_PATH</varname> is set, this
267 contents of this variable overrides the unit load
273 Load path when running in system mode (<option>--system</option>).
277 <colspec colname='path' />
278 <colspec colname='expl' />
282 <entry>Description</entry>
287 <entry><filename>/etc/systemd/system</filename></entry>
288 <entry>Local configuration</entry>
291 <entry><filename>/run/systemd/system</filename></entry>
292 <entry>Runtime units</entry>
295 <entry><filename>/usr/lib/systemd/system</filename></entry>
296 <entry>Units of installed packages</entry>
304 Load path when running in user mode (<option>--user</option>).
308 <colspec colname='path' />
309 <colspec colname='expl' />
313 <entry>Description</entry>
318 <entry><filename>$HOME/.config/systemd/user</filename></entry>
319 <entry>User configuration</entry>
322 <entry><filename>/etc/systemd/user</filename></entry>
323 <entry>Local configuration</entry>
326 <entry><filename>/run/systemd/user</filename></entry>
327 <entry>Runtime units</entry>
330 <entry><filename>/usr/lib/systemd/user</filename></entry>
331 <entry>Units of installed packages</entry>
337 <para>Additional units might be loaded into systemd
338 ("linked") from directories not on the unit load
339 path. See the <command>link</command> command for
340 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Also,
341 some units are dynamically created via generators
343 url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>.
348 <title>Options</title>
350 <para>Unit file may include a [Unit] section, which
351 carries generic information about the unit that is not
352 dependent on the type of unit:</para>
354 <variablelist class='unit-directives'>
357 <term><varname>Description=</varname></term>
358 <listitem><para>A free-form string
359 describing the unit. This is intended
360 for use in UIs to show descriptive
361 information along with the unit
362 name. The description should contain a name
363 that means something to the end user.
364 <literal>Apache2 Web Server</literal> is a good
365 example. Bad examples are
366 <literal>high-performance light-weight HTTP
367 server</literal> (too generic) or
368 <literal>Apache2</literal> (too specific and
369 meaningless for people who do not know
370 Apache).</para></listitem>
374 <term><varname>Documentation=</varname></term>
375 <listitem><para>A space-separated list
376 of URIs referencing documentation for
378 configuration. Accepted are only URIs
380 <literal>http://</literal>,
381 <literal>https://</literal>,
382 <literal>file:</literal>,
383 <literal>info:</literal>,
384 <literal>man:</literal>. For more
385 information about the syntax of these
387 <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
388 URIs should be listed in order of
389 relevance, starting with the most
390 relevant. It is a good idea to first
391 reference documentation that explains
392 what the unit's purpose is, followed
393 by how it is configured, followed by
394 any other related documentation. This
395 option may be specified more than once
396 in which case the specified list of
397 URIs is merged. If the empty string is
398 assigned to this option, the list is
399 reset and all prior assignments will
400 have no effect.</para></listitem>
404 <term><varname>Requires=</varname></term>
406 <listitem><para>Configures requirement
407 dependencies on other units. If this
408 unit gets activated, the units listed
409 here will be activated as well. If one
410 of the other units gets deactivated or
411 its activation fails, this unit will
412 be deactivated. This option may be
413 specified more than once, in which
414 case requirement dependencies for all
415 listed names are created. Note that
416 requirement dependencies do not
417 influence the order in which services
418 are started or stopped. This has to be
419 configured independently with the
420 <varname>After=</varname> or
421 <varname>Before=</varname> options. If
423 <filename>foo.service</filename>
425 <filename>bar.service</filename> as
427 <varname>Requires=</varname> and no
428 ordering is configured with
429 <varname>After=</varname> or
430 <varname>Before=</varname>, then both
431 units will be started simultaneously
432 and without any delay between them if
433 <filename>foo.service</filename> is
434 activated. Often it is a better choice
435 to use <varname>Wants=</varname>
437 <varname>Requires=</varname> in order
438 to achieve a system that is more
439 robust when dealing with failing
442 <para>Note that dependencies of this
443 type may also be configured outside of
444 the unit configuration file by
445 adding a symlink to a
446 <filename>.requires/</filename> directory
447 accompanying the unit file. For
448 details see above.</para></listitem>
452 <term><varname>RequiresOverridable=</varname></term>
454 <listitem><para>Similar to
455 <varname>Requires=</varname>.
456 Dependencies listed in
457 <varname>RequiresOverridable=</varname>
458 which cannot be fulfilled or fail to
459 start are ignored if the startup was
460 explicitly requested by the user. If
461 the start-up was pulled in indirectly
462 by some dependency or automatic
463 start-up of units that is not
464 requested by the user, this dependency
465 must be fulfilled and otherwise the
466 transaction fails. Hence, this option
467 may be used to configure dependencies
468 that are normally honored unless the
469 user explicitly starts up the unit, in
470 which case whether they failed or not
471 is irrelevant.</para></listitem>
475 <term><varname>Requisite=</varname></term>
476 <term><varname>RequisiteOverridable=</varname></term>
478 <listitem><para>Similar to
479 <varname>Requires=</varname>
480 and <varname>RequiresOverridable=</varname>, respectively. However,
481 if a unit listed here is not started
482 already it will not be started and the
484 immediately.</para></listitem>
488 <term><varname>Wants=</varname></term>
490 <listitem><para>A weaker version of
491 <varname>Requires=</varname>. A unit
492 listed in this option will be started
493 if the configuring unit is. However,
494 if the listed unit fails to start up
495 or cannot be added to the transaction
496 this has no impact on the validity of
497 the transaction as a whole. This is
498 the recommended way to hook start-up
499 of one unit to the start-up of another
502 <para>Note that dependencies of this
503 type may also be configured outside of
504 the unit configuration file by
505 adding a symlink to a
506 <filename>.wants/</filename> directory
507 accompanying the unit file. For
508 details see above.</para></listitem>
512 <term><varname>BindsTo=</varname></term>
514 <listitem><para>Configures requirement
515 dependencies, very similar in style to
516 <varname>Requires=</varname>, however
517 in addition to this behavior it also
518 declares that this unit is stopped
519 when any of the units listed suddenly
520 disappears. Units can suddenly,
521 unexpectedly disappear if a service
522 terminates on its own choice, a device
523 is unplugged or a mount point
524 unmounted without involvement of
525 systemd.</para></listitem>
529 <term><varname>PartOf=</varname></term>
531 <listitem><para>Configures dependencies
532 similar to <varname>Requires=</varname>,
533 but limited to stopping and restarting
534 of units. When systemd stops or restarts
535 the units listed here, the action is
536 propagated to this unit.
537 Note that this is a one way dependency -
538 changes to this unit do not affect the
544 <term><varname>Conflicts=</varname></term>
546 <listitem><para>Configures negative
547 requirement dependencies. If a unit
549 <varname>Conflicts=</varname> setting
550 on another unit, starting the former
551 will stop the latter and vice
552 versa. Note that this setting is
553 independent of and orthogonal to the
554 <varname>After=</varname> and
555 <varname>Before=</varname> ordering
558 <para>If a unit A that conflicts with
559 a unit B is scheduled to be started at
560 the same time as B, the transaction
561 will either fail (in case both are
562 required part of the transaction) or
563 be modified to be fixed (in case one
564 or both jobs are not a required part
565 of the transaction). In the latter
566 case the job that is not the required
567 will be removed, or in case both are
568 not required the unit that conflicts
569 will be started and the unit that is
571 stopped.</para></listitem>
575 <term><varname>Before=</varname></term>
576 <term><varname>After=</varname></term>
578 <listitem><para>Configures ordering
579 dependencies between units. If a unit
580 <filename>foo.service</filename>
582 <option>Before=bar.service</option>
583 and both units are being started,
584 <filename>bar.service</filename>'s
585 start-up is delayed until
586 <filename>foo.service</filename> is
587 started up. Note that this setting is
588 independent of and orthogonal to the
589 requirement dependencies as configured
590 by <varname>Requires=</varname>. It is
591 a common pattern to include a unit
593 <varname>After=</varname> and
594 <varname>Requires=</varname> option in
595 which case the unit listed will be
596 started before the unit that is
597 configured with these options. This
598 option may be specified more than
599 once, in which case ordering
600 dependencies for all listed names are
601 created. <varname>After=</varname> is
603 <varname>Before=</varname>, i.e. while
604 <varname>After=</varname> ensures that
605 the configured unit is started after
606 the listed unit finished starting up,
607 <varname>Before=</varname> ensures the
608 opposite, i.e. that the configured
609 unit is fully started up before the
610 listed unit is started. Note that when
611 two units with an ordering dependency
612 between them are shut down, the
613 inverse of the start-up order is
614 applied. i.e. if a unit is configured
615 with <varname>After=</varname> on
616 another unit, the former is stopped
617 before the latter if both are shut
618 down. If one unit with an ordering
619 dependency on another unit is shut
620 down while the latter is started up,
621 the shut down is ordered before the
622 start-up regardless whether the
623 ordering dependency is actually of
624 type <varname>After=</varname> or
625 <varname>Before=</varname>. If two
626 units have no ordering dependencies
627 between them, they are shut down
628 or started up simultaneously, and
630 place. </para></listitem>
634 <term><varname>OnFailure=</varname></term>
636 <listitem><para>Lists one or more
637 units that are activated when this
639 <literal>failed</literal>
640 state.</para></listitem>
644 <term><varname>PropagatesReloadTo=</varname></term>
645 <term><varname>ReloadPropagatedFrom=</varname></term>
647 <listitem><para>Lists one or more
648 units where reload requests on the
649 unit will be propagated to/on the
650 other unit will be propagated
651 from. Issuing a reload request on a
652 unit will automatically also enqueue a
653 reload request on all units that the
654 reload request shall be propagated to
656 settings.</para></listitem>
660 <term><varname>JoinsNamespaceOf=</varname></term>
662 <listitem><para>For units that start
663 processes (such as service units),
664 lists one or more other units whose
665 network and/or temporary file
666 namespace to join. This only applies
667 to unit types which support the
668 <varname>PrivateNetwork=</varname> and
669 <varname>PrivateTmp=</varname>
671 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
672 for details). If a unit that has this
673 setting set is started its processes
675 <filename>/tmp</filename>,
676 <filename>/tmp/var</filename> and
677 network namespace as one listed unit
678 that is started. If multiple listed
679 units are already started it is not
680 defined which namespace is
681 joined. Note that this setting only
683 <varname>PrivateNetwork=</varname>
684 and/or <varname>PrivateTmp=</varname>
685 is enabled for both the unit that
686 joins the namespace and the unit whose
687 namespace is joined.</para></listitem>
691 <term><varname>RequiresMountsFor=</varname></term>
693 <listitem><para>Takes a space-separated
694 list of absolute paths. Automatically
695 adds dependencies of type
696 <varname>Requires=</varname> and
697 <varname>After=</varname> for all
698 mount units required to access the
699 specified path.</para></listitem>
703 <term><varname>OnFailureJobMode=</varname></term>
705 <listitem><para>Takes a value of
706 <literal>fail</literal>,
707 <literal>replace</literal>,
708 <literal>replace-irreversibly</literal>,
709 <literal>isolate</literal>,
710 <literal>flush</literal>,
711 <literal>ignore-dependencies</literal>
713 <literal>ignore-requirements</literal>. Defaults
715 <literal>replace</literal>. Specifies
716 how the units listed in
717 <varname>OnFailure=</varname> will be
719 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
720 <option>--job-mode=</option> option
721 for details on the possible values. If
723 <literal>isolate</literal>, only a
724 single unit may be listed in
725 <varname>OnFailure=</varname>..</para></listitem>
729 <term><varname>IgnoreOnIsolate=</varname></term>
731 <listitem><para>Takes a boolean
732 argument. If <option>true</option>,
733 this unit will not be stopped when
734 isolating another unit. Defaults to
735 <option>false</option>.</para></listitem>
739 <term><varname>IgnoreOnSnapshot=</varname></term>
741 <listitem><para>Takes a boolean
742 argument. If <option>true</option>,
743 this unit will not be included in
744 snapshots. Defaults to
745 <option>true</option> for device and
746 snapshot units, <option>false</option>
747 for the others.</para></listitem>
751 <term><varname>StopWhenUnneeded=</varname></term>
753 <listitem><para>Takes a boolean
754 argument. If <option>true</option>,
755 this unit will be stopped when it is
756 no longer used. Note that in order to
757 minimize the work to be executed,
758 systemd will not stop units by default
759 unless they are conflicting with other
760 units, or the user explicitly
761 requested their shut down. If this
762 option is set, a unit will be
763 automatically cleaned up if no other
764 active unit requires it. Defaults to
765 <option>false</option>.</para></listitem>
769 <term><varname>RefuseManualStart=</varname></term>
770 <term><varname>RefuseManualStop=</varname></term>
772 <listitem><para>Takes a boolean
773 argument. If <option>true</option>,
774 this unit can only be activated
775 or deactivated indirectly. In
776 this case, explicit start-up
777 or termination requested by the
778 user is denied, however if it is
779 started or stopped as a
780 dependency of another unit, start-up
781 or termination will succeed. This
782 is mostly a safety feature to ensure
783 that the user does not accidentally
784 activate units that are not intended
785 to be activated explicitly, and not
786 accidentally deactivate units that are
787 not intended to be deactivated.
788 These options default to
789 <option>false</option>.</para></listitem>
793 <term><varname>AllowIsolate=</varname></term>
795 <listitem><para>Takes a boolean
796 argument. If <option>true</option>,
797 this unit may be used with the
798 <command>systemctl isolate</command>
799 command. Otherwise, this will be
800 refused. It probably is a good idea to
801 leave this disabled except for target
802 units that shall be used similar to
803 runlevels in SysV init systems, just
804 as a precaution to avoid unusable
805 system states. This option defaults to
806 <option>false</option>.</para></listitem>
810 <term><varname>DefaultDependencies=</varname></term>
812 <listitem><para>Takes a boolean
813 argument. If <option>true</option>,
814 (the default), a few default
815 dependencies will implicitly be
816 created for the unit. The actual
817 dependencies created depend on the
818 unit type. For example, for service
819 units, these dependencies ensure that
820 the service is started only after
821 basic system initialization is
822 completed and is properly terminated on
823 system shutdown. See the respective
824 man pages for details. Generally, only
825 services involved with early boot or
826 late shutdown should set this option
827 to <option>false</option>. It is
828 highly recommended to leave this
829 option enabled for the majority of
830 common units. If set to
831 <option>false</option>, this option
832 does not disable all implicit
833 dependencies, just non-essential
834 ones.</para></listitem>
838 <term><varname>JobTimeoutSec=</varname></term>
840 <listitem><para>When clients are
841 waiting for a job of this unit to
842 complete, time out after the specified
843 time. If this time limit is reached,
844 the job will be cancelled, the unit
845 however will not change state or even
846 enter the <literal>failed</literal>
847 mode. This value defaults to 0 (job
848 timeouts disabled), except for device
849 units. NB: this timeout is independent
850 from any unit-specific timeout (for
851 example, the timeout set with
852 <varname>Timeout=</varname> in service
853 units) as the job timeout has no
854 effect on the unit itself, only on the
855 job that might be pending for it. Or
856 in other words: unit-specific timeouts
857 are useful to abort unit state
858 changes, and revert them. The job
859 timeout set with this option however
860 is useful to abort only the job
861 waiting for the unit state to
862 change.</para></listitem>
866 <term><varname>ConditionPathExists=</varname></term>
867 <term><varname>ConditionPathExistsGlob=</varname></term>
868 <term><varname>ConditionPathIsDirectory=</varname></term>
869 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
870 <term><varname>ConditionPathIsMountPoint=</varname></term>
871 <term><varname>ConditionPathIsReadWrite=</varname></term>
872 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
873 <term><varname>ConditionFileNotEmpty=</varname></term>
874 <term><varname>ConditionFileIsExecutable=</varname></term>
875 <term><varname>ConditionKernelCommandLine=</varname></term>
876 <term><varname>ConditionVirtualization=</varname></term>
877 <term><varname>ConditionSecurity=</varname></term>
878 <term><varname>ConditionCapability=</varname></term>
879 <term><varname>ConditionHost=</varname></term>
880 <term><varname>ConditionACPower=</varname></term>
881 <term><varname>ConditionNull=</varname></term>
883 <listitem><para>Before starting a unit
884 verify that the specified condition is
885 true. If it is not true, the starting
886 of the unit will be skipped, however
887 all ordering dependencies of it are
888 still respected. A failing condition
889 will not result in the unit being
890 moved into a failure state. The
891 condition is checked at the time the
892 queued start job is to be
896 <varname>ConditionPathExists=</varname>
897 a file existence condition is
898 checked before a unit is started. If
899 the specified absolute path name does
900 not exist, the condition will
901 fail. If the absolute path name passed
903 <varname>ConditionPathExists=</varname>
904 is prefixed with an exclamation mark
905 (<literal>!</literal>), the test is negated, and the unit
906 is only started if the path does not
909 <para><varname>ConditionPathExistsGlob=</varname>
911 <varname>ConditionPathExists=</varname>,
912 but checks for the existence of at
913 least one file or directory matching
914 the specified globbing pattern.</para>
916 <para><varname>ConditionPathIsDirectory=</varname>
918 <varname>ConditionPathExists=</varname>
919 but verifies whether a certain path
923 <para><varname>ConditionPathIsSymbolicLink=</varname>
925 <varname>ConditionPathExists=</varname>
926 but verifies whether a certain path
927 exists and is a symbolic
930 <para><varname>ConditionPathIsMountPoint=</varname>
932 <varname>ConditionPathExists=</varname>
933 but verifies whether a certain path
934 exists and is a mount
937 <para><varname>ConditionPathIsReadWrite=</varname>
939 <varname>ConditionPathExists=</varname>
940 but verifies whether the underlying
941 file system is readable and writable
945 <para><varname>ConditionDirectoryNotEmpty=</varname>
947 <varname>ConditionPathExists=</varname>
948 but verifies whether a certain path
949 exists and is a non-empty
952 <para><varname>ConditionFileNotEmpty=</varname>
954 <varname>ConditionPathExists=</varname>
955 but verifies whether a certain path
956 exists and refers to a regular file
957 with a non-zero size.</para>
959 <para><varname>ConditionFileIsExecutable=</varname>
961 <varname>ConditionPathExists=</varname>
962 but verifies whether a certain path
963 exists, is a regular file and marked
967 <varname>ConditionKernelCommandLine=</varname>
968 may be used to check whether a
969 specific kernel command line option is
970 set (or if prefixed with the
971 exclamation mark unset). The argument
972 must either be a single word, or an
973 assignment (i.e. two words, separated
974 <literal>=</literal>). In the former
975 case the kernel command line is
976 searched for the word appearing as is,
977 or as left hand side of an
978 assignment. In the latter case the
979 exact assignment is looked for with
980 right and left hand side
983 <para><varname>ConditionVirtualization=</varname>
984 may be used to check whether the
985 system is executed in a virtualized
986 environment and optionally test
987 whether it is a specific
988 implementation. Takes either boolean
989 value to check if being executed in
990 any virtualized environment, or one of
991 <varname>vm</varname> and
992 <varname>container</varname> to test
993 against a generic type of
994 virtualization solution, or one of
995 <varname>qemu</varname>,
996 <varname>kvm</varname>,
997 <varname>vmware</varname>,
998 <varname>microsoft</varname>,
999 <varname>oracle</varname>,
1000 <varname>xen</varname>,
1001 <varname>bochs</varname>,
1002 <varname>chroot</varname>,
1003 <varname>uml</varname>,
1004 <varname>openvz</varname>,
1005 <varname>lxc</varname>,
1006 <varname>lxc-libvirt</varname>,
1007 <varname>systemd-nspawn</varname> to
1008 test against a specific
1009 implementation. If multiple
1010 virtualization technologies are nested,
1011 only the innermost is considered. The
1012 test may be negated by prepending an
1013 exclamation mark.</para>
1015 <para><varname>ConditionSecurity=</varname>
1016 may be used to check whether the given
1017 security module is enabled on the
1018 system. Currently the recognized values
1019 values are <varname>selinux</varname>,
1020 <varname>apparmor</varname>,
1021 <varname>ima</varname> and
1022 <varname>smack</varname>.
1023 The test may be negated by prepending
1027 <para><varname>ConditionCapability=</varname>
1028 may be used to check whether the given
1029 capability exists in the capability
1030 bounding set of the service manager
1031 (i.e. this does not check whether
1032 capability is actually available in
1033 the permitted or effective sets, see
1034 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1035 for details). Pass a capability name
1036 such as <literal>CAP_MKNOD</literal>,
1037 possibly prefixed with an exclamation
1038 mark to negate the check.</para>
1040 <para><varname>ConditionHost=</varname>
1041 may be used to match against the
1042 hostname or machine ID of the
1043 host. This either takes a hostname
1044 string (optionally with shell style
1045 globs) which is tested against the
1046 locally set hostname as returned by
1047 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1048 or a machine ID formatted as string
1050 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1051 The test may be negated by prepending
1052 an exclamation mark.</para>
1054 <para><varname>ConditionACPower=</varname>
1055 may be used to check whether the
1056 system has AC power, or is exclusively
1057 battery powered at the time of
1058 activation of the unit. This takes a
1059 boolean argument. If set to
1060 <varname>true</varname>, the condition
1061 will hold only if at least one AC
1062 connector of the system is connected
1063 to a power source, or if no AC
1064 connectors are known. Conversely, if
1065 set to <varname>false</varname>, the
1066 condition will hold only if there is
1067 at least one AC connector known and
1068 all AC connectors are disconnected
1069 from a power source.</para>
1072 <varname>ConditionNull=</varname> may
1073 be used to add a constant condition
1074 check value to the unit. It takes a
1075 boolean argument. If set to
1076 <varname>false</varname>, the condition
1077 will always fail, otherwise
1080 <para>If multiple conditions are
1081 specified, the unit will be executed if
1082 all of them apply (i.e. a logical AND
1083 is applied). Condition checks can be
1084 prefixed with a pipe symbol (|) in
1085 which case a condition becomes a
1086 triggering condition. If at least one
1087 triggering condition is defined for a
1088 unit, then the unit will be executed if
1089 at least one of the triggering
1090 conditions apply and all of the
1091 non-triggering conditions. If you
1092 prefix an argument with the pipe
1093 symbol and an exclamation mark, the
1094 pipe symbol must be passed first, the
1095 exclamation second. Except for
1096 <varname>ConditionPathIsSymbolicLink=</varname>,
1097 all path checks follow symlinks. If
1098 any of these options is assigned the
1099 empty string, the list of conditions is
1100 reset completely, all previous
1101 condition settings (of any kind) will
1102 have no effect.</para></listitem>
1106 <term><varname>SourcePath=</varname></term>
1107 <listitem><para>A path to a
1108 configuration file this unit has been
1109 generated from. This is primarily
1110 useful for implementation of generator
1111 tools that convert configuration from
1112 an external configuration file format
1113 into native unit files. Thus
1114 functionality should not be used in
1115 normal units.</para></listitem>
1119 <para>Unit file may include a [Install] section, which
1120 carries installation information for the unit. This
1121 section is not interpreted by
1122 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1123 during runtime. It is used exclusively by the
1124 <command>enable</command> and
1125 <command>disable</command> commands of the
1126 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1127 tool during installation of a unit:</para>
1129 <variablelist class='unit-directives'>
1131 <term><varname>Alias=</varname></term>
1133 <listitem><para>Additional names this
1134 unit shall be installed under. The
1135 names listed here must have the same
1136 suffix (i.e. type) as the unit file
1137 name. This option may be specified
1138 more than once, in which case all
1139 listed names are used. At installation
1141 <command>systemctl enable</command>
1142 will create symlinks from these names
1143 to the unit filename.</para></listitem>
1147 <term><varname>WantedBy=</varname></term>
1148 <term><varname>RequiredBy=</varname></term>
1150 <listitem><para>A symbolic link is
1152 <filename>.wants/</filename> or
1153 <filename>.requires/</filename> directory
1154 of the listed unit when this unit is
1155 activated by <command>systemctl
1156 enable</command>. This has the effect
1157 that a dependency of type
1158 <varname>Wants=</varname> or
1159 <varname>Requires=</varname> is added
1160 from the listed unit to the current
1161 unit. The primary result is that the
1162 current unit will be started when the
1163 listed unit is started. See the
1165 <varname>Wants=</varname> and
1166 <varname>Requires=</varname> in the
1167 [Unit] section for details.</para>
1169 <para><command>WantedBy=foo.service</command>
1171 <filename>bar.service</filename> is
1172 mostly equivalent to
1173 <command>Alias=foo.service.wants/bar.service</command>
1174 in the same file. In case of template
1175 units, <command>systemctl enable</command>
1176 must be called with an instance name, and
1177 this instance will be added to the
1178 <filename>.wants/</filename> or
1179 <filename>.requires/</filename> list
1181 E.g. <command>WantedBy=getty.target</command>
1183 <filename>getty@.service</filename>
1184 will result in <command>systemctl
1185 enable getty@tty2.service</command>
1187 <filename>getty.target.wants/getty@tty2.service</filename>
1188 link to <filename>getty@.service</filename>.
1193 <term><varname>Also=</varname></term>
1195 <listitem><para>Additional units to
1196 install/deinstall when this unit is
1197 installed/deinstalled. If the user
1198 requests installation/deinstallation
1199 of a unit with this option configured,
1200 <command>systemctl enable</command>
1201 and <command>systemctl
1202 disable</command> will automatically
1203 install/uninstall units listed in this option as
1204 well.</para></listitem>
1208 <para>The following specifiers are interpreted in the
1209 Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v.
1210 For their meaning see the next section.
1215 <title>Specifiers</title>
1217 <para>Many settings resolve specifiers which may be
1218 used to write generic unit files referring to runtime
1219 or unit parameters that are replaced when the unit
1220 files are loaded. The following specifiers are
1224 <title>Specifiers available in unit files</title>
1225 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1226 <colspec colname="spec" />
1227 <colspec colname="mean" />
1228 <colspec colname="detail" />
1231 <entry>Specifier</entry>
1232 <entry>Meaning</entry>
1233 <entry>Details</entry>
1238 <entry><literal>%n</literal></entry>
1239 <entry>Full unit name</entry>
1243 <entry><literal>%N</literal></entry>
1244 <entry>Unescaped full unit name</entry>
1248 <entry><literal>%p</literal></entry>
1249 <entry>Prefix name</entry>
1250 <entry>For instantiated units this refers to the string before the @. For non-instantiated units this refers to to the name of the unit with the type suffix removed.</entry>
1253 <entry><literal>%P</literal></entry>
1254 <entry>Unescaped prefix name</entry>
1258 <entry><literal>%i</literal></entry>
1259 <entry>Instance name</entry>
1260 <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix.</entry>
1263 <entry><literal>%I</literal></entry>
1264 <entry>Unescaped instance name</entry>
1268 <entry><literal>%f</literal></entry>
1269 <entry>Unescaped filename</entry>
1270 <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name similarly prepended with <filename>/</filename>.</entry>
1273 <entry><literal>%c</literal></entry>
1274 <entry>Control group path of the unit</entry>
1278 <entry><literal>%r</literal></entry>
1279 <entry>Root control group path where units are placed.</entry>
1280 <entry>For system instances, this usually resolves to <filename>/system</filename>, except in containers, where the path might be prefixed with the container's root control group.</entry>
1283 <entry><literal>%R</literal></entry>
1284 <entry>Parent directory of the control group path where units are placed.</entry>
1285 <entry>For system instances, this usually
1286 resolves to <filename>/</filename>, except in
1287 containers, where this resolves to the
1288 container's root directory.</entry>
1291 <entry><literal>%t</literal></entry>
1292 <entry>Runtime socket dir</entry>
1293 <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry>
1296 <entry><literal>%u</literal></entry>
1297 <entry>User name</entry>
1298 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1301 <entry><literal>%U</literal></entry>
1302 <entry>User UID</entry>
1303 <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1306 <entry><literal>%h</literal></entry>
1307 <entry>User home directory</entry>
1308 <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1311 <entry><literal>%s</literal></entry>
1312 <entry>User shell</entry>
1313 <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance. If the user is <literal>root</literal> (UID equal to 0), the shell configured in account database is ignored and <filename>/bin/sh</filename> is always used.</entry>
1316 <entry><literal>%m</literal></entry>
1317 <entry>Machine ID</entry>
1318 <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>
1321 <entry><literal>%b</literal></entry>
1322 <entry>Boot ID</entry>
1323 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1326 <entry><literal>%H</literal></entry>
1327 <entry>Host name</entry>
1328 <entry>The hostname of the running system.</entry>
1331 <entry><literal>%v</literal></entry>
1332 <entry>Kernel release</entry>
1333 <entry>Identical to <command>uname -r</command> output.</entry>
1336 <entry><literal>%%</literal></entry>
1337 <entry>Escaped %</entry>
1338 <entry>Single percent sign.</entry>
1346 <title>See Also</title>
1348 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1349 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1350 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1351 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1352 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1353 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1354 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1355 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1356 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1357 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1358 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1359 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1360 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1361 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1362 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1363 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1364 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1365 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1366 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>