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 the all 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 value 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.</para>
119 <para>If a line starts with <option>.include</option>
120 followed by a file name the specified file will be
121 read as if its contents where listed in place of the
122 <option>.include</option> directive.</para>
124 <para>Along with a unit file
125 <filename>foo.service</filename> a directory
126 <filename>foo.service.wants/</filename> may exist. All
127 units symlinked from such a directory are implicitly
128 added as dependencies of type
129 <varname>Wanted=</varname> to the unit. This is useful
130 to hook units into the start-up of other units,
131 without having to modify their unit configuration
132 files. For details about the semantics of
133 <varname>Wanted=</varname> see below. The preferred
134 way to create symlinks in the
135 <filename>.wants/</filename> directory of a service is
137 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
138 tool which reads information from the [Install]
139 section of unit files. (See below.)</para>
141 <para>Note that while systemd offers a flexible
142 dependency system between units it is recommended to
143 use this functionality only sparsely and instead rely
144 on techniques such as bus-based or socket-based
145 activation which makes dependencies implicit, which
146 both results in a simpler and more flexible
149 <para>Some unit names reflect paths existing in the
150 file system name space. Example: a device unit
151 <filename>dev-sda.device</filename> refers to a device
152 with the device node <filename>/dev/sda</filename> in
153 the file system namespace. If this applies a special
154 way to escape the path name is used, so that it is
155 usable as part of a file name. Basically, given a
156 path, "/" is replaced by "-", and all unprintable
157 characters and the "-" are replaced by C-style "\x20"
158 escapes. The root directory "/" is encoded as single
159 dash, while otherwise the initial and ending "/" is
160 removed from all paths during transformation. This
161 escaping is reversible.</para>
163 <para>Optionally, units may be instantiated from a
164 template file at runtime. This allows creation of
165 multiple units from a single configuration file. If
166 systemd looks for a unit configuration file it will
167 first search for the literal unit name in the
168 filesystem. If that yields no success and the unit
169 name contains an @ character, systemd will look for a
170 unit template that shares the same name but with the
171 instance string (i.e. the part between the @ character
172 and the suffix) removed. Example: if a service
173 <filename>getty@tty3.service</filename> is requested
174 and no file by that name is found, systemd will look
175 for <filename>getty@.service</filename> and
176 instantiate a service from that configuration file if
177 it is found. To refer to the instance string from
178 within the configuration file you may use the special
179 <literal>%i</literal> specifier in many of the
180 configuration options. Other specifiers that may be
181 used are <literal>%n</literal>, <literal>%N</literal>,
182 <literal>%p</literal>, <literal>%P</literal> and
183 <literal>%I</literal>, for the full unit name, the
184 unescaped unit name, the prefix name, the unescaped
185 prefix name and the unescaped instance name,
186 respectively. The prefix name here refers to the
187 string before the @, i.e. "getty" in the example
188 above, where "tty3" is the instance name.</para>
192 <title>Options</title>
194 <para>Unit file may include a [Unit] section, which
195 carries generic information about the unit that is not
196 dependent on the type of unit:</para>
200 <term><varname>Names=</varname></term>
202 <listitem><para>Additional names for
203 this unit. The names listed here must
204 have the same suffix (i.e. type) as
205 the unit file name. This option may be
206 specified more than once, in which
207 case all listed names are used. Note
208 that this option is different from the
209 <varname>Alias=</varname> option from
210 the [Install] section mentioned
211 below. See below for details.</para>
216 <term><varname>Description=</varname></term>
217 <listitem><para>A free-form string
218 describing the unit. This is intended
219 for use in UIs to show descriptive
220 information along with the unit
221 name.</para></listitem>
225 <term><varname>Requires=</varname></term>
227 <listitem><para>Configures requirement
228 dependencies on other units. If this
229 units get activated the units listed
230 here will be activated as well. If one
231 of the other units gets deactivated or
232 its activation fails, this unit will
233 be deactivated. This option may be
234 specified more than once, in which
235 case requirement dependencies for all
236 listed names are created. Note that
237 requirement dependencies do not
238 influence the order in which services
239 are started or stopped. This has to be
240 configured independently with the
241 <varname>After=</varname> or
242 <varname>Before=</varname> options. If
244 <filename>foo.service</filename>
246 <filename>bar.service</filename> as
248 <varname>Requires=</varname> and no
249 ordering is configured with
250 <varname>After=</varname> or
251 <varname>Before=</varname>, then both
252 units will be started simultaneously
253 and without any delay between them if
254 <filename>foo.service</filename> is
255 activated. Often it is a better choice
256 to use <varname>Wants=</varname>
258 <varname>Requires=</varname> in order
259 to achieve a system that is more
260 robust when dealing with failing
261 services.</para></listitem>
266 <term><varname>RequiresOverridable=</varname></term>
268 <listitem><para>Similar to
269 <varname>Requires=</varname>.
270 Dependencies listed in
271 <varname>RequiresOverridable=</varname>
272 which cannot be fulfilled or fail to
273 start are ignored iff the startup was
274 explicitly requested by the user. If
275 the start-up was pulled in indirectly
276 by some dependency or automatic
277 start-up of units that is not
278 requested by the user this dependency
279 must be fulfilled and otherwise the
280 transaction fails. Hence, this option
281 may be used to configure dependencies
282 that are normally honored unless the
283 user explicitly starts up the unit, in
284 which case whether they failed or not
285 is irrelevant.</para></listitem>
289 <term><varname>Requisite=</varname></term>
290 <term><varname>RequisiteOverridable=</varname></term>
292 <listitem><para>Similar to
293 <varname>Requires=</varname>
294 resp. <varname>RequiresOverridable=</varname>. However,
295 if a unit listed here is not started
296 already it will not be started and the
298 immediately.</para></listitem>
302 <term><varname>Wants=</varname></term>
304 <listitem><para>A weaker version of
305 <varname>Requires=</varname>. A unit
306 listed in this option will be started
307 if the configuring unit is. However,
308 it the listed unit fails to start up
309 or cannot be added to the transaction
310 this has no impact on the validity of
311 the transaction as a whole. This is
312 the recommended way to hook start-up
313 of one unit to the start-up of another
314 unit. Note that dependencies of this
315 type may also be configured outside of
316 the unit configuration file by
317 adding a symlink to a
318 <filename>.wants/</filename> directory
319 accompanying the unit file. For
320 details see above.</para></listitem>
324 <term><varname>Conflicts=</varname></term>
326 <listitem><para>Configures negative
327 requirement dependencies. If a unit
329 <varname>Conflicts=</varname> setting
330 on another unit starting the former
331 will stop the latter and vice
332 versa. Note that this setting is
333 independent of and orthogonal to the
334 <varname>After=</varname> and
335 <varname>Before=</varname> ordering
336 dependencies.</para></listitem>
340 <term><varname>Before=</varname></term>
341 <term><varname>After=</varname></term>
343 <listitem><para>Configures ordering
344 dependencies between units. If a unit
345 <filename>foo.service</filename>
347 <option>Before=bar.service</option>
348 and both units are being started
349 <filename>bar.service</filename>'s
350 start-up is delayed until
351 <filename>foo.service</filename> is
352 started up. Note that this setting is
353 independent of and orthogonal to the
354 requirement dependencies as configured
355 by <varname>Requires=</varname>. It is
356 a common pattern to include a unit
358 <varname>After=</varname> and
359 <varname>Requires=</varname> option in
360 which case the unit listed will be
361 started before the unit that is
362 configured with these options. This
363 option may be specified more than
364 once, in which case ordering
365 dependencies for all listed names are
366 created. <varname>After=</varname> is
368 <varname>Before=</varname>, i.e. while
369 <varname>After=</varname> ensures that
370 the configured unit is started after
371 the listed unit finished starting up,
372 <varname>Before=</varname> ensures the
373 opposite, i.e. that the configured
374 unit is fully started up before the
375 listed unit is started. Note that when
376 two units with an ordering dependency
377 between them are shut down, the
378 inverse of of the start-up order is
379 applied. i.e. if a unit is configured
380 with <varname>After=</varname> on
381 another unit, the former is stopped
382 before the latter if both are shut
383 down. If one unit with an ordering
384 dependency on another unit is shut
385 down while the latter is started up,
386 the shut down is ordered before the
387 start-up regardless whether the
388 ordering dependency is actually of
389 type <varname>After=</varname> or
390 <varname>Before=</varname>. If two
391 units have no ordering dependencies
392 between them they are shut down
393 resp. started up simultaneously, and
395 place. </para></listitem>
399 <term><varname>RecursiveStop=</varname></term>
401 <listitem><para>Takes a boolean
402 argument. If <option>true</option> and
403 the unit stops without this being
404 requested by the user all units
405 depending on it will be stopped as
406 well. (e.g. if a service exits or
407 crashes on its own behalf, units using
408 it will be stopped) Note that normally
409 if a unit stops without user request
410 units depending on it will not be
411 terminated. Only if the user requested
412 shutdown of a unit all units depending
413 on the unit will be shut down as well
414 and at the same time. Defaults to
415 <option>false</option>.</para></listitem>
419 <term><varname>StopWhenUnneeded=</varname></term>
421 <listitem><para>Takes a boolean
422 argument. If <option>true</option>
423 this unit will be stopped when it is
424 no longer used. Note that in order to
425 minimize the work to be executed
426 systemd will by default not stop units
427 unless they are conflicting with other
428 units, or the user explicitly
429 requested their shut down. If this
430 option is set a unit will be
431 automatically cleaned up if no other
432 active unit requires it. Defaults to
433 <option>false</option>.</para></listitem>
437 <term><varname>OnlyByDependency=</varname></term>
439 <listitem><para>Takes a boolean
440 argument. If <option>true</option>
441 this unit may only be activated
442 indirectly. In this case explicit
443 start-up requested by the user is
444 denied, however if it is started as
445 dependency of another unit start-up
446 will succeed. This is mostly a safety
447 feature to ensure that the user does
448 not accidentally activate units that are
449 not intended to be activated
450 explicitly. This option defaults to
451 <option>false</option>.</para></listitem>
455 <term><varname>DefaultDependencies=</varname></term>
457 <listitem><para>Takes a boolean
458 argument. If <option>true</option>
459 (the default), a few default
460 dependencies will implicitly be
461 created for the unit. The actual
462 dependencies created depend on the
463 unit type. For example, for service
464 units, these dependencies ensure that
465 the service is started only after
466 basic system initialization is
467 complete and is properly terminated on
468 system shutdown. See the respective
469 man pages for details. Generally, only
470 services involved with early boot or
471 late shutdown should set this option
472 to <option>false</option>. It is
473 highly recommended to leave this
474 option enabled for the majority of
475 common units. If set to
476 <option>false</option> this option
477 does not disable all implicit
478 dependencies, just non-essential
479 ones.</para></listitem>
484 <para>Unit file may include a [Install] section, which
485 carries installation information for the unit. This
486 section is not interpreted by
487 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
488 during runtime. It is used exclusively by the
489 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
490 tool during installation of a unit:</para>
494 <term><varname>Alias=</varname></term>
496 <listitem><para>Additional names this
497 unit shall be installed under. The
498 names listed here must have the same
499 suffix (i.e. type) as the unit file
500 name. This option may be specified
501 more than once, in which case all
502 listed names are used. At installation
504 <command>systemd-install</command>
505 will create symlinks from these names
506 to the unit file name. Note that this
507 is different from the
508 <varname>Names=</varname> option from
509 the [Unit] section mentioned above:
511 <varname>Names=</varname> apply
512 unconditionally if the unit is
513 loaded. The names from
514 <varname>Alias=</varname> apply only
515 if the unit has actually been
517 <command>systemd-install</command>
518 tool. Also, if systemd searches for a
519 unit, it will discover symlinked alias
520 names as configured with
521 <varname>Alias=</varname>, but not
522 names configured with
523 <varname>Names=</varname> only. It is
524 a common pattern to list a name in
525 both options. In this case, a unit
526 will be active under all names if
527 installed, but also if not installed
528 but requested explicitly under its
529 main name.</para></listitem>
533 <term><varname>WantedBy=</varname></term>
535 <listitem><para>Installs a symlink in
536 the <filename>.wants/</filename>
537 subdirectory for a unit. This has the
538 effect that when the listed unit name
539 is activated the unit listing it is
541 too. <command>WantedBy=foo.service</command>
543 <filename>bar.service</filename> is
545 <command>Alias=foo.service.wants/bar.service</command>
546 in the same file.</para></listitem>
550 <term><varname>Also=</varname></term>
552 <listitem><para>Additional units to
553 install when this unit is
554 installed. If the user requests
555 installation of a unit with this
557 <command>systemd-install</command>
558 will automatically install units
559 listed in this option as
560 well.</para></listitem>
567 <title>See Also</title>
569 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
570 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
571 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
572 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
573 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
574 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
575 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
576 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
577 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
578 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
579 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
580 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
581 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
582 <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>