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 formats. 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 concatenation 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
155 path,
"/" is replaced by
"-", and all unprintable
156 characters and the
"-" are replaced by C-style
"\x20"
157 escapes. The root directory
"/" is encoded as single
158 dash, while otherwise the initial and ending
"/" is
159 removed from all paths during transformation. This
160 escaping is reversible.
</para>
162 <para>Optionally, units may be instantiated from a
163 template file at runtime. This allows creation of
164 multiple units from a single configuration file. If
165 systemd looks for a unit configuration file it will
166 first search for the literal unit name in the
167 filesystem. If that yields no success and the unit
168 name contains an @ character, systemd will look for a
169 unit template that shares the same name but with the
170 instance string (i.e. the part between the @ character
171 and the suffix) removed. Example: if a service
172 <filename>getty@tty3.service
</filename> is requested
173 and no file by that name is found, systemd will look
174 for
<filename>getty@.service
</filename> and
175 instantiate a service from that configuration file if
176 it is found. To refer to the instance string from
177 within the configuration file you may use the special
178 <literal>%i
</literal> specifier in many of the
179 configuration options. Other specifiers that may be
180 used are
<literal>%n
</literal>,
<literal>%N
</literal>,
181 <literal>%p
</literal>,
<literal>%P
</literal> and
182 <literal>%I
</literal>, for the full unit name, the
183 unescaped unit name, the prefix name, the unescaped
184 prefix name and the unescaped instance name,
185 respectively. The prefix name here refers to the
186 string before the @, i.e.
"getty" in the example
187 above, where
"tty3" is the instance name.
</para>
191 <title>Options
</title>
193 <para>Unit file may include a [Unit] section, which
194 carries generic information about the unit that is not
195 dependent on the type of unit:
</para>
199 <term><varname>Names=
</varname></term>
201 <listitem><para>Additional names for
202 this unit. The names listed here must
203 have the same suffix (i.e. type) as
204 the unit file name. This option may be
205 specified more than once, in which
206 case all listed names are used. Note
207 that this option is different from the
208 <varname>Alias=
</varname> option from
209 the [Install] section mentioned
210 below. See below for details.
</para>
215 <term><varname>Description=
</varname></term>
216 <listitem><para>A free-form string
217 describing the unit. This is intended for use
218 in UIs wanting to show
219 descriptive information along with the
220 unit name.
</para></listitem>
224 <term><varname>Requires=
</varname></term>
226 <listitem><para>Configures requirement
227 dependencies on other units. If this
228 units get activated the units listed
229 here will be activated as well. If one
230 of the other units gets deactivated or
231 its activation fails, this unit will
232 be deactivated. This option may be
233 specified more than once, in which
234 case requirement dependencies for all
235 listed names are created. Note that
236 requirement dependencies do not
237 influence the order in which services
238 are started or stopped. This has to be
239 configured independently with the
240 <varname>After=
</varname> or
241 <varname>Before=
</varname> options. If
243 <filename>foo.service
</filename>
245 <filename>bar.service
</filename> as
247 <varname>Requires=
</varname> and no
248 ordering is configured with
249 <varname>After=
</varname> or
250 <varname>Before=
</varname>, then both
251 units will be started simultaneously
252 and without any delay between them if
253 <filename>foo.service
</filename> is
254 activated. Often it is a better choice
255 to use
<varname>Wants=
</varname>
257 <varname>Requires=
</varname> in order
258 to achieve a system that is more
259 robust when dealing with failing
260 services.
</para></listitem>
265 <term><varname>RequiresOverridable=
</varname></term>
267 <listitem><para>Similar to
268 <varname>Requires=
</varname>.
269 Dependencies listed in
270 <varname>RequiresOverridable=
</varname>
271 which cannot be fulfilled or fail to
272 start are ignored iff the startup was
273 explicitly requested by the user. If
274 the start-up was pulled in indirectly
275 by some dependency or automatic
276 start-up of units that is not
277 requested by the user this dependency
278 must be fulfilled and otherwise the
279 transaction fails. Hence, this option
280 may be used to configure dependencies
281 that are normally honored unless the
282 user explicitly starts up the unit, in
283 which case whether they failed or not
284 is irrelevant.
</para></listitem>
288 <term><varname>Requisite=
</varname></term>
289 <term><varname>RequisiteOverridable=
</varname></term>
291 <listitem><para>Similar to
292 <varname>Requires=
</varname>
293 resp.
<varname>RequiresOverridable=
</varname>. However,
294 if a unit listed here is not started
295 already it will not be started and the
297 immediately.
</para></listitem>
301 <term><varname>Wants=
</varname></term>
303 <listitem><para>A weaker version of
304 <varname>Requires=
</varname>. A unit
305 listed in this option will be started
306 if the configuring unit is. However,
307 it the listed unit fails to start up
308 or cannot be added to the transaction
309 this has no impact on the validity of
310 the transaction as a whole. This is
311 the recommended way to hook start-up
312 of one unit to the start-up of another
313 unit. Note that dependencies of this
314 type may also be configured outside of
315 the unit configuration file by
316 adding a symlink to a
317 <filename>.wants/
</filename> directory
318 accompanying the unit file. For
319 details see above.
</para></listitem>
323 <term><varname>Conflicts=
</varname></term>
325 <listitem><para>Configures negative
326 requirement dependencies. If a unit
328 <varname>Conflicts=
</varname> setting
329 on another unit starting the former
330 will stop the latter and vice
331 versa. Note that this setting is
332 independent of and orthogonal to the
333 <varname>After=
</varname> and
334 <varname>Before=
</varname> ordering
335 dependencies.
</para></listitem>
339 <term><varname>Before=
</varname></term>
340 <term><varname>After=
</varname></term>
342 <listitem><para>Configures ordering
343 dependencies between units. If a unit
344 <filename>foo.service
</filename>
346 <option>Before=bar.service
</option>
347 and both units are being started
348 <filename>bar.service
</filename>'s
349 start-up is delayed until
350 <filename>foo.service
</filename> is
351 started up. Note that this setting is
352 independent of and orthogonal to the
353 requirement dependencies as configured
354 by
<varname>Requires=
</varname>. It is
355 a common pattern to include a unit
357 <varname>After=
</varname> and
358 <varname>Requires=
</varname> option in
359 which case the unit listed will be
360 started before the unit that is
361 configured with these options. This
362 option may be specified more than
363 once, in which case ordering
364 dependencies for all listed names are
365 created.
<varname>After=
</varname> is
367 <varname>Before=
</varname>, i.e. while
368 <varname>After=
</varname> ensures that
369 the configured unit is started after
370 the listed unit finished starting up,
371 <varname>Before=
</varname> ensures the
372 opposite, i.e. that the configured
373 unit is fully started up before the
374 listed unit is started. Note that when
375 two units with an ordering dependency
376 between them are shut down, the
377 inverse of of the start-up order is
378 applied. i.e. if a unit is configured
379 with
<varname>After=
</varname> on
380 another unit, the former is stopped
381 before the latter if both are shut
382 down. If one unit with an ordering
383 dependency on another unit is shut
384 down while the latter is started up,
385 the shut down is ordered before the
386 start-up regardless whether the
387 ordering dependency is actually of
388 type
<varname>After=
</varname> or
389 <varname>Before=
</varname>. If two
390 units have no ordering dependencies
391 between them they are shut down
392 resp. started up simultaneously, and
394 place.
</para></listitem>
398 <term><varname>RecursiveStop=
</varname></term>
400 <listitem><para>Takes a boolean
401 argument. If
<option>true
</option> and
402 the unit stops without this being
403 requested by the user all units
404 depending on it will be stopped as
405 well. (e.g. if a service exits or
406 crashes on its own behalf, units using
407 it will be stopped) Note that normally
408 if a unit stops without user request
409 units depending on it will not be
410 terminated. Only if the user requested
411 shutdown of a unit all units depending
412 on the unit will be shut down as well
413 and at the same time. Defaults to
414 <option>false
</option>.
</para></listitem>
418 <term><varname>StopWhenUnneeded=
</varname></term>
420 <listitem><para>Takes a boolean
421 argument. If
<option>true
</option>
422 this unit will be stopped when it is
423 no longer used. Note that in order to
424 minimize the work to be executed
425 systemd will by default not stop units
426 unless they are conflicting with other
427 units, or the user explicitly
428 requested their shut down. If this
429 option is set a unit will be
430 automatically cleaned up if no other
431 active unit requires it. Defaults to
432 <option>false
</option>.
</para></listitem>
436 <term><varname>OnlyByDependency=
</varname></term>
438 <listitem><para>Takes a boolean
439 argument. If
<option>true
</option>
440 this unit may only be activated
441 indirectly. In this case explicit
442 start-up requested by the user is
443 denied, however if it is started as
444 dependency of another unit start-up
445 will succeed. This is mostly a safety
446 feature to ensure that the user does
447 not accidentally activate units that are
448 not intended to be activated
449 explicitly. This option defaults to
450 <option>false
</option>.
</para></listitem>
455 <para>Unit file may include a [Install] section, which
456 carries installation information for the unit. This
457 section is not interpreted by
458 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
459 during runtime. It is used exclusively by the
460 <citerefentry><refentrytitle>systemd-install
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
461 tool during installation of a unit:
</para>
465 <term><varname>Alias=
</varname></term>
467 <listitem><para>Additional names, this
468 unit shall be installed under. The
469 names listed here must have the same
470 suffix (i.e. type) as the unit file
471 name. This option may be specified
472 more than once, in which case all
473 listed names are used. At installation
475 <command>systemd-install
</command>
476 will create symlinks from these names
477 to the unit file name. Note that this
478 is different from the
479 <varname>Names=
</varname> option from
480 the [Unit] section mentioned above:
482 <varname>Names=
</varname> apply
483 unconditionally if the unit is
484 loaded. The names from
485 <varname>Alias=
</varname> apply only
486 if the unit has actually been
488 <command>systemd-install
</command>
489 tool. Also, if systemd searches for a
490 unit, it will discover symlinked alias
491 names as configured with
492 <varname>Alias=
</varname>, but not
493 names configured with
494 <varname>Names=
</varname> only. It is
495 a common pattern to list a name in
496 both options. In this case, a unit
497 will be active under all names if
498 installed, but also if not installed
499 but requested explicitly under its
500 main name.
</para></listitem>
504 <term><varname>WantedBy=
</varname></term>
506 <listitem><para>Installs a symlink in
507 the
<filename>.wants/
</filename>
508 subdirectory for a unit. This has the
509 effect that when the listed unit name
510 is activated the unit listing it is
512 too.
<command>WantedBy=foo.service
</command>
514 <filename>bar.service
</filename> is
516 <command>Alias=foo.service.wants/bar.service
</command>
517 in the same file.
</para></listitem>
521 <term><varname>Also=
</varname></term>
523 <listitem><para>Additional units to
524 install when this unit is
525 installed. If the user requests
526 installation of a unit with this
528 <command>systemd-install
</command>
529 will automatically install units
530 listed in this option as
531 well.
</para></listitem>
538 <title>See Also
</title>
540 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
541 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
542 <citerefentry><refentrytitle>systemd-install
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
543 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
544 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
545 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
546 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
547 <citerefentry><refentrytitle>systemd.mount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
548 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
549 <citerefentry><refentrytitle>systemd.swap
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
550 <citerefentry><refentrytitle>systemd.target
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
551 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
552 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
projects / thirdparty / systemd.git / blob