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>
195 <title>Options</title>
197 <para>Unit file may include a [Unit] section, which
198 carries generic information about the unit that is not
199 dependent on the type of unit:</para>
203 <term><varname>Names=</varname></term>
205 <listitem><para>Additional names for
206 this unit. The names listed here must
207 have the same suffix (i.e. type) as
208 the unit file name. This option may be
209 specified more than once, in which
210 case all listed names are used. Note
211 that this option is different from the
212 <varname>Alias=</varname> option from
213 the [Install] section mentioned
214 below. See below for details.</para>
219 <term><varname>Description=</varname></term>
220 <listitem><para>A free-form string
221 describing the unit. This is intended
222 for use in UIs to show descriptive
223 information along with the unit
224 name.</para></listitem>
228 <term><varname>Requires=</varname></term>
230 <listitem><para>Configures requirement
231 dependencies on other units. If this
232 unit gets activated, the units listed
233 here will be activated as well. If one
234 of the other units gets deactivated or
235 its activation fails, this unit will
236 be deactivated. This option may be
237 specified more than once, in which
238 case requirement dependencies for all
239 listed names are created. Note that
240 requirement dependencies do not
241 influence the order in which services
242 are started or stopped. This has to be
243 configured independently with the
244 <varname>After=</varname> or
245 <varname>Before=</varname> options. If
247 <filename>foo.service</filename>
249 <filename>bar.service</filename> as
251 <varname>Requires=</varname> and no
252 ordering is configured with
253 <varname>After=</varname> or
254 <varname>Before=</varname>, then both
255 units will be started simultaneously
256 and without any delay between them if
257 <filename>foo.service</filename> is
258 activated. Often it is a better choice
259 to use <varname>Wants=</varname>
261 <varname>Requires=</varname> in order
262 to achieve a system that is more
263 robust when dealing with failing
264 services.</para></listitem>
269 <term><varname>RequiresOverridable=</varname></term>
271 <listitem><para>Similar to
272 <varname>Requires=</varname>.
273 Dependencies listed in
274 <varname>RequiresOverridable=</varname>
275 which cannot be fulfilled or fail to
276 start are ignored if the startup was
277 explicitly requested by the user. If
278 the start-up was pulled in indirectly
279 by some dependency or automatic
280 start-up of units that is not
281 requested by the user this dependency
282 must be fulfilled and otherwise the
283 transaction fails. Hence, this option
284 may be used to configure dependencies
285 that are normally honored unless the
286 user explicitly starts up the unit, in
287 which case whether they failed or not
288 is irrelevant.</para></listitem>
292 <term><varname>Requisite=</varname></term>
293 <term><varname>RequisiteOverridable=</varname></term>
295 <listitem><para>Similar to
296 <varname>Requires=</varname>
297 resp. <varname>RequiresOverridable=</varname>. However,
298 if a unit listed here is not started
299 already it will not be started and the
301 immediately.</para></listitem>
305 <term><varname>Wants=</varname></term>
307 <listitem><para>A weaker version of
308 <varname>Requires=</varname>. A unit
309 listed in this option will be started
310 if the configuring unit is. However,
311 if the listed unit fails to start up
312 or cannot be added to the transaction
313 this has no impact on the validity of
314 the transaction as a whole. This is
315 the recommended way to hook start-up
316 of one unit to the start-up of another
317 unit. Note that dependencies of this
318 type may also be configured outside of
319 the unit configuration file by
320 adding a symlink to a
321 <filename>.wants/</filename> directory
322 accompanying the unit file. For
323 details see above.</para></listitem>
327 <term><varname>Conflicts=</varname></term>
329 <listitem><para>Configures negative
330 requirement dependencies. If a unit
332 <varname>Conflicts=</varname> setting
333 on another unit, starting the former
334 will stop the latter and vice
335 versa. Note that this setting is
336 independent of and orthogonal to the
337 <varname>After=</varname> and
338 <varname>Before=</varname> ordering
341 <para>If a unit A that conflicts with
342 a unit B is scheduled to be started at
343 the same time as B, the transaction
344 will either fail (in case both are
345 required part of the transaction) or
346 be modified to be fixed (in case one
347 or both jobs are not a required part
348 of the transaction). In the latter
349 case the job that is not the required
350 will be removed, or in case both are
351 not required the unit that conflicts
352 will be started and the unit that is
354 stopped.</para></listitem>
358 <term><varname>Before=</varname></term>
359 <term><varname>After=</varname></term>
361 <listitem><para>Configures ordering
362 dependencies between units. If a unit
363 <filename>foo.service</filename>
365 <option>Before=bar.service</option>
366 and both units are being started,
367 <filename>bar.service</filename>'s
368 start-up is delayed until
369 <filename>foo.service</filename> is
370 started up. Note that this setting is
371 independent of and orthogonal to the
372 requirement dependencies as configured
373 by <varname>Requires=</varname>. It is
374 a common pattern to include a unit
376 <varname>After=</varname> and
377 <varname>Requires=</varname> option in
378 which case the unit listed will be
379 started before the unit that is
380 configured with these options. This
381 option may be specified more than
382 once, in which case ordering
383 dependencies for all listed names are
384 created. <varname>After=</varname> is
386 <varname>Before=</varname>, i.e. while
387 <varname>After=</varname> ensures that
388 the configured unit is started after
389 the listed unit finished starting up,
390 <varname>Before=</varname> ensures the
391 opposite, i.e. that the configured
392 unit is fully started up before the
393 listed unit is started. Note that when
394 two units with an ordering dependency
395 between them are shut down, the
396 inverse of the start-up order is
397 applied. i.e. if a unit is configured
398 with <varname>After=</varname> on
399 another unit, the former is stopped
400 before the latter if both are shut
401 down. If one unit with an ordering
402 dependency on another unit is shut
403 down while the latter is started up,
404 the shut down is ordered before the
405 start-up regardless whether the
406 ordering dependency is actually of
407 type <varname>After=</varname> or
408 <varname>Before=</varname>. If two
409 units have no ordering dependencies
410 between them they are shut down
411 resp. started up simultaneously, and
413 place. </para></listitem>
417 <term><varname>OnFailure=</varname></term>
419 <listitem><para>Lists one or more
420 units that are activated when this
422 '<literal>failed</literal>'
423 state.</para></listitem>
427 <term><varname>RecursiveStop=</varname></term>
429 <listitem><para>Takes a boolean
430 argument. If <option>true</option> and
431 the unit stops without being requested
432 by the user, all units
433 depending on it will be stopped as
434 well. (e.g. if a service exits or
435 crashes on its own behalf, units using
436 it will be stopped) Note that normally
437 if a unit stops without a user request,
438 units depending on it will not be
439 terminated. Only if the user requested
440 shutdown of a unit, all units depending
441 on that unit will be shut down as well
442 and at the same time. Defaults to
443 <option>false</option>.</para></listitem>
447 <term><varname>StopWhenUnneeded=</varname></term>
449 <listitem><para>Takes a boolean
450 argument. If <option>true</option>
451 this unit will be stopped when it is
452 no longer used. Note that in order to
453 minimize the work to be executed,
454 systemd will not stop units by default
455 unless they are conflicting with other
456 units, or the user explicitly
457 requested their shut down. If this
458 option is set, a unit will be
459 automatically cleaned up if no other
460 active unit requires it. Defaults to
461 <option>false</option>.</para></listitem>
465 <term><varname>RefuseManualStart=</varname></term>
466 <term><varname>RefuseManualStop=</varname></term>
468 <listitem><para>Takes a boolean
469 argument. If <option>true</option>
470 this unit can only be activated
471 (resp. deactivated) indirectly. In
472 this case explicit start-up
473 (resp. termination) requested by the
474 user is denied, however if it is
475 started (resp. stopped) as a
476 dependency of another unit, start-up
477 (resp. termination) will succeed. This
478 is mostly a safety feature to ensure
479 that the user does not accidentally
480 activate units that are not intended
481 to be activated explicitly, and not
482 accidentally deactivate units that are
483 not intended to be deactivated.
484 These options default to
485 <option>false</option>.</para></listitem>
489 <term><varname>AllowIsolate=</varname></term>
491 <listitem><para>Takes a boolean
492 argument. If <option>true</option>
493 this unit may be used with the
494 <command>systemctl isolate</command>
495 command. Otherwise this will be
496 refused. It probably is a good idea to
497 leave this disabled except for target
498 units that shall be used similar to
499 runlevels in SysV init systems, just
500 as a precaution to avoid unusable
501 system states. This option defaults to
502 <option>false</option>.</para></listitem>
506 <term><varname>DefaultDependencies=</varname></term>
508 <listitem><para>Takes a boolean
509 argument. If <option>true</option>
510 (the default), a few default
511 dependencies will implicitly be
512 created for the unit. The actual
513 dependencies created depend on the
514 unit type. For example, for service
515 units, these dependencies ensure that
516 the service is started only after
517 basic system initialization is
518 completed and is properly terminated on
519 system shutdown. See the respective
520 man pages for details. Generally, only
521 services involved with early boot or
522 late shutdown should set this option
523 to <option>false</option>. It is
524 highly recommended to leave this
525 option enabled for the majority of
526 common units. If set to
527 <option>false</option> this option
528 does not disable all implicit
529 dependencies, just non-essential
530 ones.</para></listitem>
534 <term><varname>IgnoreDependencyFailure=</varname></term>
536 <listitem><para>Takes a boolean
537 argument. If <option>true</option> and
538 a requirement dependency of this unit
539 fails to start up this unit will be
540 started nonetheless, ignoring that
541 failure. If <option>false</option>
542 (the default) and a dependency unit
543 fails the unit will immediately fail
544 too and the job is removed.</para></listitem>
548 <term><varname>JobTimeoutSec=</varname></term>
550 <listitem><para>When clients are
551 waiting for a job of this unit to
552 complete, time out after the specified
553 time. If this time limit is reached
554 the job will be cancelled, the unit
555 however will not change state or even
556 enter the '<literal>failed</literal>'
557 mode. This value defaults to 0 (job
558 timeouts disabled), except for device
559 units. NB: this timeout is independent
560 from any unit-specific timeout (for
561 example, the timeout set with
562 <varname>Timeout=</varname> in service
563 units) as the job timeout has no
564 effect on the unit itself, only on the
565 job that might be pending for it. Or
566 in other words: unit-specific timeouts
567 are useful to abort unit state
568 changes, and revert them. The job
569 timeout set with this option however
570 is useful to abort only the job
571 waiting for the unit state to
572 change.</para></listitem>
577 <para>Unit file may include a [Install] section, which
578 carries installation information for the unit. This
579 section is not interpreted by
580 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
581 during runtime. It is used exclusively by the
582 <command>enable</command> and
583 <command>disable</command> commands of the
584 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
585 tool during installation of a unit:</para>
589 <term><varname>Alias=</varname></term>
591 <listitem><para>Additional names this
592 unit shall be installed under. The
593 names listed here must have the same
594 suffix (i.e. type) as the unit file
595 name. This option may be specified
596 more than once, in which case all
597 listed names are used. At installation
599 <command>systemctl enable</command>
600 will create symlinks from these names
601 to the unit file name. Note that this
602 is different from the
603 <varname>Names=</varname> option from
604 the [Unit] section mentioned above:
606 <varname>Names=</varname> apply
607 unconditionally if the unit is
608 loaded. The names from
609 <varname>Alias=</varname> apply only
610 if the unit has actually been
612 <command>systemctl enable</command>
613 command. Also, if systemd searches for a
614 unit, it will discover symlinked alias
615 names as configured with
616 <varname>Alias=</varname>, but not
617 names configured with
618 <varname>Names=</varname> only. It is
619 a common pattern to list a name in
620 both options. In this case, a unit
621 will be active under all names if
622 installed, but also if not installed
623 but requested explicitly under its
624 main name.</para></listitem>
628 <term><varname>WantedBy=</varname></term>
630 <listitem><para>Installs a symlink in
631 the <filename>.wants/</filename>
632 subdirectory for a unit. This has the
633 effect that when the listed unit name
634 is activated the unit listing it is
636 too. <command>WantedBy=foo.service</command>
638 <filename>bar.service</filename> is
640 <command>Alias=foo.service.wants/bar.service</command>
641 in the same file.</para></listitem>
645 <term><varname>Also=</varname></term>
647 <listitem><para>Additional units to
648 install when this unit is
649 installed. If the user requests
650 installation of a unit with this
652 <command>systemctl enable</command>
653 will automatically install units
654 listed in this option as
655 well.</para></listitem>
662 <title>See Also</title>
664 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
665 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
666 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
667 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
668 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
669 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
670 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
671 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
672 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
673 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
674 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
675 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
676 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>