1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemd.unit">
27 <title>systemd.unit</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.unit</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.unit</refname>
47 <refpurpose>Unit configuration</refpurpose>
51 <para><filename>systemd.service</filename>,
52 <filename>systemd.socket</filename>,
53 <filename>systemd.device</filename>,
54 <filename>systemd.mount</filename>,
55 <filename>systemd.automount</filename>,
56 <filename>systemd.swap</filename>,
57 <filename>systemd.target</filename>,
58 <filename>systemd.path</filename>,
59 <filename>systemd.timer</filename>,
60 <filename>systemd.snapshot</filename></para>
64 <title>Description</title>
66 <para>A unit configuration file encodes information
67 about a service, a socket, a device, a mount point, an
68 automount point, a swap file or partition, a start-up
69 target, a file system path or a timer controlled and
71 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
72 syntax is inspired by <ulink
73 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
74 Desktop Entry Specification</ulink> <filename>.desktop</filename> files, which are in turn
75 inspired by Microsoft Windows
76 <filename>.ini</filename> files.</para>
78 <para>This man page lists the common configuration
79 options of all the unit types. These options need to
80 be configured in the [Unit] or [Install]
81 sections of the unit files.</para>
83 <para>In addition to the generic [Unit] and [Install]
84 sections described here, each unit may have a
85 type-specific section, e.g. [Service] for a service
86 unit. See the respective man pages for more
89 <para>Unit files may contain additional options on top
90 of those listed here. If systemd encounters an unknown
91 option it will write a warning log message but
92 continue loading the unit. If an option is prefixed
93 with <option>X-</option> it is ignored completely by
94 systemd. Applications may use this to include
95 additional information in the unit files.</para>
97 <para>Boolean arguments used in unit files can be
98 written in various formats. For positive settings the
99 strings <option>1</option>, <option>yes</option>,
100 <option>true</option> and <option>on</option> are
101 equivalent. For negative settings the strings
102 <option>0</option>, <option>no</option>,
103 <option>false</option> and <option>off</option> are
106 <para>Time span values encoded in unit files can be
107 written in various formats. A stand-alone number
108 specifies a time in seconds. If suffixed with a time
109 unit, the unit is honored. A concatenation of multiple
110 values with units is supported, in which case the
111 values are added up. Example: "50" refers to 50
112 seconds; "2min 200ms" refers to 2 minutes plus 200
113 milliseconds, i.e. 120200ms. The following time units
114 are understood: s, min, h, d, w, ms, us. For details
116 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
118 <para>Empty lines and lines starting with # or ; are
119 ignored. This may be used for commenting. Lines ending
120 in a backslash are concatenated with the following
121 line while reading and the backslash is replaced by a
122 space character. This may be used to wrap long lines.</para>
124 <para>Along with a unit file
125 <filename>foo.service</filename> the directory
126 <filename>foo.service.wants/</filename> may exist. All
127 unit files symlinked from such a directory are
128 implicitly added as dependencies of type
129 <varname>Wanted=</varname> to the unit. This is useful
130 to hook units into the start-up of other units,
131 without having to modify their unit files. For details
132 about the semantics of <varname>Wanted=</varname> see
133 below. The preferred way to create symlinks in the
134 <filename>.wants/</filename> directory of a unit file
135 is with the <command>enable</command> command of the
136 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
137 tool which reads information from the [Install]
138 section of unit files (see below). A similar
139 functionality exists for <varname>Requires=</varname>
140 type dependencies as well, the directory suffix is
141 <filename>.requires/</filename> in this case.</para>
143 <para>Along with a unit file
144 <filename>foo.service</filename> a directory
145 <filename>foo.service.d/</filename> may exist. All
146 files with the suffix <filename>.conf</filename> from
147 this directory will be parsed after the file itself is
148 parsed. This is useful to alter or add configuration
149 settings to a unit, without having to modify their
150 unit files. Make sure that the file that is included
151 has the appropriate section headers before any
154 <para>If a line starts with <option>.include</option>
155 followed by a file name, the specified file will be
156 parsed at this point. Make sure that the file that is
157 included has the appropriate section headers before
158 any directives.</para>
160 <para>Note that while systemd offers a flexible
161 dependency system between units it is recommended to
162 use this functionality only sparingly and instead rely
163 on techniques such as bus-based or socket-based
164 activation which make dependencies implicit, resulting
165 in a both simpler and more flexible system.</para>
167 <para>Some unit names reflect paths existing in the
168 file system name space. Example: a device unit
169 <filename>dev-sda.device</filename> refers to a device
170 with the device node <filename>/dev/sda</filename> in
171 the file system namespace. If this applies a special
172 way to escape the path name is used, so that the
173 result is usable as part of a file name. Basically,
174 given a path, "/" is replaced by "-", and all
175 unprintable characters and the "-" are replaced by
176 C-style "\x20" escapes. The root directory "/" is
177 encoded as single dash, while otherwise the initial
178 and ending "/" is removed from all paths during
179 transformation. This escaping is reversible.</para>
181 <para>Optionally, units may be instantiated from a
182 template file at runtime. This allows creation of
183 multiple units from a single configuration file. If
184 systemd looks for a unit configuration file it will
185 first search for the literal unit name in the
186 filesystem. If that yields no success and the unit
187 name contains an @ character, systemd will look for a
188 unit template that shares the same name but with the
189 instance string (i.e. the part between the @ character
190 and the suffix) removed. Example: if a service
191 <filename>getty@tty3.service</filename> is requested
192 and no file by that name is found, systemd will look
193 for <filename>getty@.service</filename> and
194 instantiate a service from that configuration file if
197 <para>To refer to the instance string from
198 within the configuration file you may use the special
199 <literal>%i</literal> specifier in many of the
200 configuration options. See below for details.</para>
202 <para>If a unit file is empty (i.e. has the file size
203 0) or is symlinked to <filename>/dev/null</filename>
204 its configuration will not be loaded and it appears
205 with a load state of <literal>masked</literal>, and
206 cannot be activated. Use this as an effective way to
207 fully disable a unit, making it impossible to start it
208 even manually.</para>
210 <para>The unit file format is covered by the
212 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
213 Stability Promise</ulink>.</para>
218 <title>Options</title>
220 <para>Unit file may include a [Unit] section, which
221 carries generic information about the unit that is not
222 dependent on the type of unit:</para>
224 <variablelist class='unit-directives'>
227 <term><varname>Description=</varname></term>
228 <listitem><para>A free-form string
229 describing the unit. This is intended
230 for use in UIs to show descriptive
231 information along with the unit
232 name.</para></listitem>
236 <term><varname>Documentation=</varname></term>
237 <listitem><para>A space separated list
238 of URIs referencing documentation for
240 configuration. Accepted are only URIs
242 <literal>http://</literal>,
243 <literal>https://</literal>,
244 <literal>file:</literal>,
245 <literal>info:</literal>,
246 <literal>man:</literal>. For more
247 information about the syntax of these
249 <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
250 URIs should be listed in order of
251 relevance, starting with the most
252 relevant. It is a good idea to first
253 reference documentation that explains
254 what the unit's purpose is, followed
255 by how it is configured, followed by
256 any other related documentation. This
257 option may be specified more than once
258 in which case the specified list of
259 URIs is merged. If the empty string is
260 assigned to this option the list is
261 reset and all prior assignments will
262 have no effect.</para></listitem>
266 <term><varname>Requires=</varname></term>
268 <listitem><para>Configures requirement
269 dependencies on other units. If this
270 unit gets activated, the units listed
271 here will be activated as well. If one
272 of the other units gets deactivated or
273 its activation fails, this unit will
274 be deactivated. This option may be
275 specified more than once, in which
276 case requirement dependencies for all
277 listed names are created. Note that
278 requirement dependencies do not
279 influence the order in which services
280 are started or stopped. This has to be
281 configured independently with the
282 <varname>After=</varname> or
283 <varname>Before=</varname> options. If
285 <filename>foo.service</filename>
287 <filename>bar.service</filename> as
289 <varname>Requires=</varname> and no
290 ordering is configured with
291 <varname>After=</varname> or
292 <varname>Before=</varname>, then both
293 units will be started simultaneously
294 and without any delay between them if
295 <filename>foo.service</filename> is
296 activated. Often it is a better choice
297 to use <varname>Wants=</varname>
299 <varname>Requires=</varname> in order
300 to achieve a system that is more
301 robust when dealing with failing
304 <para>Note that dependencies of this
305 type may also be configured outside of
306 the unit configuration file by
307 adding a symlink to a
308 <filename>.requires/</filename> directory
309 accompanying the unit file. For
310 details see above.</para></listitem>
314 <term><varname>RequiresOverridable=</varname></term>
316 <listitem><para>Similar to
317 <varname>Requires=</varname>.
318 Dependencies listed in
319 <varname>RequiresOverridable=</varname>
320 which cannot be fulfilled or fail to
321 start are ignored if the startup was
322 explicitly requested by the user. If
323 the start-up was pulled in indirectly
324 by some dependency or automatic
325 start-up of units that is not
326 requested by the user this dependency
327 must be fulfilled and otherwise the
328 transaction fails. Hence, this option
329 may be used to configure dependencies
330 that are normally honored unless the
331 user explicitly starts up the unit, in
332 which case whether they failed or not
333 is irrelevant.</para></listitem>
337 <term><varname>Requisite=</varname></term>
338 <term><varname>RequisiteOverridable=</varname></term>
340 <listitem><para>Similar to
341 <varname>Requires=</varname>
342 and <varname>RequiresOverridable=</varname>, respectively. However,
343 if a unit listed here is not started
344 already it will not be started and the
346 immediately.</para></listitem>
350 <term><varname>Wants=</varname></term>
352 <listitem><para>A weaker version of
353 <varname>Requires=</varname>. A unit
354 listed in this option will be started
355 if the configuring unit is. However,
356 if the listed unit fails to start up
357 or cannot be added to the transaction
358 this has no impact on the validity of
359 the transaction as a whole. This is
360 the recommended way to hook start-up
361 of one unit to the start-up of another
364 <para>Note that dependencies of this
365 type may also be configured outside of
366 the unit configuration file by
367 adding a symlink to a
368 <filename>.wants/</filename> directory
369 accompanying the unit file. For
370 details see above.</para></listitem>
374 <term><varname>BindsTo=</varname></term>
376 <listitem><para>Configures requirement
377 dependencies, very similar in style to
378 <varname>Requires=</varname>, however
379 in addition to this behavior it also
380 declares that this unit is stopped
381 when any of the units listed suddenly
382 disappears. Units can suddenly,
383 unexpectedly disappear if a service
384 terminates on its own choice, a device
385 is unplugged or a mount point
386 unmounted without involvement of
387 systemd.</para></listitem>
391 <term><varname>PartOf=</varname></term>
393 <listitem><para>Configures dependencies
394 similar to <varname>Requires=</varname>,
395 but limited to stopping and restarting
396 of units. When systemd stops or restarts
397 the units listed here, the action is
398 propagated to this unit.
399 Note that this is a one way dependency -
400 changes to this unit do not affect the
406 <term><varname>Conflicts=</varname></term>
408 <listitem><para>Configures negative
409 requirement dependencies. If a unit
411 <varname>Conflicts=</varname> setting
412 on another unit, starting the former
413 will stop the latter and vice
414 versa. Note that this setting is
415 independent of and orthogonal to the
416 <varname>After=</varname> and
417 <varname>Before=</varname> ordering
420 <para>If a unit A that conflicts with
421 a unit B is scheduled to be started at
422 the same time as B, the transaction
423 will either fail (in case both are
424 required part of the transaction) or
425 be modified to be fixed (in case one
426 or both jobs are not a required part
427 of the transaction). In the latter
428 case the job that is not the required
429 will be removed, or in case both are
430 not required the unit that conflicts
431 will be started and the unit that is
433 stopped.</para></listitem>
437 <term><varname>Before=</varname></term>
438 <term><varname>After=</varname></term>
440 <listitem><para>Configures ordering
441 dependencies between units. If a unit
442 <filename>foo.service</filename>
444 <option>Before=bar.service</option>
445 and both units are being started,
446 <filename>bar.service</filename>'s
447 start-up is delayed until
448 <filename>foo.service</filename> is
449 started up. Note that this setting is
450 independent of and orthogonal to the
451 requirement dependencies as configured
452 by <varname>Requires=</varname>. It is
453 a common pattern to include a unit
455 <varname>After=</varname> and
456 <varname>Requires=</varname> option in
457 which case the unit listed will be
458 started before the unit that is
459 configured with these options. This
460 option may be specified more than
461 once, in which case ordering
462 dependencies for all listed names are
463 created. <varname>After=</varname> is
465 <varname>Before=</varname>, i.e. while
466 <varname>After=</varname> ensures that
467 the configured unit is started after
468 the listed unit finished starting up,
469 <varname>Before=</varname> ensures the
470 opposite, i.e. that the configured
471 unit is fully started up before the
472 listed unit is started. Note that when
473 two units with an ordering dependency
474 between them are shut down, the
475 inverse of the start-up order is
476 applied. i.e. if a unit is configured
477 with <varname>After=</varname> on
478 another unit, the former is stopped
479 before the latter if both are shut
480 down. If one unit with an ordering
481 dependency on another unit is shut
482 down while the latter is started up,
483 the shut down is ordered before the
484 start-up regardless whether the
485 ordering dependency is actually of
486 type <varname>After=</varname> or
487 <varname>Before=</varname>. If two
488 units have no ordering dependencies
489 between them they are shut down
490 or started up simultaneously, and
492 place. </para></listitem>
496 <term><varname>OnFailure=</varname></term>
498 <listitem><para>Lists one or more
499 units that are activated when this
501 '<literal>failed</literal>'
502 state.</para></listitem>
506 <term><varname>PropagatesReloadTo=</varname></term>
507 <term><varname>ReloadPropagatedFrom=</varname></term>
509 <listitem><para>Lists one or more
510 units where reload requests on the
511 unit will be propagated to/on the
512 other unit will be propagated
513 from. Issuing a reload request on a
514 unit will automatically also enqueue a
515 reload request on all units that the
516 reload request shall be propagated to
518 settings.</para></listitem>
522 <term><varname>RequiresMountsFor=</varname></term>
524 <listitem><para>Takes a space
525 separated list of absolute paths. Automatically
526 adds dependencies of type
527 <varname>Requires=</varname> and
528 <varname>After=</varname> for all
529 mount units required to access the
530 specified path.</para></listitem>
534 <term><varname>OnFailureIsolate=</varname></term>
536 <listitem><para>Takes a boolean
537 argument. If <option>true</option> the
539 <varname>OnFailure=</varname> will be
540 enqueued in isolation mode, i.e. all
541 units that are not its dependency will
542 be stopped. If this is set only a
543 single unit may be listed in
544 <varname>OnFailure=</varname>. Defaults
546 <option>false</option>.</para></listitem>
550 <term><varname>IgnoreOnIsolate=</varname></term>
552 <listitem><para>Takes a boolean
553 argument. If <option>true</option>
554 this unit will not be stopped when
555 isolating another unit. Defaults to
556 <option>false</option>.</para></listitem>
560 <term><varname>IgnoreOnSnapshot=</varname></term>
562 <listitem><para>Takes a boolean
563 argument. If <option>true</option>
564 this unit will not be included in
565 snapshots. Defaults to
566 <option>true</option> for device and
567 snapshot units, <option>false</option>
568 for the others.</para></listitem>
572 <term><varname>StopWhenUnneeded=</varname></term>
574 <listitem><para>Takes a boolean
575 argument. If <option>true</option>
576 this unit will be stopped when it is
577 no longer used. Note that in order to
578 minimize the work to be executed,
579 systemd will not stop units by default
580 unless they are conflicting with other
581 units, or the user explicitly
582 requested their shut down. If this
583 option is set, a unit will be
584 automatically cleaned up if no other
585 active unit requires it. Defaults to
586 <option>false</option>.</para></listitem>
590 <term><varname>RefuseManualStart=</varname></term>
591 <term><varname>RefuseManualStop=</varname></term>
593 <listitem><para>Takes a boolean
594 argument. If <option>true</option>
595 this unit can only be activated
596 or deactivated indirectly. In
597 this case explicit start-up
598 or termination requested by the
599 user is denied, however if it is
600 started or stopped as a
601 dependency of another unit, start-up
602 or termination will succeed. This
603 is mostly a safety feature to ensure
604 that the user does not accidentally
605 activate units that are not intended
606 to be activated explicitly, and not
607 accidentally deactivate units that are
608 not intended to be deactivated.
609 These options default to
610 <option>false</option>.</para></listitem>
614 <term><varname>AllowIsolate=</varname></term>
616 <listitem><para>Takes a boolean
617 argument. If <option>true</option>
618 this unit may be used with the
619 <command>systemctl isolate</command>
620 command. Otherwise this will be
621 refused. It probably is a good idea to
622 leave this disabled except for target
623 units that shall be used similar to
624 runlevels in SysV init systems, just
625 as a precaution to avoid unusable
626 system states. This option defaults to
627 <option>false</option>.</para></listitem>
631 <term><varname>DefaultDependencies=</varname></term>
633 <listitem><para>Takes a boolean
634 argument. If <option>true</option>
635 (the default), a few default
636 dependencies will implicitly be
637 created for the unit. The actual
638 dependencies created depend on the
639 unit type. For example, for service
640 units, these dependencies ensure that
641 the service is started only after
642 basic system initialization is
643 completed and is properly terminated on
644 system shutdown. See the respective
645 man pages for details. Generally, only
646 services involved with early boot or
647 late shutdown should set this option
648 to <option>false</option>. It is
649 highly recommended to leave this
650 option enabled for the majority of
651 common units. If set to
652 <option>false</option> this option
653 does not disable all implicit
654 dependencies, just non-essential
655 ones.</para></listitem>
659 <term><varname>JobTimeoutSec=</varname></term>
661 <listitem><para>When clients are
662 waiting for a job of this unit to
663 complete, time out after the specified
664 time. If this time limit is reached
665 the job will be cancelled, the unit
666 however will not change state or even
667 enter the '<literal>failed</literal>'
668 mode. This value defaults to 0 (job
669 timeouts disabled), except for device
670 units. NB: this timeout is independent
671 from any unit-specific timeout (for
672 example, the timeout set with
673 <varname>Timeout=</varname> in service
674 units) as the job timeout has no
675 effect on the unit itself, only on the
676 job that might be pending for it. Or
677 in other words: unit-specific timeouts
678 are useful to abort unit state
679 changes, and revert them. The job
680 timeout set with this option however
681 is useful to abort only the job
682 waiting for the unit state to
683 change.</para></listitem>
687 <term><varname>ConditionPathExists=</varname></term>
688 <term><varname>ConditionPathExistsGlob=</varname></term>
689 <term><varname>ConditionPathIsDirectory=</varname></term>
690 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
691 <term><varname>ConditionPathIsMountPoint=</varname></term>
692 <term><varname>ConditionPathIsReadWrite=</varname></term>
693 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
694 <term><varname>ConditionFileNotEmpty=</varname></term>
695 <term><varname>ConditionFileIsExecutable=</varname></term>
696 <term><varname>ConditionKernelCommandLine=</varname></term>
697 <term><varname>ConditionVirtualization=</varname></term>
698 <term><varname>ConditionSecurity=</varname></term>
699 <term><varname>ConditionCapability=</varname></term>
700 <term><varname>ConditionHost=</varname></term>
701 <term><varname>ConditionACPower=</varname></term>
702 <term><varname>ConditionNull=</varname></term>
704 <listitem><para>Before starting a unit
705 verify that the specified condition is
706 true. If it is not true the starting
707 of the unit will be skipped, however
708 all ordering dependencies of it are
709 still respected. A failing condition
710 will not result in the unit being
711 moved into a failure state. The
712 condition is checked at the time the
713 queued start job is to be
717 <varname>ConditionPathExists=</varname>
718 a file existence condition is
719 checked before a unit is started. If
720 the specified absolute path name does
721 not exist the condition will
722 fail. If the absolute path name passed
724 <varname>ConditionPathExists=</varname>
725 is prefixed with an exclamation mark
726 ('!'), the test is negated, and the unit
727 is only started if the path does not
730 <para><varname>ConditionPathExistsGlob=</varname>
732 <varname>ConditionPathExists=</varname>,
733 but checks for the existence of at
734 least one file or directory matching
735 the specified globbing pattern.</para>
737 <para><varname>ConditionPathIsDirectory=</varname>
739 <varname>ConditionPathExists=</varname>
740 but verifies whether a certain path
744 <para><varname>ConditionPathIsSymbolicLink=</varname>
746 <varname>ConditionPathExists=</varname>
747 but verifies whether a certain path
748 exists and is a symbolic
751 <para><varname>ConditionPathIsMountPoint=</varname>
753 <varname>ConditionPathExists=</varname>
754 but verifies whether a certain path
755 exists and is a mount
758 <para><varname>ConditionPathIsReadWrite=</varname>
760 <varname>ConditionPathExists=</varname>
761 but verifies whether the underlying
762 file system is readable and writable
766 <para><varname>ConditionDirectoryNotEmpty=</varname>
768 <varname>ConditionPathExists=</varname>
769 but verifies whether a certain path
770 exists and is a non-empty
773 <para><varname>ConditionFileNotEmpty=</varname>
775 <varname>ConditionPathExists=</varname>
776 but verifies whether a certain path
777 exists and refers to a regular file
778 with a non-zero size.</para>
780 <para><varname>ConditionFileIsExecutable=</varname>
782 <varname>ConditionPathExists=</varname>
783 but verifies whether a certain path
784 exists, is a regular file and marked
788 <varname>ConditionKernelCommandLine=</varname>
789 may be used to check whether a
790 specific kernel command line option is
791 set (or if prefixed with the
792 exclamation mark unset). The argument
793 must either be a single word, or an
794 assignment (i.e. two words, separated
796 case the kernel command line is
797 searched for the word appearing as is,
798 or as left hand side of an
799 assignment. In the latter case the
800 exact assignment is looked for with
801 right and left hand side
804 <para><varname>ConditionVirtualization=</varname>
805 may be used to check whether the
806 system is executed in a virtualized
807 environment and optionally test
808 whether it is a specific
809 implementation. Takes either boolean
810 value to check if being executed in
811 any virtualized environment, or one of
812 <varname>vm</varname> and
813 <varname>container</varname> to test
814 against a generic type of
815 virtualization solution, or one of
816 <varname>qemu</varname>,
817 <varname>kvm</varname>,
818 <varname>vmware</varname>,
819 <varname>microsoft</varname>,
820 <varname>oracle</varname>,
821 <varname>xen</varname>,
822 <varname>bochs</varname>,
823 <varname>chroot</varname>,
824 <varname>openvz</varname>,
825 <varname>lxc</varname>,
826 <varname>lxc-libvirt</varname>,
827 <varname>systemd-nspawn</varname> to
828 test against a specific
829 implementation. If multiple
830 virtualization technologies are nested
831 only the innermost is considered. The
832 test may be negated by prepending an
833 exclamation mark.</para>
835 <para><varname>ConditionSecurity=</varname>
836 may be used to check whether the given
837 security module is enabled on the
838 system. Currently the only recognized
839 value is <varname>selinux</varname>.
840 The test may be negated by prepending
844 <para><varname>ConditionCapability=</varname>
845 may be used to check whether the given
846 capability exists in the capability
847 bounding set of the service manager
848 (i.e. this does not check whether
849 capability is actually available in
850 the permitted or effective sets, see
851 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
852 for details). Pass a capability name
853 such as <literal>CAP_MKNOD</literal>,
854 possibly prefixed with an exclamation
855 mark to negate the check.</para>
857 <para><varname>ConditionHost=</varname>
858 may be used to match against the
859 host name or machine ID of the
860 host. This either takes a host name
861 string (optionally with shell style
862 globs) which is tested against the
863 locally set host name as returned by
864 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
865 or a machine ID formatted as string
867 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
868 The test may be negated by prepending
869 an exclamation mark.</para>
871 <para><varname>ConditionACPower=</varname>
872 may be used to check whether the
873 system has AC power, or is exclusively
874 battery powered at the time of
875 activation of the unit. This takes a
876 boolean argument. If set to
877 <varname>true</varname> the condition
878 will hold only if at least one AC
879 connector of the system is connected
880 to a power source, or if no AC
881 connectors are known. Conversely, if
882 set to <varname>false</varname> the
883 condition will hold only if there is
884 at least one AC connector known and
885 all AC connectors are disconnected
886 from a power source.</para>
889 <varname>ConditionNull=</varname> may
890 be used to add a constant condition
891 check value to the unit. It takes a
892 boolean argument. If set to
893 <varname>false</varname> the condition
894 will always fail, otherwise
897 <para>If multiple conditions are
898 specified the unit will be executed if
899 all of them apply (i.e. a logical AND
900 is applied). Condition checks can be
901 prefixed with a pipe symbol (|) in
902 which case a condition becomes a
903 triggering condition. If at least one
904 triggering condition is defined for a
905 unit then the unit will be executed if
906 at least one of the triggering
907 conditions apply and all of the
908 non-triggering conditions. If you
909 prefix an argument with the pipe
910 symbol and an exclamation mark the
911 pipe symbol must be passed first, the
912 exclamation second. Except for
913 <varname>ConditionPathIsSymbolicLink=</varname>,
914 all path checks follow symlinks. If
915 any of these options is assigned the
916 empty string the list of conditions is
917 reset completely, all previous
918 condition settings (of any kind) will
919 have no effect.</para></listitem>
923 <term><varname>SourcePath=</varname></term>
924 <listitem><para>A path to a
925 configuration file this unit has been
926 generated from. This is primarily
927 useful for implementation of generator
928 tools that convert configuration from
929 an external configuration file format
930 into native unit files. Thus
931 functionality should not be used in
932 normal units.</para></listitem>
936 <para>Unit file may include a [Install] section, which
937 carries installation information for the unit. This
938 section is not interpreted by
939 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
940 during runtime. It is used exclusively by the
941 <command>enable</command> and
942 <command>disable</command> commands of the
943 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
944 tool during installation of a unit:</para>
946 <variablelist class='unit-directives'>
948 <term><varname>Alias=</varname></term>
950 <listitem><para>Additional names this
951 unit shall be installed under. The
952 names listed here must have the same
953 suffix (i.e. type) as the unit file
954 name. This option may be specified
955 more than once, in which case all
956 listed names are used. At installation
958 <command>systemctl enable</command>
959 will create symlinks from these names
960 to the unit file name.</para></listitem>
964 <term><varname>WantedBy=</varname></term>
965 <term><varname>RequiredBy=</varname></term>
967 <listitem><para>Installs a symlink in
968 the <filename>.wants/</filename>
969 or <filename>.requires/</filename>
970 subdirectory for a unit, respectively. This has the
971 effect that when the listed unit name
972 is activated the unit listing it is
974 too. <command>WantedBy=foo.service</command>
976 <filename>bar.service</filename> is
978 <command>Alias=foo.service.wants/bar.service</command>
979 in the same file.</para></listitem>
983 <term><varname>Also=</varname></term>
985 <listitem><para>Additional units to
986 install when this unit is
987 installed. If the user requests
988 installation of a unit with this
990 <command>systemctl enable</command>
991 will automatically install units
992 listed in this option as
993 well.</para></listitem>
1000 <title>Specifiers</title>
1002 <para>Many settings resolve specifiers which may be
1003 used to write generic unit files referring to runtime
1004 or unit parameters that are replaced when the unit
1005 files are loaded. The following specifiers are
1009 <title>Specifiers available in unit files</title>
1010 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1011 <colspec colname="spec" />
1012 <colspec colname="mean" />
1013 <colspec colname="detail" />
1016 <entry>Specifier</entry>
1017 <entry>Meaning</entry>
1018 <entry>Details</entry>
1023 <entry><literal>%n</literal></entry>
1024 <entry>Full unit name</entry>
1028 <entry><literal>%N</literal></entry>
1029 <entry>Unescaped full unit name</entry>
1033 <entry><literal>%p</literal></entry>
1034 <entry>Prefix name</entry>
1035 <entry>For instantiated units this refers to the string before the @. For non-instantiated units this refers to to the name of the unit with the type suffix removed.</entry>
1038 <entry><literal>%P</literal></entry>
1039 <entry>Unescaped prefix name</entry>
1043 <entry><literal>%i</literal></entry>
1044 <entry>Instance name</entry>
1045 <entry>For instantiated units: this is the string between the @ character and the suffix.</entry>
1048 <entry><literal>%I</literal></entry>
1049 <entry>Unescaped instance name</entry>
1053 <entry><literal>%f</literal></entry>
1054 <entry>Unescaped file name</entry>
1055 <entry>This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /.</entry>
1058 <entry><literal>%c</literal></entry>
1059 <entry>Control group path of the unit</entry>
1063 <entry><literal>%r</literal></entry>
1064 <entry>Root control group path of systemd</entry>
1068 <entry><literal>%R</literal></entry>
1069 <entry>Parent directory of the root control group path of systemd</entry>
1073 <entry><literal>%t</literal></entry>
1074 <entry>Runtime socket dir</entry>
1075 <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry>
1078 <entry><literal>%u</literal></entry>
1079 <entry>User name</entry>
1080 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1083 <entry><literal>%U</literal></entry>
1084 <entry>User UID</entry>
1085 <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1088 <entry><literal>%h</literal></entry>
1089 <entry>User home directory</entry>
1090 <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1093 <entry><literal>%s</literal></entry>
1094 <entry>User shell</entry>
1095 <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1098 <entry><literal>%m</literal></entry>
1099 <entry>Machine ID</entry>
1100 <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>
1103 <entry><literal>%b</literal></entry>
1104 <entry>Boot ID</entry>
1105 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1108 <entry><literal>%H</literal></entry>
1109 <entry>Host name</entry>
1110 <entry>The host name of the running system.</entry>
1118 <title>See Also</title>
1120 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1121 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1122 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1123 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1124 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1125 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1126 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1127 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1128 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1129 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1130 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1131 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1132 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1133 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1134 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1135 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>