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
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>
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>
208 <para>The unit file format is covered by the
210 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
211 Stability Promise</ulink>.</para>
215 <title>Options</title>
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>
223 <term><varname>Names=</varname></term>
225 <listitem><para>Additional names for
226 this unit. The names listed here must
227 have the same suffix (i.e. type) as
228 the unit file name. This option may be
229 specified more than once, in which
230 case all listed names are used. Note
231 that this option is different from the
232 <varname>Alias=</varname> option from
233 the [Install] section mentioned
234 below. See below for details.</para>
239 <term><varname>Description=</varname></term>
240 <listitem><para>A free-form string
241 describing the unit. This is intended
242 for use in UIs to show descriptive
243 information along with the unit
244 name.</para></listitem>
248 <term><varname>Requires=</varname></term>
250 <listitem><para>Configures requirement
251 dependencies on other units. If this
252 unit gets activated, the units listed
253 here will be activated as well. If one
254 of the other units gets deactivated or
255 its activation fails, this unit will
256 be deactivated. This option may be
257 specified more than once, in which
258 case requirement dependencies for all
259 listed names are created. Note that
260 requirement dependencies do not
261 influence the order in which services
262 are started or stopped. This has to be
263 configured independently with the
264 <varname>After=</varname> or
265 <varname>Before=</varname> options. If
267 <filename>foo.service</filename>
269 <filename>bar.service</filename> as
271 <varname>Requires=</varname> and no
272 ordering is configured with
273 <varname>After=</varname> or
274 <varname>Before=</varname>, then both
275 units will be started simultaneously
276 and without any delay between them if
277 <filename>foo.service</filename> is
278 activated. Often it is a better choice
279 to use <varname>Wants=</varname>
281 <varname>Requires=</varname> in order
282 to achieve a system that is more
283 robust when dealing with failing
284 services.</para></listitem>
288 <term><varname>RequiresOverridable=</varname></term>
290 <listitem><para>Similar to
291 <varname>Requires=</varname>.
292 Dependencies listed in
293 <varname>RequiresOverridable=</varname>
294 which cannot be fulfilled or fail to
295 start are ignored if the startup was
296 explicitly requested by the user. If
297 the start-up was pulled in indirectly
298 by some dependency or automatic
299 start-up of units that is not
300 requested by the user this dependency
301 must be fulfilled and otherwise the
302 transaction fails. Hence, this option
303 may be used to configure dependencies
304 that are normally honored unless the
305 user explicitly starts up the unit, in
306 which case whether they failed or not
307 is irrelevant.</para></listitem>
311 <term><varname>Requisite=</varname></term>
312 <term><varname>RequisiteOverridable=</varname></term>
314 <listitem><para>Similar to
315 <varname>Requires=</varname>
316 resp. <varname>RequiresOverridable=</varname>. However,
317 if a unit listed here is not started
318 already it will not be started and the
320 immediately.</para></listitem>
324 <term><varname>Wants=</varname></term>
326 <listitem><para>A weaker version of
327 <varname>Requires=</varname>. A unit
328 listed in this option will be started
329 if the configuring unit is. However,
330 if the listed unit fails to start up
331 or cannot be added to the transaction
332 this has no impact on the validity of
333 the transaction as a whole. This is
334 the recommended way to hook start-up
335 of one unit to the start-up of another
336 unit. Note that dependencies of this
337 type may also be configured outside of
338 the unit configuration file by
339 adding a symlink to a
340 <filename>.wants/</filename> directory
341 accompanying the unit file. For
342 details see above.</para></listitem>
346 <term><varname>BindTo=</varname></term>
348 <listitem><para>Configures requirement
349 dependencies, very similar in style to
350 <varname>Requires=</varname>, however
351 in addition to this behaviour it also
352 declares that this unit is stopped
353 when any of the units listed suddenly
354 disappears. Units can suddenly,
355 unexpectedly disappear if a service
356 terminates on its own choice, a device
357 is unplugged or a mount point
358 unmounted without involvement of
359 systemd.</para></listitem>
363 <term><varname>Conflicts=</varname></term>
365 <listitem><para>Configures negative
366 requirement dependencies. If a unit
368 <varname>Conflicts=</varname> setting
369 on another unit, starting the former
370 will stop the latter and vice
371 versa. Note that this setting is
372 independent of and orthogonal to the
373 <varname>After=</varname> and
374 <varname>Before=</varname> ordering
377 <para>If a unit A that conflicts with
378 a unit B is scheduled to be started at
379 the same time as B, the transaction
380 will either fail (in case both are
381 required part of the transaction) or
382 be modified to be fixed (in case one
383 or both jobs are not a required part
384 of the transaction). In the latter
385 case the job that is not the required
386 will be removed, or in case both are
387 not required the unit that conflicts
388 will be started and the unit that is
390 stopped.</para></listitem>
394 <term><varname>Before=</varname></term>
395 <term><varname>After=</varname></term>
397 <listitem><para>Configures ordering
398 dependencies between units. If a unit
399 <filename>foo.service</filename>
401 <option>Before=bar.service</option>
402 and both units are being started,
403 <filename>bar.service</filename>'s
404 start-up is delayed until
405 <filename>foo.service</filename> is
406 started up. Note that this setting is
407 independent of and orthogonal to the
408 requirement dependencies as configured
409 by <varname>Requires=</varname>. It is
410 a common pattern to include a unit
412 <varname>After=</varname> and
413 <varname>Requires=</varname> option in
414 which case the unit listed will be
415 started before the unit that is
416 configured with these options. This
417 option may be specified more than
418 once, in which case ordering
419 dependencies for all listed names are
420 created. <varname>After=</varname> is
422 <varname>Before=</varname>, i.e. while
423 <varname>After=</varname> ensures that
424 the configured unit is started after
425 the listed unit finished starting up,
426 <varname>Before=</varname> ensures the
427 opposite, i.e. that the configured
428 unit is fully started up before the
429 listed unit is started. Note that when
430 two units with an ordering dependency
431 between them are shut down, the
432 inverse of the start-up order is
433 applied. i.e. if a unit is configured
434 with <varname>After=</varname> on
435 another unit, the former is stopped
436 before the latter if both are shut
437 down. If one unit with an ordering
438 dependency on another unit is shut
439 down while the latter is started up,
440 the shut down is ordered before the
441 start-up regardless whether the
442 ordering dependency is actually of
443 type <varname>After=</varname> or
444 <varname>Before=</varname>. If two
445 units have no ordering dependencies
446 between them they are shut down
447 resp. started up simultaneously, and
449 place. </para></listitem>
453 <term><varname>OnFailure=</varname></term>
455 <listitem><para>Lists one or more
456 units that are activated when this
458 '<literal>failed</literal>'
459 state.</para></listitem>
463 <term><varname>StopWhenUnneeded=</varname></term>
465 <listitem><para>Takes a boolean
466 argument. If <option>true</option>
467 this unit will be stopped when it is
468 no longer used. Note that in order to
469 minimize the work to be executed,
470 systemd will not stop units by default
471 unless they are conflicting with other
472 units, or the user explicitly
473 requested their shut down. If this
474 option is set, a unit will be
475 automatically cleaned up if no other
476 active unit requires it. Defaults to
477 <option>false</option>.</para></listitem>
481 <term><varname>RefuseManualStart=</varname></term>
482 <term><varname>RefuseManualStop=</varname></term>
484 <listitem><para>Takes a boolean
485 argument. If <option>true</option>
486 this unit can only be activated
487 (resp. deactivated) indirectly. In
488 this case explicit start-up
489 (resp. termination) requested by the
490 user is denied, however if it is
491 started (resp. stopped) as a
492 dependency of another unit, start-up
493 (resp. termination) will succeed. This
494 is mostly a safety feature to ensure
495 that the user does not accidentally
496 activate units that are not intended
497 to be activated explicitly, and not
498 accidentally deactivate units that are
499 not intended to be deactivated.
500 These options default to
501 <option>false</option>.</para></listitem>
505 <term><varname>AllowIsolate=</varname></term>
507 <listitem><para>Takes a boolean
508 argument. If <option>true</option>
509 this unit may be used with the
510 <command>systemctl isolate</command>
511 command. Otherwise this will be
512 refused. It probably is a good idea to
513 leave this disabled except for target
514 units that shall be used similar to
515 runlevels in SysV init systems, just
516 as a precaution to avoid unusable
517 system states. This option defaults to
518 <option>false</option>.</para></listitem>
522 <term><varname>DefaultDependencies=</varname></term>
524 <listitem><para>Takes a boolean
525 argument. If <option>true</option>
526 (the default), a few default
527 dependencies will implicitly be
528 created for the unit. The actual
529 dependencies created depend on the
530 unit type. For example, for service
531 units, these dependencies ensure that
532 the service is started only after
533 basic system initialization is
534 completed and is properly terminated on
535 system shutdown. See the respective
536 man pages for details. Generally, only
537 services involved with early boot or
538 late shutdown should set this option
539 to <option>false</option>. It is
540 highly recommended to leave this
541 option enabled for the majority of
542 common units. If set to
543 <option>false</option> this option
544 does not disable all implicit
545 dependencies, just non-essential
546 ones.</para></listitem>
550 <term><varname>JobTimeoutSec=</varname></term>
552 <listitem><para>When clients are
553 waiting for a job of this unit to
554 complete, time out after the specified
555 time. If this time limit is reached
556 the job will be cancelled, the unit
557 however will not change state or even
558 enter the '<literal>failed</literal>'
559 mode. This value defaults to 0 (job
560 timeouts disabled), except for device
561 units. NB: this timeout is independent
562 from any unit-specific timeout (for
563 example, the timeout set with
564 <varname>Timeout=</varname> in service
565 units) as the job timeout has no
566 effect on the unit itself, only on the
567 job that might be pending for it. Or
568 in other words: unit-specific timeouts
569 are useful to abort unit state
570 changes, and revert them. The job
571 timeout set with this option however
572 is useful to abort only the job
573 waiting for the unit state to
574 change.</para></listitem>
578 <term><varname>ConditionPathExists=</varname></term>
579 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
580 <term><varname>ConditionKernelCommandLine=</varname></term>
581 <term><varname>ConditionVirtualization=</varname></term>
582 <term><varname>ConditionNull=</varname></term>
584 <listitem><para>Before starting a unit
585 verify that the specified condition is
587 <varname>ConditionPathExists=</varname>
588 a file existance condition can be
589 checked before a unit is started. If
590 the specified absolute path name does
591 not exist startup of a unit will not
592 actually happen, however the unit is
593 still useful for ordering purposes in
594 this case. The condition is checked at
595 the time the queued start job is to be
596 executed. If the absolute path name
598 <varname>ConditionPathExists=</varname>
599 is prefixed with an exclamation mark
600 (!), the test is negated, and the unit
601 only started if the path does not
602 exist. <varname>ConditionDirectoryNotEmpty=</varname>
604 <varname>ConditionPathExists=</varname>
605 but verifies whether a certain path is
606 exists and is a non-empty
608 <varname>ConditionKernelCommandLine=</varname>
609 may be used to check whether a
610 specific kernel command line option is
611 set (or if prefixed with the
612 exclamation mark unset). The argument
613 must either be a single word, or an
614 assignment (i.e. two words, separated
615 by the equality sign). In the former
616 case the kernel command line is
617 searched for the word appearing as is,
618 or as left hand side of an
619 assignment. In the latter case the
620 exact assignment is looked for with
621 right and left hand side
622 matching. <varname>ConditionVirtualization=</varname>
623 may be used to check whether the
624 system is executed in a virtualized
625 environment and optionally test
626 whether it is a specific
627 implementation. Takes either boolean
628 value to check if being executed in
629 any virtual environment or one of the
630 <varname>qemu</varname>,
631 <varname>kvm</varname>,
632 <varname>vmware</varname>,
633 <varname>microsoft</varname>,
634 <varname>oracle</varname>,
635 <varname>xen</varname>,
636 <varname>openvz</varname> to test
637 against a specific implementation. The
638 test may be negated by prepending an
639 exclamation mark. Finally,
640 <varname>ConditionNull=</varname> may
641 be used to add a constant condition
642 check value to the unit. It takes a
643 boolean argument. If set to
644 <varname>false</varname> the condition
645 will always fail, otherwise
646 succeed. If multiple conditions are
647 specified the unit will be executed if
648 all of them apply (i.e. a logical AND
649 is applied). Condition checks can be
650 prefixed with a pipe symbol (|) in
651 which case a condition becomes a
652 triggering condition. If at least one
653 triggering condition is defined for a
654 unit then the unit will be executed if
655 at least one of the triggering
656 conditions apply and all of the
657 non-triggering conditions. If you
658 prefix an argument with the pipe
659 symbol and an exclamation mark the
660 pipe symbol must be passed first, the
661 exclamation second.</para></listitem>
665 <para>Unit file may include a [Install] section, which
666 carries installation information for the unit. This
667 section is not interpreted by
668 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
669 during runtime. It is used exclusively by the
670 <command>enable</command> and
671 <command>disable</command> commands of the
672 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
673 tool during installation of a unit:</para>
677 <term><varname>Alias=</varname></term>
679 <listitem><para>Additional names this
680 unit shall be installed under. The
681 names listed here must have the same
682 suffix (i.e. type) as the unit file
683 name. This option may be specified
684 more than once, in which case all
685 listed names are used. At installation
687 <command>systemctl enable</command>
688 will create symlinks from these names
689 to the unit file name. Note that this
690 is different from the
691 <varname>Names=</varname> option from
692 the [Unit] section mentioned above:
694 <varname>Names=</varname> apply
695 unconditionally if the unit is
696 loaded. The names from
697 <varname>Alias=</varname> apply only
698 if the unit has actually been
700 <command>systemctl enable</command>
701 command. Also, if systemd searches for a
702 unit, it will discover symlinked alias
703 names as configured with
704 <varname>Alias=</varname>, but not
705 names configured with
706 <varname>Names=</varname> only. It is
707 a common pattern to list a name in
708 both options. In this case, a unit
709 will be active under all names if
710 installed, but also if not installed
711 but requested explicitly under its
712 main name.</para></listitem>
716 <term><varname>WantedBy=</varname></term>
718 <listitem><para>Installs a symlink in
719 the <filename>.wants/</filename>
720 subdirectory for a unit. This has the
721 effect that when the listed unit name
722 is activated the unit listing it is
724 too. <command>WantedBy=foo.service</command>
726 <filename>bar.service</filename> is
728 <command>Alias=foo.service.wants/bar.service</command>
729 in the same file.</para></listitem>
733 <term><varname>Also=</varname></term>
735 <listitem><para>Additional units to
736 install when this unit is
737 installed. If the user requests
738 installation of a unit with this
740 <command>systemctl enable</command>
741 will automatically install units
742 listed in this option as
743 well.</para></listitem>
750 <title>See Also</title>
752 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
753 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
754 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
755 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
756 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
757 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
758 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
759 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
760 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
761 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
762 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
763 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
764 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>
~ianmdlvl / elogind.git / blob