]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd.unit.xml
0fc2fbe730614c1271b65c014128eb8dd2ae88c5
[thirdparty/systemd.git] / man / systemd.unit.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2010 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="systemd.unit">
25
26 <refentryinfo>
27 <title>systemd.unit</title>
28 <productname>systemd</productname>
29
30 <authorgroup>
31 <author>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
36 </author>
37 </authorgroup>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>systemd.unit</refentrytitle>
42 <manvolnum>5</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>systemd.unit</refname>
47 <refpurpose>systemd unit configuration files</refpurpose>
48 </refnamediv>
49
50 <refsynopsisdiv>
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>
61 </refsynopsisdiv>
62
63 <refsect1>
64 <title>Description</title>
65
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
70 supervised by
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>
77
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>
82
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
87 information.</para>
88
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>
96
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
104 equivalent.</para>
105
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>
115
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>
121
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>
126
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>
146
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
153 system.</para>
154
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>
168
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
183 it is found. To refer to the instance string from
184 within the configuration file you may use the special
185 <literal>%i</literal> specifier in many of the
186 configuration options. Other specifiers that may be
187 used are <literal>%n</literal>, <literal>%N</literal>,
188 <literal>%p</literal>, <literal>%P</literal>,
189 <literal>%I</literal> and <literal>%f</literal>, for
190 the full unit name, the unescaped unit name, the
191 prefix name, the unescaped prefix name, the unescaped
192 instance name and the unescaped filename,
193 respectively. The unescaped filename is either the
194 unescaped instance name (if set) with / prepended (if
195 necessary), or the prefix name similarly prepended
196 with /. The prefix name here refers to the string
197 before the @, i.e. "getty" in the example above, where
198 "tty3" is the instance name.</para>
199
200 <para>If a unit file is empty (i.e. has the file size
201 0) or is symlinked to <filename>/dev/null</filename>
202 its configuration will not be loaded and it appears
203 with a load state of <literal>masked</literal>, and
204 cannot be activated. Use this as an effective way to
205 fully disable a unit, making it impossible to start it
206 even manually.</para>
207
208 <para>The unit file format is covered by the
209 <ulink
210 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
211 Stability Promise</ulink>.</para>
212 </refsect1>
213
214 <refsect1>
215 <title>Options</title>
216
217 <para>Unit file may include a [Unit] section, which
218 carries generic information about the unit that is not
219 dependent on the type of unit:</para>
220
221 <variablelist>
222
223 <varlistentry>
224 <term><varname>Description=</varname></term>
225 <listitem><para>A free-form string
226 describing the unit. This is intended
227 for use in UIs to show descriptive
228 information along with the unit
229 name.</para></listitem>
230 </varlistentry>
231
232 <varlistentry>
233 <term><varname>Requires=</varname></term>
234
235 <listitem><para>Configures requirement
236 dependencies on other units. If this
237 unit gets activated, the units listed
238 here will be activated as well. If one
239 of the other units gets deactivated or
240 its activation fails, this unit will
241 be deactivated. This option may be
242 specified more than once, in which
243 case requirement dependencies for all
244 listed names are created. Note that
245 requirement dependencies do not
246 influence the order in which services
247 are started or stopped. This has to be
248 configured independently with the
249 <varname>After=</varname> or
250 <varname>Before=</varname> options. If
251 a unit
252 <filename>foo.service</filename>
253 requires a unit
254 <filename>bar.service</filename> as
255 configured with
256 <varname>Requires=</varname> and no
257 ordering is configured with
258 <varname>After=</varname> or
259 <varname>Before=</varname>, then both
260 units will be started simultaneously
261 and without any delay between them if
262 <filename>foo.service</filename> is
263 activated. Often it is a better choice
264 to use <varname>Wants=</varname>
265 instead of
266 <varname>Requires=</varname> in order
267 to achieve a system that is more
268 robust when dealing with failing
269 services.</para></listitem>
270 </varlistentry>
271
272 <varlistentry>
273 <term><varname>RequiresOverridable=</varname></term>
274
275 <listitem><para>Similar to
276 <varname>Requires=</varname>.
277 Dependencies listed in
278 <varname>RequiresOverridable=</varname>
279 which cannot be fulfilled or fail to
280 start are ignored if the startup was
281 explicitly requested by the user. If
282 the start-up was pulled in indirectly
283 by some dependency or automatic
284 start-up of units that is not
285 requested by the user this dependency
286 must be fulfilled and otherwise the
287 transaction fails. Hence, this option
288 may be used to configure dependencies
289 that are normally honored unless the
290 user explicitly starts up the unit, in
291 which case whether they failed or not
292 is irrelevant.</para></listitem>
293
294 </varlistentry>
295 <varlistentry>
296 <term><varname>Requisite=</varname></term>
297 <term><varname>RequisiteOverridable=</varname></term>
298
299 <listitem><para>Similar to
300 <varname>Requires=</varname>
301 resp. <varname>RequiresOverridable=</varname>. However,
302 if a unit listed here is not started
303 already it will not be started and the
304 transaction fails
305 immediately.</para></listitem>
306 </varlistentry>
307
308 <varlistentry>
309 <term><varname>Wants=</varname></term>
310
311 <listitem><para>A weaker version of
312 <varname>Requires=</varname>. A unit
313 listed in this option will be started
314 if the configuring unit is. However,
315 if the listed unit fails to start up
316 or cannot be added to the transaction
317 this has no impact on the validity of
318 the transaction as a whole. This is
319 the recommended way to hook start-up
320 of one unit to the start-up of another
321 unit. Note that dependencies of this
322 type may also be configured outside of
323 the unit configuration file by
324 adding a symlink to a
325 <filename>.wants/</filename> directory
326 accompanying the unit file. For
327 details see above.</para></listitem>
328 </varlistentry>
329
330 <varlistentry>
331 <term><varname>BindTo=</varname></term>
332
333 <listitem><para>Configures requirement
334 dependencies, very similar in style to
335 <varname>Requires=</varname>, however
336 in addition to this behaviour it also
337 declares that this unit is stopped
338 when any of the units listed suddenly
339 disappears. Units can suddenly,
340 unexpectedly disappear if a service
341 terminates on its own choice, a device
342 is unplugged or a mount point
343 unmounted without involvement of
344 systemd.</para></listitem>
345 </varlistentry>
346
347 <varlistentry>
348 <term><varname>Conflicts=</varname></term>
349
350 <listitem><para>Configures negative
351 requirement dependencies. If a unit
352 has a
353 <varname>Conflicts=</varname> setting
354 on another unit, starting the former
355 will stop the latter and vice
356 versa. Note that this setting is
357 independent of and orthogonal to the
358 <varname>After=</varname> and
359 <varname>Before=</varname> ordering
360 dependencies.</para>
361
362 <para>If a unit A that conflicts with
363 a unit B is scheduled to be started at
364 the same time as B, the transaction
365 will either fail (in case both are
366 required part of the transaction) or
367 be modified to be fixed (in case one
368 or both jobs are not a required part
369 of the transaction). In the latter
370 case the job that is not the required
371 will be removed, or in case both are
372 not required the unit that conflicts
373 will be started and the unit that is
374 conflicted is
375 stopped.</para></listitem>
376 </varlistentry>
377
378 <varlistentry>
379 <term><varname>Before=</varname></term>
380 <term><varname>After=</varname></term>
381
382 <listitem><para>Configures ordering
383 dependencies between units. If a unit
384 <filename>foo.service</filename>
385 contains a setting
386 <option>Before=bar.service</option>
387 and both units are being started,
388 <filename>bar.service</filename>'s
389 start-up is delayed until
390 <filename>foo.service</filename> is
391 started up. Note that this setting is
392 independent of and orthogonal to the
393 requirement dependencies as configured
394 by <varname>Requires=</varname>. It is
395 a common pattern to include a unit
396 name in both the
397 <varname>After=</varname> and
398 <varname>Requires=</varname> option in
399 which case the unit listed will be
400 started before the unit that is
401 configured with these options. This
402 option may be specified more than
403 once, in which case ordering
404 dependencies for all listed names are
405 created. <varname>After=</varname> is
406 the inverse of
407 <varname>Before=</varname>, i.e. while
408 <varname>After=</varname> ensures that
409 the configured unit is started after
410 the listed unit finished starting up,
411 <varname>Before=</varname> ensures the
412 opposite, i.e. that the configured
413 unit is fully started up before the
414 listed unit is started. Note that when
415 two units with an ordering dependency
416 between them are shut down, the
417 inverse of the start-up order is
418 applied. i.e. if a unit is configured
419 with <varname>After=</varname> on
420 another unit, the former is stopped
421 before the latter if both are shut
422 down. If one unit with an ordering
423 dependency on another unit is shut
424 down while the latter is started up,
425 the shut down is ordered before the
426 start-up regardless whether the
427 ordering dependency is actually of
428 type <varname>After=</varname> or
429 <varname>Before=</varname>. If two
430 units have no ordering dependencies
431 between them they are shut down
432 resp. started up simultaneously, and
433 no ordering takes
434 place. </para></listitem>
435 </varlistentry>
436
437 <varlistentry>
438 <term><varname>OnFailure=</varname></term>
439
440 <listitem><para>Lists one or more
441 units that are activated when this
442 unit enters the
443 '<literal>failed</literal>'
444 state.</para></listitem>
445 </varlistentry>
446
447 <varlistentry>
448 <term><varname>OnFailureIsolate=</varname></term>
449
450 <listitem><para>Takes a boolean
451 argument. If <option>true</option> the
452 unit listed in
453 <varname>OnFailure=</varname> will be
454 enqueued in isolation mode, i.e. all
455 units that are not its dependency will
456 be stopped. If this is set only a
457 single unit may be listed in
458 <varname>OnFailure=</varname>. Defaults
459 to
460 <option>false</option>.</para></listitem>
461 </varlistentry>
462
463 <varlistentry>
464 <term><varname>StopWhenUnneeded=</varname></term>
465
466 <listitem><para>Takes a boolean
467 argument. If <option>true</option>
468 this unit will be stopped when it is
469 no longer used. Note that in order to
470 minimize the work to be executed,
471 systemd will not stop units by default
472 unless they are conflicting with other
473 units, or the user explicitly
474 requested their shut down. If this
475 option is set, a unit will be
476 automatically cleaned up if no other
477 active unit requires it. Defaults to
478 <option>false</option>.</para></listitem>
479 </varlistentry>
480
481 <varlistentry>
482 <term><varname>RefuseManualStart=</varname></term>
483 <term><varname>RefuseManualStop=</varname></term>
484
485 <listitem><para>Takes a boolean
486 argument. If <option>true</option>
487 this unit can only be activated
488 (resp. deactivated) indirectly. In
489 this case explicit start-up
490 (resp. termination) requested by the
491 user is denied, however if it is
492 started (resp. stopped) as a
493 dependency of another unit, start-up
494 (resp. termination) will succeed. This
495 is mostly a safety feature to ensure
496 that the user does not accidentally
497 activate units that are not intended
498 to be activated explicitly, and not
499 accidentally deactivate units that are
500 not intended to be deactivated.
501 These options default to
502 <option>false</option>.</para></listitem>
503 </varlistentry>
504
505 <varlistentry>
506 <term><varname>AllowIsolate=</varname></term>
507
508 <listitem><para>Takes a boolean
509 argument. If <option>true</option>
510 this unit may be used with the
511 <command>systemctl isolate</command>
512 command. Otherwise this will be
513 refused. It probably is a good idea to
514 leave this disabled except for target
515 units that shall be used similar to
516 runlevels in SysV init systems, just
517 as a precaution to avoid unusable
518 system states. This option defaults to
519 <option>false</option>.</para></listitem>
520 </varlistentry>
521
522 <varlistentry>
523 <term><varname>DefaultDependencies=</varname></term>
524
525 <listitem><para>Takes a boolean
526 argument. If <option>true</option>
527 (the default), a few default
528 dependencies will implicitly be
529 created for the unit. The actual
530 dependencies created depend on the
531 unit type. For example, for service
532 units, these dependencies ensure that
533 the service is started only after
534 basic system initialization is
535 completed and is properly terminated on
536 system shutdown. See the respective
537 man pages for details. Generally, only
538 services involved with early boot or
539 late shutdown should set this option
540 to <option>false</option>. It is
541 highly recommended to leave this
542 option enabled for the majority of
543 common units. If set to
544 <option>false</option> this option
545 does not disable all implicit
546 dependencies, just non-essential
547 ones.</para></listitem>
548 </varlistentry>
549
550 <varlistentry>
551 <term><varname>JobTimeoutSec=</varname></term>
552
553 <listitem><para>When clients are
554 waiting for a job of this unit to
555 complete, time out after the specified
556 time. If this time limit is reached
557 the job will be cancelled, the unit
558 however will not change state or even
559 enter the '<literal>failed</literal>'
560 mode. This value defaults to 0 (job
561 timeouts disabled), except for device
562 units. NB: this timeout is independent
563 from any unit-specific timeout (for
564 example, the timeout set with
565 <varname>Timeout=</varname> in service
566 units) as the job timeout has no
567 effect on the unit itself, only on the
568 job that might be pending for it. Or
569 in other words: unit-specific timeouts
570 are useful to abort unit state
571 changes, and revert them. The job
572 timeout set with this option however
573 is useful to abort only the job
574 waiting for the unit state to
575 change.</para></listitem>
576 </varlistentry>
577
578 <varlistentry>
579 <term><varname>ConditionPathExists=</varname></term>
580 <term><varname>ConditionPathIsDirectory=</varname></term>
581 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
582 <term><varname>ConditionKernelCommandLine=</varname></term>
583 <term><varname>ConditionVirtualization=</varname></term>
584 <term><varname>ConditionSecurity=</varname></term>
585 <term><varname>ConditionNull=</varname></term>
586
587 <listitem><para>Before starting a unit
588 verify that the specified condition is
589 true. With
590 <varname>ConditionPathExists=</varname>
591 a file existance condition can be
592 checked before a unit is started. If
593 the specified absolute path name does
594 not exist startup of a unit will not
595 actually happen, however the unit is
596 still useful for ordering purposes in
597 this case. The condition is checked at
598 the time the queued start job is to be
599 executed. If the absolute path name
600 passed to
601 <varname>ConditionPathExists=</varname>
602 is prefixed with an exclamation mark
603 (!), the test is negated, and the unit
604 only started if the path does not
605 exist. <varname>ConditionPathIsDirectory=</varname>
606 is similar to
607 <varname>ConditionPathExists=</varname>
608 but verifies whether a certain path
609 exists and is a directory.
610 <varname>ConditionDirectoryNotEmpty=</varname>
611 is similar to
612 <varname>ConditionPathExists=</varname>
613 but verifies whether a certain path
614 exists and is a non-empty
615 directory. Similarly
616 <varname>ConditionKernelCommandLine=</varname>
617 may be used to check whether a
618 specific kernel command line option is
619 set (or if prefixed with the
620 exclamation mark unset). The argument
621 must either be a single word, or an
622 assignment (i.e. two words, separated
623 by the equality sign). In the former
624 case the kernel command line is
625 searched for the word appearing as is,
626 or as left hand side of an
627 assignment. In the latter case the
628 exact assignment is looked for with
629 right and left hand side
630 matching. <varname>ConditionVirtualization=</varname>
631 may be used to check whether the
632 system is executed in a virtualized
633 environment and optionally test
634 whether it is a specific
635 implementation. Takes either boolean
636 value to check if being executed in
637 any virtual environment or one of the
638 <varname>qemu</varname>,
639 <varname>kvm</varname>,
640 <varname>vmware</varname>,
641 <varname>microsoft</varname>,
642 <varname>oracle</varname>,
643 <varname>xen</varname>,
644 <varname>pidns</varname>,
645 <varname>openvz</varname> to test
646 against a specific implementation. The
647 test may be negated by prepending an
648 exclamation mark.
649 <varname>ConditionSecurity=</varname>
650 may be used to check whether the given security
651 module is enabled on the system.
652 Currently the only recognized value is
653 <varname>selinux</varname>.
654 The test may be negated by prepending an
655 exclamation mark. Finally,
656 <varname>ConditionNull=</varname> may
657 be used to add a constant condition
658 check value to the unit. It takes a
659 boolean argument. If set to
660 <varname>false</varname> the condition
661 will always fail, otherwise
662 succeed. If multiple conditions are
663 specified the unit will be executed if
664 all of them apply (i.e. a logical AND
665 is applied). Condition checks can be
666 prefixed with a pipe symbol (|) in
667 which case a condition becomes a
668 triggering condition. If at least one
669 triggering condition is defined for a
670 unit then the unit will be executed if
671 at least one of the triggering
672 conditions apply and all of the
673 non-triggering conditions. If you
674 prefix an argument with the pipe
675 symbol and an exclamation mark the
676 pipe symbol must be passed first, the
677 exclamation second.</para></listitem>
678 </varlistentry>
679
680 <varlistentry>
681 <term><varname>Names=</varname></term>
682
683 <listitem><para>Additional names for
684 this unit. The names listed here must
685 have the same suffix (i.e. type) as
686 the unit file name. This option may be
687 specified more than once, in which
688 case all listed names are used. Note
689 that this option is different from the
690 <varname>Alias=</varname> option from
691 the [Install] section mentioned
692 below. See below for details. Note
693 that in almost all cases this option
694 is not what you want. A symlink alias
695 in the file system is generally
696 preferable since it can be used as
697 lookup key. If a unit with a symlinked
698 alias name is not loaded and needs to
699 be it is easily found via the
700 symlink. However, if a unit with an
701 alias name configured with this
702 setting is not loaded it will not be
703 discovered. This settings' only use is
704 in conjunction with service
705 instances.</para>
706 </listitem>
707 </varlistentry>
708 </variablelist>
709
710 <para>Unit file may include a [Install] section, which
711 carries installation information for the unit. This
712 section is not interpreted by
713 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
714 during runtime. It is used exclusively by the
715 <command>enable</command> and
716 <command>disable</command> commands of the
717 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
718 tool during installation of a unit:</para>
719
720 <variablelist>
721 <varlistentry>
722 <term><varname>Alias=</varname></term>
723
724 <listitem><para>Additional names this
725 unit shall be installed under. The
726 names listed here must have the same
727 suffix (i.e. type) as the unit file
728 name. This option may be specified
729 more than once, in which case all
730 listed names are used. At installation
731 time,
732 <command>systemctl enable</command>
733 will create symlinks from these names
734 to the unit file name. Note that this
735 is different from the
736 <varname>Names=</varname> option from
737 the [Unit] section mentioned above:
738 The names from
739 <varname>Names=</varname> apply
740 unconditionally if the unit is
741 loaded. The names from
742 <varname>Alias=</varname> apply only
743 if the unit has actually been
744 installed with the
745 <command>systemctl enable</command>
746 command. Also, if systemd searches for a
747 unit, it will discover symlinked alias
748 names as configured with
749 <varname>Alias=</varname>, but not
750 names configured with
751 <varname>Names=</varname> only. It is
752 a common pattern to list a name in
753 both options. In this case, a unit
754 will be active under all names if
755 installed, but also if not installed
756 but requested explicitly under its
757 main name.</para></listitem>
758 </varlistentry>
759
760 <varlistentry>
761 <term><varname>WantedBy=</varname></term>
762
763 <listitem><para>Installs a symlink in
764 the <filename>.wants/</filename>
765 subdirectory for a unit. This has the
766 effect that when the listed unit name
767 is activated the unit listing it is
768 activated
769 too. <command>WantedBy=foo.service</command>
770 in a service
771 <filename>bar.service</filename> is
772 mostly equivalent to
773 <command>Alias=foo.service.wants/bar.service</command>
774 in the same file.</para></listitem>
775 </varlistentry>
776
777 <varlistentry>
778 <term><varname>Also=</varname></term>
779
780 <listitem><para>Additional units to
781 install when this unit is
782 installed. If the user requests
783 installation of a unit with this
784 option configured,
785 <command>systemctl enable</command>
786 will automatically install units
787 listed in this option as
788 well.</para></listitem>
789 </varlistentry>
790 </variablelist>
791
792 </refsect1>
793
794 <refsect1>
795 <title>See Also</title>
796 <para>
797 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
799 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
800 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
801 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
802 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
803 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
804 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
805 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
806 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
807 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
808 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
809 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>
810 </para>
811 </refsect1>
812
813 </refentry>