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
150 <title>Options</title>
152 <para>Unit file may include a [Unit] section, which
153 carries generic information about the unit that is not
154 dependent on the type of unit:</para>
158 <term><varname>Names=</varname></term>
160 <listitem><para>Additional names for
161 this unit. The names listed here must
162 have the same suffix (i.e. type) as
163 the unit file name. This option may be
164 specified more than once, in which
165 case all listed names are used. Note
166 that this option is different from the
167 <varname>Alias=</varname> option from
168 the [Install] section mentioned
169 below. See below for details.</para>
174 <term><varname>Description=</varname></term>
175 <listitem><para>A free-form string
176 describing the unit. This is intended for use
177 in UIs wanting to show
178 descriptive information along with the
179 unit name.</para></listitem>
183 <term><varname>Requires=</varname></term>
185 <listitem><para>Configures requirement
186 dependencies on other units. If this
187 units get activated the units listed
188 here will be activated as well. If one
189 of the other units gets deactivated or
190 its activation fails, this unit will
191 be deactivated. This option may be
192 specified more than once, in which
193 case requirement dependencies for all
194 listed names are created. Note that
195 requirement dependencies do not
196 influence the order in which services
197 are started or stopped. This has to be
198 configured independently with the
199 <varname>After=</varname> or
200 <varname>Before=</varname> options. If
202 <filename>foo.service</filename>
204 <filename>bar.service</filename> as
206 <varname>Requires=</varname> and no
207 ordering is configured with
208 <varname>After=</varname> or
209 <varname>Before=</varname>, then both
210 units will be started simultaneously
211 and without any delay between them if
212 <filename>foo.service</filename> is
213 activated. Often it is a better choice
214 to use <varname>Wants=</varname>
216 <varname>Requires=</varname> in order
217 to achieve a system that is more
218 robust when dealing with failing
219 services.</para></listitem>
224 <term><varname>RequiresOverridable=</varname></term>
226 <listitem><para>Similar to
227 <varname>Requires=</varname>.
228 Dependencies listed in
229 <varname>RequiresOverridable=</varname>
230 which cannot be fulfilled or fail to
231 start are ignored iff the startup was
232 explicitly requested by the user. If
233 the start-up was pulled in indirectly
234 by some dependency or automatic
235 start-up of units that is not
236 requested by the user this dependency
237 must be fulfilled and otherwise the
238 transaction fails. Hence, this option
239 may be used to configure dependencies
240 that are normally honored unless the
241 user explicitly starts up the unit, in
242 which case whether they failed or not
243 is irrelevant.</para></listitem>
247 <term><varname>Requisite=</varname></term>
248 <term><varname>RequisiteOverridable=</varname></term>
250 <listitem><para>Similar to
251 <varname>Requires=</varname>
252 resp. <varname>RequiresOverridable=</varname>. However,
253 if a unit listed here is not started
254 already it will not be started and the
256 immediately.</para></listitem>
260 <term><varname>Wants=</varname></term>
262 <listitem><para>A weaker version of
263 <varname>Requires=</varname>. A unit
264 listed in this option will be started
265 if the configuring unit is. However,
266 it the listed unit fails to start up
267 or cannot be added to the transaction
268 this has no impact on the validity of
269 the transaction as a whole. This is
270 the recommended way to hook start-up
271 of one unit to the start-up of another
272 unit. Note that dependencies of this
273 type may also be configured outside of
274 the unit configuration file by
275 adding a symlink to a
276 <filename>.wants/</filename> directory
277 accompanying the unit file. For
278 details see above.</para></listitem>
282 <term><varname>Conflicts=</varname></term>
284 <listitem><para>Configures negative
285 requirement dependencies. If a unit
287 <varname>Conflicts=</varname> setting
288 on another unit starting the former
289 will stop the latter and vice
290 versa. Note that this setting is
291 independent of and orthogonal to the
292 <varname>After=</varname> and
293 <varname>Before=</varname> ordering
294 dependencies.</para></listitem>
298 <term><varname>Before=</varname></term>
299 <term><varname>After=</varname></term>
301 <listitem><para>Configures ordering
302 dependencies between units. If a unit
303 <filename>foo.service</filename>
305 <option>Before=bar.service</option>
306 and both units are being started
307 <filename>bar.service</filename>'s
308 start-up is delayed until
309 <filename>foo.service</filename> is
310 started up. Note that this setting is
311 independent of and orthogonal to the
312 requirement dependencies as configured
313 by <varname>Requires=</varname>. It is
314 a common pattern to include a unit
316 <varname>After=</varname> and
317 <varname>Requires=</varname> option in
318 which case the unit listed will be
319 started before the unit that is
320 configured with these options. This
321 option may be specified more than
322 once, in which case ordering
323 dependencies for all listed names are
324 created. <varname>After=</varname> is
326 <varname>Before=</varname>, i.e. while
327 <varname>After=</varname> ensures that
328 the configured unit is started after
329 the listed unit finished starting up,
330 <varname>Before=</varname> ensures the
331 opposite, i.e. that the configured
332 unit is fully started up before the
333 listed unit is started. Note that when
334 two units with an ordering dependency
335 between them are shut down, the
336 inverse of of the start-up order is
337 applied. i.e. if a unit is configured
338 with <varname>After=</varname> on
339 another unit, the former is stopped
340 before the latter if both are shut
341 down. If one unit with an ordering
342 dependency on another unit is shut
343 down while the latter is started up,
344 the shut down is ordered before the
345 start-up regardless whether the
346 ordering dependency is actually of
347 type <varname>After=</varname> or
348 <varname>Before=</varname>. If two
349 units have no ordering dependencies
350 between them they are shut down
351 resp. started up simultaneously, and
353 place. </para></listitem>
357 <term><varname>RecursiveStop=</varname></term>
359 <listitem><para>Takes a boolean
360 argument. If <option>true</option> and
361 the unit stops without this being
362 requested by the user all units
363 depending on it will be stopped as
364 well. (e.g. if a service exits or
365 crashes on its own behalf, units using
366 it will be stopped) Note that normally
367 if a unit stops without user request
368 units depending on it will not be
369 terminated. Only if the user requested
370 shutdown of a unit all units depending
371 on the unit will be shut down as well
372 and at the same time. Defaults to
373 <option>false</option>.</para></listitem>
377 <term><varname>StopWhenUnneeded=</varname></term>
379 <listitem><para>Takes a boolean
380 argument. If <option>true</option>
381 this unit will be stopped when it is
382 no longer used. Note that in order to
383 minimize the work to be executed
384 systemd will by default not stop units
385 unless they are conflicting with other
386 units, or the user explicitly
387 requested their shut down. If this
388 option is set a unit will be
389 automatically cleaned up if no other
390 active unit requires it. Defaults to
391 <option>false</option>.</para></listitem>
395 <term><varname>OnlyByDependency=</varname></term>
397 <listitem><para>Takes a boolean
398 argument. If <option>true</option>
399 this unit may only be activated
400 indirectly. In this case explicit
401 start-up requested by the user is
402 denied, however if it is started as
403 dependency of another unit start-up
404 will succeed. This is mostly a safety
405 feature to ensure that the user does
406 not accidentally activate units that are
407 not intended to be activated
408 explicitly. This option defaults to
409 <option>false</option>.</para></listitem>
414 <para>Unit file may include a [Install] section, which
415 carries installation information for the unit. This
416 section is not interpreted by
417 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
418 during runtime. It is used exclusively by the
419 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
420 tool during installation of a unit:</para>
424 <term><varname>Alias=</varname></term>
426 <listitem><para>Additional names, this
427 unit shall be installed under. The
428 names listed here must have the same
429 suffix (i.e. type) as the unit file
430 name. This option may be specified
431 more than once, in which case all
432 listed names are used. At installation
434 <command>systemd-install</command>
435 will create symlinks from these names
436 to the unit file name. Note that this
437 is different from the
438 <varname>Names=</varname> option from
439 the [Unit] section mentioned above:
441 <varname>Names=</varname> apply
442 unconditionally if the unit is
443 loaded. The names from
444 <varname>Alias=</varname> apply only
445 if the unit has actually been
447 <command>systemd-install</command>
448 tool. Also, if systemd searches for a
449 unit, it will discover symlinked alias
450 names as configured with
451 <varname>Alias=</varname>, but not
452 names configured with
453 <varname>Names=</varname> only. It is
454 a common pattern to list a name in
455 both options. In this case, a unit
456 will be active under all names if
457 installed, but also if not installed
458 but requested explicitly under its
459 main name.</para></listitem>
463 <term><varname>WantedBy=</varname></term>
465 <listitem><para>Installs a symlink in
466 the <filename>.wants/</filename>
467 subdirectory for a unit. This has the
468 effect that when the listed unit name
469 is activated the unit listing it is
471 to. <command>WantedBy=foo.service</command>
473 <filename>bar.service</filename> is
475 <command>Alias=foo.service.wants/bar.service</command>
476 in the same file.</para></listitem>
480 <term><varname>Also=</varname></term>
482 <listitem><para>Additional units to
483 install when this unit is
484 installed. If the user requests
485 installation of a unit with this
487 <command>systemd-install</command>
488 will automatically install units
489 listed in this option as
490 well.</para></listitem>
497 <title>See Also</title>
499 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
500 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
501 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
502 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
503 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
504 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
505 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
506 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
507 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
508 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
509 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
510 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
511 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>