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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemd.unit">
27 <title>systemd.unit</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.unit</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.unit</refname>
47 <refpurpose>Unit configuration</refpurpose>
51 <para><filename><replaceable>service</replaceable>.service</filename>,
52 <filename><replaceable>socket</replaceable>.socket</filename>,
53 <filename><replaceable>device</replaceable>.device</filename>,
54 <filename><replaceable>mount</replaceable>.mount</filename>,
55 <filename><replaceable>automount</replaceable>.automount</filename>,
56 <filename><replaceable>swap</replaceable>.swap</filename>,
57 <filename><replaceable>target</replaceable>.target</filename>,
58 <filename><replaceable>path</replaceable>.path</filename>,
59 <filename><replaceable>timer</replaceable>.timer</filename>,
60 <filename><replaceable>snapshot</replaceable>.snapshot</filename></para>
62 <para><literallayout><filename>/etc/systemd/system/*</filename>
63 <filename>/run/systemd/system/*</filename>
64 <filename>/usr/lib/systemd/system/*</filename>
65 <filename>...</filename>
66 </literallayout></para>
68 <para><literallayout><filename>/etc/systemd/user/*</filename>
69 <filename>/run/systemd/user/*</filename>
70 <filename>/usr/lib/systemd/user/*</filename>
71 <filename>...</filename>
72 </literallayout></para>
76 <title>Description</title>
78 <para>A unit configuration file encodes information
79 about a service, a socket, a device, a mount point, an
80 automount point, a swap file or partition, a start-up
81 target, a file system path, or a timer controlled and
83 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
84 syntax is inspired by <ulink
85 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
86 Desktop Entry Specification</ulink> <filename>.desktop</filename> files, which are in turn
87 inspired by Microsoft Windows
88 <filename>.ini</filename> files.</para>
90 <para>This man page lists the common configuration
91 options of all the unit types. These options need to
92 be configured in the [Unit] or [Install]
93 sections of the unit files.</para>
95 <para>In addition to the generic [Unit] and [Install]
96 sections described here, each unit may have a
97 type-specific section, e.g. [Service] for a service
98 unit. See the respective man pages for more
100 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
101 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
102 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
103 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
104 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
105 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
106 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
107 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
108 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
109 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
112 <para>Unit files are loaded from a set of paths
113 determined during compilation, described in the next section.
116 <para>Unit files may contain additional options on top
117 of those listed here. If systemd encounters an unknown
118 option it will write a warning log message but
119 continue loading the unit. If an option is prefixed
120 with <option>X-</option> it is ignored completely by
121 systemd. Applications may use this to include
122 additional information in the unit files.</para>
124 <para>Boolean arguments used in unit files can be
125 written in various formats. For positive settings the
126 strings <option>1</option>, <option>yes</option>,
127 <option>true</option> and <option>on</option> are
128 equivalent. For negative settings the strings
129 <option>0</option>, <option>no</option>,
130 <option>false</option> and <option>off</option> are
133 <para>Time span values encoded in unit files can be
134 written in various formats. A stand-alone number
135 specifies a time in seconds. If suffixed with a time
136 unit, the unit is honored. A concatenation of multiple
137 values with units is supported, in which case the
138 values are added up. Example: "50" refers to 50
139 seconds; "2min 200ms" refers to 2 minutes plus 200
140 milliseconds, i.e. 120200ms. The following time units
141 are understood: s, min, h, d, w, ms, us. For details
143 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
145 <para>Empty lines and lines starting with # or ; are
146 ignored. This may be used for commenting. Lines ending
147 in a backslash are concatenated with the following
148 line while reading and the backslash is replaced by a
149 space character. This may be used to wrap long lines.</para>
151 <para>Along with a unit file
152 <filename>foo.service</filename> the directory
153 <filename>foo.service.wants/</filename> may exist. All
154 unit files symlinked from such a directory are
155 implicitly added as dependencies of type
156 <varname>Wanted=</varname> to the unit. This is useful
157 to hook units into the start-up of other units,
158 without having to modify their unit files. For details
159 about the semantics of <varname>Wanted=</varname> see
160 below. The preferred way to create symlinks in the
161 <filename>.wants/</filename> directory of a unit file
162 is with the <command>enable</command> command of the
163 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
164 tool which reads information from the [Install]
165 section of unit files (see below). A similar
166 functionality exists for <varname>Requires=</varname>
167 type dependencies as well, the directory suffix is
168 <filename>.requires/</filename> in this case.</para>
170 <para>Along with a unit file
171 <filename>foo.service</filename> a directory
172 <filename>foo.service.d/</filename> may exist. All
173 files with the suffix <filename>.conf</filename> from
174 this directory will be parsed after the file itself is
175 parsed. This is useful to alter or add configuration
176 settings to a unit, without having to modify their
177 unit files. Make sure that the file that is included
178 has the appropriate section headers before any
181 <para>If a line starts with <option>.include</option>
182 followed by a file name, the specified file will be
183 parsed at this point. Make sure that the file that is
184 included has the appropriate section headers before
185 any directives.</para>
187 <para>Note that while systemd offers a flexible
188 dependency system between units it is recommended to
189 use this functionality only sparingly and instead rely
190 on techniques such as bus-based or socket-based
191 activation which make dependencies implicit, resulting
192 in a both simpler and more flexible system.</para>
194 <para>Some unit names reflect paths existing in the
195 file system name space. Example: a device unit
196 <filename>dev-sda.device</filename> refers to a device
197 with the device node <filename>/dev/sda</filename> in
198 the file system namespace. If this applies a special
199 way to escape the path name is used, so that the
200 result is usable as part of a file name. Basically,
201 given a path, "/" is replaced by "-", and all
202 unprintable characters and the "-" are replaced by
203 C-style "\x20" escapes. The root directory "/" is
204 encoded as single dash, while otherwise the initial
205 and ending "/" is removed from all paths during
206 transformation. This escaping is reversible.</para>
208 <para>Optionally, units may be instantiated from a
209 template file at runtime. This allows creation of
210 multiple units from a single configuration file. If
211 systemd looks for a unit configuration file it will
212 first search for the literal unit name in the
213 filesystem. If that yields no success and the unit
214 name contains an @ character, systemd will look for a
215 unit template that shares the same name but with the
216 instance string (i.e. the part between the @ character
217 and the suffix) removed. Example: if a service
218 <filename>getty@tty3.service</filename> is requested
219 and no file by that name is found, systemd will look
220 for <filename>getty@.service</filename> and
221 instantiate a service from that configuration file if
224 <para>To refer to the instance string from
225 within the configuration file you may use the special
226 <literal>%i</literal> specifier in many of the
227 configuration options. See below for details.</para>
229 <para>If a unit file is empty (i.e. has the file size
230 0) or is symlinked to <filename>/dev/null</filename>
231 its configuration will not be loaded and it appears
232 with a load state of <literal>masked</literal>, and
233 cannot be activated. Use this as an effective way to
234 fully disable a unit, making it impossible to start it
235 even manually.</para>
237 <para>The unit file format is covered by the
239 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
240 Stability Promise</ulink>.</para>
245 <title>Unit load path</title>
247 <para>Unit files are loaded from a set of paths
248 determined during compilation, described in the two
249 tables below. Unit files found in directories higher
250 in the hierarchy override files with the same name
251 lower in the hierarchy, thus allowing overrides.
254 <para>When systemd is running in session mode
255 (<option>--user</option>) and the variable
256 <varname>$SYSTEMD_UNIT_PATH</varname> is set, this
257 contents of this variable overrides the unit load
263 Load path when running in system mode (<option>--system</option>).
267 <colspec colname='path' />
268 <colspec colname='expl' />
272 <entry>Description</entry>
277 <entry><filename>/run/systemd/generator.early</filename></entry>
278 <entry>Generated units</entry>
281 <entry><filename>@SYSTEM_CONFIG_UNIT_PATH@</filename></entry>
282 <entry morerows='1'>Local configuration</entry>
285 <entry><filename>/etc/systemd/system</filename></entry>
288 <entry><filename>/run/systemd/systemd</filename></entry>
289 <entry>Volatile units</entry>
292 <entry><filename>/run/systemd/generator</filename></entry>
293 <entry>Generated units</entry>
296 <entry><filename>/usr/local/lib/systemd/system</filename></entry>
297 <entry>Units for local packages</entry>
300 <entry><filename>@systemunitdir@</filename></entry>
301 <entry>Systemd package configuration</entry>
304 <entry><filename>/usr/lib/systemd/system</filename></entry>
305 <entry morerows='1'>Units for installed packages</entry>
308 <entry><filename>/lib/systemd/system</filename></entry>
311 <entry><filename>/run/systemd/generator.late</filename></entry>
312 <entry>Generated units</entry>
320 Load path when running in session mode (<option>--user</option>).
324 <colspec colname='path' />
325 <colspec colname='expl' />
329 <entry>Description</entry>
334 <entry><filename>/tmp/systemd-generator.early.<replaceable>XXXXXX</replaceable></filename></entry>
335 <entry>Generated units</entry>
338 <entry><filename>@USER_CONFIG_UNIT_PATH@</filename></entry>
339 <entry morerows='1'>Local configuration</entry>
342 <entry><filename>/etc/systemd/user</filename></entry>
345 <entry><filename>/run/systemd/user</filename></entry>
346 <entry>Volatile units</entry>
349 <entry><filename>/tmp/systemd-generator.<replaceable>XXXXXX</replaceable></filename></entry>
350 <entry>Generated units</entry>
353 <entry><filename>/usr/local/lib/systemd/user</filename></entry>
354 <entry morerows='1'>Units for local packages</entry>
357 <entry><filename>/usr/local/share/systemd/user</filename></entry>
360 <entry><filename>@userunitdir@</filename></entry>
361 <entry>Systemd package configuration</entry>
364 <entry><filename>/usr/lib/systemd/user</filename></entry>
365 <entry morerows='1'>Units for installed packages</entry>
368 <entry><filename>/usr/share/systemd/user</filename></entry>
371 <entry><filename>/tmp/systemd-generator.late.<replaceable>XXXXXX</replaceable></filename></entry>
372 <entry>Generated units</entry>
378 <para>Note: the paths listed above are set at
379 compilation time and differ between distributions. The
380 "authorative" list is printed by
381 <command>systemd</command> at during start and daemon
382 reconfiguration.</para>
384 <para>Additional units might be loaded into systemd
385 ("linked") from directories not on the unit load
386 path. See the <command>link</command> command for
387 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
392 <title>Options</title>
394 <para>Unit file may include a [Unit] section, which
395 carries generic information about the unit that is not
396 dependent on the type of unit:</para>
398 <variablelist class='unit-directives'>
401 <term><varname>Description=</varname></term>
402 <listitem><para>A free-form string
403 describing the unit. This is intended
404 for use in UIs to show descriptive
405 information along with the unit
406 name.</para></listitem>
410 <term><varname>Documentation=</varname></term>
411 <listitem><para>A space separated list
412 of URIs referencing documentation for
414 configuration. Accepted are only URIs
416 <literal>http://</literal>,
417 <literal>https://</literal>,
418 <literal>file:</literal>,
419 <literal>info:</literal>,
420 <literal>man:</literal>. For more
421 information about the syntax of these
423 <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
424 URIs should be listed in order of
425 relevance, starting with the most
426 relevant. It is a good idea to first
427 reference documentation that explains
428 what the unit's purpose is, followed
429 by how it is configured, followed by
430 any other related documentation. This
431 option may be specified more than once
432 in which case the specified list of
433 URIs is merged. If the empty string is
434 assigned to this option the list is
435 reset and all prior assignments will
436 have no effect.</para></listitem>
440 <term><varname>Requires=</varname></term>
442 <listitem><para>Configures requirement
443 dependencies on other units. If this
444 unit gets activated, the units listed
445 here will be activated as well. If one
446 of the other units gets deactivated or
447 its activation fails, this unit will
448 be deactivated. This option may be
449 specified more than once, in which
450 case requirement dependencies for all
451 listed names are created. Note that
452 requirement dependencies do not
453 influence the order in which services
454 are started or stopped. This has to be
455 configured independently with the
456 <varname>After=</varname> or
457 <varname>Before=</varname> options. If
459 <filename>foo.service</filename>
461 <filename>bar.service</filename> as
463 <varname>Requires=</varname> and no
464 ordering is configured with
465 <varname>After=</varname> or
466 <varname>Before=</varname>, then both
467 units will be started simultaneously
468 and without any delay between them if
469 <filename>foo.service</filename> is
470 activated. Often it is a better choice
471 to use <varname>Wants=</varname>
473 <varname>Requires=</varname> in order
474 to achieve a system that is more
475 robust when dealing with failing
478 <para>Note that dependencies of this
479 type may also be configured outside of
480 the unit configuration file by
481 adding a symlink to a
482 <filename>.requires/</filename> directory
483 accompanying the unit file. For
484 details see above.</para></listitem>
488 <term><varname>RequiresOverridable=</varname></term>
490 <listitem><para>Similar to
491 <varname>Requires=</varname>.
492 Dependencies listed in
493 <varname>RequiresOverridable=</varname>
494 which cannot be fulfilled or fail to
495 start are ignored if the startup was
496 explicitly requested by the user. If
497 the start-up was pulled in indirectly
498 by some dependency or automatic
499 start-up of units that is not
500 requested by the user this dependency
501 must be fulfilled and otherwise the
502 transaction fails. Hence, this option
503 may be used to configure dependencies
504 that are normally honored unless the
505 user explicitly starts up the unit, in
506 which case whether they failed or not
507 is irrelevant.</para></listitem>
511 <term><varname>Requisite=</varname></term>
512 <term><varname>RequisiteOverridable=</varname></term>
514 <listitem><para>Similar to
515 <varname>Requires=</varname>
516 and <varname>RequiresOverridable=</varname>, respectively. However,
517 if a unit listed here is not started
518 already it will not be started and the
520 immediately.</para></listitem>
524 <term><varname>Wants=</varname></term>
526 <listitem><para>A weaker version of
527 <varname>Requires=</varname>. A unit
528 listed in this option will be started
529 if the configuring unit is. However,
530 if the listed unit fails to start up
531 or cannot be added to the transaction
532 this has no impact on the validity of
533 the transaction as a whole. This is
534 the recommended way to hook start-up
535 of one unit to the start-up of another
538 <para>Note that dependencies of this
539 type may also be configured outside of
540 the unit configuration file by
541 adding a symlink to a
542 <filename>.wants/</filename> directory
543 accompanying the unit file. For
544 details see above.</para></listitem>
548 <term><varname>BindsTo=</varname></term>
550 <listitem><para>Configures requirement
551 dependencies, very similar in style to
552 <varname>Requires=</varname>, however
553 in addition to this behavior it also
554 declares that this unit is stopped
555 when any of the units listed suddenly
556 disappears. Units can suddenly,
557 unexpectedly disappear if a service
558 terminates on its own choice, a device
559 is unplugged or a mount point
560 unmounted without involvement of
561 systemd.</para></listitem>
565 <term><varname>PartOf=</varname></term>
567 <listitem><para>Configures dependencies
568 similar to <varname>Requires=</varname>,
569 but limited to stopping and restarting
570 of units. When systemd stops or restarts
571 the units listed here, the action is
572 propagated to this unit.
573 Note that this is a one way dependency -
574 changes to this unit do not affect the
580 <term><varname>Conflicts=</varname></term>
582 <listitem><para>Configures negative
583 requirement dependencies. If a unit
585 <varname>Conflicts=</varname> setting
586 on another unit, starting the former
587 will stop the latter and vice
588 versa. Note that this setting is
589 independent of and orthogonal to the
590 <varname>After=</varname> and
591 <varname>Before=</varname> ordering
594 <para>If a unit A that conflicts with
595 a unit B is scheduled to be started at
596 the same time as B, the transaction
597 will either fail (in case both are
598 required part of the transaction) or
599 be modified to be fixed (in case one
600 or both jobs are not a required part
601 of the transaction). In the latter
602 case the job that is not the required
603 will be removed, or in case both are
604 not required the unit that conflicts
605 will be started and the unit that is
607 stopped.</para></listitem>
611 <term><varname>Before=</varname></term>
612 <term><varname>After=</varname></term>
614 <listitem><para>Configures ordering
615 dependencies between units. If a unit
616 <filename>foo.service</filename>
618 <option>Before=bar.service</option>
619 and both units are being started,
620 <filename>bar.service</filename>'s
621 start-up is delayed until
622 <filename>foo.service</filename> is
623 started up. Note that this setting is
624 independent of and orthogonal to the
625 requirement dependencies as configured
626 by <varname>Requires=</varname>. It is
627 a common pattern to include a unit
629 <varname>After=</varname> and
630 <varname>Requires=</varname> option in
631 which case the unit listed will be
632 started before the unit that is
633 configured with these options. This
634 option may be specified more than
635 once, in which case ordering
636 dependencies for all listed names are
637 created. <varname>After=</varname> is
639 <varname>Before=</varname>, i.e. while
640 <varname>After=</varname> ensures that
641 the configured unit is started after
642 the listed unit finished starting up,
643 <varname>Before=</varname> ensures the
644 opposite, i.e. that the configured
645 unit is fully started up before the
646 listed unit is started. Note that when
647 two units with an ordering dependency
648 between them are shut down, the
649 inverse of the start-up order is
650 applied. i.e. if a unit is configured
651 with <varname>After=</varname> on
652 another unit, the former is stopped
653 before the latter if both are shut
654 down. If one unit with an ordering
655 dependency on another unit is shut
656 down while the latter is started up,
657 the shut down is ordered before the
658 start-up regardless whether the
659 ordering dependency is actually of
660 type <varname>After=</varname> or
661 <varname>Before=</varname>. If two
662 units have no ordering dependencies
663 between them they are shut down
664 or started up simultaneously, and
666 place. </para></listitem>
670 <term><varname>OnFailure=</varname></term>
672 <listitem><para>Lists one or more
673 units that are activated when this
675 '<literal>failed</literal>'
676 state.</para></listitem>
680 <term><varname>PropagatesReloadTo=</varname></term>
681 <term><varname>ReloadPropagatedFrom=</varname></term>
683 <listitem><para>Lists one or more
684 units where reload requests on the
685 unit will be propagated to/on the
686 other unit will be propagated
687 from. Issuing a reload request on a
688 unit will automatically also enqueue a
689 reload request on all units that the
690 reload request shall be propagated to
692 settings.</para></listitem>
696 <term><varname>RequiresMountsFor=</varname></term>
698 <listitem><para>Takes a space
699 separated 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>OnFailureIsolate=</varname></term>
710 <listitem><para>Takes a boolean
711 argument. If <option>true</option> the
713 <varname>OnFailure=</varname> will be
714 enqueued in isolation mode, i.e. all
715 units that are not its dependency will
716 be stopped. If this is set only a
717 single unit may be listed in
718 <varname>OnFailure=</varname>. Defaults
720 <option>false</option>.</para></listitem>
724 <term><varname>IgnoreOnIsolate=</varname></term>
726 <listitem><para>Takes a boolean
727 argument. If <option>true</option>
728 this unit will not be stopped when
729 isolating another unit. Defaults to
730 <option>false</option>.</para></listitem>
734 <term><varname>IgnoreOnSnapshot=</varname></term>
736 <listitem><para>Takes a boolean
737 argument. If <option>true</option>
738 this unit will not be included in
739 snapshots. Defaults to
740 <option>true</option> for device and
741 snapshot units, <option>false</option>
742 for the others.</para></listitem>
746 <term><varname>StopWhenUnneeded=</varname></term>
748 <listitem><para>Takes a boolean
749 argument. If <option>true</option>
750 this unit will be stopped when it is
751 no longer used. Note that in order to
752 minimize the work to be executed,
753 systemd will not stop units by default
754 unless they are conflicting with other
755 units, or the user explicitly
756 requested their shut down. If this
757 option is set, a unit will be
758 automatically cleaned up if no other
759 active unit requires it. Defaults to
760 <option>false</option>.</para></listitem>
764 <term><varname>RefuseManualStart=</varname></term>
765 <term><varname>RefuseManualStop=</varname></term>
767 <listitem><para>Takes a boolean
768 argument. If <option>true</option>
769 this unit can only be activated
770 or deactivated indirectly. In
771 this case explicit start-up
772 or termination requested by the
773 user is denied, however if it is
774 started or stopped as a
775 dependency of another unit, start-up
776 or termination will succeed. This
777 is mostly a safety feature to ensure
778 that the user does not accidentally
779 activate units that are not intended
780 to be activated explicitly, and not
781 accidentally deactivate units that are
782 not intended to be deactivated.
783 These options default to
784 <option>false</option>.</para></listitem>
788 <term><varname>AllowIsolate=</varname></term>
790 <listitem><para>Takes a boolean
791 argument. If <option>true</option>
792 this unit may be used with the
793 <command>systemctl isolate</command>
794 command. Otherwise this will be
795 refused. It probably is a good idea to
796 leave this disabled except for target
797 units that shall be used similar to
798 runlevels in SysV init systems, just
799 as a precaution to avoid unusable
800 system states. This option defaults to
801 <option>false</option>.</para></listitem>
805 <term><varname>DefaultDependencies=</varname></term>
807 <listitem><para>Takes a boolean
808 argument. If <option>true</option>
809 (the default), a few default
810 dependencies will implicitly be
811 created for the unit. The actual
812 dependencies created depend on the
813 unit type. For example, for service
814 units, these dependencies ensure that
815 the service is started only after
816 basic system initialization is
817 completed and is properly terminated on
818 system shutdown. See the respective
819 man pages for details. Generally, only
820 services involved with early boot or
821 late shutdown should set this option
822 to <option>false</option>. It is
823 highly recommended to leave this
824 option enabled for the majority of
825 common units. If set to
826 <option>false</option> this option
827 does not disable all implicit
828 dependencies, just non-essential
829 ones.</para></listitem>
833 <term><varname>JobTimeoutSec=</varname></term>
835 <listitem><para>When clients are
836 waiting for a job of this unit to
837 complete, time out after the specified
838 time. If this time limit is reached
839 the job will be cancelled, the unit
840 however will not change state or even
841 enter the '<literal>failed</literal>'
842 mode. This value defaults to 0 (job
843 timeouts disabled), except for device
844 units. NB: this timeout is independent
845 from any unit-specific timeout (for
846 example, the timeout set with
847 <varname>Timeout=</varname> in service
848 units) as the job timeout has no
849 effect on the unit itself, only on the
850 job that might be pending for it. Or
851 in other words: unit-specific timeouts
852 are useful to abort unit state
853 changes, and revert them. The job
854 timeout set with this option however
855 is useful to abort only the job
856 waiting for the unit state to
857 change.</para></listitem>
861 <term><varname>ConditionPathExists=</varname></term>
862 <term><varname>ConditionPathExistsGlob=</varname></term>
863 <term><varname>ConditionPathIsDirectory=</varname></term>
864 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
865 <term><varname>ConditionPathIsMountPoint=</varname></term>
866 <term><varname>ConditionPathIsReadWrite=</varname></term>
867 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
868 <term><varname>ConditionFileNotEmpty=</varname></term>
869 <term><varname>ConditionFileIsExecutable=</varname></term>
870 <term><varname>ConditionKernelCommandLine=</varname></term>
871 <term><varname>ConditionVirtualization=</varname></term>
872 <term><varname>ConditionSecurity=</varname></term>
873 <term><varname>ConditionCapability=</varname></term>
874 <term><varname>ConditionHost=</varname></term>
875 <term><varname>ConditionACPower=</varname></term>
876 <term><varname>ConditionNull=</varname></term>
878 <listitem><para>Before starting a unit
879 verify that the specified condition is
880 true. If it is not true the starting
881 of the unit will be skipped, however
882 all ordering dependencies of it are
883 still respected. A failing condition
884 will not result in the unit being
885 moved into a failure state. The
886 condition is checked at the time the
887 queued start job is to be
891 <varname>ConditionPathExists=</varname>
892 a file existence condition is
893 checked before a unit is started. If
894 the specified absolute path name does
895 not exist the condition will
896 fail. If the absolute path name passed
898 <varname>ConditionPathExists=</varname>
899 is prefixed with an exclamation mark
900 ('!'), the test is negated, and the unit
901 is only started if the path does not
904 <para><varname>ConditionPathExistsGlob=</varname>
906 <varname>ConditionPathExists=</varname>,
907 but checks for the existence of at
908 least one file or directory matching
909 the specified globbing pattern.</para>
911 <para><varname>ConditionPathIsDirectory=</varname>
913 <varname>ConditionPathExists=</varname>
914 but verifies whether a certain path
918 <para><varname>ConditionPathIsSymbolicLink=</varname>
920 <varname>ConditionPathExists=</varname>
921 but verifies whether a certain path
922 exists and is a symbolic
925 <para><varname>ConditionPathIsMountPoint=</varname>
927 <varname>ConditionPathExists=</varname>
928 but verifies whether a certain path
929 exists and is a mount
932 <para><varname>ConditionPathIsReadWrite=</varname>
934 <varname>ConditionPathExists=</varname>
935 but verifies whether the underlying
936 file system is readable and writable
940 <para><varname>ConditionDirectoryNotEmpty=</varname>
942 <varname>ConditionPathExists=</varname>
943 but verifies whether a certain path
944 exists and is a non-empty
947 <para><varname>ConditionFileNotEmpty=</varname>
949 <varname>ConditionPathExists=</varname>
950 but verifies whether a certain path
951 exists and refers to a regular file
952 with a non-zero size.</para>
954 <para><varname>ConditionFileIsExecutable=</varname>
956 <varname>ConditionPathExists=</varname>
957 but verifies whether a certain path
958 exists, is a regular file and marked
962 <varname>ConditionKernelCommandLine=</varname>
963 may be used to check whether a
964 specific kernel command line option is
965 set (or if prefixed with the
966 exclamation mark unset). The argument
967 must either be a single word, or an
968 assignment (i.e. two words, separated
970 case the kernel command line is
971 searched for the word appearing as is,
972 or as left hand side of an
973 assignment. In the latter case the
974 exact assignment is looked for with
975 right and left hand side
978 <para><varname>ConditionVirtualization=</varname>
979 may be used to check whether the
980 system is executed in a virtualized
981 environment and optionally test
982 whether it is a specific
983 implementation. Takes either boolean
984 value to check if being executed in
985 any virtualized environment, or one of
986 <varname>vm</varname> and
987 <varname>container</varname> to test
988 against a generic type of
989 virtualization solution, or one of
990 <varname>qemu</varname>,
991 <varname>kvm</varname>,
992 <varname>vmware</varname>,
993 <varname>microsoft</varname>,
994 <varname>oracle</varname>,
995 <varname>xen</varname>,
996 <varname>bochs</varname>,
997 <varname>chroot</varname>,
998 <varname>openvz</varname>,
999 <varname>lxc</varname>,
1000 <varname>lxc-libvirt</varname>,
1001 <varname>systemd-nspawn</varname> to
1002 test against a specific
1003 implementation. If multiple
1004 virtualization technologies are nested
1005 only the innermost is considered. The
1006 test may be negated by prepending an
1007 exclamation mark.</para>
1009 <para><varname>ConditionSecurity=</varname>
1010 may be used to check whether the given
1011 security module is enabled on the
1012 system. Currently the only recognized
1013 value is <varname>selinux</varname>.
1014 The test may be negated by prepending
1018 <para><varname>ConditionCapability=</varname>
1019 may be used to check whether the given
1020 capability exists in the capability
1021 bounding set of the service manager
1022 (i.e. this does not check whether
1023 capability is actually available in
1024 the permitted or effective sets, see
1025 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1026 for details). Pass a capability name
1027 such as <literal>CAP_MKNOD</literal>,
1028 possibly prefixed with an exclamation
1029 mark to negate the check.</para>
1031 <para><varname>ConditionHost=</varname>
1032 may be used to match against the
1033 host name or machine ID of the
1034 host. This either takes a host name
1035 string (optionally with shell style
1036 globs) which is tested against the
1037 locally set host name as returned by
1038 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1039 or a machine ID formatted as string
1041 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1042 The test may be negated by prepending
1043 an exclamation mark.</para>
1045 <para><varname>ConditionACPower=</varname>
1046 may be used to check whether the
1047 system has AC power, or is exclusively
1048 battery powered at the time of
1049 activation of the unit. This takes a
1050 boolean argument. If set to
1051 <varname>true</varname> the condition
1052 will hold only if at least one AC
1053 connector of the system is connected
1054 to a power source, or if no AC
1055 connectors are known. Conversely, if
1056 set to <varname>false</varname> the
1057 condition will hold only if there is
1058 at least one AC connector known and
1059 all AC connectors are disconnected
1060 from a power source.</para>
1063 <varname>ConditionNull=</varname> may
1064 be used to add a constant condition
1065 check value to the unit. It takes a
1066 boolean argument. If set to
1067 <varname>false</varname> the condition
1068 will always fail, otherwise
1071 <para>If multiple conditions are
1072 specified the unit will be executed if
1073 all of them apply (i.e. a logical AND
1074 is applied). Condition checks can be
1075 prefixed with a pipe symbol (|) in
1076 which case a condition becomes a
1077 triggering condition. If at least one
1078 triggering condition is defined for a
1079 unit then the unit will be executed if
1080 at least one of the triggering
1081 conditions apply and all of the
1082 non-triggering conditions. If you
1083 prefix an argument with the pipe
1084 symbol and an exclamation mark the
1085 pipe symbol must be passed first, the
1086 exclamation second. Except for
1087 <varname>ConditionPathIsSymbolicLink=</varname>,
1088 all path checks follow symlinks. If
1089 any of these options is assigned the
1090 empty string the list of conditions is
1091 reset completely, all previous
1092 condition settings (of any kind) will
1093 have no effect.</para></listitem>
1097 <term><varname>SourcePath=</varname></term>
1098 <listitem><para>A path to a
1099 configuration file this unit has been
1100 generated from. This is primarily
1101 useful for implementation of generator
1102 tools that convert configuration from
1103 an external configuration file format
1104 into native unit files. Thus
1105 functionality should not be used in
1106 normal units.</para></listitem>
1110 <para>Unit file may include a [Install] section, which
1111 carries installation information for the unit. This
1112 section is not interpreted by
1113 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1114 during runtime. It is used exclusively by the
1115 <command>enable</command> and
1116 <command>disable</command> commands of the
1117 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1118 tool during installation of a unit:</para>
1120 <variablelist class='unit-directives'>
1122 <term><varname>Alias=</varname></term>
1124 <listitem><para>Additional names this
1125 unit shall be installed under. The
1126 names listed here must have the same
1127 suffix (i.e. type) as the unit file
1128 name. This option may be specified
1129 more than once, in which case all
1130 listed names are used. At installation
1132 <command>systemctl enable</command>
1133 will create symlinks from these names
1134 to the unit file name.</para></listitem>
1138 <term><varname>WantedBy=</varname></term>
1139 <term><varname>RequiredBy=</varname></term>
1141 <listitem><para>Installs a symlink in
1142 the <filename>.wants/</filename>
1143 or <filename>.requires/</filename>
1144 subdirectory for a unit, respectively. This has the
1145 effect that when the listed unit name
1146 is activated the unit listing it is
1148 too. <command>WantedBy=foo.service</command>
1150 <filename>bar.service</filename> is
1151 mostly equivalent to
1152 <command>Alias=foo.service.wants/bar.service</command>
1153 in the same file.</para></listitem>
1157 <term><varname>Also=</varname></term>
1159 <listitem><para>Additional units to
1160 install when this unit is
1161 installed. If the user requests
1162 installation of a unit with this
1164 <command>systemctl enable</command>
1165 will automatically install units
1166 listed in this option as
1167 well.</para></listitem>
1171 <para>The following specifiers are interpreted in the
1172 Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b.
1173 For their meaning see the next section.
1178 <title>Specifiers</title>
1180 <para>Many settings resolve specifiers which may be
1181 used to write generic unit files referring to runtime
1182 or unit parameters that are replaced when the unit
1183 files are loaded. The following specifiers are
1187 <title>Specifiers available in unit files</title>
1188 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1189 <colspec colname="spec" />
1190 <colspec colname="mean" />
1191 <colspec colname="detail" />
1194 <entry>Specifier</entry>
1195 <entry>Meaning</entry>
1196 <entry>Details</entry>
1201 <entry><literal>%n</literal></entry>
1202 <entry>Full unit name</entry>
1206 <entry><literal>%N</literal></entry>
1207 <entry>Unescaped full unit name</entry>
1211 <entry><literal>%p</literal></entry>
1212 <entry>Prefix name</entry>
1213 <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>
1216 <entry><literal>%P</literal></entry>
1217 <entry>Unescaped prefix name</entry>
1221 <entry><literal>%i</literal></entry>
1222 <entry>Instance name</entry>
1223 <entry>For instantiated units: this is the string between the @ character and the suffix.</entry>
1226 <entry><literal>%I</literal></entry>
1227 <entry>Unescaped instance name</entry>
1231 <entry><literal>%f</literal></entry>
1232 <entry>Unescaped file name</entry>
1233 <entry>This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /.</entry>
1236 <entry><literal>%c</literal></entry>
1237 <entry>Control group path of the unit</entry>
1241 <entry><literal>%r</literal></entry>
1242 <entry>Root control group path of systemd</entry>
1246 <entry><literal>%R</literal></entry>
1247 <entry>Parent directory of the root control group path of systemd</entry>
1251 <entry><literal>%t</literal></entry>
1252 <entry>Runtime socket dir</entry>
1253 <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry>
1256 <entry><literal>%u</literal></entry>
1257 <entry>User name</entry>
1258 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1261 <entry><literal>%U</literal></entry>
1262 <entry>User UID</entry>
1263 <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1266 <entry><literal>%h</literal></entry>
1267 <entry>User home directory</entry>
1268 <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>
1271 <entry><literal>%s</literal></entry>
1272 <entry>User shell</entry>
1273 <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1276 <entry><literal>%m</literal></entry>
1277 <entry>Machine ID</entry>
1278 <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>
1281 <entry><literal>%b</literal></entry>
1282 <entry>Boot ID</entry>
1283 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1286 <entry><literal>%H</literal></entry>
1287 <entry>Host name</entry>
1288 <entry>The host name of the running system.</entry>
1296 <title>See Also</title>
1298 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1299 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1300 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1301 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1302 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1303 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1304 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1305 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1306 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1307 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1308 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1309 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1310 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1311 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1312 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1313 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>