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.)</para>
144 <para>Note that while systemd offers a flexible
145 dependency system between units it is recommended to
146 use this functionality only sparsely and instead rely
147 on techniques such as bus-based or socket-based
148 activation which makes dependencies implicit, which
149 both results in a simpler and more flexible
152 <para>Some unit names reflect paths existing in the
153 file system name space. Example: a device unit
154 <filename>dev-sda.device</filename> refers to a device
155 with the device node <filename>/dev/sda</filename> in
156 the file system namespace. If this applies a special
157 way to escape the path name is used, so that the
158 result is usable as part of a file name. Basically,
159 given a path, "/" is replaced by "-", and all
160 unprintable characters and the "-" are replaced by
161 C-style "\x20" escapes. The root directory "/" is
162 encoded as single dash, while otherwise the initial
163 and ending "/" is removed from all paths during
164 transformation. This escaping is reversible.</para>
166 <para>Optionally, units may be instantiated from a
167 template file at runtime. This allows creation of
168 multiple units from a single configuration file. If
169 systemd looks for a unit configuration file it will
170 first search for the literal unit name in the
171 filesystem. If that yields no success and the unit
172 name contains an @ character, systemd will look for a
173 unit template that shares the same name but with the
174 instance string (i.e. the part between the @ character
175 and the suffix) removed. Example: if a service
176 <filename>getty@tty3.service</filename> is requested
177 and no file by that name is found, systemd will look
178 for <filename>getty@.service</filename> and
179 instantiate a service from that configuration file if
180 it is found. To refer to the instance string from
181 within the configuration file you may use the special
182 <literal>%i</literal> specifier in many of the
183 configuration options. Other specifiers that may be
184 used are <literal>%n</literal>, <literal>%N</literal>,
185 <literal>%p</literal>, <literal>%P</literal>,
186 <literal>%I</literal> and <literal>%f</literal>, for
187 the full unit name, the unescaped unit name, the
188 prefix name, the unescaped prefix name, the unescaped
189 instance name and the unescaped filename,
190 respectively. The unescaped filename is either the
191 unescaped instance name (if set) with / prepended (if
192 necessary), or the prefix name similarly prepended
193 with /. The prefix name here refers to the string
194 before the @, i.e. "getty" in the example above, where
195 "tty3" is the instance name.</para>
197 <para>If a unit file is empty (i.e. has the file size
198 0) or is symlinked to <filename>/dev/null</filename>
199 its configuration will not be loaded and it appears
200 with a load state of <literal>masked</literal>, and
201 cannot be activated. Use this as an effective way to
202 fully disable a unit, making it impossible to start it
203 even manually.</para>
205 <para>The unit file format is covered by the
207 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
208 Stability Promise</ulink>.</para>
212 <title>Options</title>
214 <para>Unit file may include a [Unit] section, which
215 carries generic information about the unit that is not
216 dependent on the type of unit:</para>
220 <term><varname>Names=</varname></term>
222 <listitem><para>Additional names for
223 this unit. The names listed here must
224 have the same suffix (i.e. type) as
225 the unit file name. This option may be
226 specified more than once, in which
227 case all listed names are used. Note
228 that this option is different from the
229 <varname>Alias=</varname> option from
230 the [Install] section mentioned
231 below. See below for details.</para>
236 <term><varname>Description=</varname></term>
237 <listitem><para>A free-form string
238 describing the unit. This is intended
239 for use in UIs to show descriptive
240 information along with the unit
241 name.</para></listitem>
245 <term><varname>Requires=</varname></term>
247 <listitem><para>Configures requirement
248 dependencies on other units. If this
249 unit gets activated, the units listed
250 here will be activated as well. If one
251 of the other units gets deactivated or
252 its activation fails, this unit will
253 be deactivated. This option may be
254 specified more than once, in which
255 case requirement dependencies for all
256 listed names are created. Note that
257 requirement dependencies do not
258 influence the order in which services
259 are started or stopped. This has to be
260 configured independently with the
261 <varname>After=</varname> or
262 <varname>Before=</varname> options. If
264 <filename>foo.service</filename>
266 <filename>bar.service</filename> as
268 <varname>Requires=</varname> and no
269 ordering is configured with
270 <varname>After=</varname> or
271 <varname>Before=</varname>, then both
272 units will be started simultaneously
273 and without any delay between them if
274 <filename>foo.service</filename> is
275 activated. Often it is a better choice
276 to use <varname>Wants=</varname>
278 <varname>Requires=</varname> in order
279 to achieve a system that is more
280 robust when dealing with failing
281 services.</para></listitem>
286 <term><varname>RequiresOverridable=</varname></term>
288 <listitem><para>Similar to
289 <varname>Requires=</varname>.
290 Dependencies listed in
291 <varname>RequiresOverridable=</varname>
292 which cannot be fulfilled or fail to
293 start are ignored if the startup was
294 explicitly requested by the user. If
295 the start-up was pulled in indirectly
296 by some dependency or automatic
297 start-up of units that is not
298 requested by the user this dependency
299 must be fulfilled and otherwise the
300 transaction fails. Hence, this option
301 may be used to configure dependencies
302 that are normally honored unless the
303 user explicitly starts up the unit, in
304 which case whether they failed or not
305 is irrelevant.</para></listitem>
309 <term><varname>Requisite=</varname></term>
310 <term><varname>RequisiteOverridable=</varname></term>
312 <listitem><para>Similar to
313 <varname>Requires=</varname>
314 resp. <varname>RequiresOverridable=</varname>. However,
315 if a unit listed here is not started
316 already it will not be started and the
318 immediately.</para></listitem>
322 <term><varname>Wants=</varname></term>
324 <listitem><para>A weaker version of
325 <varname>Requires=</varname>. A unit
326 listed in this option will be started
327 if the configuring unit is. However,
328 if the listed unit fails to start up
329 or cannot be added to the transaction
330 this has no impact on the validity of
331 the transaction as a whole. This is
332 the recommended way to hook start-up
333 of one unit to the start-up of another
334 unit. Note that dependencies of this
335 type may also be configured outside of
336 the unit configuration file by
337 adding a symlink to a
338 <filename>.wants/</filename> directory
339 accompanying the unit file. For
340 details see above.</para></listitem>
344 <term><varname>Conflicts=</varname></term>
346 <listitem><para>Configures negative
347 requirement dependencies. If a unit
349 <varname>Conflicts=</varname> setting
350 on another unit, starting the former
351 will stop the latter and vice
352 versa. Note that this setting is
353 independent of and orthogonal to the
354 <varname>After=</varname> and
355 <varname>Before=</varname> ordering
358 <para>If a unit A that conflicts with
359 a unit B is scheduled to be started at
360 the same time as B, the transaction
361 will either fail (in case both are
362 required part of the transaction) or
363 be modified to be fixed (in case one
364 or both jobs are not a required part
365 of the transaction). In the latter
366 case the job that is not the required
367 will be removed, or in case both are
368 not required the unit that conflicts
369 will be started and the unit that is
371 stopped.</para></listitem>
375 <term><varname>Before=</varname></term>
376 <term><varname>After=</varname></term>
378 <listitem><para>Configures ordering
379 dependencies between units. If a unit
380 <filename>foo.service</filename>
382 <option>Before=bar.service</option>
383 and both units are being started,
384 <filename>bar.service</filename>'s
385 start-up is delayed until
386 <filename>foo.service</filename> is
387 started up. Note that this setting is
388 independent of and orthogonal to the
389 requirement dependencies as configured
390 by <varname>Requires=</varname>. It is
391 a common pattern to include a unit
393 <varname>After=</varname> and
394 <varname>Requires=</varname> option in
395 which case the unit listed will be
396 started before the unit that is
397 configured with these options. This
398 option may be specified more than
399 once, in which case ordering
400 dependencies for all listed names are
401 created. <varname>After=</varname> is
403 <varname>Before=</varname>, i.e. while
404 <varname>After=</varname> ensures that
405 the configured unit is started after
406 the listed unit finished starting up,
407 <varname>Before=</varname> ensures the
408 opposite, i.e. that the configured
409 unit is fully started up before the
410 listed unit is started. Note that when
411 two units with an ordering dependency
412 between them are shut down, the
413 inverse of the start-up order is
414 applied. i.e. if a unit is configured
415 with <varname>After=</varname> on
416 another unit, the former is stopped
417 before the latter if both are shut
418 down. If one unit with an ordering
419 dependency on another unit is shut
420 down while the latter is started up,
421 the shut down is ordered before the
422 start-up regardless whether the
423 ordering dependency is actually of
424 type <varname>After=</varname> or
425 <varname>Before=</varname>. If two
426 units have no ordering dependencies
427 between them they are shut down
428 resp. started up simultaneously, and
430 place. </para></listitem>
434 <term><varname>OnFailure=</varname></term>
436 <listitem><para>Lists one or more
437 units that are activated when this
439 '<literal>failed</literal>'
440 state.</para></listitem>
444 <term><varname>StopRetroactively=</varname></term>
446 <listitem><para>Takes a boolean
447 argument. If <option>true</option> and
448 a unit this unit requires stops
449 without this being requested by the
450 user, this unit will be stopped as
451 well. (e.g. if a service exits or
452 crashes on its own behalf, units this
453 flag is set for that require it will
454 be stopped.) Note that normally if a
455 unit stops without a user request,
456 units depending on it will not be
457 terminated. Only if the user requested
458 shutdown of a unit, all units
459 depending on that unit will be shut
460 down as well and at the same
462 <option>false</option>.</para></listitem>
466 <term><varname>StopWhenUnneeded=</varname></term>
468 <listitem><para>Takes a boolean
469 argument. If <option>true</option>
470 this unit will be stopped when it is
471 no longer used. Note that in order to
472 minimize the work to be executed,
473 systemd will not stop units by default
474 unless they are conflicting with other
475 units, or the user explicitly
476 requested their shut down. If this
477 option is set, a unit will be
478 automatically cleaned up if no other
479 active unit requires it. Defaults to
480 <option>false</option>.</para></listitem>
484 <term><varname>RefuseManualStart=</varname></term>
485 <term><varname>RefuseManualStop=</varname></term>
487 <listitem><para>Takes a boolean
488 argument. If <option>true</option>
489 this unit can only be activated
490 (resp. deactivated) indirectly. In
491 this case explicit start-up
492 (resp. termination) requested by the
493 user is denied, however if it is
494 started (resp. stopped) as a
495 dependency of another unit, start-up
496 (resp. termination) will succeed. This
497 is mostly a safety feature to ensure
498 that the user does not accidentally
499 activate units that are not intended
500 to be activated explicitly, and not
501 accidentally deactivate units that are
502 not intended to be deactivated.
503 These options default to
504 <option>false</option>.</para></listitem>
508 <term><varname>AllowIsolate=</varname></term>
510 <listitem><para>Takes a boolean
511 argument. If <option>true</option>
512 this unit may be used with the
513 <command>systemctl isolate</command>
514 command. Otherwise this will be
515 refused. It probably is a good idea to
516 leave this disabled except for target
517 units that shall be used similar to
518 runlevels in SysV init systems, just
519 as a precaution to avoid unusable
520 system states. This option defaults to
521 <option>false</option>.</para></listitem>
525 <term><varname>DefaultDependencies=</varname></term>
527 <listitem><para>Takes a boolean
528 argument. If <option>true</option>
529 (the default), a few default
530 dependencies will implicitly be
531 created for the unit. The actual
532 dependencies created depend on the
533 unit type. For example, for service
534 units, these dependencies ensure that
535 the service is started only after
536 basic system initialization is
537 completed and is properly terminated on
538 system shutdown. See the respective
539 man pages for details. Generally, only
540 services involved with early boot or
541 late shutdown should set this option
542 to <option>false</option>. It is
543 highly recommended to leave this
544 option enabled for the majority of
545 common units. If set to
546 <option>false</option> this option
547 does not disable all implicit
548 dependencies, just non-essential
549 ones.</para></listitem>
553 <term><varname>IgnoreDependencyFailure=</varname></term>
555 <listitem><para>Takes a boolean
556 argument. If <option>true</option> and
557 a requirement dependency of this unit
558 fails to start up this unit will be
559 started nonetheless, ignoring that
560 failure. If <option>false</option>
561 (the default) and a dependency unit
562 fails the unit will immediately fail
563 too and the job is removed.</para></listitem>
567 <term><varname>JobTimeoutSec=</varname></term>
569 <listitem><para>When clients are
570 waiting for a job of this unit to
571 complete, time out after the specified
572 time. If this time limit is reached
573 the job will be cancelled, the unit
574 however will not change state or even
575 enter the '<literal>failed</literal>'
576 mode. This value defaults to 0 (job
577 timeouts disabled), except for device
578 units. NB: this timeout is independent
579 from any unit-specific timeout (for
580 example, the timeout set with
581 <varname>Timeout=</varname> in service
582 units) as the job timeout has no
583 effect on the unit itself, only on the
584 job that might be pending for it. Or
585 in other words: unit-specific timeouts
586 are useful to abort unit state
587 changes, and revert them. The job
588 timeout set with this option however
589 is useful to abort only the job
590 waiting for the unit state to
591 change.</para></listitem>
595 <term><varname>ConditionPathExists=</varname></term>
596 <term><varname>ConditionKernelCommandLine=</varname></term>
598 <listitem><para>Before starting a unit
599 verify that the specified condition is
601 <varname>ConditionPathExists=</varname>
602 a file existance condition can be
603 checked before a unit is started. If
604 the specified absolute path name does
605 not exist startup of a unit will not
606 actually happen, however the unit is
607 still useful for ordering purposes in
608 this case. The condition is checked at
609 the time the queued start job is to be
610 executed. If the absolute path name
612 <varname>ConditionPathExists=</varname>
613 is prefixed with an exclamation mark
614 (!), the test is negated, and the unit
615 only started if the path does not
617 <varname>ConditionKernelCommandLine=</varname>
618 may be used to check whether a
619 specific kernel command line option is
620 set (or if prefixed with the
621 exclamation mark unset). The argument
622 must either be a single word, or an
623 assignment (i.e. two words, seperated
624 by the equality sign). In the former
625 case the kernel command line is search
626 for the word appearing as is, or as
627 left hand side of an assignment. In
628 the latter case the exact assignment
629 is looked for with right and left hand
630 side matching. If multiple conditions
631 are specified the unit will be
632 executed iff at least one of them
633 apply (i.e. a logical OR is
634 applied).</para></listitem>
638 <para>Unit file may include a [Install] section, which
639 carries installation information for the unit. This
640 section is not interpreted by
641 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
642 during runtime. It is used exclusively by the
643 <command>enable</command> and
644 <command>disable</command> commands of the
645 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
646 tool during installation of a unit:</para>
650 <term><varname>Alias=</varname></term>
652 <listitem><para>Additional names this
653 unit shall be installed under. The
654 names listed here must have the same
655 suffix (i.e. type) as the unit file
656 name. This option may be specified
657 more than once, in which case all
658 listed names are used. At installation
660 <command>systemctl enable</command>
661 will create symlinks from these names
662 to the unit file name. Note that this
663 is different from the
664 <varname>Names=</varname> option from
665 the [Unit] section mentioned above:
667 <varname>Names=</varname> apply
668 unconditionally if the unit is
669 loaded. The names from
670 <varname>Alias=</varname> apply only
671 if the unit has actually been
673 <command>systemctl enable</command>
674 command. Also, if systemd searches for a
675 unit, it will discover symlinked alias
676 names as configured with
677 <varname>Alias=</varname>, but not
678 names configured with
679 <varname>Names=</varname> only. It is
680 a common pattern to list a name in
681 both options. In this case, a unit
682 will be active under all names if
683 installed, but also if not installed
684 but requested explicitly under its
685 main name.</para></listitem>
689 <term><varname>WantedBy=</varname></term>
691 <listitem><para>Installs a symlink in
692 the <filename>.wants/</filename>
693 subdirectory for a unit. This has the
694 effect that when the listed unit name
695 is activated the unit listing it is
697 too. <command>WantedBy=foo.service</command>
699 <filename>bar.service</filename> is
701 <command>Alias=foo.service.wants/bar.service</command>
702 in the same file.</para></listitem>
706 <term><varname>Also=</varname></term>
708 <listitem><para>Additional units to
709 install when this unit is
710 installed. If the user requests
711 installation of a unit with this
713 <command>systemctl enable</command>
714 will automatically install units
715 listed in this option as
716 well.</para></listitem>
723 <title>See Also</title>
725 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
726 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
727 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
728 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
729 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
730 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
731 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
732 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
733 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
734 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
735 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
736 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
737 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>