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 sparsely and instead rely
163 on techniques such as bus-based or socket-based
164 activation which makes dependencies implicit, which
165 both results in a simpler and more flexible
168 <para>Some unit names reflect paths existing in the
169 file system name space. Example: a device unit
170 <filename>dev-sda.device</filename> refers to a device
171 with the device node <filename>/dev/sda</filename> in
172 the file system namespace. If this applies a special
173 way to escape the path name is used, so that the
174 result is usable as part of a file name. Basically,
175 given a path, "/" is replaced by "-", and all
176 unprintable characters and the "-" are replaced by
177 C-style "\x20" escapes. The root directory "/" is
178 encoded as single dash, while otherwise the initial
179 and ending "/" is removed from all paths during
180 transformation. This escaping is reversible.</para>
182 <para>Optionally, units may be instantiated from a
183 template file at runtime. This allows creation of
184 multiple units from a single configuration file. If
185 systemd looks for a unit configuration file it will
186 first search for the literal unit name in the
187 filesystem. If that yields no success and the unit
188 name contains an @ character, systemd will look for a
189 unit template that shares the same name but with the
190 instance string (i.e. the part between the @ character
191 and the suffix) removed. Example: if a service
192 <filename>getty@tty3.service</filename> is requested
193 and no file by that name is found, systemd will look
194 for <filename>getty@.service</filename> and
195 instantiate a service from that configuration file if
198 <para>To refer to the instance string from
199 within the configuration file you may use the special
200 <literal>%i</literal> specifier in many of the
201 configuration options. See below for details.</para>
203 <para>If a unit file is empty (i.e. has the file size
204 0) or is symlinked to <filename>/dev/null</filename>
205 its configuration will not be loaded and it appears
206 with a load state of <literal>masked</literal>, and
207 cannot be activated. Use this as an effective way to
208 fully disable a unit, making it impossible to start it
209 even manually.</para>
211 <para>The unit file format is covered by the
213 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
214 Stability Promise</ulink>.</para>
219 <title>Options</title>
221 <para>Unit file may include a [Unit] section, which
222 carries generic information about the unit that is not
223 dependent on the type of unit:</para>
228 <term><varname>Description=</varname></term>
229 <listitem><para>A free-form string
230 describing the unit. This is intended
231 for use in UIs to show descriptive
232 information along with the unit
233 name.</para></listitem>
237 <term><varname>Documentation=</varname></term>
238 <listitem><para>A space separated list
239 of URIs referencing documentation for
241 configuration. Accepted are only URIs
243 <literal>http://</literal>,
244 <literal>https://</literal>,
245 <literal>file:</literal>,
246 <literal>info:</literal>,
247 <literal>man:</literal>. For more
248 information about the syntax of these
250 <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
251 URIs should be listed in order of
252 relevance, starting with the most
253 relevant. It is a good idea to first
254 reference documentation that explains
255 what the unit's purpose is, followed
256 by how it is configured, followed by
258 documentation.</para></listitem>
262 <term><varname>Requires=</varname></term>
264 <listitem><para>Configures requirement
265 dependencies on other units. If this
266 unit gets activated, the units listed
267 here will be activated as well. If one
268 of the other units gets deactivated or
269 its activation fails, this unit will
270 be deactivated. This option may be
271 specified more than once, in which
272 case requirement dependencies for all
273 listed names are created. Note that
274 requirement dependencies do not
275 influence the order in which services
276 are started or stopped. This has to be
277 configured independently with the
278 <varname>After=</varname> or
279 <varname>Before=</varname> options. If
281 <filename>foo.service</filename>
283 <filename>bar.service</filename> as
285 <varname>Requires=</varname> and no
286 ordering is configured with
287 <varname>After=</varname> or
288 <varname>Before=</varname>, then both
289 units will be started simultaneously
290 and without any delay between them if
291 <filename>foo.service</filename> is
292 activated. Often it is a better choice
293 to use <varname>Wants=</varname>
295 <varname>Requires=</varname> in order
296 to achieve a system that is more
297 robust when dealing with failing
300 <para>Note that dependencies of this
301 type may also be configured outside of
302 the unit configuration file by
303 adding a symlink to a
304 <filename>.requires/</filename> directory
305 accompanying the unit file. For
306 details see above.</para></listitem>
310 <term><varname>RequiresOverridable=</varname></term>
312 <listitem><para>Similar to
313 <varname>Requires=</varname>.
314 Dependencies listed in
315 <varname>RequiresOverridable=</varname>
316 which cannot be fulfilled or fail to
317 start are ignored if the startup was
318 explicitly requested by the user. If
319 the start-up was pulled in indirectly
320 by some dependency or automatic
321 start-up of units that is not
322 requested by the user this dependency
323 must be fulfilled and otherwise the
324 transaction fails. Hence, this option
325 may be used to configure dependencies
326 that are normally honored unless the
327 user explicitly starts up the unit, in
328 which case whether they failed or not
329 is irrelevant.</para></listitem>
333 <term><varname>Requisite=</varname></term>
334 <term><varname>RequisiteOverridable=</varname></term>
336 <listitem><para>Similar to
337 <varname>Requires=</varname>
338 and <varname>RequiresOverridable=</varname>, respectively. However,
339 if a unit listed here is not started
340 already it will not be started and the
342 immediately.</para></listitem>
346 <term><varname>Wants=</varname></term>
348 <listitem><para>A weaker version of
349 <varname>Requires=</varname>. A unit
350 listed in this option will be started
351 if the configuring unit is. However,
352 if the listed unit fails to start up
353 or cannot be added to the transaction
354 this has no impact on the validity of
355 the transaction as a whole. This is
356 the recommended way to hook start-up
357 of one unit to the start-up of another
360 <para>Note that dependencies of this
361 type may also be configured outside of
362 the unit configuration file by
363 adding a symlink to a
364 <filename>.wants/</filename> directory
365 accompanying the unit file. For
366 details see above.</para></listitem>
370 <term><varname>BindsTo=</varname></term>
372 <listitem><para>Configures requirement
373 dependencies, very similar in style to
374 <varname>Requires=</varname>, however
375 in addition to this behavior it also
376 declares that this unit is stopped
377 when any of the units listed suddenly
378 disappears. Units can suddenly,
379 unexpectedly disappear if a service
380 terminates on its own choice, a device
381 is unplugged or a mount point
382 unmounted without involvement of
383 systemd.</para></listitem>
387 <term><varname>PartOf=</varname></term>
389 <listitem><para>Configures dependencies
390 similar to <varname>Requires=</varname>,
391 but limited to stopping and restarting
392 of units. When systemd stops or restarts
393 the units listed here, the action is
394 propagated to this unit.
395 Note that this is a one way dependency -
396 changes to this unit do not affect the
402 <term><varname>Conflicts=</varname></term>
404 <listitem><para>Configures negative
405 requirement dependencies. If a unit
407 <varname>Conflicts=</varname> setting
408 on another unit, starting the former
409 will stop the latter and vice
410 versa. Note that this setting is
411 independent of and orthogonal to the
412 <varname>After=</varname> and
413 <varname>Before=</varname> ordering
416 <para>If a unit A that conflicts with
417 a unit B is scheduled to be started at
418 the same time as B, the transaction
419 will either fail (in case both are
420 required part of the transaction) or
421 be modified to be fixed (in case one
422 or both jobs are not a required part
423 of the transaction). In the latter
424 case the job that is not the required
425 will be removed, or in case both are
426 not required the unit that conflicts
427 will be started and the unit that is
429 stopped.</para></listitem>
433 <term><varname>Before=</varname></term>
434 <term><varname>After=</varname></term>
436 <listitem><para>Configures ordering
437 dependencies between units. If a unit
438 <filename>foo.service</filename>
440 <option>Before=bar.service</option>
441 and both units are being started,
442 <filename>bar.service</filename>'s
443 start-up is delayed until
444 <filename>foo.service</filename> is
445 started up. Note that this setting is
446 independent of and orthogonal to the
447 requirement dependencies as configured
448 by <varname>Requires=</varname>. It is
449 a common pattern to include a unit
451 <varname>After=</varname> and
452 <varname>Requires=</varname> option in
453 which case the unit listed will be
454 started before the unit that is
455 configured with these options. This
456 option may be specified more than
457 once, in which case ordering
458 dependencies for all listed names are
459 created. <varname>After=</varname> is
461 <varname>Before=</varname>, i.e. while
462 <varname>After=</varname> ensures that
463 the configured unit is started after
464 the listed unit finished starting up,
465 <varname>Before=</varname> ensures the
466 opposite, i.e. that the configured
467 unit is fully started up before the
468 listed unit is started. Note that when
469 two units with an ordering dependency
470 between them are shut down, the
471 inverse of the start-up order is
472 applied. i.e. if a unit is configured
473 with <varname>After=</varname> on
474 another unit, the former is stopped
475 before the latter if both are shut
476 down. If one unit with an ordering
477 dependency on another unit is shut
478 down while the latter is started up,
479 the shut down is ordered before the
480 start-up regardless whether the
481 ordering dependency is actually of
482 type <varname>After=</varname> or
483 <varname>Before=</varname>. If two
484 units have no ordering dependencies
485 between them they are shut down
486 or started up simultaneously, and
488 place. </para></listitem>
492 <term><varname>OnFailure=</varname></term>
494 <listitem><para>Lists one or more
495 units that are activated when this
497 '<literal>failed</literal>'
498 state.</para></listitem>
502 <term><varname>PropagatesReloadTo=</varname></term>
503 <term><varname>ReloadPropagatedFrom=</varname></term>
505 <listitem><para>Lists one or more
506 units where reload requests on the
507 unit will be propagated to/on the
508 other unit will be propagated
509 from. Issuing a reload request on a
510 unit will automatically also enqueue a
511 reload request on all units that the
512 reload request shall be propagated to
514 settings.</para></listitem>
518 <term><varname>RequiresMountsFor=</varname></term>
520 <listitem><para>Takes a space
521 separated list of absolute paths. Automatically
522 adds dependencies of type
523 <varname>Requires=</varname> and
524 <varname>After=</varname> for all
525 mount units required to access the
526 specified path.</para></listitem>
530 <term><varname>OnFailureIsolate=</varname></term>
532 <listitem><para>Takes a boolean
533 argument. If <option>true</option> the
535 <varname>OnFailure=</varname> will be
536 enqueued in isolation mode, i.e. all
537 units that are not its dependency will
538 be stopped. If this is set only a
539 single unit may be listed in
540 <varname>OnFailure=</varname>. Defaults
542 <option>false</option>.</para></listitem>
546 <term><varname>IgnoreOnIsolate=</varname></term>
548 <listitem><para>Takes a boolean
549 argument. If <option>true</option>
550 this unit will not be stopped when
551 isolating another unit. Defaults to
552 <option>false</option>.</para></listitem>
556 <term><varname>IgnoreOnSnapshot=</varname></term>
558 <listitem><para>Takes a boolean
559 argument. If <option>true</option>
560 this unit will not be included in
561 snapshots. Defaults to
562 <option>true</option> for device and
563 snapshot units, <option>false</option>
564 for the others.</para></listitem>
568 <term><varname>StopWhenUnneeded=</varname></term>
570 <listitem><para>Takes a boolean
571 argument. If <option>true</option>
572 this unit will be stopped when it is
573 no longer used. Note that in order to
574 minimize the work to be executed,
575 systemd will not stop units by default
576 unless they are conflicting with other
577 units, or the user explicitly
578 requested their shut down. If this
579 option is set, a unit will be
580 automatically cleaned up if no other
581 active unit requires it. Defaults to
582 <option>false</option>.</para></listitem>
586 <term><varname>RefuseManualStart=</varname></term>
587 <term><varname>RefuseManualStop=</varname></term>
589 <listitem><para>Takes a boolean
590 argument. If <option>true</option>
591 this unit can only be activated
592 or deactivated indirectly. In
593 this case explicit start-up
594 or termination requested by the
595 user is denied, however if it is
596 started or stopped as a
597 dependency of another unit, start-up
598 or termination will succeed. This
599 is mostly a safety feature to ensure
600 that the user does not accidentally
601 activate units that are not intended
602 to be activated explicitly, and not
603 accidentally deactivate units that are
604 not intended to be deactivated.
605 These options default to
606 <option>false</option>.</para></listitem>
610 <term><varname>AllowIsolate=</varname></term>
612 <listitem><para>Takes a boolean
613 argument. If <option>true</option>
614 this unit may be used with the
615 <command>systemctl isolate</command>
616 command. Otherwise this will be
617 refused. It probably is a good idea to
618 leave this disabled except for target
619 units that shall be used similar to
620 runlevels in SysV init systems, just
621 as a precaution to avoid unusable
622 system states. This option defaults to
623 <option>false</option>.</para></listitem>
627 <term><varname>DefaultDependencies=</varname></term>
629 <listitem><para>Takes a boolean
630 argument. If <option>true</option>
631 (the default), a few default
632 dependencies will implicitly be
633 created for the unit. The actual
634 dependencies created depend on the
635 unit type. For example, for service
636 units, these dependencies ensure that
637 the service is started only after
638 basic system initialization is
639 completed and is properly terminated on
640 system shutdown. See the respective
641 man pages for details. Generally, only
642 services involved with early boot or
643 late shutdown should set this option
644 to <option>false</option>. It is
645 highly recommended to leave this
646 option enabled for the majority of
647 common units. If set to
648 <option>false</option> this option
649 does not disable all implicit
650 dependencies, just non-essential
651 ones.</para></listitem>
655 <term><varname>JobTimeoutSec=</varname></term>
657 <listitem><para>When clients are
658 waiting for a job of this unit to
659 complete, time out after the specified
660 time. If this time limit is reached
661 the job will be cancelled, the unit
662 however will not change state or even
663 enter the '<literal>failed</literal>'
664 mode. This value defaults to 0 (job
665 timeouts disabled), except for device
666 units. NB: this timeout is independent
667 from any unit-specific timeout (for
668 example, the timeout set with
669 <varname>Timeout=</varname> in service
670 units) as the job timeout has no
671 effect on the unit itself, only on the
672 job that might be pending for it. Or
673 in other words: unit-specific timeouts
674 are useful to abort unit state
675 changes, and revert them. The job
676 timeout set with this option however
677 is useful to abort only the job
678 waiting for the unit state to
679 change.</para></listitem>
683 <term><varname>ConditionPathExists=</varname></term>
684 <term><varname>ConditionPathExistsGlob=</varname></term>
685 <term><varname>ConditionPathIsDirectory=</varname></term>
686 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
687 <term><varname>ConditionPathIsMountPoint=</varname></term>
688 <term><varname>ConditionPathIsReadWrite=</varname></term>
689 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
690 <term><varname>ConditionFileNotEmpty=</varname></term>
691 <term><varname>ConditionFileIsExecutable=</varname></term>
692 <term><varname>ConditionKernelCommandLine=</varname></term>
693 <term><varname>ConditionVirtualization=</varname></term>
694 <term><varname>ConditionSecurity=</varname></term>
695 <term><varname>ConditionCapability=</varname></term>
696 <term><varname>ConditionHost=</varname></term>
697 <term><varname>ConditionACPower=</varname></term>
698 <term><varname>ConditionNull=</varname></term>
700 <listitem><para>Before starting a unit
701 verify that the specified condition is
702 true. If it is not true the starting
703 of the unit will be skipped, however
704 all ordering dependencies of it are
705 still respected. A failing condition
706 will not result in the unit being
707 moved into a failure state. The
708 condition is checked at the time the
709 queued start job is to be
713 <varname>ConditionPathExists=</varname>
714 a file existence condition is
715 checked before a unit is started. If
716 the specified absolute path name does
717 not exist the condition will
718 fail. If the absolute path name passed
720 <varname>ConditionPathExists=</varname>
721 is prefixed with an exclamation mark
722 ('!'), the test is negated, and the unit
723 is only started if the path does not
726 <para><varname>ConditionPathExistsGlob=</varname>
728 <varname>ConditionPathExists=</varname>,
729 but checks for the existence of at
730 least one file or directory matching
731 the specified globbing pattern.</para>
733 <para><varname>ConditionPathIsDirectory=</varname>
735 <varname>ConditionPathExists=</varname>
736 but verifies whether a certain path
740 <para><varname>ConditionPathIsSymbolicLink=</varname>
742 <varname>ConditionPathExists=</varname>
743 but verifies whether a certain path
744 exists and is a symbolic
747 <para><varname>ConditionPathIsMountPoint=</varname>
749 <varname>ConditionPathExists=</varname>
750 but verifies whether a certain path
751 exists and is a mount
754 <para><varname>ConditionPathIsReadWrite=</varname>
756 <varname>ConditionPathExists=</varname>
757 but verifies whether the underlying
758 file system is readable and writable
762 <para><varname>ConditionDirectoryNotEmpty=</varname>
764 <varname>ConditionPathExists=</varname>
765 but verifies whether a certain path
766 exists and is a non-empty
769 <para><varname>ConditionFileNotEmpty=</varname>
771 <varname>ConditionPathExists=</varname>
772 but verifies whether a certain path
773 exists and refers to a regular file
774 with a non-zero size.</para>
776 <para><varname>ConditionFileIsExecutable=</varname>
778 <varname>ConditionPathExists=</varname>
779 but verifies whether a certain path
780 exists, is a regular file and marked
784 <varname>ConditionKernelCommandLine=</varname>
785 may be used to check whether a
786 specific kernel command line option is
787 set (or if prefixed with the
788 exclamation mark unset). The argument
789 must either be a single word, or an
790 assignment (i.e. two words, separated
792 case the kernel command line is
793 searched for the word appearing as is,
794 or as left hand side of an
795 assignment. In the latter case the
796 exact assignment is looked for with
797 right and left hand side
800 <para><varname>ConditionVirtualization=</varname>
801 may be used to check whether the
802 system is executed in a virtualized
803 environment and optionally test
804 whether it is a specific
805 implementation. Takes either boolean
806 value to check if being executed in
807 any virtualized environment, or one of
808 <varname>vm</varname> and
809 <varname>container</varname> to test
810 against a generic type of
811 virtualization solution, or one of
812 <varname>qemu</varname>,
813 <varname>kvm</varname>,
814 <varname>vmware</varname>,
815 <varname>microsoft</varname>,
816 <varname>oracle</varname>,
817 <varname>xen</varname>,
818 <varname>bochs</varname>,
819 <varname>chroot</varname>,
820 <varname>openvz</varname>,
821 <varname>lxc</varname>,
822 <varname>lxc-libvirt</varname>,
823 <varname>systemd-nspawn</varname> to
824 test against a specific
825 implementation. If multiple
826 virtualization technologies are nested
827 only the innermost is considered. The
828 test may be negated by prepending an
829 exclamation mark.</para>
831 <para><varname>ConditionSecurity=</varname>
832 may be used to check whether the given
833 security module is enabled on the
834 system. Currently the only recognized
835 value is <varname>selinux</varname>.
836 The test may be negated by prepending
840 <para><varname>ConditionCapability=</varname>
841 may be used to check whether the given
842 capability exists in the capability
843 bounding set of the service manager
844 (i.e. this does not check whether
845 capability is actually available in
846 the permitted or effective sets, see
847 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
848 for details). Pass a capability name
849 such as <literal>CAP_MKNOD</literal>,
850 possibly prefixed with an exclamation
851 mark to negate the check.</para>
853 <para><varname>ConditionHost=</varname>
854 may be used to match against the
855 host name or machine ID of the
856 host. This either takes a host name
857 string (optionally with shell style
858 globs) which is tested against the
859 locally set host name as returned by
860 <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
861 or a machine ID formatted as string
863 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
864 The test may be negated by prepending
865 an exclamation mark.</para>
867 <para><varname>ConditionACPower=</varname>
868 may be used to check whether the
869 system has AC power, or is exclusively
870 battery powered at the time of
871 activation of the unit. This takes a
872 boolean argument. If set to
873 <varname>true</varname> the condition
874 will hold only if at least one AC
875 connector of the system is connected
876 to a power source, or if no AC
877 connectors are known. Conversely, if
878 set to <varname>false</varname> the
879 condition will hold only if there is
880 at least one AC connector known and
881 all AC connectors are disconnected
882 from a power source.</para>
885 <varname>ConditionNull=</varname> may
886 be used to add a constant condition
887 check value to the unit. It takes a
888 boolean argument. If set to
889 <varname>false</varname> the condition
890 will always fail, otherwise
893 <para>If multiple conditions are
894 specified the unit will be executed if
895 all of them apply (i.e. a logical AND
896 is applied). Condition checks can be
897 prefixed with a pipe symbol (|) in
898 which case a condition becomes a
899 triggering condition. If at least one
900 triggering condition is defined for a
901 unit then the unit will be executed if
902 at least one of the triggering
903 conditions apply and all of the
904 non-triggering conditions. If you
905 prefix an argument with the pipe
906 symbol and an exclamation mark the
907 pipe symbol must be passed first, the
908 exclamation second. Except for
909 <varname>ConditionPathIsSymbolicLink=</varname>,
910 all path checks follow
911 symlinks.</para></listitem>
915 <term><varname>SourcePath=</varname></term>
916 <listitem><para>A path to a
917 configuration file this unit has been
918 generated from. This is primarily
919 useful for implementation of generator
920 tools that convert configuration from
921 an external configuration file format
922 into native unit files. Thus
923 functionality should not be used in
924 normal units.</para></listitem>
928 <para>Unit file may include a [Install] section, which
929 carries installation information for the unit. This
930 section is not interpreted by
931 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
932 during runtime. It is used exclusively by the
933 <command>enable</command> and
934 <command>disable</command> commands of the
935 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
936 tool during installation of a unit:</para>
940 <term><varname>Alias=</varname></term>
942 <listitem><para>Additional names this
943 unit shall be installed under. The
944 names listed here must have the same
945 suffix (i.e. type) as the unit file
946 name. This option may be specified
947 more than once, in which case all
948 listed names are used. At installation
950 <command>systemctl enable</command>
951 will create symlinks from these names
952 to the unit file name.</para></listitem>
956 <term><varname>WantedBy=</varname></term>
957 <term><varname>RequiredBy=</varname></term>
959 <listitem><para>Installs a symlink in
960 the <filename>.wants/</filename>
961 or <filename>.requires/</filename>
962 subdirectory for a unit, respectively. This has the
963 effect that when the listed unit name
964 is activated the unit listing it is
966 too. <command>WantedBy=foo.service</command>
968 <filename>bar.service</filename> is
970 <command>Alias=foo.service.wants/bar.service</command>
971 in the same file.</para></listitem>
975 <term><varname>Also=</varname></term>
977 <listitem><para>Additional units to
978 install when this unit is
979 installed. If the user requests
980 installation of a unit with this
982 <command>systemctl enable</command>
983 will automatically install units
984 listed in this option as
985 well.</para></listitem>
992 <title>Specifiers</title>
994 <para>Many settings resolve specifiers which may be
995 used to write generic unit files referring to runtime
996 or unit parameters that are replaced when the unit
997 files are loaded. The following specifiers are
1001 <title>Specifiers available in unit files</title>
1002 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1003 <colspec colname="spec" />
1004 <colspec colname="mean" />
1005 <colspec colname="detail" />
1008 <entry>Specifier</entry>
1009 <entry>Meaning</entry>
1010 <entry>Details</entry>
1015 <entry><literal>%n</literal></entry>
1016 <entry>Full unit name</entry>
1020 <entry><literal>%N</literal></entry>
1021 <entry>Unescaped full unit name</entry>
1025 <entry><literal>%p</literal></entry>
1026 <entry>Prefix name</entry>
1027 <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>
1030 <entry><literal>%P</literal></entry>
1031 <entry>Unescaped prefix name</entry>
1035 <entry><literal>%i</literal></entry>
1036 <entry>Instance name</entry>
1037 <entry>For instantiated units: this is the string between the @ character and the suffix.</entry>
1040 <entry><literal>%I</literal></entry>
1041 <entry>Unescaped instance name</entry>
1045 <entry><literal>%f</literal></entry>
1046 <entry>Unescaped file name</entry>
1047 <entry>This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /.</entry>
1050 <entry><literal>%c</literal></entry>
1051 <entry>Control group path of the unit</entry>
1055 <entry><literal>%r</literal></entry>
1056 <entry>Root control group path of systemd</entry>
1060 <entry><literal>%R</literal></entry>
1061 <entry>Parent directory of the root control group path of systemd</entry>
1065 <entry><literal>%t</literal></entry>
1066 <entry>Runtime socket dir</entry>
1067 <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry>
1070 <entry><literal>%u</literal></entry>
1071 <entry>User name</entry>
1072 <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1075 <entry><literal>%U</literal></entry>
1076 <entry>User UID</entry>
1077 <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1080 <entry><literal>%h</literal></entry>
1081 <entry>User home directory</entry>
1082 <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>
1085 <entry><literal>%s</literal></entry>
1086 <entry>User shell</entry>
1087 <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1090 <entry><literal>%m</literal></entry>
1091 <entry>Machine ID</entry>
1092 <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>
1095 <entry><literal>%b</literal></entry>
1096 <entry>Boot ID</entry>
1097 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1100 <entry><literal>%H</literal></entry>
1101 <entry>Host name</entry>
1102 <entry>The host name of the running system.</entry>
1110 <title>See Also</title>
1112 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1113 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1114 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1115 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1116 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1117 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1118 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1119 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1120 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1121 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1122 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1123 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1124 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1125 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1126 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1127 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>