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></para>
63 <title>Description</title>
65 <para>A unit configuration file encodes information
66 about a service, a socket, a device, a mount point, an
67 automount point, a swap file or partition, a start-up
68 target, a file system path or a timer controlled and
70 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
71 syntax is inspired by <ulink
72 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
73 Desktop Entry Specification</ulink> <filename>.desktop</filename> files, which are in turn
74 inspired by Microsoft Windows
75 <filename>.ini</filename> files.</para>
77 <para>This man pages lists the common configuration
78 options of the all unit types. These options need to
79 be configured in the [Unit] resp. [Install]
80 section of the unit files.</para>
82 <para>In addition to the generic [Unit] and [Install]
83 sections described here each unit should have a
84 type-specific section, e.g. [Service] for a service
85 unit. See the respective man pages for more
88 <para>Unit files may contain additional options on top
89 of those listed here. If systemd encounters an unknown
90 option it will write a warning log message but
91 continue loading the unit. If an option is prefixed
92 with <option>X-</option> it is ignored completely by
93 systemd. Applications may use this to include
94 additional information in the unit files.</para>
96 <para>Boolean arguments used in unit files can be
97 written in various forms. For positive settings the
98 strings <option>1</option>, <option>yes</option>,
99 <option>true</option> and <option>on</option> are
100 equivalent. For negative settings the strings
101 <option>0</option>, <option>no</option>,
102 <option>false</option> and <option>off</option> are
105 <para>Time span values encoded in unit files can be
106 written in various formats. A stand-alone number
107 specifies a time in seconds. If suffixed with a time
108 unit, the unit is honored. A concatentation of
109 multiple value with units is supported, in which case
110 the values are added up. Example: "50" refers to 50
111 seconds; "2min 200ms" refers to 2 minutes plus 200
112 milliseconds, i.e. 120200ms. The following time units
113 are understood: s, min, h, d, w, ms, us.</para>
115 <para>Empty lines and lines starting with # or ; are
116 ignored. This may be used for commenting.</para>
118 <para>If a line starts with <option>.include</option>
119 followed by a file name the specified file will be
120 read as if its contents where listed in place of the
121 <option>.include</option> directive.</para>
123 <para>Along with a unit file
124 <filename>foo.service</filename> a directory
125 <filename>foo.service.wants/</filename> may exist. All
126 units symlinked from such a directory are implicitly
127 added as dependencies of type
128 <varname>Wanted=</varname> to the unit. This is useful
129 to hook units into the start-up of other units,
130 without having to modify their unit configuration
131 files. For details about the semantics of
132 <varname>Wanted=</varname> see below. The preferred
133 way to create symlinks in the
134 <filename>.wants/</filename> directory of a service is
136 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
137 tool which reads information from the [Install]
138 section of unit files. (See below.)</para>
140 <para>Note that while systemd offers a flexible
141 dependency system between units it is recommended to
142 use this functionality only sparsely and instead rely
143 on techniques such as bus-based or socket-based
144 activation which makes dependencies implicit, which
145 both results in a simpler and more flexible
148 <para>Some unit names reflect paths existing in the
149 file system name space. Example: a device unit
150 <filename>dev-sda.device</filename> refers to a device
151 with the device node <filename>/dev/sda</filename> in
152 the file system namespace. If this applies a special
153 way to escape the path name is used, so that it is
154 usable as part of a file name. Basically, given a path,
155 "/" is replaced by "-", and all unprintable characters
156 and the "-" are replaced by C-style "\x20"
157 escapes. This escaping is reversible.</para>
159 <para>Optionally, units may be instantiated from a
160 template file at runtime. This allows creation of
161 multiple units from a single configuration file. If
162 systemd looks for a unit configuration file it will
163 first search for the literal unit name in the
164 filesystem. If that yields no success and the unit
165 name contains an @ character, systemd will look for a
166 unit template that shares the same name but with the
167 instance string (i.e. the part between the @ character
168 and the suffix) removed. Example: if a service
169 <filename>getty@tty3.service</filename> is requested
170 and no file by that name is found, systemd will look
171 for <filename>getty@.service</filename> and
172 instantiate a service from that configuration file if
173 it is found. To refer to the instance string from
174 within the configuration file you may use the special
175 <literal>%i</literal> specifier in many of the
176 configuration options. Other specifiers that may be
177 used are <literal>%n</literal>, <literal>%N</literal>,
178 <literal>%p</literal>, <literal>%P</literal> and
179 <literal>%I</literal>, for the full unit name, the
180 unescaped unit name, the prefix name, the unescaped
181 prefix name and the unescaped instance name,
182 respectively. The prefix name here refers to the
183 string before the @, i.e. "getty" in the example
184 above, where "tty3" is the instance name.</para>
188 <title>Options</title>
190 <para>Unit file may include a [Unit] section, which
191 carries generic information about the unit that is not
192 dependent on the type of unit:</para>
196 <term><varname>Names=</varname></term>
198 <listitem><para>Additional names for
199 this unit. The names listed here must
200 have the same suffix (i.e. type) as
201 the unit file name. This option may be
202 specified more than once, in which
203 case all listed names are used. Note
204 that this option is different from the
205 <varname>Alias=</varname> option from
206 the [Install] section mentioned
207 below. See below for details.</para>
212 <term><varname>Description=</varname></term>
213 <listitem><para>A free-form string
214 describing the unit. This is intended for use
215 in UIs wanting to show
216 descriptive information along with the
217 unit name.</para></listitem>
221 <term><varname>Requires=</varname></term>
223 <listitem><para>Configures requirement
224 dependencies on other units. If this
225 units get activated the units listed
226 here will be activated as well. If one
227 of the other units gets deactivated or
228 its activation fails, this unit will
229 be deactivated. This option may be
230 specified more than once, in which
231 case requirement dependencies for all
232 listed names are created. Note that
233 requirement dependencies do not
234 influence the order in which services
235 are started or stopped. This has to be
236 configured independently with the
237 <varname>After=</varname> or
238 <varname>Before=</varname> options. If
240 <filename>foo.service</filename>
242 <filename>bar.service</filename> as
244 <varname>Requires=</varname> and no
245 ordering is configured with
246 <varname>After=</varname> or
247 <varname>Before=</varname>, then both
248 units will be started simultaneously
249 and without any delay between them if
250 <filename>foo.service</filename> is
251 activated. Often it is a better choice
252 to use <varname>Wants=</varname>
254 <varname>Requires=</varname> in order
255 to achieve a system that is more
256 robust when dealing with failing
257 services.</para></listitem>
262 <term><varname>RequiresOverridable=</varname></term>
264 <listitem><para>Similar to
265 <varname>Requires=</varname>.
266 Dependencies listed in
267 <varname>RequiresOverridable=</varname>
268 which cannot be fulfilled or fail to
269 start are ignored iff the startup was
270 explicitly requested by the user. If
271 the start-up was pulled in indirectly
272 by some dependency or automatic
273 start-up of units that is not
274 requested by the user this dependency
275 must be fulfilled and otherwise the
276 transaction fails. Hence, this option
277 may be used to configure dependencies
278 that are normally honored unless the
279 user explicitly starts up the unit, in
280 which case whether they failed or not
281 is irrelevant.</para></listitem>
285 <term><varname>Requisite=</varname></term>
286 <term><varname>RequisiteOverridable=</varname></term>
288 <listitem><para>Similar to
289 <varname>Requires=</varname>
290 resp. <varname>RequiresOverridable=</varname>. However,
291 if a unit listed here is not started
292 already it will not be started and the
294 immediately.</para></listitem>
298 <term><varname>Wants=</varname></term>
300 <listitem><para>A weaker version of
301 <varname>Requires=</varname>. A unit
302 listed in this option will be started
303 if the configuring unit is. However,
304 it the listed unit fails to start up
305 or cannot be added to the transaction
306 this has no impact on the validity of
307 the transaction as a whole. This is
308 the recommended way to hook start-up
309 of one unit to the start-up of another
310 unit. Note that dependencies of this
311 type may also be configured outside of
312 the unit configuration file by
313 adding a symlink to a
314 <filename>.wants/</filename> directory
315 accompanying the unit file. For
316 details see above.</para></listitem>
320 <term><varname>Conflicts=</varname></term>
322 <listitem><para>Configures negative
323 requirement dependencies. If a unit
325 <varname>Conflicts=</varname> setting
326 on another unit starting the former
327 will stop the latter and vice
328 versa. Note that this setting is
329 independent of and orthogonal to the
330 <varname>After=</varname> and
331 <varname>Before=</varname> ordering
332 dependencies.</para></listitem>
336 <term><varname>Before=</varname></term>
337 <term><varname>After=</varname></term>
339 <listitem><para>Configures ordering
340 dependencies between units. If a unit
341 <filename>foo.service</filename>
343 <option>Before=bar.service</option>
344 and both units are being started
345 <filename>bar.service</filename>'s
346 start-up is delayed until
347 <filename>foo.service</filename> is
348 started up. Note that this setting is
349 independent of and orthogonal to the
350 requirement dependencies as configured
351 by <varname>Requires=</varname>. It is
352 a common pattern to include a unit
354 <varname>After=</varname> and
355 <varname>Requires=</varname> option in
356 which case the unit listed will be
357 started before the unit that is
358 configured with these options. This
359 option may be specified more than
360 once, in which case ordering
361 dependencies for all listed names are
362 created. <varname>After=</varname> is
364 <varname>Before=</varname>, i.e. while
365 <varname>After=</varname> ensures that
366 the configured unit is started after
367 the listed unit finished starting up,
368 <varname>Before=</varname> ensures the
369 opposite, i.e. that the configured
370 unit is fully started up before the
371 listed unit is started. Note that when
372 two units with an ordering dependency
373 between them are shut down, the
374 inverse of of the start-up order is
375 applied. i.e. if a unit is configured
376 with <varname>After=</varname> on
377 another unit, the former is stopped
378 before the latter if both are shut
379 down. If one unit with an ordering
380 dependency on another unit is shut
381 down while the latter is started up,
382 the shut down is ordered before the
383 start-up regardless whether the
384 ordering dependency is actually of
385 type <varname>After=</varname> or
386 <varname>Before=</varname>. If two
387 units have no ordering dependencies
388 between them they are shut down
389 resp. started up simultaneously, and
391 place. </para></listitem>
395 <term><varname>RecursiveStop=</varname></term>
397 <listitem><para>Takes a boolean
398 argument. If <option>true</option> and
399 the unit stops without this being
400 requested by the user all units
401 depending on it will be stopped as
402 well. (e.g. if a service exits or
403 crashes on its own behalf, units using
404 it will be stopped) Note that normally
405 if a unit stops without user request
406 units depending on it will not be
407 terminated. Only if the user requested
408 shutdown of a unit all units depending
409 on the unit will be shut down as well
410 and at the same time. Defaults to
411 <option>false</option>.</para></listitem>
415 <term><varname>StopWhenUnneeded=</varname></term>
417 <listitem><para>Takes a boolean
418 argument. If <option>true</option>
419 this unit will be stopped when it is
420 no longer used. Note that in order to
421 minimize the work to be executed
422 systemd will by default not stop units
423 unless they are conflicting with other
424 units, or the user explicitly
425 requested their shut down. If this
426 option is set a unit will be
427 automatically cleaned up if no other
428 active unit requires it. Defaults to
429 <option>false</option>.</para></listitem>
433 <term><varname>OnlyByDependency=</varname></term>
435 <listitem><para>Takes a boolean
436 argument. If <option>true</option>
437 this unit may only be activated
438 indirectly. In this case explicit
439 start-up requested by the user is
440 denied, however if it is started as
441 dependency of another unit start-up
442 will succeed. This is mostly a safety
443 feature to ensure that the user does
444 not accidentally activate units that are
445 not intended to be activated
446 explicitly. This option defaults to
447 <option>false</option>.</para></listitem>
452 <para>Unit file may include a [Install] section, which
453 carries installation information for the unit. This
454 section is not interpreted by
455 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
456 during runtime. It is used exclusively by the
457 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
458 tool during installation of a unit:</para>
462 <term><varname>Alias=</varname></term>
464 <listitem><para>Additional names, this
465 unit shall be installed under. The
466 names listed here must have the same
467 suffix (i.e. type) as the unit file
468 name. This option may be specified
469 more than once, in which case all
470 listed names are used. At installation
472 <command>systemd-install</command>
473 will create symlinks from these names
474 to the unit file name. Note that this
475 is different from the
476 <varname>Names=</varname> option from
477 the [Unit] section mentioned above:
479 <varname>Names=</varname> apply
480 unconditionally if the unit is
481 loaded. The names from
482 <varname>Alias=</varname> apply only
483 if the unit has actually been
485 <command>systemd-install</command>
486 tool. Also, if systemd searches for a
487 unit, it will discover symlinked alias
488 names as configured with
489 <varname>Alias=</varname>, but not
490 names configured with
491 <varname>Names=</varname> only. It is
492 a common pattern to list a name in
493 both options. In this case, a unit
494 will be active under all names if
495 installed, but also if not installed
496 but requested explicitly under its
497 main name.</para></listitem>
501 <term><varname>WantedBy=</varname></term>
503 <listitem><para>Installs a symlink in
504 the <filename>.wants/</filename>
505 subdirectory for a unit. This has the
506 effect that when the listed unit name
507 is activated the unit listing it is
509 to. <command>WantedBy=foo.service</command>
511 <filename>bar.service</filename> is
513 <command>Alias=foo.service.wants/bar.service</command>
514 in the same file.</para></listitem>
518 <term><varname>Also=</varname></term>
520 <listitem><para>Additional units to
521 install when this unit is
522 installed. If the user requests
523 installation of a unit with this
525 <command>systemd-install</command>
526 will automatically install units
527 listed in this option as
528 well.</para></listitem>
535 <title>See Also</title>
537 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
538 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
539 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
540 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
541 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
542 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
543 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
544 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
545 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
546 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
547 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
548 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
549 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>