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> and
186 <literal>%I</literal>, for the full unit name, the
187 unescaped unit name, the prefix name, the unescaped
188 prefix name and the unescaped instance name,
189 respectively. The prefix name here refers to the
190 string before the @, i.e. "getty" in the example
191 above, where "tty3" is the instance name.</para>
193 <para>If a unit file is empty (i.e. has the file size
194 0) or is symlinked to <filename>/dev/null</filename>
195 its configuration will not be loaded and it appears
196 with a load state of <literal>masked</literal>, and
197 cannot be activated. Use this as an effective way to
198 fully disable a unit, making it impossible to start it
199 even manually.</para>
201 <para>The unit file format is covered by the
203 url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
204 Stability Promise</ulink>.</para>
208 <title>Options</title>
210 <para>Unit file may include a [Unit] section, which
211 carries generic information about the unit that is not
212 dependent on the type of unit:</para>
216 <term><varname>Names=</varname></term>
218 <listitem><para>Additional names for
219 this unit. The names listed here must
220 have the same suffix (i.e. type) as
221 the unit file name. This option may be
222 specified more than once, in which
223 case all listed names are used. Note
224 that this option is different from the
225 <varname>Alias=</varname> option from
226 the [Install] section mentioned
227 below. See below for details.</para>
232 <term><varname>Description=</varname></term>
233 <listitem><para>A free-form string
234 describing the unit. This is intended
235 for use in UIs to show descriptive
236 information along with the unit
237 name.</para></listitem>
241 <term><varname>Requires=</varname></term>
243 <listitem><para>Configures requirement
244 dependencies on other units. If this
245 unit gets activated, the units listed
246 here will be activated as well. If one
247 of the other units gets deactivated or
248 its activation fails, this unit will
249 be deactivated. This option may be
250 specified more than once, in which
251 case requirement dependencies for all
252 listed names are created. Note that
253 requirement dependencies do not
254 influence the order in which services
255 are started or stopped. This has to be
256 configured independently with the
257 <varname>After=</varname> or
258 <varname>Before=</varname> options. If
260 <filename>foo.service</filename>
262 <filename>bar.service</filename> as
264 <varname>Requires=</varname> and no
265 ordering is configured with
266 <varname>After=</varname> or
267 <varname>Before=</varname>, then both
268 units will be started simultaneously
269 and without any delay between them if
270 <filename>foo.service</filename> is
271 activated. Often it is a better choice
272 to use <varname>Wants=</varname>
274 <varname>Requires=</varname> in order
275 to achieve a system that is more
276 robust when dealing with failing
277 services.</para></listitem>
282 <term><varname>RequiresOverridable=</varname></term>
284 <listitem><para>Similar to
285 <varname>Requires=</varname>.
286 Dependencies listed in
287 <varname>RequiresOverridable=</varname>
288 which cannot be fulfilled or fail to
289 start are ignored if the startup was
290 explicitly requested by the user. If
291 the start-up was pulled in indirectly
292 by some dependency or automatic
293 start-up of units that is not
294 requested by the user this dependency
295 must be fulfilled and otherwise the
296 transaction fails. Hence, this option
297 may be used to configure dependencies
298 that are normally honored unless the
299 user explicitly starts up the unit, in
300 which case whether they failed or not
301 is irrelevant.</para></listitem>
305 <term><varname>Requisite=</varname></term>
306 <term><varname>RequisiteOverridable=</varname></term>
308 <listitem><para>Similar to
309 <varname>Requires=</varname>
310 resp. <varname>RequiresOverridable=</varname>. However,
311 if a unit listed here is not started
312 already it will not be started and the
314 immediately.</para></listitem>
318 <term><varname>Wants=</varname></term>
320 <listitem><para>A weaker version of
321 <varname>Requires=</varname>. A unit
322 listed in this option will be started
323 if the configuring unit is. However,
324 if the listed unit fails to start up
325 or cannot be added to the transaction
326 this has no impact on the validity of
327 the transaction as a whole. This is
328 the recommended way to hook start-up
329 of one unit to the start-up of another
330 unit. Note that dependencies of this
331 type may also be configured outside of
332 the unit configuration file by
333 adding a symlink to a
334 <filename>.wants/</filename> directory
335 accompanying the unit file. For
336 details see above.</para></listitem>
340 <term><varname>Conflicts=</varname></term>
342 <listitem><para>Configures negative
343 requirement dependencies. If a unit
345 <varname>Conflicts=</varname> setting
346 on another unit, starting the former
347 will stop the latter and vice
348 versa. Note that this setting is
349 independent of and orthogonal to the
350 <varname>After=</varname> and
351 <varname>Before=</varname> ordering
354 <para>If a unit A that conflicts with
355 a unit B is scheduled to be started at
356 the same time as B, the transaction
357 will either fail (in case both are
358 required part of the transaction) or
359 be modified to be fixed (in case one
360 or both jobs are not a required part
361 of the transaction). In the latter
362 case the job that is not the required
363 will be removed, or in case both are
364 not required the unit that conflicts
365 will be started and the unit that is
367 stopped.</para></listitem>
371 <term><varname>Before=</varname></term>
372 <term><varname>After=</varname></term>
374 <listitem><para>Configures ordering
375 dependencies between units. If a unit
376 <filename>foo.service</filename>
378 <option>Before=bar.service</option>
379 and both units are being started,
380 <filename>bar.service</filename>'s
381 start-up is delayed until
382 <filename>foo.service</filename> is
383 started up. Note that this setting is
384 independent of and orthogonal to the
385 requirement dependencies as configured
386 by <varname>Requires=</varname>. It is
387 a common pattern to include a unit
389 <varname>After=</varname> and
390 <varname>Requires=</varname> option in
391 which case the unit listed will be
392 started before the unit that is
393 configured with these options. This
394 option may be specified more than
395 once, in which case ordering
396 dependencies for all listed names are
397 created. <varname>After=</varname> is
399 <varname>Before=</varname>, i.e. while
400 <varname>After=</varname> ensures that
401 the configured unit is started after
402 the listed unit finished starting up,
403 <varname>Before=</varname> ensures the
404 opposite, i.e. that the configured
405 unit is fully started up before the
406 listed unit is started. Note that when
407 two units with an ordering dependency
408 between them are shut down, the
409 inverse of the start-up order is
410 applied. i.e. if a unit is configured
411 with <varname>After=</varname> on
412 another unit, the former is stopped
413 before the latter if both are shut
414 down. If one unit with an ordering
415 dependency on another unit is shut
416 down while the latter is started up,
417 the shut down is ordered before the
418 start-up regardless whether the
419 ordering dependency is actually of
420 type <varname>After=</varname> or
421 <varname>Before=</varname>. If two
422 units have no ordering dependencies
423 between them they are shut down
424 resp. started up simultaneously, and
426 place. </para></listitem>
430 <term><varname>OnFailure=</varname></term>
432 <listitem><para>Lists one or more
433 units that are activated when this
435 '<literal>failed</literal>'
436 state.</para></listitem>
440 <term><varname>RecursiveStop=</varname></term>
442 <listitem><para>Takes a boolean
443 argument. If <option>true</option> and
444 the unit stops without being requested
445 by the user, all units
446 depending on it will be stopped as
447 well. (e.g. if a service exits or
448 crashes on its own behalf, units using
449 it will be stopped) Note that normally
450 if a unit stops without a user request,
451 units depending on it will not be
452 terminated. Only if the user requested
453 shutdown of a unit, all units depending
454 on that unit will be shut down as well
455 and at the same time. Defaults to
456 <option>false</option>.</para></listitem>
460 <term><varname>StopWhenUnneeded=</varname></term>
462 <listitem><para>Takes a boolean
463 argument. If <option>true</option>
464 this unit will be stopped when it is
465 no longer used. Note that in order to
466 minimize the work to be executed,
467 systemd will not stop units by default
468 unless they are conflicting with other
469 units, or the user explicitly
470 requested their shut down. If this
471 option is set, a unit will be
472 automatically cleaned up if no other
473 active unit requires it. Defaults to
474 <option>false</option>.</para></listitem>
478 <term><varname>RefuseManualStart=</varname></term>
479 <term><varname>RefuseManualStop=</varname></term>
481 <listitem><para>Takes a boolean
482 argument. If <option>true</option>
483 this unit can only be activated
484 (resp. deactivated) indirectly. In
485 this case explicit start-up
486 (resp. termination) requested by the
487 user is denied, however if it is
488 started (resp. stopped) as a
489 dependency of another unit, start-up
490 (resp. termination) will succeed. This
491 is mostly a safety feature to ensure
492 that the user does not accidentally
493 activate units that are not intended
494 to be activated explicitly, and not
495 accidentally deactivate units that are
496 not intended to be deactivated.
497 These options default to
498 <option>false</option>.</para></listitem>
502 <term><varname>AllowIsolate=</varname></term>
504 <listitem><para>Takes a boolean
505 argument. If <option>true</option>
506 this unit may be used with the
507 <command>systemctl isolate</command>
508 command. Otherwise this will be
509 refused. It probably is a good idea to
510 leave this disabled except for target
511 units that shall be used similar to
512 runlevels in SysV init systems, just
513 as a precaution to avoid unusable
514 system states. This option defaults to
515 <option>false</option>.</para></listitem>
519 <term><varname>DefaultDependencies=</varname></term>
521 <listitem><para>Takes a boolean
522 argument. If <option>true</option>
523 (the default), a few default
524 dependencies will implicitly be
525 created for the unit. The actual
526 dependencies created depend on the
527 unit type. For example, for service
528 units, these dependencies ensure that
529 the service is started only after
530 basic system initialization is
531 completed and is properly terminated on
532 system shutdown. See the respective
533 man pages for details. Generally, only
534 services involved with early boot or
535 late shutdown should set this option
536 to <option>false</option>. It is
537 highly recommended to leave this
538 option enabled for the majority of
539 common units. If set to
540 <option>false</option> this option
541 does not disable all implicit
542 dependencies, just non-essential
543 ones.</para></listitem>
547 <term><varname>IgnoreDependencyFailure=</varname></term>
549 <listitem><para>Takes a boolean
550 argument. If <option>true</option> and
551 a requirement dependency of this unit
552 fails to start up this unit will be
553 started nonetheless, ignoring that
554 failure. If <option>false</option>
555 (the default) and a dependency unit
556 fails the unit will immediately fail
557 too and the job is removed.</para></listitem>
561 <term><varname>JobTimeoutSec=</varname></term>
563 <listitem><para>When clients are
564 waiting for a job of this unit to
565 complete, time out after the specified
566 time. If this time limit is reached
567 the job will be cancelled, the unit
568 however will not change state or even
569 enter the '<literal>failed</literal>'
570 mode. This value defaults to 0 (job
571 timeouts disabled), except for device
572 units. NB: this timeout is independent
573 from any unit-specific timeout (for
574 example, the timeout set with
575 <varname>Timeout=</varname> in service
576 units) as the job timeout has no
577 effect on the unit itself, only on the
578 job that might be pending for it. Or
579 in other words: unit-specific timeouts
580 are useful to abort unit state
581 changes, and revert them. The job
582 timeout set with this option however
583 is useful to abort only the job
584 waiting for the unit state to
585 change.</para></listitem>
589 <term><varname>ConditionPathExists=</varname></term>
590 <term><varname>ConditionKernelCommandLine=</varname></term>
592 <listitem><para>Before starting a unit
593 verify that the specified condition is
595 <varname>ConditionPathExists=</varname>
596 a file existance condition can be
597 checked before a unit is started. If
598 the specified absolute path name does
599 not exist startup of a unit will not
600 actually happen, however the unit is
601 still useful for ordering purposes in
602 this case. The condition is checked at
603 the time the queued start job is to be
604 executed. If the absolute path name
606 <varname>ConditionPathExists=</varname>
607 is prefixed with an exclamation mark
608 (!), the test is negated, and the unit
609 only started if the path does not
611 <varname>ConditionKernelCommandLine=</varname>
612 may be used to check whether a
613 specific kernel command line option is
614 set (or if prefixed with the
615 exclamation mark unset). The argument
616 must either be a single word, or an
617 assignment (i.e. two words, seperated
618 by the equality sign). In the former
619 case the kernel command line is search
620 for the word appearing as is, or as
621 left hand side of an assignment. In
622 the latter case the exact assignment
623 is looked for with right and left hand
624 side matching. If multiple conditions
625 are specified the unit will be
626 executed iff at least one of them
627 apply (i.e. a logical OR is
628 applied).</para></listitem>
632 <para>Unit file may include a [Install] section, which
633 carries installation information for the unit. This
634 section is not interpreted by
635 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
636 during runtime. It is used exclusively by the
637 <command>enable</command> and
638 <command>disable</command> commands of the
639 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
640 tool during installation of a unit:</para>
644 <term><varname>Alias=</varname></term>
646 <listitem><para>Additional names this
647 unit shall be installed under. The
648 names listed here must have the same
649 suffix (i.e. type) as the unit file
650 name. This option may be specified
651 more than once, in which case all
652 listed names are used. At installation
654 <command>systemctl enable</command>
655 will create symlinks from these names
656 to the unit file name. Note that this
657 is different from the
658 <varname>Names=</varname> option from
659 the [Unit] section mentioned above:
661 <varname>Names=</varname> apply
662 unconditionally if the unit is
663 loaded. The names from
664 <varname>Alias=</varname> apply only
665 if the unit has actually been
667 <command>systemctl enable</command>
668 command. Also, if systemd searches for a
669 unit, it will discover symlinked alias
670 names as configured with
671 <varname>Alias=</varname>, but not
672 names configured with
673 <varname>Names=</varname> only. It is
674 a common pattern to list a name in
675 both options. In this case, a unit
676 will be active under all names if
677 installed, but also if not installed
678 but requested explicitly under its
679 main name.</para></listitem>
683 <term><varname>WantedBy=</varname></term>
685 <listitem><para>Installs a symlink in
686 the <filename>.wants/</filename>
687 subdirectory for a unit. This has the
688 effect that when the listed unit name
689 is activated the unit listing it is
691 too. <command>WantedBy=foo.service</command>
693 <filename>bar.service</filename> is
695 <command>Alias=foo.service.wants/bar.service</command>
696 in the same file.</para></listitem>
700 <term><varname>Also=</varname></term>
702 <listitem><para>Additional units to
703 install when this unit is
704 installed. If the user requests
705 installation of a unit with this
707 <command>systemctl enable</command>
708 will automatically install units
709 listed in this option as
710 well.</para></listitem>
717 <title>See Also</title>
719 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
720 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
721 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
722 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
723 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
724 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
725 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
726 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
727 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
728 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
729 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
730 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
731 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>
~ianmdlvl / elogind.git / blob