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 or multiple
414 space-separated units may be specified
415 in one option in which case
416 requirement dependencies for all
417 listed names will be created. Note
418 that requirement dependencies do not
419 influence the order in which services
420 are started or stopped. This has to be
421 configured independently with the
422 <varname>After=</varname> or
423 <varname>Before=</varname> options. If
425 <filename>foo.service</filename>
427 <filename>bar.service</filename> as
429 <varname>Requires=</varname> and no
430 ordering is configured with
431 <varname>After=</varname> or
432 <varname>Before=</varname>, then both
433 units will be started simultaneously
434 and without any delay between them if
435 <filename>foo.service</filename> is
436 activated. Often it is a better choice
437 to use <varname>Wants=</varname>
439 <varname>Requires=</varname> in order
440 to achieve a system that is more
441 robust when dealing with failing
444 <para>Note that dependencies of this
445 type may also be configured outside of
446 the unit configuration file by
447 adding a symlink to a
448 <filename>.requires/</filename> directory
449 accompanying the unit file. For
450 details see above.</para></listitem>
454 <term><varname>RequiresOverridable=</varname></term>
456 <listitem><para>Similar to
457 <varname>Requires=</varname>.
458 Dependencies listed in
459 <varname>RequiresOverridable=</varname>
460 which cannot be fulfilled or fail to
461 start are ignored if the startup was
462 explicitly requested by the user. If
463 the start-up was pulled in indirectly
464 by some dependency or automatic
465 start-up of units that is not
466 requested by the user, this dependency
467 must be fulfilled and otherwise the
468 transaction fails. Hence, this option
469 may be used to configure dependencies
470 that are normally honored unless the
471 user explicitly starts up the unit, in
472 which case whether they failed or not
473 is irrelevant.</para></listitem>
477 <term><varname>Requisite=</varname></term>
478 <term><varname>RequisiteOverridable=</varname></term>
480 <listitem><para>Similar to
481 <varname>Requires=</varname> and
482 <varname>RequiresOverridable=</varname>,
483 respectively. However, if the units
484 listed here are not started already
485 they will not be started and the
486 transaction will fail immediately.
491 <term><varname>Wants=</varname></term>
493 <listitem><para>A weaker version of
494 <varname>Requires=</varname>. Units
495 listed in this option will be started
496 if the configuring unit is. However,
497 if the listed units fail to start
498 or cannot be added to the transaction
499 this has no impact on the validity of
500 the transaction as a whole. This is
501 the recommended way to hook start-up
502 of one unit to the start-up of another
505 <para>Note that dependencies of this
506 type may also be configured outside of
507 the unit configuration file by adding
509 <filename>.wants/</filename> directory
510 accompanying the unit file. For
511 details see above.</para></listitem>
515 <term><varname>BindsTo=</varname></term>
517 <listitem><para>Configures requirement
518 dependencies, very similar in style to
519 <varname>Requires=</varname>, however
520 in addition to this behavior it also
521 declares that this unit is stopped
522 when any of the units listed suddenly
523 disappears. Units can suddenly,
524 unexpectedly disappear if a service
525 terminates on its own choice, a device
526 is unplugged or a mount point
527 unmounted without involvement of
528 systemd.</para></listitem>
532 <term><varname>PartOf=</varname></term>
534 <listitem><para>Configures dependencies
535 similar to <varname>Requires=</varname>,
536 but limited to stopping and restarting
537 of units. When systemd stops or restarts
538 the units listed here, the action is
539 propagated to this unit.
540 Note that this is a one way dependency —
541 changes to this unit do not affect the
547 <term><varname>Conflicts=</varname></term>
549 <listitem><para>A space-separated list
550 of unit names. Configures negative
551 requirement dependencies. If a unit
552 has a <varname>Conflicts=</varname>
553 setting on another unit, starting the
554 former will stop the latter and vice
555 versa. Note that this setting is
556 independent of and orthogonal to the
557 <varname>After=</varname> and
558 <varname>Before=</varname> ordering
561 <para>If a unit A that conflicts with
562 a unit B is scheduled to be started at
563 the same time as B, the transaction
564 will either fail (in case both are
565 required part of the transaction) or
566 be modified to be fixed (in case one
567 or both jobs are not a required part
568 of the transaction). In the latter
569 case the job that is not the required
570 will be removed, or in case both are
571 not required the unit that conflicts
572 will be started and the unit that is
574 stopped.</para></listitem>
578 <term><varname>Before=</varname></term>
579 <term><varname>After=</varname></term>
581 <listitem><para>A space-separated list
582 of unit names. Configures ordering
583 dependencies between units. If a unit
584 <filename>foo.service</filename>
586 <option>Before=bar.service</option>
587 and both units are being started,
588 <filename>bar.service</filename>'s
589 start-up is delayed until
590 <filename>foo.service</filename> is
591 started up. Note that this setting is
592 independent of and orthogonal to the
593 requirement dependencies as configured
594 by <varname>Requires=</varname>. It is
595 a common pattern to include a unit
597 <varname>After=</varname> and
598 <varname>Requires=</varname> option in
599 which case the unit listed will be
600 started before the unit that is
601 configured with these options. This
602 option may be specified more than
603 once, in which case ordering
604 dependencies for all listed names are
605 created. <varname>After=</varname> is
607 <varname>Before=</varname>, i.e. while
608 <varname>After=</varname> ensures that
609 the configured unit is started after
610 the listed unit finished starting up,
611 <varname>Before=</varname> ensures the
612 opposite, i.e. that the configured
613 unit is fully started up before the
614 listed unit is started. Note that when
615 two units with an ordering dependency
616 between them are shut down, the
617 inverse of the start-up order is
618 applied. i.e. if a unit is configured
619 with <varname>After=</varname> on
620 another unit, the former is stopped
621 before the latter if both are shut
622 down. If one unit with an ordering
623 dependency on another unit is shut
624 down while the latter is started up,
625 the shut down is ordered before the
626 start-up regardless whether the
627 ordering dependency is actually of
628 type <varname>After=</varname> or
629 <varname>Before=</varname>. If two
630 units have no ordering dependencies
631 between them, they are shut down or
632 started up simultaneously, and no
634 place. </para></listitem>
638 <term><varname>OnFailure=</varname></term>
640 <listitem><para>A space-separated list
641 of one or more units that are
642 activated when this unit enters the
643 <literal>failed</literal>
644 state.</para></listitem>
648 <term><varname>PropagatesReloadTo=</varname></term>
649 <term><varname>ReloadPropagatedFrom=</varname></term>
651 <listitem><para>A space-separated list
652 of one or more units where reload
653 requests on this unit will be
654 propagated to, or reload requests on
655 the other unit will be propagated to
656 this unit, respectively. Issuing a
657 reload request on a unit will
658 automatically also enqueue a reload
659 request on all units that the reload
660 request shall be propagated to via
661 these two settings.</para></listitem>
665 <term><varname>JoinsNamespaceOf=</varname></term>
667 <listitem><para>For units that start
668 processes (such as service units),
669 lists one or more other units whose
670 network and/or temporary file
671 namespace to join. This only applies
672 to unit types which support the
673 <varname>PrivateNetwork=</varname> and
674 <varname>PrivateTmp=</varname>
676 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
677 for details). If a unit that has this
678 setting set is started its processes
680 <filename>/tmp</filename>,
681 <filename>/tmp/var</filename> and
682 network namespace as one listed unit
683 that is started. If multiple listed
684 units are already started it is not
685 defined which namespace is
686 joined. Note that this setting only
688 <varname>PrivateNetwork=</varname>
689 and/or <varname>PrivateTmp=</varname>
690 is enabled for both the unit that
691 joins the namespace and the unit whose
692 namespace is joined.</para></listitem>
696 <term><varname>RequiresMountsFor=</varname></term>
698 <listitem><para>Takes a space-separated
699 list of absolute paths. Automatically
700 adds dependencies of type
701 <varname>Requires=</varname> and
702 <varname>After=</varname> for all
703 mount units required to access the
704 specified path.</para></listitem>
708 <term><varname>OnFailureJobMode=</varname></term>
710 <listitem><para>Takes a value of
711 <literal>fail</literal>,
712 <literal>replace</literal>,
713 <literal>replace-irreversibly</literal>,
714 <literal>isolate</literal>,
715 <literal>flush</literal>,
716 <literal>ignore-dependencies</literal>
718 <literal>ignore-requirements</literal>. Defaults
720 <literal>replace</literal>. Specifies
721 how the units listed in
722 <varname>OnFailure=</varname> will be
724 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
725 <option>--job-mode=</option> option
726 for details on the possible values. If
728 <literal>isolate</literal>, only a
729 single unit may be listed in
730 <varname>OnFailure=</varname>..</para></listitem>
734 <term><varname>IgnoreOnIsolate=</varname></term>
736 <listitem><para>Takes a boolean
737 argument. If <option>true</option>,
738 this unit will not be stopped when
739 isolating another unit. Defaults to
740 <option>false</option>.</para></listitem>
744 <term><varname>IgnoreOnSnapshot=</varname></term>
746 <listitem><para>Takes a boolean
747 argument. If <option>true</option>,
748 this unit will not be included in
749 snapshots. Defaults to
750 <option>true</option> for device and
751 snapshot units, <option>false</option>
752 for the others.</para></listitem>
756 <term><varname>StopWhenUnneeded=</varname></term>
758 <listitem><para>Takes a boolean
759 argument. If <option>true</option>,
760 this unit will be stopped when it is
761 no longer used. Note that in order to
762 minimize the work to be executed,
763 systemd will not stop units by default
764 unless they are conflicting with other
765 units, or the user explicitly
766 requested their shut down. If this
767 option is set, a unit will be
768 automatically cleaned up if no other
769 active unit requires it. Defaults to
770 <option>false</option>.</para></listitem>
774 <term><varname>RefuseManualStart=</varname></term>
775 <term><varname>RefuseManualStop=</varname></term>
777 <listitem><para>Takes a boolean
778 argument. If <option>true</option>,
779 this unit can only be activated
780 or deactivated indirectly. In
781 this case, explicit start-up
782 or termination requested by the
783 user is denied, however if it is
784 started or stopped as a
785 dependency of another unit, start-up
786 or termination will succeed. This
787 is mostly a safety feature to ensure
788 that the user does not accidentally
789 activate units that are not intended
790 to be activated explicitly, and not
791 accidentally deactivate units that are
792 not intended to be deactivated.
793 These options default to
794 <option>false</option>.</para></listitem>
798 <term><varname>AllowIsolate=</varname></term>
800 <listitem><para>Takes a boolean
801 argument. If <option>true</option>,
802 this unit may be used with the
803 <command>systemctl isolate</command>
804 command. Otherwise, this will be
805 refused. It probably is a good idea to
806 leave this disabled except for target
807 units that shall be used similar to
808 runlevels in SysV init systems, just
809 as a precaution to avoid unusable
810 system states. This option defaults to
811 <option>false</option>.</para></listitem>
815 <term><varname>DefaultDependencies=</varname></term>
817 <listitem><para>Takes a boolean
818 argument. If <option>true</option>,
819 (the default), a few default
820 dependencies will implicitly be
821 created for the unit. The actual
822 dependencies created depend on the
823 unit type. For example, for service
824 units, these dependencies ensure that
825 the service is started only after
826 basic system initialization is
827 completed and is properly terminated on
828 system shutdown. See the respective
829 man pages for details. Generally, only
830 services involved with early boot or
831 late shutdown should set this option
832 to <option>false</option>. It is
833 highly recommended to leave this
834 option enabled for the majority of
835 common units. If set to
836 <option>false</option>, this option
837 does not disable all implicit
838 dependencies, just non-essential
839 ones.</para></listitem>
843 <term><varname>JobTimeoutSec=</varname></term>
845 <listitem><para>When clients are
846 waiting for a job of this unit to
847 complete, time out after the specified
848 time. If this time limit is reached,
849 the job will be cancelled, the unit
850 however will not change state or even
851 enter the <literal>failed</literal>
852 mode. This value defaults to 0 (job
853 timeouts disabled), except for device
854 units. NB: this timeout is independent
855 from any unit-specific timeout (for
856 example, the timeout set with
857 <varname>Timeout=</varname> in service
858 units) as the job timeout has no
859 effect on the unit itself, only on the
860 job that might be pending for it. Or
861 in other words: unit-specific timeouts
862 are useful to abort unit state
863 changes, and revert them. The job
864 timeout set with this option however
865 is useful to abort only the job
866 waiting for the unit state to
867 change.</para></listitem>
871 <term><varname>ConditionPathExists=</varname></term>
872 <term><varname>ConditionPathExistsGlob=</varname></term>
873 <term><varname>ConditionPathIsDirectory=</varname></term>
874 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
875 <term><varname>ConditionPathIsMountPoint=</varname></term>
876 <term><varname>ConditionPathIsReadWrite=</varname></term>
877 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
878 <term><varname>ConditionFileNotEmpty=</varname></term>
879 <term><varname>ConditionFileIsExecutable=</varname></term>
880 <term><varname>ConditionKernelCommandLine=</varname></term>
881 <term><varname>ConditionVirtualization=</varname></term>
882 <term><varname>ConditionSecurity=</varname></term>
883 <term><varname>ConditionCapability=</varname></term>
884 <term><varname>ConditionHost=</varname></term>
885 <term><varname>ConditionACPower=</varname></term>
886 <term><varname>ConditionNull=</varname></term>
888 <listitem><para>Before starting a unit
889 verify that the specified condition is
890 true. If it is not true, the starting
891 of the unit will be skipped, however
892 all ordering dependencies of it are
893 still respected. A failing condition
894 will not result in the unit being
895 moved into a failure state. The
896 condition is checked at the time the
897 queued start job is to be
901 <varname>ConditionPathExists=</varname>
902 a file existence condition is
903 checked before a unit is started. If
904 the specified absolute path name does
905 not exist, the condition will
906 fail. If the absolute path name passed
908 <varname>ConditionPathExists=</varname>
909 is prefixed with an exclamation mark
910 (<literal>!</literal>), the test is negated, and the unit
911 is only started if the path does not
914 <para><varname>ConditionPathExistsGlob=</varname>
916 <varname>ConditionPathExists=</varname>,
917 but checks for the existence of at
918 least one file or directory matching
919 the specified globbing pattern.</para>
921 <para><varname>ConditionPathIsDirectory=</varname>
923 <varname>ConditionPathExists=</varname>
924 but verifies whether a certain path
928 <para><varname>ConditionPathIsSymbolicLink=</varname>
930 <varname>ConditionPathExists=</varname>
931 but verifies whether a certain path
932 exists and is a symbolic
935 <para><varname>ConditionPathIsMountPoint=</varname>
937 <varname>ConditionPathExists=</varname>
938 but verifies whether a certain path
939 exists and is a mount
942 <para><varname>ConditionPathIsReadWrite=</varname>
944 <varname>ConditionPathExists=</varname>
945 but verifies whether the underlying
946 file system is readable and writable
950 <para><varname>ConditionDirectoryNotEmpty=</varname>
952 <varname>ConditionPathExists=</varname>
953 but verifies whether a certain path
954 exists and is a non-empty
957 <para><varname>ConditionFileNotEmpty=</varname>
959 <varname>ConditionPathExists=</varname>
960 but verifies whether a certain path
961 exists and refers to a regular file
962 with a non-zero size.</para>
964 <para><varname>ConditionFileIsExecutable=</varname>
966 <varname>ConditionPathExists=</varname>
967 but verifies whether a certain path
968 exists, is a regular file and marked
972 <varname>ConditionKernelCommandLine=</varname>
973 may be used to check whether a
974 specific kernel command line option is
975 set (or if prefixed with the
976 exclamation mark unset). The argument
977 must either be a single word, or an
978 assignment (i.e. two words, separated
979 <literal>=</literal>). In the former
980 case the kernel command line is
981 searched for the word appearing as is,
982 or as left hand side of an
983 assignment. In the latter case the
984 exact assignment is looked for with
985 right and left hand side
988 <para><varname>ConditionVirtualization=</varname>
989 may be used to check whether the
990 system is executed in a virtualized
991 environment and optionally test
992 whether it is a specific
993 implementation. Takes either boolean
994 value to check if being executed in
995 any virtualized environment, or one of
996 <varname>vm</varname> and
997 <varname>container</varname> to test
998 against a generic type of
999 virtualization solution, or one of
1000 <varname>qemu</varname>,
1001 <varname>kvm</varname>,
1002 <varname>vmware</varname>,
1003 <varname>microsoft</varname>,
1004 <varname>oracle</varname>,
1005 <varname>xen</varname>,
1006 <varname>bochs</varname>,
1007 <varname>chroot</varname>,
1008 <varname>uml</varname>,
1009 <varname>openvz</varname>,
1010 <varname>lxc</varname>,
1011 <varname>lxc-libvirt</varname>,
1012 <varname>systemd-nspawn</varname> to
1013 test against a specific
1014 implementation. If multiple
1015 virtualization technologies are nested,
1016 only the innermost is considered. The
1017 test may be negated by prepending an
1018 exclamation mark.</para>
1020 <para><varname>ConditionSecurity=</varname>
1021 may be used to check whether the given
1022 security module is enabled on the
1023 system. Currently the recognized values
1024 values are <varname>selinux</varname>,
1025 <varname>apparmor</varname>,
1026 <varname>ima</varname> and
1027 <varname>smack</varname>.
1028 The test may be negated by prepending
1032 <para><varname>ConditionCapability=</varname>
1033 may be used to check whether the given
1034 capability exists in the capability
1035 bounding set of the service manager
1036 (i.e. this does not check whether
1037 capability is actually available in
1038 the permitted or effective sets, see
1039 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1040 for details). Pass a capability name
1041 such as <literal>CAP_MKNOD</literal>,
1042 possibly prefixed with an exclamation
1043 mark to negate the check.</para>
1045 <para><varname>ConditionHost=</varname>
1046 may be used to match against the
1047 hostname or machine ID of the
1048 host. This either takes a hostname
1049 string (optionally with shell style
1050 globs) which is tested against the
1051 locally set hostname as returned by
1052 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1053 or a machine ID formatted as string
1055 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1056 The test may be negated by prepending
1057 an exclamation mark.</para>
1059 <para><varname>ConditionACPower=</varname>
1060 may be used to check whether the
1061 system has AC power, or is exclusively
1062 battery powered at the time of
1063 activation of the unit. This takes a
1064 boolean argument. If set to
1065 <varname>true</varname>, the condition
1066 will hold only if at least one AC
1067 connector of the system is connected
1068 to a power source, or if no AC
1069 connectors are known. Conversely, if
1070 set to <varname>false</varname>, the
1071 condition will hold only if there is
1072 at least one AC connector known and
1073 all AC connectors are disconnected
1074 from a power source.</para>
1077 <varname>ConditionNull=</varname> may
1078 be used to add a constant condition
1079 check value to the unit. It takes a
1080 boolean argument. If set to
1081 <varname>false</varname>, the condition
1082 will always fail, otherwise
1085 <para>If multiple conditions are
1086 specified, the unit will be executed if
1087 all of them apply (i.e. a logical AND
1088 is applied). Condition checks can be
1089 prefixed with a pipe symbol (|) in
1090 which case a condition becomes a
1091 triggering condition. If at least one
1092 triggering condition is defined for a
1093 unit, then the unit will be executed if
1094 at least one of the triggering
1095 conditions apply and all of the
1096 non-triggering conditions. If you
1097 prefix an argument with the pipe
1098 symbol and an exclamation mark, the
1099 pipe symbol must be passed first, the
1100 exclamation second. Except for
1101 <varname>ConditionPathIsSymbolicLink=</varname>,
1102 all path checks follow symlinks. If
1103 any of these options is assigned the
1104 empty string, the list of conditions is
1105 reset completely, all previous
1106 condition settings (of any kind) will
1107 have no effect.</para></listitem>
1111 <term><varname>SourcePath=</varname></term>
1112 <listitem><para>A path to a
1113 configuration file this unit has been
1114 generated from. This is primarily
1115 useful for implementation of generator
1116 tools that convert configuration from
1117 an external configuration file format
1118 into native unit files. Thus
1119 functionality should not be used in
1120 normal units.</para></listitem>
1124 <para>Unit file may include a [Install] section, which
1125 carries installation information for the unit. This
1126 section is not interpreted by
1127 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1128 during runtime. It is used exclusively by the
1129 <command>enable</command> and
1130 <command>disable</command> commands of the
1131 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1132 tool during installation of a unit:</para>
1134 <variablelist class='unit-directives'>
1136 <term><varname>Alias=</varname></term>
1138 <listitem><para>A space-seperated list
1139 of additional names this unit shall be
1140 installed under. The names listed here
1141 must have the same suffix (i.e. type)
1142 as the unit file name. This option may
1143 be specified more than once, in which
1144 case all listed names are used. At
1145 installation time, <command>systemctl
1146 enable</command> will create symlinks
1147 from these names to the unit
1148 filename.</para></listitem>
1152 <term><varname>WantedBy=</varname></term>
1153 <term><varname>RequiredBy=</varname></term>
1155 <listitem><para>This option may be
1156 used more than once, or a
1157 space-separated list of unit names may
1158 be given. A symbolic link is created
1159 in the <filename>.wants/</filename> or
1160 <filename>.requires/</filename>
1161 directory of each of the listed units
1162 when this unit is installed by
1163 <command>systemctl enable</command>.
1164 This has the effect that a dependency
1165 of type <varname>Wants=</varname> or
1166 <varname>Requires=</varname> is added
1167 from the listed unit to the current
1168 unit. The primary result is that the
1169 current unit will be started when the
1170 listed unit is started. See the
1172 <varname>Wants=</varname> and
1173 <varname>Requires=</varname> in the
1174 [Unit] section for details.</para>
1176 <para><command>WantedBy=foo.service</command>
1178 <filename>bar.service</filename> is
1179 mostly equivalent to
1180 <command>Alias=foo.service.wants/bar.service</command>
1181 in the same file. In case of template
1182 units, <command>systemctl enable</command>
1183 must be called with an instance name, and
1184 this instance will be added to the
1185 <filename>.wants/</filename> or
1186 <filename>.requires/</filename> list
1188 E.g. <command>WantedBy=getty.target</command>
1190 <filename>getty@.service</filename>
1191 will result in <command>systemctl
1192 enable getty@tty2.service</command>
1194 <filename>getty.target.wants/getty@tty2.service</filename>
1195 link to <filename>getty@.service</filename>.
1200 <term><varname>Also=</varname></term>
1202 <listitem><para>Additional units to
1203 install/deinstall when this unit is
1204 installed/deinstalled. If the user
1205 requests installation/deinstallation
1206 of a unit with this option configured,
1207 <command>systemctl enable</command>
1208 and <command>systemctl
1209 disable</command> will automatically
1210 install/uninstall units listed in this option as
1213 <para>This option may be used more
1214 than once, or a space-separated list
1215 of unit names may be
1216 given.</para></listitem>
1220 <para>The following specifiers are interpreted in the
1221 Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v.
1222 For their meaning see the next section.
1227 <title>Specifiers</title>
1229 <para>Many settings resolve specifiers which may be
1230 used to write generic unit files referring to runtime
1231 or unit parameters that are replaced when the unit
1232 files are loaded. The following specifiers are
1236 <title>Specifiers available in unit files</title>
1237 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1238 <colspec colname="spec" />
1239 <colspec colname="mean" />
1240 <colspec colname="detail" />
1243 <entry>Specifier</entry>
1244 <entry>Meaning</entry>
1245 <entry>Details</entry>
1250 <entry><literal>%n</literal></entry>
1251 <entry>Full unit name</entry>
1255 <entry><literal>%N</literal></entry>
1256 <entry>Unescaped full unit name</entry>
1260 <entry><literal>%p</literal></entry>
1261 <entry>Prefix name</entry>
1262 <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>
1265 <entry><literal>%P</literal></entry>
1266 <entry>Unescaped prefix name</entry>
1270 <entry><literal>%i</literal></entry>
1271 <entry>Instance name</entry>
1272 <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix.</entry>
1275 <entry><literal>%I</literal></entry>
1276 <entry>Unescaped instance name</entry>
1280 <entry><literal>%f</literal></entry>
1281 <entry>Unescaped filename</entry>
1282 <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>
1285 <entry><literal>%c</literal></entry>
1286 <entry>Control group path of the unit</entry>
1290 <entry><literal>%r</literal></entry>
1291 <entry>Root control group path where units are placed.</entry>
1292 <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>
1295 <entry><literal>%R</literal></entry>
1296 <entry>Parent directory of the control group path where units are placed.</entry>
1297 <entry>For system instances, this usually
1298 resolves to <filename>/</filename>, except in
1299 containers, where this resolves to the
1300 container's root directory.</entry>
1303 <entry><literal>%t</literal></entry>
1304 <entry>Runtime socket dir</entry>
1305 <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry>
1308 <entry><literal>%u</literal></entry>
1309 <entry>User name</entry>
1310 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1313 <entry><literal>%U</literal></entry>
1314 <entry>User UID</entry>
1315 <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1318 <entry><literal>%h</literal></entry>
1319 <entry>User home directory</entry>
1320 <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>
1323 <entry><literal>%s</literal></entry>
1324 <entry>User shell</entry>
1325 <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>
1328 <entry><literal>%m</literal></entry>
1329 <entry>Machine ID</entry>
1330 <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>
1333 <entry><literal>%b</literal></entry>
1334 <entry>Boot ID</entry>
1335 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1338 <entry><literal>%H</literal></entry>
1339 <entry>Host name</entry>
1340 <entry>The hostname of the running system.</entry>
1343 <entry><literal>%v</literal></entry>
1344 <entry>Kernel release</entry>
1345 <entry>Identical to <command>uname -r</command> output.</entry>
1348 <entry><literal>%%</literal></entry>
1349 <entry>Escaped %</entry>
1350 <entry>Single percent sign.</entry>
1358 <title>See Also</title>
1360 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1361 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1362 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1363 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1364 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1365 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1366 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1367 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1368 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1369 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1370 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1371 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1372 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1373 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1374 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1375 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1376 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1377 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1378 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>