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>$XDG_CONFIG_HOME/systemd/user/*</filename>
74 <filename>$HOME/.config/systemd/user/*</filename>
75 <filename>/etc/systemd/user/*</filename>
76 <filename>/run/systemd/user/*</filename>
77 <filename>/usr/lib/systemd/user/*</filename>
78 <filename>...</filename>
79 </literallayout></para>
83 <title>Description</title>
85 <para>A unit configuration file encodes information
86 about a service, a socket, a device, a mount point, an
87 automount point, a swap file or partition, a start-up
88 target, a watched file system path, a timer controlled
90 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
91 a temporary system state snapshot, a resource
92 management slice or a group of externally created
93 processes. The syntax is inspired by <ulink
94 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
95 Desktop Entry Specification</ulink>
96 <filename>.desktop</filename> files, which are in turn
97 inspired by Microsoft Windows
98 <filename>.ini</filename> files.</para>
100 <para>This man page lists the common configuration
101 options of all the unit types. These options need to
102 be configured in the [Unit] or [Install]
103 sections of the unit files.</para>
105 <para>In addition to the generic [Unit] and [Install]
106 sections described here, each unit may have a
107 type-specific section, e.g. [Service] for a service
108 unit. See the respective man pages for more
110 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
111 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
112 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
113 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
114 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
115 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
116 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
117 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
118 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
119 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
120 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
121 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
124 <para>Various settings are allowed to be specified
125 more than once, in which case the interpretation
126 depends on the setting. Often, multiple settings form
127 a list, and setting to an empty value "resets", which
128 means that previous assignments are ignored. When this
129 is allowed, it is mentioned in the description of the
130 setting. Note that using multiple assignments to the
131 same value makes the unit file incompatible with
132 parsers for the XDG <filename>.desktop</filename> file
135 <para>Unit files are loaded from a set of paths
136 determined during compilation, described in the next section.
139 <para>Unit files may contain additional options on top
140 of those listed here. If systemd encounters an unknown
141 option, it will write a warning log message but
142 continue loading the unit. If an option or section name
143 is prefixed with <option>X-</option>, it is ignored
144 completely by systemd. Options within an ignored
145 section do not need the prefix. Applications may use
146 this to include additional information in the unit
149 <para>Boolean arguments used in unit files can be
150 written in various formats. For positive settings the
151 strings <option>1</option>, <option>yes</option>,
152 <option>true</option> and <option>on</option> are
153 equivalent. For negative settings, the strings
154 <option>0</option>, <option>no</option>,
155 <option>false</option> and <option>off</option> are
158 <para>Time span values encoded in unit files can be
159 written in various formats. A stand-alone number
160 specifies a time in seconds. If suffixed with a time
161 unit, the unit is honored. A concatenation of multiple
162 values with units is supported, in which case the
163 values are added up. Example: "50" refers to 50
164 seconds; "2min 200ms" refers to 2 minutes plus 200
165 milliseconds, i.e. 120200ms. The following time units
166 are understood: s, min, h, d, w, ms, us. For details
168 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
170 <para>Empty lines and lines starting with # or ; are
171 ignored. This may be used for commenting. Lines ending
172 in a backslash are concatenated with the following
173 line while reading and the backslash is replaced by a
174 space character. This may be used to wrap long lines.</para>
176 <para>Along with a unit file
177 <filename>foo.service</filename>, the directory
178 <filename>foo.service.wants/</filename> may exist. All
179 unit files symlinked from such a directory are
180 implicitly added as dependencies of type
181 <varname>Wanted=</varname> to the unit. This is useful
182 to hook units into the start-up of other units,
183 without having to modify their unit files. For details
184 about the semantics of <varname>Wanted=</varname>, see
185 below. The preferred way to create symlinks in the
186 <filename>.wants/</filename> directory of a unit file
187 is with the <command>enable</command> command of the
188 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
189 tool which reads information from the [Install]
190 section of unit files (see below). A similar
191 functionality exists for <varname>Requires=</varname>
192 type dependencies as well, the directory suffix is
193 <filename>.requires/</filename> in this case.</para>
195 <para>Along with a unit file
196 <filename>foo.service</filename>, a directory
197 <filename>foo.service.d/</filename> may exist. All
198 files with the suffix <literal>.conf</literal> from
199 this directory will be parsed after the file itself is
200 parsed. This is useful to alter or add configuration
201 settings to a unit, without having to modify their
202 unit files. Make sure that the file that is included
203 has the appropriate section headers before any
206 <para>Note that while systemd offers a flexible
207 dependency system between units it is recommended to
208 use this functionality only sparingly and instead rely
209 on techniques such as bus-based or socket-based
210 activation which make dependencies implicit, resulting
211 in a both simpler and more flexible system.</para>
213 <para>Some unit names reflect paths existing in the
214 file system namespace. Example: a device unit
215 <filename>dev-sda.device</filename> refers to a device
216 with the device node <filename noindex='true'>/dev/sda</filename> in
217 the file system namespace. If this applies, a special
218 way to escape the path name is used, so that the
219 result is usable as part of a filename. Basically,
220 given a path, "/" is replaced by "-", and all
221 unprintable characters and the "-" are replaced by
222 C-style "\x20" escapes. The root directory "/" is
223 encoded as single dash, while otherwise the initial
224 and ending "/" is removed from all paths during
225 transformation. This escaping is reversible.</para>
227 <para>Optionally, units may be instantiated from a
228 template file at runtime. This allows creation of
229 multiple units from a single configuration file. If
230 systemd looks for a unit configuration file, it will
231 first search for the literal unit name in the
232 file system. If that yields no success and the unit
233 name contains an <literal>@</literal> character, systemd will look for a
234 unit template that shares the same name but with the
235 instance string (i.e. the part between the <literal>@</literal> character
236 and the suffix) removed. Example: if a service
237 <filename>getty@tty3.service</filename> is requested
238 and no file by that name is found, systemd will look
239 for <filename>getty@.service</filename> and
240 instantiate a service from that configuration file if
243 <para>To refer to the instance string from
244 within the configuration file you may use the special
245 <literal>%i</literal> specifier in many of the
246 configuration options. See below for details.</para>
248 <para>If a unit file is empty (i.e. has the file size
249 0) or is symlinked to <filename>/dev/null</filename>,
250 its configuration will not be loaded and it appears
251 with a load state of <literal>masked</literal>, and
252 cannot be activated. Use this as an effective way to
253 fully disable a unit, making it impossible to start it
254 even manually.</para>
256 <para>The unit file format is covered by the
258 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
259 Stability Promise</ulink>.</para>
264 <title>Unit Load Path</title>
266 <para>Unit files are loaded from a set of paths
267 determined during compilation, described in the two
268 tables below. Unit files found in directories listed
269 earlier override files with the same name in
270 directories lower in the list.</para>
272 <para>When systemd is running in user mode
273 (<option>--user</option>) and the variable
274 <varname>$SYSTEMD_UNIT_PATH</varname> is set, this
275 contents of this variable overrides the unit load
281 Load path when running in system mode (<option>--system</option>).
285 <colspec colname='path' />
286 <colspec colname='expl' />
290 <entry>Description</entry>
295 <entry><filename>/etc/systemd/system</filename></entry>
296 <entry>Local configuration</entry>
299 <entry><filename>/run/systemd/system</filename></entry>
300 <entry>Runtime units</entry>
303 <entry><filename>/usr/lib/systemd/system</filename></entry>
304 <entry>Units of installed packages</entry>
312 Load path when running in user mode (<option>--user</option>).
316 <colspec colname='path' />
317 <colspec colname='expl' />
321 <entry>Description</entry>
326 <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
327 <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
330 <entry><filename>$HOME/.config/systemd/user</filename></entry>
331 <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
334 <entry><filename>/etc/systemd/user</filename></entry>
335 <entry>Local configuration</entry>
338 <entry><filename>/run/systemd/user</filename></entry>
339 <entry>Runtime units</entry>
342 <entry><filename>/usr/lib/systemd/user</filename></entry>
343 <entry>Units of installed packages</entry>
349 <para>Additional units might be loaded into systemd
350 ("linked") from directories not on the unit load
351 path. See the <command>link</command> command for
352 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Also,
353 some units are dynamically created via generators
355 url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>.
360 <title>[Unit] Section Options</title>
362 <para>Unit file may include a [Unit] section, which
363 carries generic information about the unit that is not
364 dependent on the type of unit:</para>
366 <variablelist class='unit-directives'>
369 <term><varname>Description=</varname></term>
370 <listitem><para>A free-form string
371 describing the unit. This is intended
372 for use in UIs to show descriptive
373 information along with the unit
374 name. The description should contain a name
375 that means something to the end user.
376 <literal>Apache2 Web Server</literal> is a good
377 example. Bad examples are
378 <literal>high-performance light-weight HTTP
379 server</literal> (too generic) or
380 <literal>Apache2</literal> (too specific and
381 meaningless for people who do not know
382 Apache).</para></listitem>
386 <term><varname>Documentation=</varname></term>
387 <listitem><para>A space-separated list
388 of URIs referencing documentation for
390 configuration. Accepted are only URIs
392 <literal>http://</literal>,
393 <literal>https://</literal>,
394 <literal>file:</literal>,
395 <literal>info:</literal>,
396 <literal>man:</literal>. For more
397 information about the syntax of these
399 <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
400 URIs should be listed in order of
401 relevance, starting with the most
402 relevant. It is a good idea to first
403 reference documentation that explains
404 what the unit's purpose is, followed
405 by how it is configured, followed by
406 any other related documentation. This
407 option may be specified more than once,
408 in which case the specified list of
409 URIs is merged. If the empty string is
410 assigned to this option, the list is
411 reset and all prior assignments will
412 have no effect.</para></listitem>
416 <term><varname>Requires=</varname></term>
418 <listitem><para>Configures requirement
419 dependencies on other units. If this
420 unit gets activated, the units listed
421 here will be activated as well. If one
422 of the other units gets deactivated or
423 its activation fails, this unit will
424 be deactivated. This option may be
425 specified more than once or multiple
426 space-separated units may be specified
427 in one option in which case
428 requirement dependencies for all
429 listed names will be created. Note
430 that requirement dependencies do not
431 influence the order in which services
432 are started or stopped. This has to be
433 configured independently with the
434 <varname>After=</varname> or
435 <varname>Before=</varname> options. If
437 <filename>foo.service</filename>
439 <filename>bar.service</filename> as
441 <varname>Requires=</varname> and no
442 ordering is configured with
443 <varname>After=</varname> or
444 <varname>Before=</varname>, then both
445 units will be started simultaneously
446 and without any delay between them if
447 <filename>foo.service</filename> is
448 activated. Often it is a better choice
449 to use <varname>Wants=</varname>
451 <varname>Requires=</varname> in order
452 to achieve a system that is more
453 robust when dealing with failing
456 <para>Note that dependencies of this
457 type may also be configured outside of
458 the unit configuration file by
459 adding a symlink to a
460 <filename>.requires/</filename> directory
461 accompanying the unit file. For
462 details see above.</para></listitem>
466 <term><varname>RequiresOverridable=</varname></term>
468 <listitem><para>Similar to
469 <varname>Requires=</varname>.
470 Dependencies listed in
471 <varname>RequiresOverridable=</varname>
472 which cannot be fulfilled or fail to
473 start are ignored if the startup was
474 explicitly requested by the user. If
475 the start-up was pulled in indirectly
476 by some dependency or automatic
477 start-up of units that is not
478 requested by the user, this dependency
479 must be fulfilled and otherwise the
480 transaction fails. Hence, this option
481 may be used to configure dependencies
482 that are normally honored unless the
483 user explicitly starts up the unit, in
484 which case whether they failed or not
485 is irrelevant.</para></listitem>
489 <term><varname>Requisite=</varname></term>
490 <term><varname>RequisiteOverridable=</varname></term>
492 <listitem><para>Similar to
493 <varname>Requires=</varname> and
494 <varname>RequiresOverridable=</varname>,
495 respectively. However, if the units
496 listed here are not started already,
497 they will not be started and the
498 transaction will fail immediately.
503 <term><varname>Wants=</varname></term>
505 <listitem><para>A weaker version of
506 <varname>Requires=</varname>. Units
507 listed in this option will be started
508 if the configuring unit is. However,
509 if the listed units fail to start
510 or cannot be added to the transaction,
511 this has no impact on the validity of
512 the transaction as a whole. This is
513 the recommended way to hook start-up
514 of one unit to the start-up of another
517 <para>Note that dependencies of this
518 type may also be configured outside of
519 the unit configuration file by adding
521 <filename>.wants/</filename> directory
522 accompanying the unit file. For
523 details, see above.</para></listitem>
527 <term><varname>BindsTo=</varname></term>
529 <listitem><para>Configures requirement
530 dependencies, very similar in style to
531 <varname>Requires=</varname>, however
532 in addition to this behavior, it also
533 declares that this unit is stopped
534 when any of the units listed suddenly
535 disappears. Units can suddenly,
536 unexpectedly disappear if a service
537 terminates on its own choice, a device
538 is unplugged or a mount point
539 unmounted without involvement of
540 systemd.</para></listitem>
544 <term><varname>PartOf=</varname></term>
546 <listitem><para>Configures dependencies
547 similar to <varname>Requires=</varname>,
548 but limited to stopping and restarting
549 of units. When systemd stops or restarts
550 the units listed here, the action is
551 propagated to this unit.
552 Note that this is a one-way dependency —
553 changes to this unit do not affect the
559 <term><varname>Conflicts=</varname></term>
561 <listitem><para>A space-separated list
562 of unit names. Configures negative
563 requirement dependencies. If a unit
564 has a <varname>Conflicts=</varname>
565 setting on another unit, starting the
566 former will stop the latter and vice
567 versa. Note that this setting is
568 independent of and orthogonal to the
569 <varname>After=</varname> and
570 <varname>Before=</varname> ordering
573 <para>If a unit A that conflicts with
574 a unit B is scheduled to be started at
575 the same time as B, the transaction
576 will either fail (in case both are
577 required part of the transaction) or
578 be modified to be fixed (in case one
579 or both jobs are not a required part
580 of the transaction). In the latter
581 case, the job that is not the required
582 will be removed, or in case both are
583 not required, the unit that conflicts
584 will be started and the unit that is
586 stopped.</para></listitem>
590 <term><varname>Before=</varname></term>
591 <term><varname>After=</varname></term>
593 <listitem><para>A space-separated list
594 of unit names. Configures ordering
595 dependencies between units. If a unit
596 <filename>foo.service</filename>
598 <option>Before=bar.service</option>
599 and both units are being started,
600 <filename>bar.service</filename>'s
601 start-up is delayed until
602 <filename>foo.service</filename> is
603 started up. Note that this setting is
604 independent of and orthogonal to the
605 requirement dependencies as configured
606 by <varname>Requires=</varname>. It is
607 a common pattern to include a unit
609 <varname>After=</varname> and
610 <varname>Requires=</varname> option, in
611 which case the unit listed will be
612 started before the unit that is
613 configured with these options. This
614 option may be specified more than
615 once, in which case ordering
616 dependencies for all listed names are
617 created. <varname>After=</varname> is
619 <varname>Before=</varname>, i.e. while
620 <varname>After=</varname> ensures that
621 the configured unit is started after
622 the listed unit finished starting up,
623 <varname>Before=</varname> ensures the
624 opposite, i.e. that the configured
625 unit is fully started up before the
626 listed unit is started. Note that when
627 two units with an ordering dependency
628 between them are shut down, the
629 inverse of the start-up order is
630 applied. i.e. if a unit is configured
631 with <varname>After=</varname> on
632 another unit, the former is stopped
633 before the latter if both are shut
634 down. If one unit with an ordering
635 dependency on another unit is shut
636 down while the latter is started up,
637 the shut down is ordered before the
638 start-up regardless of whether the
639 ordering dependency is actually of
640 type <varname>After=</varname> or
641 <varname>Before=</varname>. If two
642 units have no ordering dependencies
643 between them, they are shut down or
644 started up simultaneously, and no
646 place. </para></listitem>
650 <term><varname>OnFailure=</varname></term>
652 <listitem><para>A space-separated list
653 of one or more units that are
654 activated when this unit enters the
655 <literal>failed</literal>
656 state.</para></listitem>
660 <term><varname>PropagatesReloadTo=</varname></term>
661 <term><varname>ReloadPropagatedFrom=</varname></term>
663 <listitem><para>A space-separated list
664 of one or more units where reload
665 requests on this unit will be
666 propagated to, or reload requests on
667 the other unit will be propagated to
668 this unit, respectively. Issuing a
669 reload request on a unit will
670 automatically also enqueue a reload
671 request on all units that the reload
672 request shall be propagated to via
673 these two settings.</para></listitem>
677 <term><varname>JoinsNamespaceOf=</varname></term>
679 <listitem><para>For units that start
680 processes (such as service units),
681 lists one or more other units whose
682 network and/or temporary file
683 namespace to join. This only applies
684 to unit types which support the
685 <varname>PrivateNetwork=</varname> and
686 <varname>PrivateTmp=</varname>
688 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
689 for details). If a unit that has this
690 setting set is started, its processes
692 <filename>/tmp</filename>,
693 <filename>/tmp/var</filename> and
694 network namespace as one listed unit
695 that is started. If multiple listed
696 units are already started, it is not
697 defined which namespace is
698 joined. Note that this setting only
700 <varname>PrivateNetwork=</varname>
701 and/or <varname>PrivateTmp=</varname>
702 is enabled for both the unit that
703 joins the namespace and the unit whose
704 namespace is joined.</para></listitem>
708 <term><varname>RequiresMountsFor=</varname></term>
710 <listitem><para>Takes a
711 space-separated list of absolute
712 paths. Automatically adds dependencies
713 of type <varname>Requires=</varname>
714 and <varname>After=</varname> for all
715 mount units required to access the
716 specified path.</para>
718 <para>Mount points marked with
719 <option>noauto</option> are not
720 mounted automatically and will be
721 ignored for the purposes of this
722 option. If such a mount should be a
723 requirement for this unit,
724 direct dependencies on the mount
726 (<varname>Requires=</varname> and
727 <varname>After=</varname> or
728 some other combination).
733 <term><varname>OnFailureJobMode=</varname></term>
735 <listitem><para>Takes a value of
736 <literal>fail</literal>,
737 <literal>replace</literal>,
738 <literal>replace-irreversibly</literal>,
739 <literal>isolate</literal>,
740 <literal>flush</literal>,
741 <literal>ignore-dependencies</literal>
743 <literal>ignore-requirements</literal>. Defaults
745 <literal>replace</literal>. Specifies
746 how the units listed in
747 <varname>OnFailure=</varname> will be
749 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
750 <option>--job-mode=</option> option
751 for details on the possible values. If
753 <literal>isolate</literal>, only a
754 single unit may be listed in
755 <varname>OnFailure=</varname>..</para></listitem>
759 <term><varname>IgnoreOnIsolate=</varname></term>
761 <listitem><para>Takes a boolean
762 argument. If <option>true</option>,
763 this unit will not be stopped when
764 isolating another unit. Defaults to
765 <option>false</option>.</para></listitem>
769 <term><varname>IgnoreOnSnapshot=</varname></term>
771 <listitem><para>Takes a boolean
772 argument. If <option>true</option>,
773 this unit will not be included in
774 snapshots. Defaults to
775 <option>true</option> for device and
776 snapshot units, <option>false</option>
777 for the others.</para></listitem>
781 <term><varname>StopWhenUnneeded=</varname></term>
783 <listitem><para>Takes a boolean
784 argument. If <option>true</option>,
785 this unit will be stopped when it is
786 no longer used. Note that in order to
787 minimize the work to be executed,
788 systemd will not stop units by default
789 unless they are conflicting with other
790 units, or the user explicitly
791 requested their shut down. If this
792 option is set, a unit will be
793 automatically cleaned up if no other
794 active unit requires it. Defaults to
795 <option>false</option>.</para></listitem>
799 <term><varname>RefuseManualStart=</varname></term>
800 <term><varname>RefuseManualStop=</varname></term>
802 <listitem><para>Takes a boolean
803 argument. If <option>true</option>,
804 this unit can only be activated
805 or deactivated indirectly. In
806 this case, explicit start-up
807 or termination requested by the
808 user is denied, however if it is
809 started or stopped as a
810 dependency of another unit, start-up
811 or termination will succeed. This
812 is mostly a safety feature to ensure
813 that the user does not accidentally
814 activate units that are not intended
815 to be activated explicitly, and not
816 accidentally deactivate units that are
817 not intended to be deactivated.
818 These options default to
819 <option>false</option>.</para></listitem>
823 <term><varname>AllowIsolate=</varname></term>
825 <listitem><para>Takes a boolean
826 argument. If <option>true</option>,
827 this unit may be used with the
828 <command>systemctl isolate</command>
829 command. Otherwise, this will be
830 refused. It probably is a good idea to
831 leave this disabled except for target
832 units that shall be used similar to
833 runlevels in SysV init systems, just
834 as a precaution to avoid unusable
835 system states. This option defaults to
836 <option>false</option>.</para></listitem>
840 <term><varname>DefaultDependencies=</varname></term>
842 <listitem><para>Takes a boolean
843 argument. If <option>true</option>,
844 (the default), a few default
845 dependencies will implicitly be
846 created for the unit. The actual
847 dependencies created depend on the
848 unit type. For example, for service
849 units, these dependencies ensure that
850 the service is started only after
851 basic system initialization is
852 completed and is properly terminated on
853 system shutdown. See the respective
854 man pages for details. Generally, only
855 services involved with early boot or
856 late shutdown should set this option
857 to <option>false</option>. It is
858 highly recommended to leave this
859 option enabled for the majority of
860 common units. If set to
861 <option>false</option>, this option
862 does not disable all implicit
863 dependencies, just non-essential
864 ones.</para></listitem>
868 <term><varname>JobTimeoutSec=</varname></term>
870 <listitem><para>When clients are
871 waiting for a job of this unit to
872 complete, time out after the specified
873 time. If this time limit is reached,
874 the job will be cancelled, the unit
875 however will not change state or even
876 enter the <literal>failed</literal>
877 mode. This value defaults to 0 (job
878 timeouts disabled), except for device
879 units. NB: this timeout is independent
880 from any unit-specific timeout (for
881 example, the timeout set with
882 <varname>Timeout=</varname> in service
883 units) as the job timeout has no
884 effect on the unit itself, only on the
885 job that might be pending for it. Or
886 in other words: unit-specific timeouts
887 are useful to abort unit state
888 changes, and revert them. The job
889 timeout set with this option however
890 is useful to abort only the job
891 waiting for the unit state to
892 change.</para></listitem>
896 <term><varname>ConditionArchitecture=</varname></term>
897 <term><varname>ConditionVirtualization=</varname></term>
898 <term><varname>ConditionHost=</varname></term>
899 <term><varname>ConditionKernelCommandLine=</varname></term>
900 <term><varname>ConditionSecurity=</varname></term>
901 <term><varname>ConditionCapability=</varname></term>
902 <term><varname>ConditionACPower=</varname></term>
903 <term><varname>ConditionNeedsUpdate=</varname></term>
904 <term><varname>ConditionPathExists=</varname></term>
905 <term><varname>ConditionPathExistsGlob=</varname></term>
906 <term><varname>ConditionPathIsDirectory=</varname></term>
907 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
908 <term><varname>ConditionPathIsMountPoint=</varname></term>
909 <term><varname>ConditionPathIsReadWrite=</varname></term>
910 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
911 <term><varname>ConditionFileNotEmpty=</varname></term>
912 <term><varname>ConditionFileIsExecutable=</varname></term>
913 <term><varname>ConditionNull=</varname></term>
915 <listitem><para>Before starting a unit
916 verify that the specified condition is
917 true. If it is not true, the starting
918 of the unit will be skipped, however
919 all ordering dependencies of it are
920 still respected. A failing condition
921 will not result in the unit being
922 moved into a failure state. The
923 condition is checked at the time the
924 queued start job is to be
927 <para><varname>ConditionArchitecture=</varname>
928 may be used to check whether the
929 system is running on a specific
930 architecture. Takes one of
931 <varname>x86</varname>,
932 <varname>x86-64</varname>,
933 <varname>ppc</varname>,
934 <varname>ppc64</varname>,
935 <varname>ia64</varname>,
936 <varname>parisc</varname>,
937 <varname>parisc64</varname>,
938 <varname>s390</varname>,
939 <varname>s390x</varname>,
940 <varname>sparc</varname>,
941 <varname>sparc64</varname>,
942 <varname>mips</varname>,
943 <varname>mips64</varname>,
944 <varname>alpha</varname>,
945 <varname>arm</varname>,
946 <varname>arm-be</varname>,
947 <varname>arm64</varname>,
948 <varname>arm64-be</varname>,
949 <varname>sh</varname>,
950 <varname>sh64</varname>,
951 <varname>m86k</varname> to test
952 against a specific architecture. The
953 architecture is determined from the
954 information returned by
955 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
956 and is thus subject to
957 <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Note
958 that a <varname>Personality=</varname>
959 setting in the same unit file has no
960 effect on this condition. A special
962 <varname>native</varname> is mapped to
963 the architecture the system manager
964 itself is compiled for. The test may
965 be negated by prepending an
966 exclamation mark.</para>
968 <para><varname>ConditionVirtualization=</varname>
969 may be used to check whether the
970 system is executed in a virtualized
971 environment and optionally test
972 whether it is a specific
973 implementation. Takes either boolean
974 value to check if being executed in
975 any virtualized environment, or one of
976 <varname>vm</varname> and
977 <varname>container</varname> to test
978 against a generic type of
979 virtualization solution, or one of
980 <varname>qemu</varname>,
981 <varname>kvm</varname>,
982 <varname>vmware</varname>,
983 <varname>microsoft</varname>,
984 <varname>oracle</varname>,
985 <varname>xen</varname>,
986 <varname>bochs</varname>,
987 <varname>chroot</varname>,
988 <varname>uml</varname>,
989 <varname>openvz</varname>,
990 <varname>lxc</varname>,
991 <varname>lxc-libvirt</varname>,
992 <varname>systemd-nspawn</varname> to
993 test against a specific
994 implementation. If multiple
995 virtualization technologies are nested,
996 only the innermost is considered. The
997 test may be negated by prepending an
998 exclamation mark.</para>
1000 <para><varname>ConditionHost=</varname>
1001 may be used to match against the
1002 hostname or machine ID of the
1003 host. This either takes a hostname
1004 string (optionally with shell style
1005 globs) which is tested against the
1006 locally set hostname as returned by
1007 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
1008 or a machine ID formatted as string
1010 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
1011 The test may be negated by prepending
1012 an exclamation mark.</para>
1014 <para><varname>ConditionKernelCommandLine=</varname>
1015 may be used to check whether a
1016 specific kernel command line option is
1017 set (or if prefixed with the
1018 exclamation mark unset). The argument
1019 must either be a single word, or an
1020 assignment (i.e. two words, separated
1021 <literal>=</literal>). In the former
1022 case the kernel command line is
1023 searched for the word appearing as is,
1024 or as left hand side of an
1025 assignment. In the latter case, the
1026 exact assignment is looked for with
1027 right and left hand side
1030 <para><varname>ConditionSecurity=</varname>
1031 may be used to check whether the given
1032 security module is enabled on the
1033 system. Currently the recognized values
1034 values are <varname>selinux</varname>,
1035 <varname>apparmor</varname>,
1036 <varname>ima</varname> and
1037 <varname>smack</varname>.
1038 The test may be negated by prepending
1042 <para><varname>ConditionCapability=</varname>
1043 may be used to check whether the given
1044 capability exists in the capability
1045 bounding set of the service manager
1046 (i.e. this does not check whether
1047 capability is actually available in
1048 the permitted or effective sets, see
1049 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1050 for details). Pass a capability name
1051 such as <literal>CAP_MKNOD</literal>,
1052 possibly prefixed with an exclamation
1053 mark to negate the check.</para>
1055 <para><varname>ConditionACPower=</varname>
1056 may be used to check whether the
1057 system has AC power, or is exclusively
1058 battery powered at the time of
1059 activation of the unit. This takes a
1060 boolean argument. If set to
1061 <varname>true</varname>, the condition
1062 will hold only if at least one AC
1063 connector of the system is connected
1064 to a power source, or if no AC
1065 connectors are known. Conversely, if
1066 set to <varname>false</varname>, the
1067 condition will hold only if there is
1068 at least one AC connector known and
1069 all AC connectors are disconnected
1070 from a power source.</para>
1072 <para><varname>ConditionNeedsUpdate=</varname>
1073 takes one of <filename>/var</filename>
1074 or <filename>/etc</filename> as
1075 argument, possibly prefixed with a
1076 <literal>!</literal> (for inverting
1077 the condition). This condition may be
1078 used to conditionalize units on
1079 whether the specified directory
1080 requires an update because
1081 <filename>/usr</filename>'s
1082 modification time is newer than the
1084 <filename>.updated</filename> in the
1085 specified directory. This is useful to
1086 implement offline updates of the
1087 vendor operating system resources in
1088 <filename>/usr</filename> that require
1089 updating of <filename>/etc</filename>
1090 or <filename>/var</filename> on the
1091 next following boot. Units making use
1092 of this condition should order
1094 <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1095 to make sure they run before the stamp
1096 files's modification time gets reset
1097 indicating a completed update.</para>
1100 <varname>ConditionPathExists=</varname>
1101 a file existence condition is
1102 checked before a unit is started. If
1103 the specified absolute path name does
1104 not exist, the condition will
1105 fail. If the absolute path name passed
1107 <varname>ConditionPathExists=</varname>
1108 is prefixed with an exclamation mark
1109 (<literal>!</literal>), the test is negated, and the unit
1110 is only started if the path does not
1113 <para><varname>ConditionPathExistsGlob=</varname>
1115 <varname>ConditionPathExists=</varname>,
1116 but checks for the existence of at
1117 least one file or directory matching
1118 the specified globbing pattern.</para>
1120 <para><varname>ConditionPathIsDirectory=</varname>
1122 <varname>ConditionPathExists=</varname>
1123 but verifies whether a certain path
1127 <para><varname>ConditionPathIsSymbolicLink=</varname>
1129 <varname>ConditionPathExists=</varname>
1130 but verifies whether a certain path
1131 exists and is a symbolic
1134 <para><varname>ConditionPathIsMountPoint=</varname>
1136 <varname>ConditionPathExists=</varname>
1137 but verifies whether a certain path
1138 exists and is a mount
1141 <para><varname>ConditionPathIsReadWrite=</varname>
1143 <varname>ConditionPathExists=</varname>
1144 but verifies whether the underlying
1145 file system is readable and writable
1149 <para><varname>ConditionDirectoryNotEmpty=</varname>
1151 <varname>ConditionPathExists=</varname>
1152 but verifies whether a certain path
1153 exists and is a non-empty
1156 <para><varname>ConditionFileNotEmpty=</varname>
1158 <varname>ConditionPathExists=</varname>
1159 but verifies whether a certain path
1160 exists and refers to a regular file
1161 with a non-zero size.</para>
1163 <para><varname>ConditionFileIsExecutable=</varname>
1165 <varname>ConditionPathExists=</varname>
1166 but verifies whether a certain path
1167 exists, is a regular file and marked
1171 <varname>ConditionNull=</varname> may
1172 be used to add a constant condition
1173 check value to the unit. It takes a
1174 boolean argument. If set to
1175 <varname>false</varname>, the condition
1176 will always fail, otherwise
1179 <para>If multiple conditions are
1180 specified, the unit will be executed if
1181 all of them apply (i.e. a logical AND
1182 is applied). Condition checks can be
1183 prefixed with a pipe symbol (|) in
1184 which case a condition becomes a
1185 triggering condition. If at least one
1186 triggering condition is defined for a
1187 unit, then the unit will be executed if
1188 at least one of the triggering
1189 conditions apply and all of the
1190 non-triggering conditions. If you
1191 prefix an argument with the pipe
1192 symbol and an exclamation mark, the
1193 pipe symbol must be passed first, the
1194 exclamation second. Except for
1195 <varname>ConditionPathIsSymbolicLink=</varname>,
1196 all path checks follow symlinks. If
1197 any of these options is assigned the
1198 empty string, the list of conditions is
1199 reset completely, all previous
1200 condition settings (of any kind) will
1201 have no effect.</para></listitem>
1205 <term><varname>SourcePath=</varname></term>
1206 <listitem><para>A path to a
1207 configuration file this unit has been
1208 generated from. This is primarily
1209 useful for implementation of generator
1210 tools that convert configuration from
1211 an external configuration file format
1212 into native unit files. This
1213 functionality should not be used in
1214 normal units.</para></listitem>
1221 <title>[Install] Section Options</title>
1223 <para>Unit file may include a [Install] section, which
1224 carries installation information for the unit. This
1225 section is not interpreted by
1226 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1227 during runtime. It is used exclusively by the
1228 <command>enable</command> and
1229 <command>disable</command> commands of the
1230 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1231 tool during installation of a unit:</para>
1233 <variablelist class='unit-directives'>
1235 <term><varname>Alias=</varname></term>
1237 <listitem><para>A space-seperated list
1238 of additional names this unit shall be
1239 installed under. The names listed here
1240 must have the same suffix (i.e. type)
1241 as the unit file name. This option may
1242 be specified more than once, in which
1243 case all listed names are used. At
1244 installation time, <command>systemctl
1245 enable</command> will create symlinks
1246 from these names to the unit
1247 filename.</para></listitem>
1251 <term><varname>WantedBy=</varname></term>
1252 <term><varname>RequiredBy=</varname></term>
1254 <listitem><para>This option may be
1255 used more than once, or a
1256 space-separated list of unit names may
1257 be given. A symbolic link is created
1258 in the <filename>.wants/</filename> or
1259 <filename>.requires/</filename>
1260 directory of each of the listed units
1261 when this unit is installed by
1262 <command>systemctl enable</command>.
1263 This has the effect that a dependency
1264 of type <varname>Wants=</varname> or
1265 <varname>Requires=</varname> is added
1266 from the listed unit to the current
1267 unit. The primary result is that the
1268 current unit will be started when the
1269 listed unit is started. See the
1271 <varname>Wants=</varname> and
1272 <varname>Requires=</varname> in the
1273 [Unit] section for details.</para>
1275 <para><command>WantedBy=foo.service</command>
1277 <filename>bar.service</filename> is
1278 mostly equivalent to
1279 <command>Alias=foo.service.wants/bar.service</command>
1280 in the same file. In case of template
1281 units, <command>systemctl enable</command>
1282 must be called with an instance name, and
1283 this instance will be added to the
1284 <filename>.wants/</filename> or
1285 <filename>.requires/</filename> list
1287 E.g. <command>WantedBy=getty.target</command>
1289 <filename>getty@.service</filename>
1290 will result in <command>systemctl
1291 enable getty@tty2.service</command>
1293 <filename>getty.target.wants/getty@tty2.service</filename>
1294 link to <filename>getty@.service</filename>.
1299 <term><varname>Also=</varname></term>
1301 <listitem><para>Additional units to
1302 install/deinstall when this unit is
1303 installed/deinstalled. If the user
1304 requests installation/deinstallation
1305 of a unit with this option configured,
1306 <command>systemctl enable</command>
1307 and <command>systemctl
1308 disable</command> will automatically
1309 install/uninstall units listed in this option as
1312 <para>This option may be used more
1313 than once, or a space-separated list
1314 of unit names may be
1315 given.</para></listitem>
1319 <term><varname>DefaultInstance=</varname></term>
1321 <listitem><para>In template unit files,
1322 this specifies for which instance the
1323 unit shall be enabled if the template
1324 is enabled without any explicitly set
1325 instance. This option has no effect in
1326 non-template unit files. The specified
1327 string must be usable as instance
1328 identifier.</para></listitem>
1332 <para>The following specifiers are interpreted in the
1333 Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v.
1334 For their meaning see the next section.
1339 <title>Specifiers</title>
1341 <para>Many settings resolve specifiers which may be
1342 used to write generic unit files referring to runtime
1343 or unit parameters that are replaced when the unit
1344 files are loaded. The following specifiers are
1348 <title>Specifiers available in unit files</title>
1349 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1350 <colspec colname="spec" />
1351 <colspec colname="mean" />
1352 <colspec colname="detail" />
1355 <entry>Specifier</entry>
1356 <entry>Meaning</entry>
1357 <entry>Details</entry>
1362 <entry><literal>%n</literal></entry>
1363 <entry>Full unit name</entry>
1367 <entry><literal>%N</literal></entry>
1368 <entry>Unescaped full unit name</entry>
1369 <entry>Same as <literal>%n</literal>, but with escaping undone</entry>
1372 <entry><literal>%p</literal></entry>
1373 <entry>Prefix name</entry>
1374 <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>
1377 <entry><literal>%P</literal></entry>
1378 <entry>Unescaped prefix name</entry>
1379 <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
1382 <entry><literal>%i</literal></entry>
1383 <entry>Instance name</entry>
1384 <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry>
1387 <entry><literal>%I</literal></entry>
1388 <entry>Unescaped instance name</entry>
1389 <entry>Same as <literal>%i</literal>, but with escaping undone</entry>
1392 <entry><literal>%f</literal></entry>
1393 <entry>Unescaped filename</entry>
1394 <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>
1397 <entry><literal>%c</literal></entry>
1398 <entry>Control group path of the unit</entry>
1399 <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry>
1402 <entry><literal>%r</literal></entry>
1403 <entry>Control group path of the slice the unit is placed in</entry>
1404 <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry>
1407 <entry><literal>%R</literal></entry>
1408 <entry>Root control group path below which slices and units are placed</entry>
1409 <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry>
1412 <entry><literal>%t</literal></entry>
1413 <entry>Runtime directory</entry>
1414 <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>
1417 <entry><literal>%u</literal></entry>
1418 <entry>User name</entry>
1419 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1422 <entry><literal>%U</literal></entry>
1423 <entry>User UID</entry>
1424 <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>
1427 <entry><literal>%h</literal></entry>
1428 <entry>User home directory</entry>
1429 <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>
1432 <entry><literal>%s</literal></entry>
1433 <entry>User shell</entry>
1434 <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>
1437 <entry><literal>%m</literal></entry>
1438 <entry>Machine ID</entry>
1439 <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>
1442 <entry><literal>%b</literal></entry>
1443 <entry>Boot ID</entry>
1444 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1447 <entry><literal>%H</literal></entry>
1448 <entry>Host name</entry>
1449 <entry>The hostname of the running system at the point in time the unit configuation is loaded.</entry>
1452 <entry><literal>%v</literal></entry>
1453 <entry>Kernel release</entry>
1454 <entry>Identical to <command>uname -r</command> output</entry>
1457 <entry><literal>%%</literal></entry>
1458 <entry>Single percent sign</entry>
1459 <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry>
1467 <title>See Also</title>
1469 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1470 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1471 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1472 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1473 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1474 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1475 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1476 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1477 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1478 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1479 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1480 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1481 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1482 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1483 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1484 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1485 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1486 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1487 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>