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>Empty lines and lines starting with # or ; are
106 ignored. This may be used for commenting.</para>
108 <para>If a line starts with <option>.include</option>
109 followed by a file name the specified file will be
110 read as if its contents where listed in place of the
111 <option>.include</option> directive.</para>
113 <para>Along with a unit file
114 <filename>foo.service</filename> a directory
115 <filename>foo.service.wants/</filename> may exist. All
116 units symlinked from such a directory are implicitly
117 added as dependencies of type
118 <varname>Wanted=</varname> to the unit. This is useful
119 to hook units into the start-up of other units,
120 without having to modify their unit configuration
121 files. For details about the semantics of
122 <varname>Wanted=</varname> see below. The preferred
123 way to create symlinks in the
124 <filename>.wants/</filename> directory of a service is
126 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
127 tool which reads information from the [Install]
128 section of unit files. (See below.)</para>
130 <para>Note that while systemd offers a flexible
131 dependency system between units it is recommended to
132 use this functionality only sparsely and instead rely
133 on techniques such as bus-based or socket-based
134 activation which makes dependencies implicit, which
135 both results in a simpler and more flexible
140 <title>Options</title>
142 <para>Unit file may include a [Unit] section, which
143 carries generic information about the unit that is not
144 dependent on the type of unit:</para>
148 <term><varname>Names=</varname></term>
150 <listitem><para>Additional names for
151 this unit. The names listed here must
152 have the same suffix (i.e. type) as
153 the unit file name. This option may be
154 specified more than once, in which
155 case all listed names are used. Note
156 that this option is different from the
157 <varname>Alias=</varname> option from
158 the [Install] section mentioned
159 below. See below for details.</para>
164 <term><varname>Description=</varname></term>
165 <listitem><para>A free-form string
166 describing the unit. This is intended for use
167 in UIs wanting to show
168 descriptive information along with the
169 unit name.</para></listitem>
173 <term><varname>Requires=</varname></term>
175 <listitem><para>Configures requirement
176 dependencies on other units. If this
177 units get activated the units listed
178 here will be activated as well. If one
179 of the other units gets deactivated or
180 its activation fails, this unit will
181 be deactivated. This option may be
182 specified more than once, in which
183 case requirement dependencies for all
184 listed names are created. Note that
185 requirement dependencies do not
186 influence the order in which services
187 are started or stopped. This has to be
188 configured independently with the
189 <varname>After=</varname> or
190 <varname>Before=</varname> options. If
192 <filename>foo.service</filename>
194 <filename>bar.service</filename> as
196 <varname>Requires=</varname> and no
197 ordering is configured with
198 <varname>After=</varname> or
199 <varname>Before=</varname>, then both
200 units will be started simultaneously
201 and without any delay between them if
202 <filename>foo.service</filename> is
203 activated. Often it is a better choice
204 to use <varname>Wants=</varname>
206 <varname>Requires=</varname> in order
207 to achieve a system that is more
208 robust when dealing with failing
209 services.</para></listitem>
214 <term><varname>RequiresOverridable=</varname></term>
216 <listitem><para>Similar to
217 <varname>Requires=</varname>.
218 Dependencies listed in
219 <varname>RequiresOverridable=</varname>
220 which cannot be fulfilled or fail to
221 start are ignored iff the startup was
222 explicitly requested by the user. If
223 the start-up was pulled in indirectly
224 by some dependency or automatic
225 start-up of units that is not
226 requested by the user this dependency
227 must be fulfilled and otherwise the
228 transaction fails. Hence, this option
229 may be used to configure dependencies
230 that are normally honored unless the
231 user explicitly starts up the unit, in
232 which case whether they failed or not
233 is irrelevant.</para></listitem>
237 <term><varname>Requisite=</varname></term>
238 <term><varname>RequisiteOverridable=</varname></term>
240 <listitem><para>Similar to
241 <varname>Requires=</varname>
242 resp. <varname>RequiresOverridable=</varname>. However,
243 if a unit listed here is not started
244 already it will not be started and the
246 immediately.</para></listitem>
250 <term><varname>Wants=</varname></term>
252 <listitem><para>A weaker version of
253 <varname>Requires=</varname>. A unit
254 listed in this option will be started
255 if the configuring unit is. However,
256 it the listed unit fails to start up
257 or cannot be added to the transaction
258 this has no impact on the validity of
259 the transaction as a whole. This is
260 the recommended way to hook start-up
261 of one unit to the start-up of another
262 unit. Note that dependencies of this
263 type may also be configured outside of
264 the unit configuration file by
265 adding a symlink to a
266 <filename>.wants/</filename> directory
267 accompanying the unit file. For
268 details see above.</para></listitem>
272 <term><varname>Conflicts=</varname></term>
274 <listitem><para>Configures negative
275 requirement dependencies. If a unit
277 <varname>Conflicts=</varname> setting
278 on another unit starting the former
279 will stop the latter and vice
280 versa. Note that this setting is
281 independent of and orthogonal to the
282 <varname>After=</varname> and
283 <varname>Before=</varname> ordering
284 dependencies.</para></listitem>
288 <term><varname>Before=</varname></term>
289 <term><varname>After=</varname></term>
291 <listitem><para>Configures ordering
292 dependencies between units. If a unit
293 <filename>foo.service</filename>
295 <option>Before=bar.service</option>
296 and both units are being started
297 <filename>bar.service</filename>'s
298 start-up is delayed until
299 <filename>foo.service</filename> is
300 started up. Note that this setting is
301 independent of and orthogonal to the
302 requirement dependencies as configured
303 by <varname>Requires=</varname>. It is
304 a common pattern to include a unit
306 <varname>After=</varname> and
307 <varname>Requires=</varname> option in
308 which case the unit listed will be
309 started before the unit that is
310 configured with these options. This
311 option may be specified more than
312 once, in which case ordering
313 dependencies for all listed names are
314 created. <varname>After=</varname> is
316 <varname>Before=</varname>, i.e. while
317 <varname>After=</varname> ensures that
318 the configured unit is started after
319 the listed unit finished starting up,
320 <varname>Before=</varname> ensures the
321 opposite, i.e. that the configured
322 unit is fully started up before the
323 listed unit is started. Note that when
324 two units with an ordering dependency
325 between them are shut down, the
326 inverse of of the start-up order is
327 applied. i.e. if a unit is configured
328 with <varname>After=</varname> on
329 another unit, the former is stopped
330 before the latter if both are shut
331 down. If one unit with an ordering
332 dependency on another unit is shut
333 down while the latter is started up,
334 the shut down is ordered before the
335 start-up regardless whether the
336 ordering dependency is actually of
337 type <varname>After=</varname> or
338 <varname>Before=</varname>. If two
339 units have no ordering dependencies
340 between them they are shut down
341 resp. started up simultaneously, and
343 place. </para></listitem>
347 <term><varname>RecursiveStop=</varname></term>
349 <listitem><para>Takes a boolean
350 argument. If <option>true</option> and
351 the unit stops without this being
352 requested by the user all units
353 depending on it will be stopped as
354 well. (e.g. if a service exits or
355 crashes on its own behalf, units using
356 it will be stopped) Note that normally
357 if a unit stops without user request
358 units depending on it will not be
359 terminated. Only if the user requested
360 shutdown of a unit all units depending
361 on the unit will be shut down as well
362 and at the same time. Defaults to
363 <option>false</option>.</para></listitem>
367 <term><varname>StopWhenUnneeded=</varname></term>
369 <listitem><para>Takes a boolean
370 argument. If <option>true</option>
371 this unit will be stopped when it is
372 no longer used. Note that in order to
373 minimize the work to be executed
374 systemd will by default not stop units
375 unless they are conflicting with other
376 units, or the user explicitly
377 requested their shut down. If this
378 option is set a unit will be
379 automatically cleaned up if no other
380 active unit requires it. Defaults to
381 <option>false</option>.</para></listitem>
385 <term><varname>OnlyByDependency=</varname></term>
387 <listitem><para>Takes a boolean
388 argument. If <option>true</option>
389 this unit may only be activated
390 indirectly. In this case explicit
391 start-up requested by the user is
392 denied, however if it is started as
393 dependency of another unit start-up
394 will succeed. This is mostly a safety
395 feature to ensure that the user does
396 not accidentally activate units that are
397 not intended to be activated
398 explicitly. This option defaults to
399 <option>false</option>.</para></listitem>
404 <para>Unit file may include a [Install] section, which
405 carries installation information for the unit. This
406 section is not interpreted by
407 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
408 during runtime. It is used exclusively by the
409 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
410 tool during installation of a unit:</para>
414 <term><varname>Alias=</varname></term>
416 <listitem><para>Additional names, this
417 unit shall be installed under. The
418 names listed here must have the same
419 suffix (i.e. type) as the unit file
420 name. This option may be specified
421 more than once, in which case all
422 listed names are used. At installation
424 <command>systemd-install</command>
425 will create symlinks from these names
426 to the unit file name. Note that this
427 is different from the
428 <varname>Names=</varname> option from
429 the [Unit] section mentioned above:
431 <varname>Names=</varname> apply
432 unconditionally if the unit is
433 loaded. The names from
434 <varname>Alias=</varname> apply only
435 if the unit has actually been
437 <command>systemd-install</command>
438 tool. Also, if systemd searches for a
439 unit, it will discover symlinked alias
440 names as configured with
441 <varname>Alias=</varname>, but not
442 names configured with
443 <varname>Names=</varname> only. It is
444 a common pattern to list a name in
445 both options. In this case, a unit
446 will be active under all names if
447 installed, but also if not installed
448 but requested explicitly under its
449 main name.</para></listitem>
453 <term><varname>WantedBy=</varname></term>
455 <listitem><para>Installs a symlink in
456 the <filename>.wants/</filename>
457 subdirectory for a unit. This has the
458 effect that when the listed unit name
459 is activated the unit listing it is
461 to. <command>WantedBy=foo.service</command>
463 <filename>bar.service</filename> is
465 <command>Alias=foo.service.wants/bar.service</command>
466 in the same file.</para></listitem>
470 <term><varname>Also=</varname></term>
472 <listitem><para>Additional units to
473 install when this unit is
474 installed. If the user requests
475 installation of a unit with this
477 <command>systemd-install</command>
478 will automatically install units
479 listed in this option as
480 well.</para></listitem>
487 <title>See Also</title>
489 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
490 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
491 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
492 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
493 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
494 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
495 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
496 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
497 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
498 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
499 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
500 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
501 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>