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>/etc/systemd/user/*</filename>
74 <filename>/run/systemd/user/*</filename>
75 <filename>/usr/lib/systemd/user/*</filename>
76 <filename>...</filename>
77 </literallayout></para>
81 <title>Description</title>
83 <para>A unit configuration file encodes information
84 about a service, a socket, a device, a mount point, an
85 automount point, a swap file or partition, a start-up
86 target, a watched file system path, a timer controlled
88 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
89 a temporary system state snapshot, a resource
90 management slice or a group of externally created
91 processes. The syntax is inspired by <ulink
92 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
93 Desktop Entry Specification</ulink>
94 <filename>.desktop</filename> files, which are in turn
95 inspired by Microsoft Windows
96 <filename>.ini</filename> files.</para>
98 <para>This man page lists the common configuration
99 options of all the unit types. These options need to
100 be configured in the [Unit] or [Install]
101 sections of the unit files.</para>
103 <para>In addition to the generic [Unit] and [Install]
104 sections described here, each unit may have a
105 type-specific section, e.g. [Service] for a service
106 unit. See the respective man pages for more
108 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
109 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
110 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
111 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
112 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
113 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
114 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
115 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
116 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
117 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
118 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
119 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
122 <para>Unit files are loaded from a set of paths
123 determined during compilation, described in the next section.
126 <para>Unit files may contain additional options on top
127 of those listed here. If systemd encounters an unknown
128 option it will write a warning log message but
129 continue loading the unit. If an option is prefixed
130 with <option>X-</option> it is ignored completely by
131 systemd. Applications may use this to include
132 additional information in the unit files.</para>
134 <para>Boolean arguments used in unit files can be
135 written in various formats. For positive settings the
136 strings <option>1</option>, <option>yes</option>,
137 <option>true</option> and <option>on</option> are
138 equivalent. For negative settings the strings
139 <option>0</option>, <option>no</option>,
140 <option>false</option> and <option>off</option> are
143 <para>Time span values encoded in unit files can be
144 written in various formats. A stand-alone number
145 specifies a time in seconds. If suffixed with a time
146 unit, the unit is honored. A concatenation of multiple
147 values with units is supported, in which case the
148 values are added up. Example: "50" refers to 50
149 seconds; "2min 200ms" refers to 2 minutes plus 200
150 milliseconds, i.e. 120200ms. The following time units
151 are understood: s, min, h, d, w, ms, us. For details
153 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
155 <para>Empty lines and lines starting with # or ; are
156 ignored. This may be used for commenting. Lines ending
157 in a backslash are concatenated with the following
158 line while reading and the backslash is replaced by a
159 space character. This may be used to wrap long lines.</para>
161 <para>Along with a unit file
162 <filename>foo.service</filename> the directory
163 <filename>foo.service.wants/</filename> may exist. All
164 unit files symlinked from such a directory are
165 implicitly added as dependencies of type
166 <varname>Wanted=</varname> to the unit. This is useful
167 to hook units into the start-up of other units,
168 without having to modify their unit files. For details
169 about the semantics of <varname>Wanted=</varname> see
170 below. The preferred way to create symlinks in the
171 <filename>.wants/</filename> directory of a unit file
172 is with the <command>enable</command> command of the
173 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
174 tool which reads information from the [Install]
175 section of unit files (see below). A similar
176 functionality exists for <varname>Requires=</varname>
177 type dependencies as well, the directory suffix is
178 <filename>.requires/</filename> in this case.</para>
180 <para>Along with a unit file
181 <filename>foo.service</filename> a directory
182 <filename>foo.service.d/</filename> may exist. All
183 files with the suffix <literal>.conf</literal> from
184 this directory will be parsed after the file itself is
185 parsed. This is useful to alter or add configuration
186 settings to a unit, without having to modify their
187 unit files. Make sure that the file that is included
188 has the appropriate section headers before any
191 <para>If a line starts with <option>.include</option>
192 followed by a filename, the specified file will be
193 parsed at this point. Make sure that the file that is
194 included has the appropriate section headers before
195 any directives.</para>
197 <para>Note that while systemd offers a flexible
198 dependency system between units it is recommended to
199 use this functionality only sparingly and instead rely
200 on techniques such as bus-based or socket-based
201 activation which make dependencies implicit, resulting
202 in a both simpler and more flexible system.</para>
204 <para>Some unit names reflect paths existing in the
205 file system namespace. Example: a device unit
206 <filename>dev-sda.device</filename> refers to a device
207 with the device node <filename noindex='true'>/dev/sda</filename> in
208 the file system namespace. If this applies a special
209 way to escape the path name is used, so that the
210 result is usable as part of a filename. Basically,
211 given a path, "/" is replaced by "-", and all
212 unprintable characters and the "-" are replaced by
213 C-style "\x20" escapes. The root directory "/" is
214 encoded as single dash, while otherwise the initial
215 and ending "/" is removed from all paths during
216 transformation. This escaping is reversible.</para>
218 <para>Optionally, units may be instantiated from a
219 template file at runtime. This allows creation of
220 multiple units from a single configuration file. If
221 systemd looks for a unit configuration file it will
222 first search for the literal unit name in the
223 filesystem. If that yields no success and the unit
224 name contains an <literal>@</literal> character, systemd will look for a
225 unit template that shares the same name but with the
226 instance string (i.e. the part between the <literal>@</literal> character
227 and the suffix) removed. Example: if a service
228 <filename>getty@tty3.service</filename> is requested
229 and no file by that name is found, systemd will look
230 for <filename>getty@.service</filename> and
231 instantiate a service from that configuration file if
234 <para>To refer to the instance string from
235 within the configuration file you may use the special
236 <literal>%i</literal> specifier in many of the
237 configuration options. See below for details.</para>
239 <para>If a unit file is empty (i.e. has the file size
240 0) or is symlinked to <filename>/dev/null</filename>
241 its configuration will not be loaded and it appears
242 with a load state of <literal>masked</literal>, and
243 cannot be activated. Use this as an effective way to
244 fully disable a unit, making it impossible to start it
245 even manually.</para>
247 <para>The unit file format is covered by the
249 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
250 Stability Promise</ulink>.</para>
255 <title>Unit Load Path</title>
257 <para>Unit files are loaded from a set of paths
258 determined during compilation, described in the two
259 tables below. Unit files found in directories higher
260 in the hierarchy override files with the same name
261 lower in the hierarchy, thus allowing overrides.
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>/run/systemd/generator.early</filename></entry>
288 <entry>Generated units (early)</entry>
291 <entry><filename>/etc/systemd/system</filename></entry>
292 <entry>Local configuration</entry>
295 <entry><filename>/run/systemd/system</filename></entry>
296 <entry>Volatile units</entry>
299 <entry><filename>/run/systemd/generator</filename></entry>
300 <entry>Generated units (middle)</entry>
303 <entry><filename>/usr/local/lib/systemd/system</filename></entry>
304 <entry>Units for local packages</entry>
307 <entry><filename>/usr/lib/systemd/system</filename></entry>
308 <entry>Units for installed packages</entry>
311 <entry><filename>/run/systemd/generator.late</filename></entry>
312 <entry>Generated units (late)</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 (early)</entry>
338 <entry><filename>/etc/systemd/user</filename></entry>
339 <entry>Local configuration</entry>
342 <entry><filename>/run/systemd/user</filename></entry>
343 <entry>Volatile units</entry>
346 <entry><filename>/tmp/systemd-generator.<replaceable>XXXXXX</replaceable></filename></entry>
347 <entry>Generated units (middle)</entry>
350 <entry><filename>/usr/local/lib/systemd/user</filename></entry>
351 <entry>Units for local packages</entry>
354 <entry><filename>/usr/lib/systemd/user</filename></entry>
355 <entry>Units for installed packages</entry>
358 <entry><filename>/tmp/systemd-generator.late.<replaceable>XXXXXX</replaceable></filename></entry>
359 <entry>Generated units (late)</entry>
365 <para>Additional units might be loaded into systemd
366 ("linked") from directories not on the unit load
367 path. See the <command>link</command> command for
368 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
373 <title>Options</title>
375 <para>Unit file may include a [Unit] section, which
376 carries generic information about the unit that is not
377 dependent on the type of unit:</para>
379 <variablelist class='unit-directives'>
382 <term><varname>Description=</varname></term>
383 <listitem><para>A free-form string
384 describing the unit. This is intended
385 for use in UIs to show descriptive
386 information along with the unit
387 name.</para></listitem>
391 <term><varname>Documentation=</varname></term>
392 <listitem><para>A space-separated list
393 of URIs referencing documentation for
395 configuration. Accepted are only URIs
397 <literal>http://</literal>,
398 <literal>https://</literal>,
399 <literal>file:</literal>,
400 <literal>info:</literal>,
401 <literal>man:</literal>. For more
402 information about the syntax of these
404 <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
405 URIs should be listed in order of
406 relevance, starting with the most
407 relevant. It is a good idea to first
408 reference documentation that explains
409 what the unit's purpose is, followed
410 by how it is configured, followed by
411 any other related documentation. This
412 option may be specified more than once
413 in which case the specified list of
414 URIs is merged. If the empty string is
415 assigned to this option, the list is
416 reset and all prior assignments will
417 have no effect.</para></listitem>
421 <term><varname>Requires=</varname></term>
423 <listitem><para>Configures requirement
424 dependencies on other units. If this
425 unit gets activated, the units listed
426 here will be activated as well. If one
427 of the other units gets deactivated or
428 its activation fails, this unit will
429 be deactivated. This option may be
430 specified more than once, in which
431 case requirement dependencies for all
432 listed names are created. Note that
433 requirement dependencies do not
434 influence the order in which services
435 are started or stopped. This has to be
436 configured independently with the
437 <varname>After=</varname> or
438 <varname>Before=</varname> options. If
440 <filename>foo.service</filename>
442 <filename>bar.service</filename> as
444 <varname>Requires=</varname> and no
445 ordering is configured with
446 <varname>After=</varname> or
447 <varname>Before=</varname>, then both
448 units will be started simultaneously
449 and without any delay between them if
450 <filename>foo.service</filename> is
451 activated. Often it is a better choice
452 to use <varname>Wants=</varname>
454 <varname>Requires=</varname> in order
455 to achieve a system that is more
456 robust when dealing with failing
459 <para>Note that dependencies of this
460 type may also be configured outside of
461 the unit configuration file by
462 adding a symlink to a
463 <filename>.requires/</filename> directory
464 accompanying the unit file. For
465 details see above.</para></listitem>
469 <term><varname>RequiresOverridable=</varname></term>
471 <listitem><para>Similar to
472 <varname>Requires=</varname>.
473 Dependencies listed in
474 <varname>RequiresOverridable=</varname>
475 which cannot be fulfilled or fail to
476 start are ignored if the startup was
477 explicitly requested by the user. If
478 the start-up was pulled in indirectly
479 by some dependency or automatic
480 start-up of units that is not
481 requested by the user this dependency
482 must be fulfilled and otherwise the
483 transaction fails. Hence, this option
484 may be used to configure dependencies
485 that are normally honored unless the
486 user explicitly starts up the unit, in
487 which case whether they failed or not
488 is irrelevant.</para></listitem>
492 <term><varname>Requisite=</varname></term>
493 <term><varname>RequisiteOverridable=</varname></term>
495 <listitem><para>Similar to
496 <varname>Requires=</varname>
497 and <varname>RequiresOverridable=</varname>, respectively. However,
498 if a unit listed here is not started
499 already it will not be started and the
501 immediately.</para></listitem>
505 <term><varname>Wants=</varname></term>
507 <listitem><para>A weaker version of
508 <varname>Requires=</varname>. A unit
509 listed in this option will be started
510 if the configuring unit is. However,
511 if the listed unit fails to start up
512 or cannot be added to the transaction
513 this has no impact on the validity of
514 the transaction as a whole. This is
515 the recommended way to hook start-up
516 of one unit to the start-up of another
519 <para>Note that dependencies of this
520 type may also be configured outside of
521 the unit configuration file by
522 adding a symlink to a
523 <filename>.wants/</filename> directory
524 accompanying the unit file. For
525 details see above.</para></listitem>
529 <term><varname>BindsTo=</varname></term>
531 <listitem><para>Configures requirement
532 dependencies, very similar in style to
533 <varname>Requires=</varname>, however
534 in addition to this behavior it also
535 declares that this unit is stopped
536 when any of the units listed suddenly
537 disappears. Units can suddenly,
538 unexpectedly disappear if a service
539 terminates on its own choice, a device
540 is unplugged or a mount point
541 unmounted without involvement of
542 systemd.</para></listitem>
546 <term><varname>PartOf=</varname></term>
548 <listitem><para>Configures dependencies
549 similar to <varname>Requires=</varname>,
550 but limited to stopping and restarting
551 of units. When systemd stops or restarts
552 the units listed here, the action is
553 propagated to this unit.
554 Note that this is a one way dependency -
555 changes to this unit do not affect the
561 <term><varname>Conflicts=</varname></term>
563 <listitem><para>Configures negative
564 requirement dependencies. If a unit
566 <varname>Conflicts=</varname> setting
567 on another unit, starting the former
568 will stop the latter and vice
569 versa. Note that this setting is
570 independent of and orthogonal to the
571 <varname>After=</varname> and
572 <varname>Before=</varname> ordering
575 <para>If a unit A that conflicts with
576 a unit B is scheduled to be started at
577 the same time as B, the transaction
578 will either fail (in case both are
579 required part of the transaction) or
580 be modified to be fixed (in case one
581 or both jobs are not a required part
582 of the transaction). In the latter
583 case the job that is not the required
584 will be removed, or in case both are
585 not required the unit that conflicts
586 will be started and the unit that is
588 stopped.</para></listitem>
592 <term><varname>Before=</varname></term>
593 <term><varname>After=</varname></term>
595 <listitem><para>Configures ordering
596 dependencies between units. If a unit
597 <filename>foo.service</filename>
599 <option>Before=bar.service</option>
600 and both units are being started,
601 <filename>bar.service</filename>'s
602 start-up is delayed until
603 <filename>foo.service</filename> is
604 started up. Note that this setting is
605 independent of and orthogonal to the
606 requirement dependencies as configured
607 by <varname>Requires=</varname>. It is
608 a common pattern to include a unit
610 <varname>After=</varname> and
611 <varname>Requires=</varname> option in
612 which case the unit listed will be
613 started before the unit that is
614 configured with these options. This
615 option may be specified more than
616 once, in which case ordering
617 dependencies for all listed names are
618 created. <varname>After=</varname> is
620 <varname>Before=</varname>, i.e. while
621 <varname>After=</varname> ensures that
622 the configured unit is started after
623 the listed unit finished starting up,
624 <varname>Before=</varname> ensures the
625 opposite, i.e. that the configured
626 unit is fully started up before the
627 listed unit is started. Note that when
628 two units with an ordering dependency
629 between them are shut down, the
630 inverse of the start-up order is
631 applied. i.e. if a unit is configured
632 with <varname>After=</varname> on
633 another unit, the former is stopped
634 before the latter if both are shut
635 down. If one unit with an ordering
636 dependency on another unit is shut
637 down while the latter is started up,
638 the shut down is ordered before the
639 start-up regardless whether the
640 ordering dependency is actually of
641 type <varname>After=</varname> or
642 <varname>Before=</varname>. If two
643 units have no ordering dependencies
644 between them they are shut down
645 or started up simultaneously, and
647 place. </para></listitem>
651 <term><varname>OnFailure=</varname></term>
653 <listitem><para>Lists one or more
654 units that are activated when this
656 <literal>failed</literal>
657 state.</para></listitem>
661 <term><varname>PropagatesReloadTo=</varname></term>
662 <term><varname>ReloadPropagatedFrom=</varname></term>
664 <listitem><para>Lists one or more
665 units where reload requests on the
666 unit will be propagated to/on the
667 other unit will be propagated
668 from. Issuing a reload request on a
669 unit will automatically also enqueue a
670 reload request on all units that the
671 reload request shall be propagated to
673 settings.</para></listitem>
677 <term><varname>RequiresMountsFor=</varname></term>
679 <listitem><para>Takes a space-separated
680 list of absolute paths. Automatically
681 adds dependencies of type
682 <varname>Requires=</varname> and
683 <varname>After=</varname> for all
684 mount units required to access the
685 specified path.</para></listitem>
689 <term><varname>OnFailureIsolate=</varname></term>
691 <listitem><para>Takes a boolean
692 argument. If <option>true</option> the
694 <varname>OnFailure=</varname> will be
695 enqueued in isolation mode, i.e. all
696 units that are not its dependency will
697 be stopped. If this is set only a
698 single unit may be listed in
699 <varname>OnFailure=</varname>. Defaults
701 <option>false</option>.</para></listitem>
705 <term><varname>IgnoreOnIsolate=</varname></term>
707 <listitem><para>Takes a boolean
708 argument. If <option>true</option>
709 this unit will not be stopped when
710 isolating another unit. Defaults to
711 <option>false</option>.</para></listitem>
715 <term><varname>IgnoreOnSnapshot=</varname></term>
717 <listitem><para>Takes a boolean
718 argument. If <option>true</option>
719 this unit will not be included in
720 snapshots. Defaults to
721 <option>true</option> for device and
722 snapshot units, <option>false</option>
723 for the others.</para></listitem>
727 <term><varname>StopWhenUnneeded=</varname></term>
729 <listitem><para>Takes a boolean
730 argument. If <option>true</option>
731 this unit will be stopped when it is
732 no longer used. Note that in order to
733 minimize the work to be executed,
734 systemd will not stop units by default
735 unless they are conflicting with other
736 units, or the user explicitly
737 requested their shut down. If this
738 option is set, a unit will be
739 automatically cleaned up if no other
740 active unit requires it. Defaults to
741 <option>false</option>.</para></listitem>
745 <term><varname>RefuseManualStart=</varname></term>
746 <term><varname>RefuseManualStop=</varname></term>
748 <listitem><para>Takes a boolean
749 argument. If <option>true</option>
750 this unit can only be activated
751 or deactivated indirectly. In
752 this case explicit start-up
753 or termination requested by the
754 user is denied, however if it is
755 started or stopped as a
756 dependency of another unit, start-up
757 or termination will succeed. This
758 is mostly a safety feature to ensure
759 that the user does not accidentally
760 activate units that are not intended
761 to be activated explicitly, and not
762 accidentally deactivate units that are
763 not intended to be deactivated.
764 These options default to
765 <option>false</option>.</para></listitem>
769 <term><varname>AllowIsolate=</varname></term>
771 <listitem><para>Takes a boolean
772 argument. If <option>true</option>
773 this unit may be used with the
774 <command>systemctl isolate</command>
775 command. Otherwise this will be
776 refused. It probably is a good idea to
777 leave this disabled except for target
778 units that shall be used similar to
779 runlevels in SysV init systems, just
780 as a precaution to avoid unusable
781 system states. This option defaults to
782 <option>false</option>.</para></listitem>
786 <term><varname>DefaultDependencies=</varname></term>
788 <listitem><para>Takes a boolean
789 argument. If <option>true</option>
790 (the default), a few default
791 dependencies will implicitly be
792 created for the unit. The actual
793 dependencies created depend on the
794 unit type. For example, for service
795 units, these dependencies ensure that
796 the service is started only after
797 basic system initialization is
798 completed and is properly terminated on
799 system shutdown. See the respective
800 man pages for details. Generally, only
801 services involved with early boot or
802 late shutdown should set this option
803 to <option>false</option>. It is
804 highly recommended to leave this
805 option enabled for the majority of
806 common units. If set to
807 <option>false</option>, this option
808 does not disable all implicit
809 dependencies, just non-essential
810 ones.</para></listitem>
814 <term><varname>JobTimeoutSec=</varname></term>
816 <listitem><para>When clients are
817 waiting for a job of this unit to
818 complete, time out after the specified
819 time. If this time limit is reached
820 the job will be cancelled, the unit
821 however will not change state or even
822 enter the <literal>failed</literal>
823 mode. This value defaults to 0 (job
824 timeouts disabled), except for device
825 units. NB: this timeout is independent
826 from any unit-specific timeout (for
827 example, the timeout set with
828 <varname>Timeout=</varname> in service
829 units) as the job timeout has no
830 effect on the unit itself, only on the
831 job that might be pending for it. Or
832 in other words: unit-specific timeouts
833 are useful to abort unit state
834 changes, and revert them. The job
835 timeout set with this option however
836 is useful to abort only the job
837 waiting for the unit state to
838 change.</para></listitem>
842 <term><varname>ConditionPathExists=</varname></term>
843 <term><varname>ConditionPathExistsGlob=</varname></term>
844 <term><varname>ConditionPathIsDirectory=</varname></term>
845 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
846 <term><varname>ConditionPathIsMountPoint=</varname></term>
847 <term><varname>ConditionPathIsReadWrite=</varname></term>
848 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
849 <term><varname>ConditionFileNotEmpty=</varname></term>
850 <term><varname>ConditionFileIsExecutable=</varname></term>
851 <term><varname>ConditionKernelCommandLine=</varname></term>
852 <term><varname>ConditionVirtualization=</varname></term>
853 <term><varname>ConditionSecurity=</varname></term>
854 <term><varname>ConditionCapability=</varname></term>
855 <term><varname>ConditionHost=</varname></term>
856 <term><varname>ConditionACPower=</varname></term>
857 <term><varname>ConditionNull=</varname></term>
859 <listitem><para>Before starting a unit
860 verify that the specified condition is
861 true. If it is not true the starting
862 of the unit will be skipped, however
863 all ordering dependencies of it are
864 still respected. A failing condition
865 will not result in the unit being
866 moved into a failure state. The
867 condition is checked at the time the
868 queued start job is to be
872 <varname>ConditionPathExists=</varname>
873 a file existence condition is
874 checked before a unit is started. If
875 the specified absolute path name does
876 not exist the condition will
877 fail. If the absolute path name passed
879 <varname>ConditionPathExists=</varname>
880 is prefixed with an exclamation mark
881 (<literal>!</literal>), the test is negated, and the unit
882 is only started if the path does not
885 <para><varname>ConditionPathExistsGlob=</varname>
887 <varname>ConditionPathExists=</varname>,
888 but checks for the existence of at
889 least one file or directory matching
890 the specified globbing pattern.</para>
892 <para><varname>ConditionPathIsDirectory=</varname>
894 <varname>ConditionPathExists=</varname>
895 but verifies whether a certain path
899 <para><varname>ConditionPathIsSymbolicLink=</varname>
901 <varname>ConditionPathExists=</varname>
902 but verifies whether a certain path
903 exists and is a symbolic
906 <para><varname>ConditionPathIsMountPoint=</varname>
908 <varname>ConditionPathExists=</varname>
909 but verifies whether a certain path
910 exists and is a mount
913 <para><varname>ConditionPathIsReadWrite=</varname>
915 <varname>ConditionPathExists=</varname>
916 but verifies whether the underlying
917 file system is readable and writable
921 <para><varname>ConditionDirectoryNotEmpty=</varname>
923 <varname>ConditionPathExists=</varname>
924 but verifies whether a certain path
925 exists and is a non-empty
928 <para><varname>ConditionFileNotEmpty=</varname>
930 <varname>ConditionPathExists=</varname>
931 but verifies whether a certain path
932 exists and refers to a regular file
933 with a non-zero size.</para>
935 <para><varname>ConditionFileIsExecutable=</varname>
937 <varname>ConditionPathExists=</varname>
938 but verifies whether a certain path
939 exists, is a regular file and marked
943 <varname>ConditionKernelCommandLine=</varname>
944 may be used to check whether a
945 specific kernel command line option is
946 set (or if prefixed with the
947 exclamation mark unset). The argument
948 must either be a single word, or an
949 assignment (i.e. two words, separated
950 <literal>=</literal>). In the former
951 case the kernel command line is
952 searched for the word appearing as is,
953 or as left hand side of an
954 assignment. In the latter case the
955 exact assignment is looked for with
956 right and left hand side
959 <para><varname>ConditionVirtualization=</varname>
960 may be used to check whether the
961 system is executed in a virtualized
962 environment and optionally test
963 whether it is a specific
964 implementation. Takes either boolean
965 value to check if being executed in
966 any virtualized environment, or one of
967 <varname>vm</varname> and
968 <varname>container</varname> to test
969 against a generic type of
970 virtualization solution, or one of
971 <varname>qemu</varname>,
972 <varname>kvm</varname>,
973 <varname>vmware</varname>,
974 <varname>microsoft</varname>,
975 <varname>oracle</varname>,
976 <varname>xen</varname>,
977 <varname>bochs</varname>,
978 <varname>chroot</varname>,
979 <varname>uml</varname>,
980 <varname>openvz</varname>,
981 <varname>lxc</varname>,
982 <varname>lxc-libvirt</varname>,
983 <varname>systemd-nspawn</varname> to
984 test against a specific
985 implementation. If multiple
986 virtualization technologies are nested
987 only the innermost is considered. The
988 test may be negated by prepending an
989 exclamation mark.</para>
991 <para><varname>ConditionSecurity=</varname>
992 may be used to check whether the given
993 security module is enabled on the
994 system. Currently the recognized values
995 values are <varname>selinux</varname>,
996 <varname>apparmor</varname>,
997 <varname>ima</varname> and
998 <varname>smack</varname>.
999 The test may be negated by prepending
1003 <para><varname>ConditionCapability=</varname>
1004 may be used to check whether the given
1005 capability exists in the capability
1006 bounding set of the service manager
1007 (i.e. this does not check whether
1008 capability is actually available in
1009 the permitted or effective sets, see
1010 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1011 for details). Pass a capability name
1012 such as <literal>CAP_MKNOD</literal>,
1013 possibly prefixed with an exclamation
1014 mark to negate the check.</para>
1016 <para><varname>ConditionHost=</varname>
1017 may be used to match against the
1018 hostname or machine ID of the
1019 host. This either takes a hostname
1020 string (optionally with shell style
1021 globs) which is tested against the
1022 locally set hostname as returned by
1023 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1024 or a machine ID formatted as string
1026 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1027 The test may be negated by prepending
1028 an exclamation mark.</para>
1030 <para><varname>ConditionACPower=</varname>
1031 may be used to check whether the
1032 system has AC power, or is exclusively
1033 battery powered at the time of
1034 activation of the unit. This takes a
1035 boolean argument. If set to
1036 <varname>true</varname> the condition
1037 will hold only if at least one AC
1038 connector of the system is connected
1039 to a power source, or if no AC
1040 connectors are known. Conversely, if
1041 set to <varname>false</varname> the
1042 condition will hold only if there is
1043 at least one AC connector known and
1044 all AC connectors are disconnected
1045 from a power source.</para>
1048 <varname>ConditionNull=</varname> may
1049 be used to add a constant condition
1050 check value to the unit. It takes a
1051 boolean argument. If set to
1052 <varname>false</varname> the condition
1053 will always fail, otherwise
1056 <para>If multiple conditions are
1057 specified the unit will be executed if
1058 all of them apply (i.e. a logical AND
1059 is applied). Condition checks can be
1060 prefixed with a pipe symbol (|) in
1061 which case a condition becomes a
1062 triggering condition. If at least one
1063 triggering condition is defined for a
1064 unit then the unit will be executed if
1065 at least one of the triggering
1066 conditions apply and all of the
1067 non-triggering conditions. If you
1068 prefix an argument with the pipe
1069 symbol and an exclamation mark the
1070 pipe symbol must be passed first, the
1071 exclamation second. Except for
1072 <varname>ConditionPathIsSymbolicLink=</varname>,
1073 all path checks follow symlinks. If
1074 any of these options is assigned the
1075 empty string the list of conditions is
1076 reset completely, all previous
1077 condition settings (of any kind) will
1078 have no effect.</para></listitem>
1082 <term><varname>SourcePath=</varname></term>
1083 <listitem><para>A path to a
1084 configuration file this unit has been
1085 generated from. This is primarily
1086 useful for implementation of generator
1087 tools that convert configuration from
1088 an external configuration file format
1089 into native unit files. Thus
1090 functionality should not be used in
1091 normal units.</para></listitem>
1095 <para>Unit file may include a [Install] section, which
1096 carries installation information for the unit. This
1097 section is not interpreted by
1098 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1099 during runtime. It is used exclusively by the
1100 <command>enable</command> and
1101 <command>disable</command> commands of the
1102 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1103 tool during installation of a unit:</para>
1105 <variablelist class='unit-directives'>
1107 <term><varname>Alias=</varname></term>
1109 <listitem><para>Additional names this
1110 unit shall be installed under. The
1111 names listed here must have the same
1112 suffix (i.e. type) as the unit file
1113 name. This option may be specified
1114 more than once, in which case all
1115 listed names are used. At installation
1117 <command>systemctl enable</command>
1118 will create symlinks from these names
1119 to the unit filename.</para></listitem>
1123 <term><varname>WantedBy=</varname></term>
1124 <term><varname>RequiredBy=</varname></term>
1126 <listitem><para>A symbolic link is
1128 <filename>.wants/</filename> or
1129 <filename>.requires/</filename> directory
1130 of the listed unit when this unit is
1131 activated by <command>systemctl
1132 enable</command>. This has the effect
1133 that a dependency of type
1134 <varname>Wants=</varname> or
1135 <varname>Requires=</varname> is added
1136 from the listed unit to the current
1137 unit. The primary result is that the
1138 current unit will be started when the
1139 listed unit is started. See the
1141 <varname>Wants=</varname> and
1142 <varname>Requires=</varname> in the
1143 [Unit] section for details.</para>
1145 <para><command>WantedBy=foo.service</command>
1147 <filename>bar.service</filename> is
1148 mostly equivalent to
1149 <command>Alias=foo.service.wants/bar.service</command>
1150 in the same file. In case of template
1151 units, <command>systemctl enable</command>
1152 must be called with an instance name, and
1153 this instance will be added to the
1154 <filename>.wants/</filename> or
1155 <filename>.requires/</filename> list
1157 E.g. <command>WantedBy=getty.target</command>
1159 <filename>getty@.service</filename>
1160 will result in <command>systemctl
1161 enable getty@tty2.service</command>
1163 <filename>getty.target.wants/getty@tty2.service</filename>
1164 link to <filename>getty@.service</filename>.
1169 <term><varname>Also=</varname></term>
1171 <listitem><para>Additional units to
1172 install/deinstall when this unit is
1173 installed/deinstalled. If the user
1174 requests installation/deinstallation
1175 of a unit with this option configured,
1176 <command>systemctl enable</command>
1177 and <command>systemctl
1178 disable</command> will automatically
1179 install/uninstall units listed in this option as
1180 well.</para></listitem>
1184 <para>The following specifiers are interpreted in the
1185 Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v.
1186 For their meaning see the next section.
1191 <title>Specifiers</title>
1193 <para>Many settings resolve specifiers which may be
1194 used to write generic unit files referring to runtime
1195 or unit parameters that are replaced when the unit
1196 files are loaded. The following specifiers are
1200 <title>Specifiers available in unit files</title>
1201 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1202 <colspec colname="spec" />
1203 <colspec colname="mean" />
1204 <colspec colname="detail" />
1207 <entry>Specifier</entry>
1208 <entry>Meaning</entry>
1209 <entry>Details</entry>
1214 <entry><literal>%n</literal></entry>
1215 <entry>Full unit name</entry>
1219 <entry><literal>%N</literal></entry>
1220 <entry>Unescaped full unit name</entry>
1224 <entry><literal>%p</literal></entry>
1225 <entry>Prefix name</entry>
1226 <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>
1229 <entry><literal>%P</literal></entry>
1230 <entry>Unescaped prefix name</entry>
1234 <entry><literal>%i</literal></entry>
1235 <entry>Instance name</entry>
1236 <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix.</entry>
1239 <entry><literal>%I</literal></entry>
1240 <entry>Unescaped instance name</entry>
1244 <entry><literal>%f</literal></entry>
1245 <entry>Unescaped filename</entry>
1246 <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>
1249 <entry><literal>%c</literal></entry>
1250 <entry>Control group path of the unit</entry>
1254 <entry><literal>%r</literal></entry>
1255 <entry>Root control group path where units are placed.</entry>
1256 <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>
1259 <entry><literal>%R</literal></entry>
1260 <entry>Parent directory of the control group path where units are placed.</entry>
1261 <entry>For system instances this usually resolves to <filename>/</filename>, except in containers, where this resolves to the container's root directory. This specifier is particularly useful in the <varname>ControlGroup=</varname> setting (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</entry>
1264 <entry><literal>%t</literal></entry>
1265 <entry>Runtime socket dir</entry>
1266 <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry>
1269 <entry><literal>%u</literal></entry>
1270 <entry>User name</entry>
1271 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1274 <entry><literal>%U</literal></entry>
1275 <entry>User UID</entry>
1276 <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1279 <entry><literal>%h</literal></entry>
1280 <entry>User home directory</entry>
1281 <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>
1284 <entry><literal>%s</literal></entry>
1285 <entry>User shell</entry>
1286 <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>
1289 <entry><literal>%m</literal></entry>
1290 <entry>Machine ID</entry>
1291 <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>
1294 <entry><literal>%b</literal></entry>
1295 <entry>Boot ID</entry>
1296 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1299 <entry><literal>%H</literal></entry>
1300 <entry>Host name</entry>
1301 <entry>The hostname of the running system.</entry>
1304 <entry><literal>%v</literal></entry>
1305 <entry>Kernel release</entry>
1306 <entry>Identical to <command>uname -r</command> output.</entry>
1309 <entry><literal>%%</literal></entry>
1310 <entry>Escaped %</entry>
1311 <entry>Single percent sign.</entry>
1319 <title>See Also</title>
1321 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1322 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1323 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1324 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1325 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1326 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1327 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1328 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1329 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1330 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1331 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1332 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1333 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1334 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1335 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1336 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1337 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1338 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1339 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>