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 General Public License as published by
12 the Free Software Foundation; either version 2 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 General Public License for more details.
20 You should have received a copy of the GNU 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>systemd unit configuration files</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 pages lists the common configuration
79 options of all the unit types. These options need to
80 be configured in the [Unit] resp. [Install]
81 section of the unit files.</para>
83 <para>In addition to the generic [Unit] and [Install]
84 sections described here, each unit should 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
110 multiple values with units is supported, in which case
111 the 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.</para>
116 <para>Empty lines and lines starting with # or ; are
117 ignored. This may be used for commenting. Lines ending
118 in a backslash are concatenated with the following
119 line while reading and the backslash is replaced by a
120 space character. This may be used to wrap long lines.</para>
122 <para>If a line starts with <option>.include</option>
123 followed by a file name, the specified file will be
124 read as if its contents were listed in place of the
125 <option>.include</option> directive.</para>
127 <para>Along with a unit file
128 <filename>foo.service</filename> a directory
129 <filename>foo.service.wants/</filename> may exist. All
130 units symlinked from such a directory are implicitly
131 added as dependencies of type
132 <varname>Wanted=</varname> to the unit. This is useful
133 to hook units into the start-up of other units,
134 without having to modify their unit configuration
135 files. For details about the semantics of
136 <varname>Wanted=</varname> see below. The preferred
137 way to create symlinks in the
138 <filename>.wants/</filename> directory of a service is
139 with the <command>enable</command> command of the
140 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
141 tool which reads information from the [Install]
142 section of unit files. (See below.) A similar
143 functionality exists for <varname>Requires=</varname>
144 type dependencies as well, the directory suffix is
145 <filename>.requires/</filename> in this case.</para>
147 <para>Note that while systemd offers a flexible
148 dependency system between units it is recommended to
149 use this functionality only sparsely and instead rely
150 on techniques such as bus-based or socket-based
151 activation which makes dependencies implicit, which
152 both results in a simpler and more flexible
155 <para>Some unit names reflect paths existing in the
156 file system name space. Example: a device unit
157 <filename>dev-sda.device</filename> refers to a device
158 with the device node <filename>/dev/sda</filename> in
159 the file system namespace. If this applies a special
160 way to escape the path name is used, so that the
161 result is usable as part of a file name. Basically,
162 given a path, "/" is replaced by "-", and all
163 unprintable characters and the "-" are replaced by
164 C-style "\x20" escapes. The root directory "/" is
165 encoded as single dash, while otherwise the initial
166 and ending "/" is removed from all paths during
167 transformation. This escaping is reversible.</para>
169 <para>Optionally, units may be instantiated from a
170 template file at runtime. This allows creation of
171 multiple units from a single configuration file. If
172 systemd looks for a unit configuration file it will
173 first search for the literal unit name in the
174 filesystem. If that yields no success and the unit
175 name contains an @ character, systemd will look for a
176 unit template that shares the same name but with the
177 instance string (i.e. the part between the @ character
178 and the suffix) removed. Example: if a service
179 <filename>getty@tty3.service</filename> is requested
180 and no file by that name is found, systemd will look
181 for <filename>getty@.service</filename> and
182 instantiate a service from that configuration file if
185 <para>To refer to the instance string from
186 within the configuration file you may use the special
187 <literal>%i</literal> specifier in many of the
188 configuration options. Other specifiers exist, the
192 <title>Specifiers available in unit files</title>
193 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
194 <colspec colname="spec" />
195 <colspec colname="mean" />
196 <colspec colname="detail" />
199 <entry>Specifier</entry>
200 <entry>Meaning</entry>
201 <entry>Details</entry>
206 <entry><literal>%n</literal></entry>
207 <entry>Full unit name</entry>
211 <entry><literal>%N</literal></entry>
212 <entry>Unescaped full unit name</entry>
216 <entry><literal>%p</literal></entry>
217 <entry>Prefix name</entry>
218 <entry>This refers to the string before the @, i.e. "getty" in the example above, where "tty3" is the instance name.</entry>
221 <entry><literal>%P</literal></entry>
222 <entry>Unescaped prefix name</entry>
226 <entry><literal>%i</literal></entry>
227 <entry>Instance name</entry>
228 <entry>This is the string between the @ character and the suffix.</entry>
231 <entry><literal>%I</literal></entry>
232 <entry>Unescaped instance name</entry>
236 <entry><literal>%f</literal></entry>
237 <entry>Unescaped file name</entry>
238 <entry>This is either the unescaped instance name (if set) with / prepended (if necessary), or the prefix name similarly prepended with /.</entry>
241 <entry><literal>%c</literal></entry>
242 <entry>Control group path of the unit</entry>
246 <entry><literal>%r</literal></entry>
247 <entry>Root control group path of systemd</entry>
251 <entry><literal>%R</literal></entry>
252 <entry>Parent directory of the root control group path of systemd</entry>
256 <entry><literal>%t</literal></entry>
257 <entry>Runtime socket dir</entry>
258 <entry>This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers).</entry>
264 <para>If a unit file is empty (i.e. has the file size
265 0) or is symlinked to <filename>/dev/null</filename>
266 its configuration will not be loaded and it appears
267 with a load state of <literal>masked</literal>, and
268 cannot be activated. Use this as an effective way to
269 fully disable a unit, making it impossible to start it
270 even manually.</para>
272 <para>The unit file format is covered by the
274 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
275 Stability Promise</ulink>.</para>
279 <title>Options</title>
281 <para>Unit file may include a [Unit] section, which
282 carries generic information about the unit that is not
283 dependent on the type of unit:</para>
288 <term><varname>Description=</varname></term>
289 <listitem><para>A free-form string
290 describing the unit. This is intended
291 for use in UIs to show descriptive
292 information along with the unit
293 name.</para></listitem>
297 <term><varname>Requires=</varname></term>
299 <listitem><para>Configures requirement
300 dependencies on other units. If this
301 unit gets activated, the units listed
302 here will be activated as well. If one
303 of the other units gets deactivated or
304 its activation fails, this unit will
305 be deactivated. This option may be
306 specified more than once, in which
307 case requirement dependencies for all
308 listed names are created. Note that
309 requirement dependencies do not
310 influence the order in which services
311 are started or stopped. This has to be
312 configured independently with the
313 <varname>After=</varname> or
314 <varname>Before=</varname> options. If
316 <filename>foo.service</filename>
318 <filename>bar.service</filename> as
320 <varname>Requires=</varname> and no
321 ordering is configured with
322 <varname>After=</varname> or
323 <varname>Before=</varname>, then both
324 units will be started simultaneously
325 and without any delay between them if
326 <filename>foo.service</filename> is
327 activated. Often it is a better choice
328 to use <varname>Wants=</varname>
330 <varname>Requires=</varname> in order
331 to achieve a system that is more
332 robust when dealing with failing
333 services.</para></listitem>
337 <term><varname>RequiresOverridable=</varname></term>
339 <listitem><para>Similar to
340 <varname>Requires=</varname>.
341 Dependencies listed in
342 <varname>RequiresOverridable=</varname>
343 which cannot be fulfilled or fail to
344 start are ignored if the startup was
345 explicitly requested by the user. If
346 the start-up was pulled in indirectly
347 by some dependency or automatic
348 start-up of units that is not
349 requested by the user this dependency
350 must be fulfilled and otherwise the
351 transaction fails. Hence, this option
352 may be used to configure dependencies
353 that are normally honored unless the
354 user explicitly starts up the unit, in
355 which case whether they failed or not
356 is irrelevant.</para></listitem>
360 <term><varname>Requisite=</varname></term>
361 <term><varname>RequisiteOverridable=</varname></term>
363 <listitem><para>Similar to
364 <varname>Requires=</varname>
365 resp. <varname>RequiresOverridable=</varname>. However,
366 if a unit listed here is not started
367 already it will not be started and the
369 immediately.</para></listitem>
373 <term><varname>Wants=</varname></term>
375 <listitem><para>A weaker version of
376 <varname>Requires=</varname>. A unit
377 listed in this option will be started
378 if the configuring unit is. However,
379 if the listed unit fails to start up
380 or cannot be added to the transaction
381 this has no impact on the validity of
382 the transaction as a whole. This is
383 the recommended way to hook start-up
384 of one unit to the start-up of another
385 unit. Note that dependencies of this
386 type may also be configured outside of
387 the unit configuration file by
388 adding a symlink to a
389 <filename>.wants/</filename> directory
390 accompanying the unit file. For
391 details see above.</para></listitem>
395 <term><varname>BindTo=</varname></term>
397 <listitem><para>Configures requirement
398 dependencies, very similar in style to
399 <varname>Requires=</varname>, however
400 in addition to this behaviour it also
401 declares that this unit is stopped
402 when any of the units listed suddenly
403 disappears. Units can suddenly,
404 unexpectedly disappear if a service
405 terminates on its own choice, a device
406 is unplugged or a mount point
407 unmounted without involvement of
408 systemd.</para></listitem>
412 <term><varname>Conflicts=</varname></term>
414 <listitem><para>Configures negative
415 requirement dependencies. If a unit
417 <varname>Conflicts=</varname> setting
418 on another unit, starting the former
419 will stop the latter and vice
420 versa. Note that this setting is
421 independent of and orthogonal to the
422 <varname>After=</varname> and
423 <varname>Before=</varname> ordering
426 <para>If a unit A that conflicts with
427 a unit B is scheduled to be started at
428 the same time as B, the transaction
429 will either fail (in case both are
430 required part of the transaction) or
431 be modified to be fixed (in case one
432 or both jobs are not a required part
433 of the transaction). In the latter
434 case the job that is not the required
435 will be removed, or in case both are
436 not required the unit that conflicts
437 will be started and the unit that is
439 stopped.</para></listitem>
443 <term><varname>Before=</varname></term>
444 <term><varname>After=</varname></term>
446 <listitem><para>Configures ordering
447 dependencies between units. If a unit
448 <filename>foo.service</filename>
450 <option>Before=bar.service</option>
451 and both units are being started,
452 <filename>bar.service</filename>'s
453 start-up is delayed until
454 <filename>foo.service</filename> is
455 started up. Note that this setting is
456 independent of and orthogonal to the
457 requirement dependencies as configured
458 by <varname>Requires=</varname>. It is
459 a common pattern to include a unit
461 <varname>After=</varname> and
462 <varname>Requires=</varname> option in
463 which case the unit listed will be
464 started before the unit that is
465 configured with these options. This
466 option may be specified more than
467 once, in which case ordering
468 dependencies for all listed names are
469 created. <varname>After=</varname> is
471 <varname>Before=</varname>, i.e. while
472 <varname>After=</varname> ensures that
473 the configured unit is started after
474 the listed unit finished starting up,
475 <varname>Before=</varname> ensures the
476 opposite, i.e. that the configured
477 unit is fully started up before the
478 listed unit is started. Note that when
479 two units with an ordering dependency
480 between them are shut down, the
481 inverse of the start-up order is
482 applied. i.e. if a unit is configured
483 with <varname>After=</varname> on
484 another unit, the former is stopped
485 before the latter if both are shut
486 down. If one unit with an ordering
487 dependency on another unit is shut
488 down while the latter is started up,
489 the shut down is ordered before the
490 start-up regardless whether the
491 ordering dependency is actually of
492 type <varname>After=</varname> or
493 <varname>Before=</varname>. If two
494 units have no ordering dependencies
495 between them they are shut down
496 resp. started up simultaneously, and
498 place. </para></listitem>
502 <term><varname>OnFailure=</varname></term>
504 <listitem><para>Lists one or more
505 units that are activated when this
507 '<literal>failed</literal>'
508 state.</para></listitem>
512 <term><varname>OnFailureIsolate=</varname></term>
514 <listitem><para>Takes a boolean
515 argument. If <option>true</option> the
517 <varname>OnFailure=</varname> will be
518 enqueued in isolation mode, i.e. all
519 units that are not its dependency will
520 be stopped. If this is set only a
521 single unit may be listed in
522 <varname>OnFailure=</varname>. Defaults
524 <option>false</option>.</para></listitem>
528 <term><varname>IgnoreOnIsolate=</varname></term>
530 <listitem><para>Takes a boolean
531 argument. If <option>true</option>
532 this unit will not be stopped when
533 isolating another unit. Defaults to
534 <option>false</option>.</para></listitem>
538 <term><varname>IgnoreOnSnapshot=</varname></term>
540 <listitem><para>Takes a boolean
541 argument. If <option>true</option>
542 this unit will not be included in
543 snapshots. Defaults to
544 <option>true</option> for device and
545 snapshot units, <option>false</option>
546 for the others.</para></listitem>
550 <term><varname>StopWhenUnneeded=</varname></term>
552 <listitem><para>Takes a boolean
553 argument. If <option>true</option>
554 this unit will be stopped when it is
555 no longer used. Note that in order to
556 minimize the work to be executed,
557 systemd will not stop units by default
558 unless they are conflicting with other
559 units, or the user explicitly
560 requested their shut down. If this
561 option is set, a unit will be
562 automatically cleaned up if no other
563 active unit requires it. Defaults to
564 <option>false</option>.</para></listitem>
568 <term><varname>RefuseManualStart=</varname></term>
569 <term><varname>RefuseManualStop=</varname></term>
571 <listitem><para>Takes a boolean
572 argument. If <option>true</option>
573 this unit can only be activated
574 (resp. deactivated) indirectly. In
575 this case explicit start-up
576 (resp. termination) requested by the
577 user is denied, however if it is
578 started (resp. stopped) as a
579 dependency of another unit, start-up
580 (resp. termination) will succeed. This
581 is mostly a safety feature to ensure
582 that the user does not accidentally
583 activate units that are not intended
584 to be activated explicitly, and not
585 accidentally deactivate units that are
586 not intended to be deactivated.
587 These options default to
588 <option>false</option>.</para></listitem>
592 <term><varname>AllowIsolate=</varname></term>
594 <listitem><para>Takes a boolean
595 argument. If <option>true</option>
596 this unit may be used with the
597 <command>systemctl isolate</command>
598 command. Otherwise this will be
599 refused. It probably is a good idea to
600 leave this disabled except for target
601 units that shall be used similar to
602 runlevels in SysV init systems, just
603 as a precaution to avoid unusable
604 system states. This option defaults to
605 <option>false</option>.</para></listitem>
609 <term><varname>DefaultDependencies=</varname></term>
611 <listitem><para>Takes a boolean
612 argument. If <option>true</option>
613 (the default), a few default
614 dependencies will implicitly be
615 created for the unit. The actual
616 dependencies created depend on the
617 unit type. For example, for service
618 units, these dependencies ensure that
619 the service is started only after
620 basic system initialization is
621 completed and is properly terminated on
622 system shutdown. See the respective
623 man pages for details. Generally, only
624 services involved with early boot or
625 late shutdown should set this option
626 to <option>false</option>. It is
627 highly recommended to leave this
628 option enabled for the majority of
629 common units. If set to
630 <option>false</option> this option
631 does not disable all implicit
632 dependencies, just non-essential
633 ones.</para></listitem>
637 <term><varname>JobTimeoutSec=</varname></term>
639 <listitem><para>When clients are
640 waiting for a job of this unit to
641 complete, time out after the specified
642 time. If this time limit is reached
643 the job will be cancelled, the unit
644 however will not change state or even
645 enter the '<literal>failed</literal>'
646 mode. This value defaults to 0 (job
647 timeouts disabled), except for device
648 units. NB: this timeout is independent
649 from any unit-specific timeout (for
650 example, the timeout set with
651 <varname>Timeout=</varname> in service
652 units) as the job timeout has no
653 effect on the unit itself, only on the
654 job that might be pending for it. Or
655 in other words: unit-specific timeouts
656 are useful to abort unit state
657 changes, and revert them. The job
658 timeout set with this option however
659 is useful to abort only the job
660 waiting for the unit state to
661 change.</para></listitem>
665 <term><varname>ConditionPathExists=</varname></term>
666 <term><varname>ConditionPathExistsGlob=</varname></term>
667 <term><varname>ConditionPathIsDirectory=</varname></term>
668 <term><varname>ConditionPathIsSymbolicLink=</varname></term>
669 <term><varname>ConditionPathIsMountPoint=</varname></term>
670 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
671 <term><varname>ConditionFileIsExecutable=</varname></term>
672 <term><varname>ConditionKernelCommandLine=</varname></term>
673 <term><varname>ConditionVirtualization=</varname></term>
674 <term><varname>ConditionSecurity=</varname></term>
675 <term><varname>ConditionNull=</varname></term>
677 <listitem><para>Before starting a unit
678 verify that the specified condition is
680 <varname>ConditionPathExists=</varname>
681 a file existence condition can be
682 checked before a unit is started. If
683 the specified absolute path name does
684 not exist, startup of a unit will not
685 actually happen, however the unit is
686 still useful for ordering purposes in
687 this case. The condition is checked at
688 the time the queued start job is to be
689 executed. If the absolute path name
691 <varname>ConditionPathExists=</varname>
692 is prefixed with an exclamation mark
693 (!), the test is negated, and the unit
694 is only started if the path does not
696 <varname>ConditionPathExistsGlob=</varname>
697 works in a similar way, but checks for
698 the existence of at least one file or
699 directory matching the specified
701 pattern. <varname>ConditionPathIsDirectory=</varname>
703 <varname>ConditionPathExists=</varname>
704 but verifies whether a certain path
706 directory. <varname>ConditionPathIsSymbolicLink=</varname>
708 <varname>ConditionPathExists=</varname>
709 but verifies whether a certain path
710 exists and is a symbolic
711 link. <varname>ConditionPathIsMountPoint=</varname>
713 <varname>ConditionPathExists=</varname>
714 but verifies whether a certain path
715 exists and is a mount
716 point. <varname>ConditionFileIsExecutable=</varname>
718 <varname>ConditionPathExists=</varname>
719 but verifies whether a certain path
720 exists, is a regular file and marked
722 <varname>ConditionDirectoryNotEmpty=</varname>
724 <varname>ConditionPathExists=</varname>
725 but verifies whether a certain path
726 exists and is a non-empty
728 <varname>ConditionKernelCommandLine=</varname>
729 may be used to check whether a
730 specific kernel command line option is
731 set (or if prefixed with the
732 exclamation mark unset). The argument
733 must either be a single word, or an
734 assignment (i.e. two words, separated
735 by the equality sign). In the former
736 case the kernel command line is
737 searched for the word appearing as is,
738 or as left hand side of an
739 assignment. In the latter case the
740 exact assignment is looked for with
741 right and left hand side
742 matching. <varname>ConditionVirtualization=</varname>
743 may be used to check whether the
744 system is executed in a virtualized
745 environment and optionally test
746 whether it is a specific
747 implementation. Takes either boolean
748 value to check if being executed in
749 any virtualized environment, or one of
750 <varname>vm</varname> and
751 <varname>container</varname> to test against
752 a specific type of virtualization
754 <varname>qemu</varname>,
755 <varname>kvm</varname>,
756 <varname>vmware</varname>,
757 <varname>microsoft</varname>,
758 <varname>oracle</varname>,
759 <varname>xen</varname>,
760 <varname>bochs</varname>,
761 <varname>chroot</varname>,
762 <varname>openvz</varname>,
763 <varname>lxc</varname>,
764 <varname>systemd-nspawn</varname>,
765 <varname>pidns</varname> to test
766 against a specific implementation. If
767 multiple virtualization technologies
768 are nested only the innermost is
769 considered. The test may be negated by
770 prepending an exclamation mark.
771 <varname>ConditionSecurity=</varname>
772 may be used to check whether the given
773 security module is enabled on the
774 system. Currently the only recognized
775 value is <varname>selinux</varname>.
776 The test may be negated by prepending
777 an exclamation mark. Finally,
778 <varname>ConditionNull=</varname> may
779 be used to add a constant condition
780 check value to the unit. It takes a
781 boolean argument. If set to
782 <varname>false</varname> the condition
783 will always fail, otherwise
784 succeed. If multiple conditions are
785 specified the unit will be executed if
786 all of them apply (i.e. a logical AND
787 is applied). Condition checks can be
788 prefixed with a pipe symbol (|) in
789 which case a condition becomes a
790 triggering condition. If at least one
791 triggering condition is defined for a
792 unit then the unit will be executed if
793 at least one of the triggering
794 conditions apply and all of the
795 non-triggering conditions. If you
796 prefix an argument with the pipe
797 symbol and an exclamation mark the
798 pipe symbol must be passed first, the
799 exclamation second. Except for
800 <varname>ConditionPathIsSymbolicLink=</varname>,
801 all path checks follow
802 symlinks.</para></listitem>
806 <term><varname>Names=</varname></term>
808 <listitem><para>Additional names for
809 this unit. The names listed here must
810 have the same suffix (i.e. type) as
811 the unit file name. This option may be
812 specified more than once, in which
813 case all listed names are used. Note
814 that this option is different from the
815 <varname>Alias=</varname> option from
816 the [Install] section mentioned
817 below. See below for details. Note
818 that in almost all cases this option
819 is not what you want. A symlink alias
820 in the file system is generally
821 preferable since it can be used as
822 lookup key. If a unit with a symlinked
823 alias name is not loaded and needs to
824 be it is easily found via the
825 symlink. However, if a unit with an
826 alias name configured with this
827 setting is not loaded it will not be
828 discovered. This settings' only use is
829 in conjunction with service
835 <para>Unit file may include a [Install] section, which
836 carries installation information for the unit. This
837 section is not interpreted by
838 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
839 during runtime. It is used exclusively by the
840 <command>enable</command> and
841 <command>disable</command> commands of the
842 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
843 tool during installation of a unit:</para>
847 <term><varname>Alias=</varname></term>
849 <listitem><para>Additional names this
850 unit shall be installed under. The
851 names listed here must have the same
852 suffix (i.e. type) as the unit file
853 name. This option may be specified
854 more than once, in which case all
855 listed names are used. At installation
857 <command>systemctl enable</command>
858 will create symlinks from these names
859 to the unit file name. Note that this
860 is different from the
861 <varname>Names=</varname> option from
862 the [Unit] section mentioned above:
864 <varname>Names=</varname> apply
865 unconditionally if the unit is
866 loaded. The names from
867 <varname>Alias=</varname> apply only
868 if the unit has actually been
870 <command>systemctl enable</command>
871 command. Also, if systemd searches for a
872 unit, it will discover symlinked alias
873 names as configured with
874 <varname>Alias=</varname>, but not
875 names configured with
876 <varname>Names=</varname> only. It is
877 a common pattern to list a name in
878 both options. In this case, a unit
879 will be active under all names if
880 installed, but also if not installed
881 but requested explicitly under its
882 main name.</para></listitem>
886 <term><varname>WantedBy=</varname></term>
888 <listitem><para>Installs a symlink in
889 the <filename>.wants/</filename>
890 subdirectory for a unit. This has the
891 effect that when the listed unit name
892 is activated the unit listing it is
894 too. <command>WantedBy=foo.service</command>
896 <filename>bar.service</filename> is
898 <command>Alias=foo.service.wants/bar.service</command>
899 in the same file.</para></listitem>
903 <term><varname>Also=</varname></term>
905 <listitem><para>Additional units to
906 install when this unit is
907 installed. If the user requests
908 installation of a unit with this
910 <command>systemctl enable</command>
911 will automatically install units
912 listed in this option as
913 well.</para></listitem>
920 <title>See Also</title>
922 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
923 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
924 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
925 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
926 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
927 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
928 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
929 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
930 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
931 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
932 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
933 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
934 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>