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