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>Various settings are allowed to be specified
124 more than once, in which case the interpretation
125 depends on the setting. Often, multiple settings form
126 a list, and setting to an empty value "resets", which
127 means that previous assignments are ignored. When this
128 is allowed, it is mentioned in the description of the
129 setting. Note that using multiple assignments to the
130 same value makes the unit file incompatible with
131 parsers for the XDG <filename>.desktop</filename> file
134 <para>Unit files are loaded from a set of paths
135 determined during compilation, described in the next section.
138 <para>Unit files may contain additional options on top
139 of those listed here. If systemd encounters an unknown
140 option, it will write a warning log message but
141 continue loading the unit. If an option is prefixed
142 with <option>X-</option>, it is ignored completely by
143 systemd. Applications may use this to include
144 additional information in the unit files.</para>
146 <para>Boolean arguments used in unit files can be
147 written in various formats. For positive settings the
148 strings <option>1</option>, <option>yes</option>,
149 <option>true</option> and <option>on</option> are
150 equivalent. For negative settings, the strings
151 <option>0</option>, <option>no</option>,
152 <option>false</option> and <option>off</option> are
155 <para>Time span values encoded in unit files can be
156 written in various formats. A stand-alone number
157 specifies a time in seconds. If suffixed with a time
158 unit, the unit is honored. A concatenation of multiple
159 values with units is supported, in which case the
160 values are added up. Example: "50" refers to 50
161 seconds; "2min 200ms" refers to 2 minutes plus 200
162 milliseconds, i.e. 120200ms. The following time units
163 are understood: s, min, h, d, w, ms, us. For details
165 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
167 <para>Empty lines and lines starting with # or ; are
168 ignored. This may be used for commenting. Lines ending
169 in a backslash are concatenated with the following
170 line while reading and the backslash is replaced by a
171 space character. This may be used to wrap long lines.</para>
173 <para>Along with a unit file
174 <filename>foo.service</filename>, the directory
175 <filename>foo.service.wants/</filename> may exist. All
176 unit files symlinked from such a directory are
177 implicitly added as dependencies of type
178 <varname>Wanted=</varname> to the unit. This is useful
179 to hook units into the start-up of other units,
180 without having to modify their unit files. For details
181 about the semantics of <varname>Wanted=</varname>, see
182 below. The preferred way to create symlinks in the
183 <filename>.wants/</filename> directory of a unit file
184 is with the <command>enable</command> command of the
185 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
186 tool which reads information from the [Install]
187 section of unit files (see below). A similar
188 functionality exists for <varname>Requires=</varname>
189 type dependencies as well, the directory suffix is
190 <filename>.requires/</filename> in this case.</para>
192 <para>Along with a unit file
193 <filename>foo.service</filename>, a directory
194 <filename>foo.service.d/</filename> may exist. All
195 files with the suffix <literal>.conf</literal> from
196 this directory will be parsed after the file itself is
197 parsed. This is useful to alter or add configuration
198 settings to a unit, without having to modify their
199 unit files. Make sure that the file that is included
200 has the appropriate section headers before any
203 <para>If a line starts with <option>.include</option>
204 followed by a filename, the specified file will be
205 parsed at this point. Make sure that the file that is
206 included has the appropriate section headers before
207 any directives.</para>
209 <para>Note that while systemd offers a flexible
210 dependency system between units it is recommended to
211 use this functionality only sparingly and instead rely
212 on techniques such as bus-based or socket-based
213 activation which make dependencies implicit, resulting
214 in a both simpler and more flexible system.</para>
216 <para>Some unit names reflect paths existing in the
217 file system namespace. Example: a device unit
218 <filename>dev-sda.device</filename> refers to a device
219 with the device node <filename noindex='true'>/dev/sda</filename> in
220 the file system namespace. If this applies, a special
221 way to escape the path name is used, so that the
222 result is usable as part of a filename. Basically,
223 given a path, "/" is replaced by "-", and all
224 unprintable characters and the "-" are replaced by
225 C-style "\x20" escapes. The root directory "/" is
226 encoded as single dash, while otherwise the initial
227 and ending "/" is removed from all paths during
228 transformation. This escaping is reversible.</para>
230 <para>Optionally, units may be instantiated from a
231 template file at runtime. This allows creation of
232 multiple units from a single configuration file. If
233 systemd looks for a unit configuration file, it will
234 first search for the literal unit name in the
235 filesystem. If that yields no success and the unit
236 name contains an <literal>@</literal> character, systemd will look for a
237 unit template that shares the same name but with the
238 instance string (i.e. the part between the <literal>@</literal> character
239 and the suffix) removed. Example: if a service
240 <filename>getty@tty3.service</filename> is requested
241 and no file by that name is found, systemd will look
242 for <filename>getty@.service</filename> and
243 instantiate a service from that configuration file if
246 <para>To refer to the instance string from
247 within the configuration file you may use the special
248 <literal>%i</literal> specifier in many of the
249 configuration options. See below for details.</para>
251 <para>If a unit file is empty (i.e. has the file size
252 0) or is symlinked to <filename>/dev/null</filename>,
253 its configuration will not be loaded and it appears
254 with a load state of <literal>masked</literal>, and
255 cannot be activated. Use this as an effective way to
256 fully disable a unit, making it impossible to start it
257 even manually.</para>
259 <para>The unit file format is covered by the
261 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
262 Stability Promise</ulink>.</para>
267 <title>Unit Load Path</title>
269 <para>Unit files are loaded from a set of paths
270 determined during compilation, described in the two
271 tables below. Unit files found in directories listed
272 earlier override files with the same name in
273 directories lower in the list.</para>
275 <para>When systemd is running in user mode
276 (<option>--user</option>) and the variable
277 <varname>$SYSTEMD_UNIT_PATH</varname> is set, this
278 contents of this variable overrides the unit load
284 Load path when running in system mode (<option>--system</option>).
288 <colspec colname='path' />
289 <colspec colname='expl' />
293 <entry>Description</entry>
298 <entry><filename>/etc/systemd/system</filename></entry>
299 <entry>Local configuration</entry>
302 <entry><filename>/run/systemd/system</filename></entry>
303 <entry>Runtime units</entry>
306 <entry><filename>/usr/lib/systemd/system</filename></entry>
307 <entry>Units of installed packages</entry>
315 Load path when running in user mode (<option>--user</option>).
319 <colspec colname='path' />
320 <colspec colname='expl' />
324 <entry>Description</entry>
329 <entry><filename>$HOME/.config/systemd/user</filename></entry>
330 <entry>User configuration</entry>
333 <entry><filename>/etc/systemd/user</filename></entry>
334 <entry>Local configuration</entry>
337 <entry><filename>/run/systemd/user</filename></entry>
338 <entry>Runtime units</entry>
341 <entry><filename>/usr/lib/systemd/user</filename></entry>
342 <entry>Units of installed packages</entry>
348 <para>Additional units might be loaded into systemd
349 ("linked") from directories not on the unit load
350 path. See the <command>link</command> command for
351 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Also,
352 some units are dynamically created via generators
354 url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>.
359 <title>Options</title>
361 <para>Unit file may include a [Unit] section, which
362 carries generic information about the unit that is not
363 dependent on the type of unit:</para>
365 <variablelist class='unit-directives'>
368 <term><varname>Description=</varname></term>
369 <listitem><para>A free-form string
370 describing the unit. This is intended
371 for use in UIs to show descriptive
372 information along with the unit
373 name. The description should contain a name
374 that means something to the end user.
375 <literal>Apache2 Web Server</literal> is a good
376 example. Bad examples are
377 <literal>high-performance light-weight HTTP
378 server</literal> (too generic) or
379 <literal>Apache2</literal> (too specific and
380 meaningless for people who do not know
381 Apache).</para></listitem>
385 <term><varname>Documentation=</varname></term>
386 <listitem><para>A space-separated list
387 of URIs referencing documentation for
389 configuration. Accepted are only URIs
391 <literal>http://</literal>,
392 <literal>https://</literal>,
393 <literal>file:</literal>,
394 <literal>info:</literal>,
395 <literal>man:</literal>. For more
396 information about the syntax of these
398 <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
399 URIs should be listed in order of
400 relevance, starting with the most
401 relevant. It is a good idea to first
402 reference documentation that explains
403 what the unit's purpose is, followed
404 by how it is configured, followed by
405 any other related documentation. This
406 option may be specified more than once
407 in which case the specified list of
408 URIs is merged. If the empty string is
409 assigned to this option, the list is
410 reset and all prior assignments will
411 have no effect.</para></listitem>
415 <term><varname>Requires=</varname></term>
417 <listitem><para>Configures requirement
418 dependencies on other units. If this
419 unit gets activated, the units listed
420 here will be activated as well. If one
421 of the other units gets deactivated or
422 its activation fails, this unit will
423 be deactivated. This option may be
424 specified more than once or multiple
425 space-separated units may be specified
426 in one option in which case
427 requirement dependencies for all
428 listed names will be created. Note
429 that requirement dependencies do not
430 influence the order in which services
431 are started or stopped. This has to be
432 configured independently with the
433 <varname>After=</varname> or
434 <varname>Before=</varname> options. If
436 <filename>foo.service</filename>
438 <filename>bar.service</filename> as
440 <varname>Requires=</varname> and no
441 ordering is configured with
442 <varname>After=</varname> or
443 <varname>Before=</varname>, then both
444 units will be started simultaneously
445 and without any delay between them if
446 <filename>foo.service</filename> is
447 activated. Often it is a better choice
448 to use <varname>Wants=</varname>
450 <varname>Requires=</varname> in order
451 to achieve a system that is more
452 robust when dealing with failing
455 <para>Note that dependencies of this
456 type may also be configured outside of
457 the unit configuration file by
458 adding a symlink to a
459 <filename>.requires/</filename> directory
460 accompanying the unit file. For
461 details see above.</para></listitem>
465 <term><varname>RequiresOverridable=</varname></term>
467 <listitem><para>Similar to
468 <varname>Requires=</varname>.
469 Dependencies listed in
470 <varname>RequiresOverridable=</varname>
471 which cannot be fulfilled or fail to
472 start are ignored if the startup was
473 explicitly requested by the user. If
474 the start-up was pulled in indirectly
475 by some dependency or automatic
476 start-up of units that is not
477 requested by the user, this dependency
478 must be fulfilled and otherwise the
479 transaction fails. Hence, this option
480 may be used to configure dependencies
481 that are normally honored unless the
482 user explicitly starts up the unit, in
483 which case whether they failed or not
484 is irrelevant.</para></listitem>
488 <term><varname>Requisite=</varname></term>
489 <term><varname>RequisiteOverridable=</varname></term>
491 <listitem><para>Similar to
492 <varname>Requires=</varname> and
493 <varname>RequiresOverridable=</varname>,
494 respectively. However, if the units
495 listed here are not started already
496 they will not be started and the
497 transaction will fail immediately.
502 <term><varname>Wants=</varname></term>
504 <listitem><para>A weaker version of
505 <varname>Requires=</varname>. Units
506 listed in this option will be started
507 if the configuring unit is. However,
508 if the listed units fail to start
509 or cannot be added to the transaction
510 this has no impact on the validity of
511 the transaction as a whole. This is
512 the recommended way to hook start-up
513 of one unit to the start-up of another
516 <para>Note that dependencies of this
517 type may also be configured outside of
518 the unit configuration file by adding
520 <filename>.wants/</filename> directory
521 accompanying the unit file. For
522 details see above.</para></listitem>
526 <term><varname>BindsTo=</varname></term>
528 <listitem><para>Configures requirement
529 dependencies, very similar in style to
530 <varname>Requires=</varname>, however
531 in addition to this behavior it also
532 declares that this unit is stopped
533 when any of the units listed suddenly
534 disappears. Units can suddenly,
535 unexpectedly disappear if a service
536 terminates on its own choice, a device
537 is unplugged or a mount point
538 unmounted without involvement of
539 systemd.</para></listitem>
543 <term><varname>PartOf=</varname></term>
545 <listitem><para>Configures dependencies
546 similar to <varname>Requires=</varname>,
547 but limited to stopping and restarting
548 of units. When systemd stops or restarts
549 the units listed here, the action is
550 propagated to this unit.
551 Note that this is a one way dependency —
552 changes to this unit do not affect the
558 <term><varname>Conflicts=</varname></term>
560 <listitem><para>A space-separated list
561 of unit names. Configures negative
562 requirement dependencies. If a unit
563 has a <varname>Conflicts=</varname>
564 setting on another unit, starting the
565 former will stop the latter and vice
566 versa. Note that this setting is
567 independent of and orthogonal to the
568 <varname>After=</varname> and
569 <varname>Before=</varname> ordering
572 <para>If a unit A that conflicts with
573 a unit B is scheduled to be started at
574 the same time as B, the transaction
575 will either fail (in case both are
576 required part of the transaction) or
577 be modified to be fixed (in case one
578 or both jobs are not a required part
579 of the transaction). In the latter
580 case the job that is not the required
581 will be removed, or in case both are
582 not required the unit that conflicts
583 will be started and the unit that is
585 stopped.</para></listitem>
589 <term><varname>Before=</varname></term>
590 <term><varname>After=</varname></term>
592 <listitem><para>A space-separated list
593 of unit names. Configures ordering
594 dependencies between units. If a unit
595 <filename>foo.service</filename>
597 <option>Before=bar.service</option>
598 and both units are being started,
599 <filename>bar.service</filename>'s
600 start-up is delayed until
601 <filename>foo.service</filename> is
602 started up. Note that this setting is
603 independent of and orthogonal to the
604 requirement dependencies as configured
605 by <varname>Requires=</varname>. It is
606 a common pattern to include a unit
608 <varname>After=</varname> and
609 <varname>Requires=</varname> option in
610 which case the unit listed will be
611 started before the unit that is
612 configured with these options. This
613 option may be specified more than
614 once, in which case ordering
615 dependencies for all listed names are
616 created. <varname>After=</varname> is
618 <varname>Before=</varname>, i.e. while
619 <varname>After=</varname> ensures that
620 the configured unit is started after
621 the listed unit finished starting up,
622 <varname>Before=</varname> ensures the
623 opposite, i.e. that the configured
624 unit is fully started up before the
625 listed unit is started. Note that when
626 two units with an ordering dependency
627 between them are shut down, the
628 inverse of the start-up order is
629 applied. i.e. if a unit is configured
630 with <varname>After=</varname> on
631 another unit, the former is stopped
632 before the latter if both are shut
633 down. If one unit with an ordering
634 dependency on another unit is shut
635 down while the latter is started up,
636 the shut down is ordered before the
637 start-up regardless whether the
638 ordering dependency is actually of
639 type <varname>After=</varname> or
640 <varname>Before=</varname>. If two
641 units have no ordering dependencies
642 between them, they are shut down or
643 started up simultaneously, and no
645 place. </para></listitem>
649 <term><varname>OnFailure=</varname></term>
651 <listitem><para>A space-separated list
652 of one or more units that are
653 activated when this unit enters the
654 <literal>failed</literal>
655 state.</para></listitem>
659 <term><varname>PropagatesReloadTo=</varname></term>
660 <term><varname>ReloadPropagatedFrom=</varname></term>
662 <listitem><para>A space-separated list
663 of one or more units where reload
664 requests on this unit will be
665 propagated to, or reload requests on
666 the other unit will be propagated to
667 this unit, respectively. Issuing a
668 reload request on a unit will
669 automatically also enqueue a reload
670 request on all units that the reload
671 request shall be propagated to via
672 these two settings.</para></listitem>
676 <term><varname>JoinsNamespaceOf=</varname></term>
678 <listitem><para>For units that start
679 processes (such as service units),
680 lists one or more other units whose
681 network and/or temporary file
682 namespace to join. This only applies
683 to unit types which support the
684 <varname>PrivateNetwork=</varname> and
685 <varname>PrivateTmp=</varname>
687 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
688 for details). If a unit that has this
689 setting set is started its processes
691 <filename>/tmp</filename>,
692 <filename>/tmp/var</filename> and
693 network namespace as one listed unit
694 that is started. If multiple listed
695 units are already started it is not
696 defined which namespace is
697 joined. Note that this setting only
699 <varname>PrivateNetwork=</varname>
700 and/or <varname>PrivateTmp=</varname>
701 is enabled for both the unit that
702 joins the namespace and the unit whose
703 namespace is joined.</para></listitem>
707 <term><varname>RequiresMountsFor=</varname></term>
709 <listitem><para>Takes a space-separated
710 list of absolute paths. Automatically
711 adds dependencies of type
712 <varname>Requires=</varname> and
713 <varname>After=</varname> for all
714 mount units required to access the
715 specified path.</para></listitem>
719 <term><varname>OnFailureJobMode=</varname></term>
721 <listitem><para>Takes a value of
722 <literal>fail</literal>,
723 <literal>replace</literal>,
724 <literal>replace-irreversibly</literal>,
725 <literal>isolate</literal>,
726 <literal>flush</literal>,
727 <literal>ignore-dependencies</literal>
729 <literal>ignore-requirements</literal>. Defaults
731 <literal>replace</literal>. Specifies
732 how the units listed in
733 <varname>OnFailure=</varname> will be
735 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
736 <option>--job-mode=</option> option
737 for details on the possible values. If
739 <literal>isolate</literal>, only a
740 single unit may be listed in
741 <varname>OnFailure=</varname>..</para></listitem>
745 <term><varname>IgnoreOnIsolate=</varname></term>
747 <listitem><para>Takes a boolean
748 argument. If <option>true</option>,
749 this unit will not be stopped when
750 isolating another unit. Defaults to
751 <option>false</option>.</para></listitem>
755 <term><varname>IgnoreOnSnapshot=</varname></term>
757 <listitem><para>Takes a boolean
758 argument. If <option>true</option>,
759 this unit will not be included in
760 snapshots. Defaults to
761 <option>true</option> for device and
762 snapshot units, <option>false</option>
763 for the others.</para></listitem>
767 <term><varname>StopWhenUnneeded=</varname></term>
769 <listitem><para>Takes a boolean
770 argument. If <option>true</option>,
771 this unit will be stopped when it is
772 no longer used. Note that in order to
773 minimize the work to be executed,
774 systemd will not stop units by default
775 unless they are conflicting with other
776 units, or the user explicitly
777 requested their shut down. If this
778 option is set, a unit will be
779 automatically cleaned up if no other
780 active unit requires it. Defaults to
781 <option>false</option>.</para></listitem>
785 <term><varname>RefuseManualStart=</varname></term>
786 <term><varname>RefuseManualStop=</varname></term>
788 <listitem><para>Takes a boolean
789 argument. If <option>true</option>,
790 this unit can only be activated
791 or deactivated indirectly. In
792 this case, explicit start-up
793 or termination requested by the
794 user is denied, however if it is
795 started or stopped as a
796 dependency of another unit, start-up
797 or termination will succeed. This
798 is mostly a safety feature to ensure
799 that the user does not accidentally
800 activate units that are not intended
801 to be activated explicitly, and not
802 accidentally deactivate units that are
803 not intended to be deactivated.
804 These options default to
805 <option>false</option>.</para></listitem>
809 <term><varname>AllowIsolate=</varname></term>
811 <listitem><para>Takes a boolean
812 argument. If <option>true</option>,
813 this unit may be used with the
814 <command>systemctl isolate</command>
815 command. Otherwise, this will be
816 refused. It probably is a good idea to
817 leave this disabled except for target
818 units that shall be used similar to
819 runlevels in SysV init systems, just
820 as a precaution to avoid unusable
821 system states. This option defaults to
822 <option>false</option>.</para></listitem>
826 <term><varname>DefaultDependencies=</varname></term>
828 <listitem><para>Takes a boolean
829 argument. If <option>true</option>,
830 (the default), a few default
831 dependencies will implicitly be
832 created for the unit. The actual
833 dependencies created depend on the
834 unit type. For example, for service
835 units, these dependencies ensure that
836 the service is started only after
837 basic system initialization is
838 completed and is properly terminated on
839 system shutdown. See the respective
840 man pages for details. Generally, only
841 services involved with early boot or
842 late shutdown should set this option
843 to <option>false</option>. It is
844 highly recommended to leave this
845 option enabled for the majority of
846 common units. If set to
847 <option>false</option>, this option
848 does not disable all implicit
849 dependencies, just non-essential
850 ones.</para></listitem>
854 <term><varname>JobTimeoutSec=</varname></term>
856 <listitem><para>When clients are
857 waiting for a job of this unit to
858 complete, time out after the specified
859 time. If this time limit is reached,
860 the job will be cancelled, the unit
861 however will not change state or even
862 enter the <literal>failed</literal>
863 mode. This value defaults to 0 (job
864 timeouts disabled), except for device
865 units. NB: this timeout is independent
866 from any unit-specific timeout (for
867 example, the timeout set with
868 <varname>Timeout=</varname> in service
869 units) as the job timeout has no
870 effect on the unit itself, only on the
871 job that might be pending for it. Or
872 in other words: unit-specific timeouts
873 are useful to abort unit state
874 changes, and revert them. The job
875 timeout set with this option however
876 is useful to abort only the job
877 waiting for the unit state to
878 change.</para></listitem>
882 <term><varname>ConditionPathExists=</varname></term>
883 <term><varname>ConditionPathExistsGlob=</varname></term>
884 <term><varname>ConditionPathIsDirectory=</varname></term>
885 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
886 <term><varname>ConditionPathIsMountPoint=</varname></term>
887 <term><varname>ConditionPathIsReadWrite=</varname></term>
888 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
889 <term><varname>ConditionFileNotEmpty=</varname></term>
890 <term><varname>ConditionFileIsExecutable=</varname></term>
891 <term><varname>ConditionKernelCommandLine=</varname></term>
892 <term><varname>ConditionVirtualization=</varname></term>
893 <term><varname>ConditionSecurity=</varname></term>
894 <term><varname>ConditionCapability=</varname></term>
895 <term><varname>ConditionHost=</varname></term>
896 <term><varname>ConditionACPower=</varname></term>
897 <term><varname>ConditionNull=</varname></term>
899 <listitem><para>Before starting a unit
900 verify that the specified condition is
901 true. If it is not true, the starting
902 of the unit will be skipped, however
903 all ordering dependencies of it are
904 still respected. A failing condition
905 will not result in the unit being
906 moved into a failure state. The
907 condition is checked at the time the
908 queued start job is to be
912 <varname>ConditionPathExists=</varname>
913 a file existence condition is
914 checked before a unit is started. If
915 the specified absolute path name does
916 not exist, the condition will
917 fail. If the absolute path name passed
919 <varname>ConditionPathExists=</varname>
920 is prefixed with an exclamation mark
921 (<literal>!</literal>), the test is negated, and the unit
922 is only started if the path does not
925 <para><varname>ConditionPathExistsGlob=</varname>
927 <varname>ConditionPathExists=</varname>,
928 but checks for the existence of at
929 least one file or directory matching
930 the specified globbing pattern.</para>
932 <para><varname>ConditionPathIsDirectory=</varname>
934 <varname>ConditionPathExists=</varname>
935 but verifies whether a certain path
939 <para><varname>ConditionPathIsSymbolicLink=</varname>
941 <varname>ConditionPathExists=</varname>
942 but verifies whether a certain path
943 exists and is a symbolic
946 <para><varname>ConditionPathIsMountPoint=</varname>
948 <varname>ConditionPathExists=</varname>
949 but verifies whether a certain path
950 exists and is a mount
953 <para><varname>ConditionPathIsReadWrite=</varname>
955 <varname>ConditionPathExists=</varname>
956 but verifies whether the underlying
957 file system is readable and writable
961 <para><varname>ConditionDirectoryNotEmpty=</varname>
963 <varname>ConditionPathExists=</varname>
964 but verifies whether a certain path
965 exists and is a non-empty
968 <para><varname>ConditionFileNotEmpty=</varname>
970 <varname>ConditionPathExists=</varname>
971 but verifies whether a certain path
972 exists and refers to a regular file
973 with a non-zero size.</para>
975 <para><varname>ConditionFileIsExecutable=</varname>
977 <varname>ConditionPathExists=</varname>
978 but verifies whether a certain path
979 exists, is a regular file and marked
983 <varname>ConditionKernelCommandLine=</varname>
984 may be used to check whether a
985 specific kernel command line option is
986 set (or if prefixed with the
987 exclamation mark unset). The argument
988 must either be a single word, or an
989 assignment (i.e. two words, separated
990 <literal>=</literal>). In the former
991 case the kernel command line is
992 searched for the word appearing as is,
993 or as left hand side of an
994 assignment. In the latter case the
995 exact assignment is looked for with
996 right and left hand side
999 <para><varname>ConditionVirtualization=</varname>
1000 may be used to check whether the
1001 system is executed in a virtualized
1002 environment and optionally test
1003 whether it is a specific
1004 implementation. Takes either boolean
1005 value to check if being executed in
1006 any virtualized environment, or one of
1007 <varname>vm</varname> and
1008 <varname>container</varname> to test
1009 against a generic type of
1010 virtualization solution, or one of
1011 <varname>qemu</varname>,
1012 <varname>kvm</varname>,
1013 <varname>vmware</varname>,
1014 <varname>microsoft</varname>,
1015 <varname>oracle</varname>,
1016 <varname>xen</varname>,
1017 <varname>bochs</varname>,
1018 <varname>chroot</varname>,
1019 <varname>uml</varname>,
1020 <varname>openvz</varname>,
1021 <varname>lxc</varname>,
1022 <varname>lxc-libvirt</varname>,
1023 <varname>systemd-nspawn</varname> to
1024 test against a specific
1025 implementation. If multiple
1026 virtualization technologies are nested,
1027 only the innermost is considered. The
1028 test may be negated by prepending an
1029 exclamation mark.</para>
1031 <para><varname>ConditionSecurity=</varname>
1032 may be used to check whether the given
1033 security module is enabled on the
1034 system. Currently the recognized values
1035 values are <varname>selinux</varname>,
1036 <varname>apparmor</varname>,
1037 <varname>ima</varname> and
1038 <varname>smack</varname>.
1039 The test may be negated by prepending
1043 <para><varname>ConditionCapability=</varname>
1044 may be used to check whether the given
1045 capability exists in the capability
1046 bounding set of the service manager
1047 (i.e. this does not check whether
1048 capability is actually available in
1049 the permitted or effective sets, see
1050 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1051 for details). Pass a capability name
1052 such as <literal>CAP_MKNOD</literal>,
1053 possibly prefixed with an exclamation
1054 mark to negate the check.</para>
1056 <para><varname>ConditionHost=</varname>
1057 may be used to match against the
1058 hostname or machine ID of the
1059 host. This either takes a hostname
1060 string (optionally with shell style
1061 globs) which is tested against the
1062 locally set hostname as returned by
1063 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1064 or a machine ID formatted as string
1066 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1067 The test may be negated by prepending
1068 an exclamation mark.</para>
1070 <para><varname>ConditionACPower=</varname>
1071 may be used to check whether the
1072 system has AC power, or is exclusively
1073 battery powered at the time of
1074 activation of the unit. This takes a
1075 boolean argument. If set to
1076 <varname>true</varname>, the condition
1077 will hold only if at least one AC
1078 connector of the system is connected
1079 to a power source, or if no AC
1080 connectors are known. Conversely, if
1081 set to <varname>false</varname>, the
1082 condition will hold only if there is
1083 at least one AC connector known and
1084 all AC connectors are disconnected
1085 from a power source.</para>
1088 <varname>ConditionNull=</varname> may
1089 be used to add a constant condition
1090 check value to the unit. It takes a
1091 boolean argument. If set to
1092 <varname>false</varname>, the condition
1093 will always fail, otherwise
1096 <para>If multiple conditions are
1097 specified, the unit will be executed if
1098 all of them apply (i.e. a logical AND
1099 is applied). Condition checks can be
1100 prefixed with a pipe symbol (|) in
1101 which case a condition becomes a
1102 triggering condition. If at least one
1103 triggering condition is defined for a
1104 unit, then the unit will be executed if
1105 at least one of the triggering
1106 conditions apply and all of the
1107 non-triggering conditions. If you
1108 prefix an argument with the pipe
1109 symbol and an exclamation mark, the
1110 pipe symbol must be passed first, the
1111 exclamation second. Except for
1112 <varname>ConditionPathIsSymbolicLink=</varname>,
1113 all path checks follow symlinks. If
1114 any of these options is assigned the
1115 empty string, the list of conditions is
1116 reset completely, all previous
1117 condition settings (of any kind) will
1118 have no effect.</para></listitem>
1122 <term><varname>SourcePath=</varname></term>
1123 <listitem><para>A path to a
1124 configuration file this unit has been
1125 generated from. This is primarily
1126 useful for implementation of generator
1127 tools that convert configuration from
1128 an external configuration file format
1129 into native unit files. Thus
1130 functionality should not be used in
1131 normal units.</para></listitem>
1135 <para>Unit file may include a [Install] section, which
1136 carries installation information for the unit. This
1137 section is not interpreted by
1138 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1139 during runtime. It is used exclusively by the
1140 <command>enable</command> and
1141 <command>disable</command> commands of the
1142 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1143 tool during installation of a unit:</para>
1145 <variablelist class='unit-directives'>
1147 <term><varname>Alias=</varname></term>
1149 <listitem><para>A space-seperated list
1150 of additional names this unit shall be
1151 installed under. The names listed here
1152 must have the same suffix (i.e. type)
1153 as the unit file name. This option may
1154 be specified more than once, in which
1155 case all listed names are used. At
1156 installation time, <command>systemctl
1157 enable</command> will create symlinks
1158 from these names to the unit
1159 filename.</para></listitem>
1163 <term><varname>WantedBy=</varname></term>
1164 <term><varname>RequiredBy=</varname></term>
1166 <listitem><para>This option may be
1167 used more than once, or a
1168 space-separated list of unit names may
1169 be given. A symbolic link is created
1170 in the <filename>.wants/</filename> or
1171 <filename>.requires/</filename>
1172 directory of each of the listed units
1173 when this unit is installed by
1174 <command>systemctl enable</command>.
1175 This has the effect that a dependency
1176 of type <varname>Wants=</varname> or
1177 <varname>Requires=</varname> is added
1178 from the listed unit to the current
1179 unit. The primary result is that the
1180 current unit will be started when the
1181 listed unit is started. See the
1183 <varname>Wants=</varname> and
1184 <varname>Requires=</varname> in the
1185 [Unit] section for details.</para>
1187 <para><command>WantedBy=foo.service</command>
1189 <filename>bar.service</filename> is
1190 mostly equivalent to
1191 <command>Alias=foo.service.wants/bar.service</command>
1192 in the same file. In case of template
1193 units, <command>systemctl enable</command>
1194 must be called with an instance name, and
1195 this instance will be added to the
1196 <filename>.wants/</filename> or
1197 <filename>.requires/</filename> list
1199 E.g. <command>WantedBy=getty.target</command>
1201 <filename>getty@.service</filename>
1202 will result in <command>systemctl
1203 enable getty@tty2.service</command>
1205 <filename>getty.target.wants/getty@tty2.service</filename>
1206 link to <filename>getty@.service</filename>.
1211 <term><varname>Also=</varname></term>
1213 <listitem><para>Additional units to
1214 install/deinstall when this unit is
1215 installed/deinstalled. If the user
1216 requests installation/deinstallation
1217 of a unit with this option configured,
1218 <command>systemctl enable</command>
1219 and <command>systemctl
1220 disable</command> will automatically
1221 install/uninstall units listed in this option as
1224 <para>This option may be used more
1225 than once, or a space-separated list
1226 of unit names may be
1227 given.</para></listitem>
1231 <para>The following specifiers are interpreted in the
1232 Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v.
1233 For their meaning see the next section.
1238 <title>Specifiers</title>
1240 <para>Many settings resolve specifiers which may be
1241 used to write generic unit files referring to runtime
1242 or unit parameters that are replaced when the unit
1243 files are loaded. The following specifiers are
1247 <title>Specifiers available in unit files</title>
1248 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1249 <colspec colname="spec" />
1250 <colspec colname="mean" />
1251 <colspec colname="detail" />
1254 <entry>Specifier</entry>
1255 <entry>Meaning</entry>
1256 <entry>Details</entry>
1261 <entry><literal>%n</literal></entry>
1262 <entry>Full unit name</entry>
1266 <entry><literal>%N</literal></entry>
1267 <entry>Unescaped full unit name</entry>
1268 <entry>Same as <literal>%n</literal>, but with escaping undone</entry>
1271 <entry><literal>%p</literal></entry>
1272 <entry>Prefix name</entry>
1273 <entry>For instantiated units this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units this refers to the name of the unit with the type suffix removed.</entry>
1276 <entry><literal>%P</literal></entry>
1277 <entry>Unescaped prefix name</entry>
1278 <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
1281 <entry><literal>%i</literal></entry>
1282 <entry>Instance name</entry>
1283 <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry>
1286 <entry><literal>%I</literal></entry>
1287 <entry>Unescaped instance name</entry>
1288 <entry>Same as <literal>%i</literal>, but with escaping undone</entry>
1291 <entry><literal>%f</literal></entry>
1292 <entry>Unescaped filename</entry>
1293 <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry>
1296 <entry><literal>%c</literal></entry>
1297 <entry>Control group path of the unit</entry>
1298 <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry>
1301 <entry><literal>%r</literal></entry>
1302 <entry>Control group path of the slice the unit is placed in</entry>
1303 <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry>
1306 <entry><literal>%R</literal></entry>
1307 <entry>Root control group path where slices and units are placed below</entry>
1308 <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry>
1311 <entry><literal>%t</literal></entry>
1312 <entry>Runtime directory</entry>
1313 <entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry>
1316 <entry><literal>%u</literal></entry>
1317 <entry>User name</entry>
1318 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1321 <entry><literal>%U</literal></entry>
1322 <entry>User UID</entry>
1323 <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.</entry>
1326 <entry><literal>%h</literal></entry>
1327 <entry>User home directory</entry>
1328 <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal> this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
1331 <entry><literal>%s</literal></entry>
1332 <entry>User shell</entry>
1333 <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal> this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
1336 <entry><literal>%m</literal></entry>
1337 <entry>Machine ID</entry>
1338 <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>
1341 <entry><literal>%b</literal></entry>
1342 <entry>Boot ID</entry>
1343 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1346 <entry><literal>%H</literal></entry>
1347 <entry>Host name</entry>
1348 <entry>The hostname of the running system at the point in time the unit configuation is loaded.</entry>
1351 <entry><literal>%v</literal></entry>
1352 <entry>Kernel release</entry>
1353 <entry>Identical to <command>uname -r</command> output</entry>
1356 <entry><literal>%%</literal></entry>
1357 <entry>Single percent sign</entry>
1358 <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry>
1366 <title>See Also</title>
1368 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1369 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1370 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1371 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1372 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1373 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1374 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1375 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1376 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1377 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1378 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1379 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1380 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1381 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1382 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1383 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1384 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1385 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1386 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>