1SYSTEMD.UNIT(5) systemd.unit SYSTEMD.UNIT(5)
2
6 systemd.unit - Unit configuration
7
9 service.service, socket.socket, device.device, mount.mount,
10 automount.automount, swap.swap, target.target, path.path, timer.timer,
11 slice.slice, scope.scope
12 System Unit Search Path
14 /etc/systemd/system.control/*
15 /run/systemd/system.control/*
16 /run/systemd/transient/*
17 /run/systemd/generator.early/*
18 /etc/systemd/system/*
19 /etc/systemd/systemd.attached/*
20 /run/systemd/system/*
21 /run/systemd/systemd.attached/*
22 /run/systemd/generator/*
23 ...
24 /usr/lib/systemd/system/*
25 /run/systemd/generator.late/*
26 User Unit Search Path
28 ~/.config/systemd/user.control/*
29 $XDG_RUNTIME_DIR/systemd/user.control/*
30 $XDG_RUNTIME_DIR/systemd/transient/*
31 $XDG_RUNTIME_DIR/systemd/generator.early/*
32 ~/.config/systemd/user/*
33 /etc/systemd/user/*
34 $XDG_RUNTIME_DIR/systemd/user/*
35 /run/systemd/user/*
36 $XDG_RUNTIME_DIR/systemd/generator/*
37 ~/.local/share/systemd/user/*
38 ...
39 /usr/lib/systemd/user/*
40 $XDG_RUNTIME_DIR/systemd/generator.late/*
41
43 A unit file is a plain text ini-style file that encodes information
44 about a service, a socket, a device, a mount point, an automount point,
45 a swap file or partition, a start-up target, a watched file system
46 path, a timer controlled and supervised by systemd(1), a resource
47 management slice or a group of externally created processes. See
48 systemd.syntax(5) for a general description of the syntax.
49 This man page lists the common configuration options of all the unit
51 types. These options need to be configured in the [Unit] or [Install]
52 sections of the unit files.
53 In addition to the generic [Unit] and [Install] sections described
55 here, each unit may have a type-specific section, e.g. [Service] for a
56 service unit. See the respective man pages for more information:
57 systemd.service(5), systemd.socket(5), systemd.device(5),
58 systemd.mount(5), systemd.automount(5), systemd.swap(5),
59 systemd.target(5), systemd.path(5), systemd.timer(5), systemd.slice(5),
60 systemd.scope(5).
61 Unit files are loaded from a set of paths determined during
63 compilation, described in the next section.
64 Unit files can be parameterized by a single argument called the
66 "instance name". The unit is then constructed based on a "template
67 file" which serves as the definition of multiple services or other
68 units. A template unit must have a single "@" at the end of the name
69 (right before the type suffix). The name of the full unit is formed by
70 inserting the instance name between "@" and the unit type suffix. In
71 the unit file itself, the instance parameter may be referred to using
72 "%i" and other specifiers, see below.
73 Unit files may contain additional options on top of those listed here.
75 If systemd encounters an unknown option, it will write a warning log
76 message but continue loading the unit. If an option or section name is
77 prefixed with X-, it is ignored completely by systemd. Options within
78 an ignored section do not need the prefix. Applications may use this to
79 include additional information in the unit files.
80 Units can be aliased (have an alternative name), by creating a symlink
82 from the new name to the existing name in one of the unit search paths.
83 For example, systemd-networkd.service has the alias
84 dbus-org.freedesktop.network1.service, created during installation as
85 the symlink
86 /usr/lib/systemd/system/dbus-org.freedesktop.network1.service. In
87 addition, unit files may specify aliases through the Alias= directive
88 in the [Install] section; those aliases are only effective when the
89 unit is enabled. When the unit is enabled, symlinks will be created for
90 those names, and removed when the unit is disabled. For example,
91 reboot.target specifies Alias=ctrl-alt-del.target, so when enabled it
92 will be invoked whenever CTRL+ALT+DEL is pressed. Alias names may be
93 used in commands like enable, disable, start, stop, status, ..., and in
94 unit dependency directives Wants=, Requires=, Before=, After=, ...,
95 with the limitation that aliases specified through Alias= are only
96 effective when the unit is enabled. Aliases cannot be used with the
97 preset command.
98 Along with a unit file foo.service, the directory foo.service.wants/
100 may exist. All unit files symlinked from such a directory are
101 implicitly added as dependencies of type Wants= to the unit. This is
102 useful to hook units into the start-up of other units, without having
103 to modify their unit files. For details about the semantics of Wants=,
104 see below. The preferred way to create symlinks in the .wants/
105 directory of a unit file is with the enable command of the systemctl(1)
106 tool which reads information from the [Install] section of unit files
107 (see below). A similar functionality exists for Requires= type
108 dependencies as well, the directory suffix is .requires/ in this case.
109 Along with a unit file foo.service, a "drop-in" directory
111 foo.service.d/ may exist. All files with the suffix ".conf" from this
112 directory will be parsed after the unit file itself is parsed. This is
113 useful to alter or add configuration settings for a unit, without
114 having to modify unit files. Drop-in files must contain appropriate
115 section headers. For instantiated units, this logic will first look for
116 the instance ".d/" subdirectory (e.g. "foo@bar.service.d/") and read
117 its ".conf" files, followed by the template ".d/" subdirectory (e.g.
118 "foo@.service.d/") and the ".conf" files there. Moreover for units
119 names containing dashes ("-"), the set of directories generated by
120 truncating the unit name after all dashes is searched too.
121 Specifically, for a unit name foo-bar-baz.service not only the regular
122 drop-in directory foo-bar-baz.service.d/ is searched but also both
123 foo-bar-.service.d/ and foo-.service.d/. This is useful for defining
124 common drop-ins for a set of related units, whose names begin with a
125 common prefix. This scheme is particularly useful for mount, automount
126 and slice units, whose systematic naming structure is built around
127 dashes as component separators. Note that equally named drop-in files
128 further down the prefix hierarchy override those further up, i.e.
129 foo-bar-.service.d/10-override.conf overrides
130 foo-.service.d/10-override.conf.
131 In addition to /etc/systemd/system, the drop-in ".d/" directories for
133 system services can be placed in /usr/lib/systemd/system or
134 /run/systemd/system directories. Drop-in files in /etc take precedence
135 over those in /run which in turn take precedence over those in
136 /usr/lib. Drop-in files under any of these directories take precedence
137 over unit files wherever located. Multiple drop-in files with different
138 names are applied in lexicographic order, regardless of which of the
139 directories they reside in.
140 Note that while systemd offers a flexible dependency system between
142 units it is recommended to use this functionality only sparingly and
143 instead rely on techniques such as bus-based or socket-based activation
144 which make dependencies implicit, resulting in a both simpler and more
145 flexible system.
146 As mentioned above, a unit may be instantiated from a template file.
148 This allows creation of multiple units from a single configuration
149 file. If systemd looks for a unit configuration file, it will first
150 search for the literal unit name in the file system. If that yields no
151 success and the unit name contains an "@" character, systemd will look
152 for a unit template that shares the same name but with the instance
153 string (i.e. the part between the "@" character and the suffix)
154 removed. Example: if a service getty@tty3.service is requested and no
155 file by that name is found, systemd will look for getty@.service and
156 instantiate a service from that configuration file if it is found.
157 To refer to the instance string from within the configuration file you
159 may use the special "%i" specifier in many of the configuration
160 options. See below for details.
161 If a unit file is empty (i.e. has the file size 0) or is symlinked to
163 /dev/null, its configuration will not be loaded and it appears with a
164 load state of "masked", and cannot be activated. Use this as an
165 effective way to fully disable a unit, making it impossible to start it
166 even manually.
167 The unit file format is covered by the Interface Stability Promise[1].
169
171 Sometimes it is useful to convert arbitrary strings into unit names. To
172 facilitate this, a method of string escaping is used, in order to map
173 strings containing arbitrary byte values (except NUL) into valid unit
174 names and their restricted character set. A common special case are
175 unit names that reflect paths to objects in the file system hierarchy.
176 Example: a device unit dev-sda.device refers to a device with the
177 device node /dev/sda in the file system.
178 The escaping algorithm operates as follows: given a string, any "/"
180 character is replaced by "-", and all other characters which are not
181 ASCII alphanumerics or "_" are replaced by C-style "\x2d" escapes. In
182 addition, "." is replaced with such a C-style escape when it would
183 appear as the first character in the escaped string.
184 When the input qualifies as absolute file system path, this algorithm
186 is extended slightly: the path to the root directory "/" is encoded as
187 single dash "-". In addition, any leading, trailing or duplicate "/"
188 characters are removed from the string before transformation. Example:
189 /foo//bar/baz/ becomes "foo-bar-baz".
190 This escaping is fully reversible, as long as it is known whether the
192 escaped string was a path (the unescaping results are different for
193 paths and non-path strings). The systemd-escape(1) command may be used
194 to apply and reverse escaping on arbitrary strings. Use systemd-escape
195 --path to escape path strings, and systemd-escape without --path
196 otherwise.
197
199 Implicit Dependencies
200 A number of unit dependencies are implicitly established, depending on
201 unit type and unit configuration. These implicit dependencies can make
202 unit configuration file cleaner. For the implicit dependencies in each
203 unit type, please refer to section "Implicit Dependencies" in
204 respective man pages.
205 For example, service units with Type=dbus automatically acquire
207 dependencies of type Requires= and After= on dbus.socket. See
208 systemd.service(5) for details.
209 Default Dependencies
211 Default dependencies are similar to implicit dependencies, but can be
212 turned on and off by setting DefaultDependencies= to yes (the default)
213 and no, while implicit dependencies are always in effect. See section
214 "Default Dependencies" in respective man pages for the effect of
215 enabling DefaultDependencies= in each unit types.
216 For example, target units will complement all configured dependencies
218 of type Wants= or Requires= with dependencies of type After= unless
219 DefaultDependencies=no is set in the specified units. See
220 systemd.target(5) for details. Note that this behavior can be turned
221 off by setting DefaultDependencies=no.
222
224 Unit files are loaded from a set of paths determined during
225 compilation, described in the two tables below. Unit files found in
226 directories listed earlier override files with the same name in
227 directories lower in the list.
228 When the variable $SYSTEMD_UNIT_PATH is set, the contents of this
230 variable overrides the unit load path. If $SYSTEMD_UNIT_PATH ends with
231 an empty component (":"), the usual unit load path will be appended to
232 the contents of the variable.
233 Table 1. Load path when running in system mode (--system).
235 ┌──────────────────────────────┬────────────────────────────┐
236 │Path │ Description │
237 ├──────────────────────────────┼────────────────────────────┤
238 │/etc/systemd/system.control │ Persistent and transient │
239 ├──────────────────────────────┤ configuration created │
240 │/run/systemd/system.control │ using the dbus API │
241 ├──────────────────────────────┼────────────────────────────┤
242 │/run/systemd/transient │ Dynamic configuration for │
243 │ │ transient units │
244 ├──────────────────────────────┼────────────────────────────┤
245 │/run/systemd/generator.early │ Generated units with high │
246 │ │ priority (see early-dir in │
247 │ │ systemd.generator(7)) │
248 ├──────────────────────────────┼────────────────────────────┤
249 │/etc/systemd/system │ Local configuration │
250 ├──────────────────────────────┼────────────────────────────┤
251 │/run/systemd/system │ Runtime units │
252 ├──────────────────────────────┼────────────────────────────┤
253 │/run/systemd/generator │ Generated units with │
254 │ │ medium priority (see │
255 │ │ normal-dir in │
256 │ │ systemd.generator(7)) │
257 ├──────────────────────────────┼────────────────────────────┤
258 │/usr/local/lib/systemd/system │ Units of installed │
259 ├──────────────────────────────┤ packages │
260 │/usr/lib/systemd/system │ │
261 ├──────────────────────────────┼────────────────────────────┤
262 │/run/systemd/generator.late │ Generated units with low │
263 │ │ priority (see late-dir in │
264 │ │ systemd.generator(7)) │
265 └──────────────────────────────┴────────────────────────────┘
266 Table 2. Load path when running in user mode (--user).
268 ┌────────────────────────────────────────┬────────────────────────────┐
269 │Path │ Description │
270 ├────────────────────────────────────────┼────────────────────────────┤
271 │$XDG_CONFIG_HOME/systemd/user.control │ Persistent and transient │
272 │or │ configuration created │
273 │~/.config/systemd/user.control │ using the dbus API │
274 ├────────────────────────────────────────┤ ($XDG_CONFIG_HOME is used │
275 │$XDG_RUNTIME_DIR/systemd/user.control │ if set, ~/.config │
276 │ │ otherwise) │
277 ├────────────────────────────────────────┼────────────────────────────┤
278 │/run/systemd/transient │ Dynamic configuration for │
279 │ │ transient units │
280 ├────────────────────────────────────────┼────────────────────────────┤
281 │/run/systemd/generator.early │ Generated units with high │
282 │ │ priority (see early-dir in │
283 │ │ systemd.generator(7)) │
284 ├────────────────────────────────────────┼────────────────────────────┤
285 │$XDG_CONFIG_HOME/systemd/user or │ User configuration │
286 │$HOME/.config/systemd/user │ ($XDG_CONFIG_HOME is used │
287 │ │ if set, ~/.config │
288 │ │ otherwise) │
289 ├────────────────────────────────────────┼────────────────────────────┤
290 │/etc/systemd/user │ Local configuration │
291 ├────────────────────────────────────────┼────────────────────────────┤
292 │$XDG_RUNTIME_DIR/systemd/user │ Runtime units (only used │
293 │ │ when $XDG_RUNTIME_DIR is │
294 │ │ set) │
295 ├────────────────────────────────────────┼────────────────────────────┤
296 │/run/systemd/user │ Runtime units │
297 ├────────────────────────────────────────┼────────────────────────────┤
298 │$XDG_RUNTIME_DIR/systemd/generator │ Generated units with │
299 │ │ medium priority (see │
300 │ │ normal-dir in │
301 │ │ systemd.generator(7)) │
302 ├────────────────────────────────────────┼────────────────────────────┤
303 │$XDG_DATA_HOME/systemd/user or │ Units of packages that │
304 │$HOME/.local/share/systemd/user │ have been installed in the │
305 │ │ home directory │
306 │ │ ($XDG_DATA_HOME is used if │
307 │ │ set, ~/.local/share │
308 │ │ otherwise) │
309 ├────────────────────────────────────────┼────────────────────────────┤
310 │$dir/systemd/user for each $dir in │ Additional locations for │
311 │$XDG_DATA_DIRS │ installed user units, one │
312 │ │ for each entry in │
313 │ │ $XDG_DATA_DIRS │
314 ├────────────────────────────────────────┼────────────────────────────┤
315 │/usr/local/lib/systemd/user │ Units of packages that │
316 ├────────────────────────────────────────┤ have been installed │
317 │/usr/lib/systemd/user │ system-wide │
318 ├────────────────────────────────────────┼────────────────────────────┤
319 │$XDG_RUNTIME_DIR/systemd/generator.late │ Generated units with low │
320 │ │ priority (see late-dir in │
321 │ │ systemd.generator(7)) │
322 └────────────────────────────────────────┴────────────────────────────┘
323 The set of load paths for the user manager instance may be augmented or
325 changed using various environment variables. And environment variables
326 may in turn be set using environment generators, see
327 systemd.environment-generator(7). In particular, $XDG_DATA_HOME and
328 $XDG_DATA_DIRS may be easily set using systemd-environment-d-
329 generator(8). Thus, directories listed here are just the defaults. To
330 see the actual list that would be used based on compilation options and
331 current environment use
332 systemd-analyze --user unit-paths
334 Moreover, additional units might be loaded into systemd ("linked") from
336 directories not on the unit load path. See the link command for
337 systemctl(1).
338
340 The system and service manager loads a unit's configuration
341 automatically when a unit is referenced for the first time. It will
342 automatically unload the unit configuration and state again when the
343 unit is not needed anymore ("garbage collection"). A unit may be
344 referenced through a number of different mechanisms:
345 1. Another loaded unit references it with a dependency such as After=,
347 Wants=, ...
348 2. The unit is currently starting, running, reloading or stopping.
350 3. The unit is currently in the failed state. (But see below.)
352 4. A job for the unit is pending.
354 5. The unit is pinned by an active IPC client program.
356 6. The unit is a special "perpetual" unit that is always active and
358 loaded. Examples for perpetual units are the root mount unit
359 -.mount or the scope unit init.scope that the service manager
360 itself lives in.
361 7. The unit has running processes associated with it.
363 The garbage collection logic may be altered with the CollectMode=
365 option, which allows configuration whether automatic unloading of units
366 that are in failed state is permissible, see below.
367 Note that when a unit's configuration and state is unloaded, all
369 execution results, such as exit codes, exit signals, resource
370 consumption and other statistics are lost, except for what is stored in
371 the log subsystem.
372 Use systemctl daemon-reload or an equivalent command to reload unit
374 configuration while the unit is already loaded. In this case all
375 configuration settings are flushed out and replaced with the new
376 configuration (which however might not be in effect immediately),
377 however all runtime state is saved/restored.
378
380 The unit file may include a [Unit] section, which carries generic
381 information about the unit that is not dependent on the type of unit:
382 Description=
384 A human readable name for the unit. This is used by systemd (and
385 other UIs) as the label for the unit, so this string should
386 identify the unit rather than describe it, despite the name.
387 "Apache2 Web Server" is a good example. Bad examples are
388 "high-performance light-weight HTTP server" (too generic) or
389 "Apache2" (too specific and meaningless for people who do not know
390 Apache). systemd will use this string as a noun in status messages
391 ("Starting description...", "Started description.", "Reached target
392 description.", "Failed to start description."), so it should be
393 capitalized, and should not be a full sentence or a phrase with a
394 continous verb. Bad examples include "exiting the container" or
395 "updating the database once per day.".
396 Documentation=
398 A space-separated list of URIs referencing documentation for this
399 unit or its configuration. Accepted are only URIs of the types
400 "http://", "https://", "file:", "info:", "man:". For more
401 information about the syntax of these URIs, see uri(7). The URIs
402 should be listed in order of relevance, starting with the most
403 relevant. It is a good idea to first reference documentation that
404 explains what the unit's purpose is, followed by how it is
405 configured, followed by any other related documentation. This
406 option may be specified more than once, in which case the specified
407 list of URIs is merged. If the empty string is assigned to this
408 option, the list is reset and all prior assignments will have no
409 effect.
410 Requires=
412 Configures requirement dependencies on other units. If this unit
413 gets activated, the units listed here will be activated as well. If
414 one of the other units fails to activate, and an ordering
415 dependency After= on the failing unit is set, this unit will not be
416 started. Besides, with or without specifying After=, this unit will
417 be stopped if one of the other units is explicitly stopped. This
418 option may be specified more than once or multiple space-separated
419 units may be specified in one option in which case requirement
420 dependencies for all listed names will be created. Note that
421 requirement dependencies do not influence the order in which
422 services are started or stopped. This has to be configured
423 independently with the After= or Before= options. If a unit
424 foo.service requires a unit bar.service as configured with
425 Requires= and no ordering is configured with After= or Before=,
426 then both units will be started simultaneously and without any
427 delay between them if foo.service is activated. Often, it is a
428 better choice to use Wants= instead of Requires= in order to
429 achieve a system that is more robust when dealing with failing
430 services.
431 Note that this dependency type does not imply that the other unit
433 always has to be in active state when this unit is running.
434 Specifically: failing condition checks (such as
435 ConditionPathExists=, ConditionPathIsSymbolicLink=, ... — see
436 below) do not cause the start job of a unit with a Requires=
437 dependency on it to fail. Also, some unit types may deactivate on
438 their own (for example, a service process may decide to exit
439 cleanly, or a device may be unplugged by the user), which is not
440 propagated to units having a Requires= dependency. Use the BindsTo=
441 dependency type together with After= to ensure that a unit may
442 never be in active state without a specific other unit also in
443 active state (see below).
444 Note that dependencies of this type may also be configured outside
446 of the unit configuration file by adding a symlink to a .requires/
447 directory accompanying the unit file. For details, see above.
448 Requisite=
450 Similar to Requires=. However, if the units listed here are not
451 started already, they will not be started and the starting of this
452 unit will fail immediately. Requisite= does not imply an ordering
453 dependency, even if both units are started in the same transaction.
454 Hence this setting should usually be combined with After=, to
455 ensure this unit is not started before the other unit.
456 When Requisite=b.service is used on a.service, this dependency will
458 show as RequisiteOf=a.service in property listing of b.service.
459 RequisiteOf= dependency cannot be specified directly.
460 Wants=
462 A weaker version of Requires=. Units listed in this option will be
463 started if the configuring unit is. However, if the listed units
464 fail to start or cannot be added to the transaction, this has no
465 impact on the validity of the transaction as a whole. This is the
466 recommended way to hook start-up of one unit to the start-up of
467 another unit.
468 Note that dependencies of this type may also be configured outside
470 of the unit configuration file by adding symlinks to a .wants/
471 directory accompanying the unit file. For details, see above.
472 BindsTo=
474 Configures requirement dependencies, very similar in style to
475 Requires=. However, this dependency type is stronger: in addition
476 to the effect of Requires= it declares that if the unit bound to is
477 stopped, this unit will be stopped too. This means a unit bound to
478 another unit that suddenly enters inactive state will be stopped
479 too. Units can suddenly, unexpectedly enter inactive state for
480 different reasons: the main process of a service unit might
481 terminate on its own choice, the backing device of a device unit
482 might be unplugged or the mount point of a mount unit might be
483 unmounted without involvement of the system and service manager.
484 When used in conjunction with After= on the same unit the behaviour
486 of BindsTo= is even stronger. In this case, the unit bound to
487 strictly has to be in active state for this unit to also be in
488 active state. This not only means a unit bound to another unit that
489 suddenly enters inactive state, but also one that is bound to
490 another unit that gets skipped due to a failed condition check
491 (such as ConditionPathExists=, ConditionPathIsSymbolicLink=, ... —
492 see below) will be stopped, should it be running. Hence, in many
493 cases it is best to combine BindsTo= with After=.
494 When BindsTo=b.service is used on a.service, this dependency will
496 show as BoundBy=a.service in property listing of b.service.
497 BoundBy= dependency cannot be specified directly.
498 PartOf=
500 Configures dependencies similar to Requires=, but limited to
501 stopping and restarting of units. When systemd stops or restarts
502 the units listed here, the action is propagated to this unit. Note
503 that this is a one-way dependency — changes to this unit do not
504 affect the listed units.
505 When PartOf=b.service is used on a.service, this dependency will
507 show as ConsistsOf=a.service in property listing of b.service.
508 ConsistsOf= dependency cannot be specified directly.
509 Conflicts=
511 A space-separated list of unit names. Configures negative
512 requirement dependencies. If a unit has a Conflicts= setting on
513 another unit, starting the former will stop the latter and vice
514 versa. Note that this setting is independent of and orthogonal to
515 the After= and Before= ordering dependencies.
516 If a unit A that conflicts with a unit B is scheduled to be started
518 at the same time as B, the transaction will either fail (in case
519 both are required parts of the transaction) or be modified to be
520 fixed (in case one or both jobs are not a required part of the
521 transaction). In the latter case, the job that is not required will
522 be removed, or in case both are not required, the unit that
523 conflicts will be started and the unit that is conflicted is
524 stopped.
525 Before=, After=
527 These two settings expect a space-separated list of unit names.
528 They configure ordering dependencies between units. If a unit
529 foo.service contains a setting Before=bar.service and both units
530 are being started, bar.service's start-up is delayed until
531 foo.service has finished starting up. Note that this setting is
532 independent of and orthogonal to the requirement dependencies as
533 configured by Requires=, Wants= or BindsTo=. It is a common pattern
534 to include a unit name in both the After= and Requires= options, in
535 which case the unit listed will be started before the unit that is
536 configured with these options. This option may be specified more
537 than once, in which case ordering dependencies for all listed names
538 are created. After= is the inverse of Before=, i.e. while After=
539 ensures that the configured unit is started after the listed unit
540 finished starting up, Before= ensures the opposite, that the
541 configured unit is fully started up before the listed unit is
542 started. Note that when two units with an ordering dependency
543 between them are shut down, the inverse of the start-up order is
544 applied. i.e. if a unit is configured with After= on another unit,
545 the former is stopped before the latter if both are shut down.
546 Given two units with any ordering dependency between them, if one
547 unit is shut down and the other is started up, the shutdown is
548 ordered before the start-up. It doesn't matter if the ordering
549 dependency is After= or Before=, in this case. It also doesn't
550 matter which of the two is shut down, as long as one is shut down
551 and the other is started up. The shutdown is ordered before the
552 start-up in all cases. If two units have no ordering dependencies
553 between them, they are shut down or started up simultaneously, and
554 no ordering takes place. It depends on the unit type when precisely
555 a unit has finished starting up. Most importantly, for service
556 units start-up is considered completed for the purpose of
557 Before=/After= when all its configured start-up commands have been
558 invoked and they either failed or reported start-up success.
559 OnFailure=
561 A space-separated list of one or more units that are activated when
562 this unit enters the "failed" state. A service unit using Restart=
563 enters the failed state only after the start limits are reached.
564 PropagatesReloadTo=, ReloadPropagatedFrom=
566 A space-separated list of one or more units where reload requests
567 on this unit will be propagated to, or reload requests on the other
568 unit will be propagated to this unit, respectively. Issuing a
569 reload request on a unit will automatically also enqueue a reload
570 request on all units that the reload request shall be propagated to
571 via these two settings.
572 JoinsNamespaceOf=
574 For units that start processes (such as service units), lists one
575 or more other units whose network and/or temporary file namespace
576 to join. This only applies to unit types which support the
577 PrivateNetwork= and PrivateTmp= directives (see systemd.exec(5) for
578 details). If a unit that has this setting set is started, its
579 processes will see the same /tmp, /var/tmp and network namespace as
580 one listed unit that is started. If multiple listed units are
581 already started, it is not defined which namespace is joined. Note
582 that this setting only has an effect if PrivateNetwork= and/or
583 PrivateTmp= is enabled for both the unit that joins the namespace
584 and the unit whose namespace is joined.
585 RequiresMountsFor=
587 Takes a space-separated list of absolute paths. Automatically adds
588 dependencies of type Requires= and After= for all mount units
589 required to access the specified path.
590 Mount points marked with noauto are not mounted automatically
592 through local-fs.target, but are still honored for the purposes of
593 this option, i.e. they will be pulled in by this unit.
594 OnFailureJobMode=
596 Takes a value of "fail", "replace", "replace-irreversibly",
597 "isolate", "flush", "ignore-dependencies" or "ignore-requirements".
598 Defaults to "replace". Specifies how the units listed in OnFailure=
599 will be enqueued. See systemctl(1)'s --job-mode= option for details
600 on the possible values. If this is set to "isolate", only a single
601 unit may be listed in OnFailure=..
602 IgnoreOnIsolate=
604 Takes a boolean argument. If true, this unit will not be stopped
605 when isolating another unit. Defaults to false for service, target,
606 socket, busname, timer, and path units, and true for slice, scope,
607 device, swap, mount, and automount units.
608 StopWhenUnneeded=
610 Takes a boolean argument. If true, this unit will be stopped when
611 it is no longer used. Note that, in order to minimize the work to
612 be executed, systemd will not stop units by default unless they are
613 conflicting with other units, or the user explicitly requested
614 their shut down. If this option is set, a unit will be
615 automatically cleaned up if no other active unit requires it.
616 Defaults to false.
617 RefuseManualStart=, RefuseManualStop=
619 Takes a boolean argument. If true, this unit can only be activated
620 or deactivated indirectly. In this case, explicit start-up or
621 termination requested by the user is denied, however if it is
622 started or stopped as a dependency of another unit, start-up or
623 termination will succeed. This is mostly a safety feature to ensure
624 that the user does not accidentally activate units that are not
625 intended to be activated explicitly, and not accidentally
626 deactivate units that are not intended to be deactivated. These
627 options default to false.
628 AllowIsolate=
630 Takes a boolean argument. If true, this unit may be used with the
631 systemctl isolate command. Otherwise, this will be refused. It
632 probably is a good idea to leave this disabled except for target
633 units that shall be used similar to runlevels in SysV init systems,
634 just as a precaution to avoid unusable system states. This option
635 defaults to false.
636 DefaultDependencies=
638 Takes a boolean argument. If true, (the default), a few default
639 dependencies will implicitly be created for the unit. The actual
640 dependencies created depend on the unit type. For example, for
641 service units, these dependencies ensure that the service is
642 started only after basic system initialization is completed and is
643 properly terminated on system shutdown. See the respective man
644 pages for details. Generally, only services involved with early
645 boot or late shutdown should set this option to false. It is highly
646 recommended to leave this option enabled for the majority of common
647 units. If set to false, this option does not disable all implicit
648 dependencies, just non-essential ones.
649 CollectMode=
651 Tweaks the "garbage collection" algorithm for this unit. Takes one
652 of inactive or inactive-or-failed. If set to inactive the unit will
653 be unloaded if it is in the inactive state and is not referenced by
654 clients, jobs or other units — however it is not unloaded if it is
655 in the failed state. In failed mode, failed units are not unloaded
656 until the user invoked systemctl reset-failed on them to reset the
657 failed state, or an equivalent command. This behaviour is altered
658 if this option is set to inactive-or-failed: in this case the unit
659 is unloaded even if the unit is in a failed state, and thus an
660 explicitly resetting of the failed state is not necessary. Note
661 that if this mode is used unit results (such as exit codes, exit
662 signals, consumed resources, ...) are flushed out immediately after
663 the unit completed, except for what is stored in the logging
664 subsystem. Defaults to inactive.
665 FailureAction=, SuccessAction=
667 Configure the action to take when the unit stops and enters a
668 failed state or inactive state. Takes one of none, reboot,
669 reboot-force, reboot-immediate, poweroff, poweroff-force,
670 poweroff-immediate, exit, and exit-force. In system mode, all
671 options are allowed. In user mode, only none, exit, and exit-force
672 are allowed. Both options default to none.
673 If none is set, no action will be triggered. reboot causes a
675 reboot following the normal shutdown procedure (i.e. equivalent to
676 systemctl reboot). reboot-force causes a forced reboot which will
677 terminate all processes forcibly but should cause no dirty file
678 systems on reboot (i.e. equivalent to systemctl reboot -f) and
679 reboot-immediate causes immediate execution of the reboot(2) system
680 call, which might result in data loss (i.e. equivalent to systemctl
681 reboot -ff). Similarly, poweroff, poweroff-force,
682 poweroff-immediate have the effect of powering down the system with
683 similar semantics. exit causes the manager to exit following the
684 normal shutdown procedure, and exit-force causes it terminate
685 without shutting down services. When exit or exit-force is used by
686 default the exit status of the main process of the unit (if this
687 applies) is returned from the service manager. However, this may be
688 overriden with FailureActionExitStatus=/SuccessActionExitStatus=,
689 see below.
690 FailureActionExitStatus=, SuccessActionExitStatus=
692 Controls the exit status to propagate back to an invoking container
693 manager (in case of a system service) or service manager (in case
694 of a user manager) when the FailureAction=/SuccessAction= are set
695 to exit or exit-force and the action is triggered. By default the
696 exit status of the main process of the triggering unit (if this
697 applies) is propagated. Takes a value in the range 0...255 or the
698 empty string to request default behaviour.
699 JobTimeoutSec=, JobRunningTimeoutSec=
701 When a job for this unit is queued, a timeout JobTimeoutSec= may be
702 configured. Similarly, JobRunningTimeoutSec= starts counting when
703 the queued job is actually started. If either time limit is
704 reached, the job will be cancelled, the unit however will not
705 change state or even enter the "failed" mode. This value defaults
706 to "infinity" (job timeouts disabled), except for device units
707 (JobRunningTimeoutSec= defaults to DefaultTimeoutStartSec=). NB:
708 this timeout is independent from any unit-specific timeout (for
709 example, the timeout set with TimeoutStartSec= in service units) as
710 the job timeout has no effect on the unit itself, only on the job
711 that might be pending for it. Or in other words: unit-specific
712 timeouts are useful to abort unit state changes, and revert them.
713 The job timeout set with this option however is useful to abort
714 only the job waiting for the unit state to change.
715 JobTimeoutAction=, JobTimeoutRebootArgument=
717 JobTimeoutAction= optionally configures an additional action to
718 take when the timeout is hit, see description of JobTimeoutSec= and
719 JobRunningTimeoutSec= above. It takes the same values as
720 StartLimitAction=. Defaults to none. JobTimeoutRebootArgument=
721 configures an optional reboot string to pass to the reboot(2)
722 system call.
723 StartLimitIntervalSec=interval, StartLimitBurst=burst
725 Configure unit start rate limiting. Units which are started more
726 than burst times within an interval time interval are not permitted
727 to start any more. Use StartLimitIntervalSec= to configure the
728 checking interval (defaults to DefaultStartLimitIntervalSec= in
729 manager configuration file, set it to 0 to disable any kind of rate
730 limiting). Use StartLimitBurst= to configure how many starts per
731 interval are allowed (defaults to DefaultStartLimitBurst= in
732 manager configuration file). These configuration options are
733 particularly useful in conjunction with the service setting
734 Restart= (see systemd.service(5)); however, they apply to all kinds
735 of starts (including manual), not just those triggered by the
736 Restart= logic. Note that units which are configured for Restart=
737 and which reach the start limit are not attempted to be restarted
738 anymore; however, they may still be restarted manually at a later
739 point, after the interval has passed. From this point on, the
740 restart logic is activated again. Note that systemctl reset-failed
741 will cause the restart rate counter for a service to be flushed,
742 which is useful if the administrator wants to manually start a unit
743 and the start limit interferes with that. Note that this
744 rate-limiting is enforced after any unit condition checks are
745 executed, and hence unit activations with failing conditions do not
746 count towards this rate limit. This setting does not apply to
747 slice, target, device, and scope units, since they are unit types
748 whose activation may either never fail, or may succeed only a
749 single time.
750 When a unit is unloaded due to the garbage collection logic (see
752 above) its rate limit counters are flushed out too. This means that
753 configuring start rate limiting for a unit that is not referenced
754 continuously has no effect.
755 StartLimitAction=
757 Configure an additional action to take if the rate limit configured
758 with StartLimitIntervalSec= and StartLimitBurst= is hit. Takes the
759 same values as the setting FailureAction=/SuccessAction= settings
760 and executes the same actions. If none is set, hitting the rate
761 limit will trigger no action besides that the start will not be
762 permitted. Defaults to none.
763 RebootArgument=
765 Configure the optional argument for the reboot(2) system call if
766 StartLimitAction= or FailureAction= is a reboot action. This works
767 just like the optional argument to systemctl reboot command.
768 ConditionArchitecture=, ConditionVirtualization=, ConditionHost=,
770 ConditionKernelCommandLine=, ConditionKernelVersion=,
771 ConditionSecurity=, ConditionCapability=, ConditionACPower=,
772 ConditionNeedsUpdate=, ConditionFirstBoot=, ConditionPathExists=,
773 ConditionPathExistsGlob=, ConditionPathIsDirectory=,
774 ConditionPathIsSymbolicLink=, ConditionPathIsMountPoint=,
775 ConditionPathIsReadWrite=, ConditionDirectoryNotEmpty=,
776 ConditionFileNotEmpty=, ConditionFileIsExecutable=, ConditionUser=,
777 ConditionGroup=, ConditionControlGroupController=
778 Before starting a unit, verify that the specified condition is
779 true. If it is not true, the starting of the unit will be (mostly
780 silently) skipped, however all ordering dependencies of it are
781 still respected. A failing condition will not result in the unit
782 being moved into the "failed" state. The condition is checked at
783 the time the queued start job is to be executed. Use condition
784 expressions in order to silently skip units that do not apply to
785 the local running system, for example because the kernel or runtime
786 environment doesn't require their functionality. Use the various
787 AssertArchitecture=, AssertVirtualization=, ... options for a
788 similar mechanism that causes the job to fail (instead of being
789 skipped) and results in logging about the failed check (instead of
790 being silently processed). For details about assertion conditions
791 see below.
792 ConditionArchitecture= may be used to check whether the system is
794 running on a specific architecture. Takes one of x86, x86-64, ppc,
795 ppc-le, ppc64, ppc64-le, ia64, parisc, parisc64, s390, s390x,
796 sparc, sparc64, mips, mips-le, mips64, mips64-le, alpha, arm,
797 arm-be, arm64, arm64-be, sh, sh64, m68k, tilegx, cris, arc, arc-be
798 to test against a specific architecture. The architecture is
799 determined from the information returned by uname(2) and is thus
800 subject to personality(2). Note that a Personality= setting in the
801 same unit file has no effect on this condition. A special
802 architecture name native is mapped to the architecture the system
803 manager itself is compiled for. The test may be negated by
804 prepending an exclamation mark.
805 ConditionVirtualization= may be used to check whether the system is
807 executed in a virtualized environment and optionally test whether
808 it is a specific implementation. Takes either boolean value to
809 check if being executed in any virtualized environment, or one of
810 vm and container to test against a generic type of virtualization
811 solution, or one of qemu, kvm, zvm, vmware, microsoft, oracle, xen,
812 bochs, uml, bhyve, qnx, openvz, lxc, lxc-libvirt, systemd-nspawn,
813 docker, rkt to test against a specific implementation, or
814 private-users to check whether we are running in a user namespace.
815 See systemd-detect-virt(1) for a full list of known virtualization
816 technologies and their identifiers. If multiple virtualization
817 technologies are nested, only the innermost is considered. The test
818 may be negated by prepending an exclamation mark.
819 ConditionHost= may be used to match against the hostname or machine
821 ID of the host. This either takes a hostname string (optionally
822 with shell style globs) which is tested against the locally set
823 hostname as returned by gethostname(2), or a machine ID formatted
824 as string (see machine-id(5)). The test may be negated by
825 prepending an exclamation mark.
826 ConditionKernelCommandLine= may be used to check whether a specific
828 kernel command line option is set (or if prefixed with the
829 exclamation mark unset). The argument must either be a single word,
830 or an assignment (i.e. two words, separated "="). In the former
831 case the kernel command line is searched for the word appearing as
832 is, or as left hand side of an assignment. In the latter case, the
833 exact assignment is looked for with right and left hand side
834 matching.
835 ConditionKernelVersion= may be used to check whether the kernel
837 version (as reported by uname -r) matches a certain expression (or
838 if prefixed with the exclamation mark does not match it). The
839 argument must be a single string. If the string starts with one of
840 "<", "<=", "=", ">=", ">" a relative version comparison is done,
841 otherwise the specified string is matched with shell-style globs.
842 Note that using the kernel version string is an unreliable way to
844 determine which features are supported by a kernel, because of the
845 widespread practice of backporting drivers, features, and fixes
846 from newer upstream kernels into older versions provided by
847 distributions. Hence, this check is inherently unportable and
848 should not be used for units which may be used on different
849 distributions.
850 ConditionSecurity= may be used to check whether the given security
852 technology is enabled on the system. Currently, the recognized
853 values are selinux, apparmor, tomoyo, ima, smack, audit and
854 uefi-secureboot. The test may be negated by prepending an
855 exclamation mark.
856 ConditionCapability= may be used to check whether the given
858 capability exists in the capability bounding set of the service
859 manager (i.e. this does not check whether capability is actually
860 available in the permitted or effective sets, see capabilities(7)
861 for details). Pass a capability name such as "CAP_MKNOD", possibly
862 prefixed with an exclamation mark to negate the check.
863 ConditionACPower= may be used to check whether the system has AC
865 power, or is exclusively battery powered at the time of activation
866 of the unit. This takes a boolean argument. If set to true, the
867 condition will hold only if at least one AC connector of the system
868 is connected to a power source, or if no AC connectors are known.
869 Conversely, if set to false, the condition will hold only if there
870 is at least one AC connector known and all AC connectors are
871 disconnected from a power source.
872 ConditionNeedsUpdate= takes one of /var or /etc as argument,
874 possibly prefixed with a "!" (for inverting the condition). This
875 condition may be used to conditionalize units on whether the
876 specified directory requires an update because /usr's modification
877 time is newer than the stamp file .updated in the specified
878 directory. This is useful to implement offline updates of the
879 vendor operating system resources in /usr that require updating of
880 /etc or /var on the next following boot. Units making use of this
881 condition should order themselves before systemd-update-
882 done.service(8), to make sure they run before the stamp file's
883 modification time gets reset indicating a completed update.
884 ConditionFirstBoot= takes a boolean argument. This condition may be
886 used to conditionalize units on whether the system is booting up
887 with an unpopulated /etc directory (specifically: an /etc with no
888 /etc/machine-id). This may be used to populate /etc on the first
889 boot after factory reset, or when a new system instance boots up
890 for the first time.
891 With ConditionPathExists= a file existence condition is checked
893 before a unit is started. If the specified absolute path name does
894 not exist, the condition will fail. If the absolute path name
895 passed to ConditionPathExists= is prefixed with an exclamation mark
896 ("!"), the test is negated, and the unit is only started if the
897 path does not exist.
898 ConditionPathExistsGlob= is similar to ConditionPathExists=, but
900 checks for the existence of at least one file or directory matching
901 the specified globbing pattern.
902 ConditionPathIsDirectory= is similar to ConditionPathExists= but
904 verifies whether a certain path exists and is a directory.
905 ConditionPathIsSymbolicLink= is similar to ConditionPathExists= but
907 verifies whether a certain path exists and is a symbolic link.
908 ConditionPathIsMountPoint= is similar to ConditionPathExists= but
910 verifies whether a certain path exists and is a mount point.
911 ConditionPathIsReadWrite= is similar to ConditionPathExists= but
913 verifies whether the underlying file system is readable and
914 writable (i.e. not mounted read-only).
915 ConditionDirectoryNotEmpty= is similar to ConditionPathExists= but
917 verifies whether a certain path exists and is a non-empty
918 directory.
919 ConditionFileNotEmpty= is similar to ConditionPathExists= but
921 verifies whether a certain path exists and refers to a regular file
922 with a non-zero size.
923 ConditionFileIsExecutable= is similar to ConditionPathExists= but
925 verifies whether a certain path exists, is a regular file and
926 marked executable.
927 ConditionUser= takes a numeric "UID", a UNIX user name, or the
929 special value "@system". This condition may be used to check
930 whether the service manager is running as the given user. The
931 special value "@system" can be used to check if the user id is
932 within the system user range. This option is not useful for system
933 services, as the system manager exclusively runs as the root user,
934 and thus the test result is constant.
935 ConditionGroup= is similar to ConditionUser= but verifies that the
937 service manager's real or effective group, or any of its auxiliary
938 groups match the specified group or GID. This setting does not have
939 a special value "@system".
940 ConditionControlGroupController= takes a cgroup controller name
942 (eg. cpu), verifying that it is available for use on the system.
943 For example, a particular controller may not be available if it was
944 disabled on the kernel command line with cgroup_disable=controller.
945 Multiple controllers may be passed with a space separating them; in
946 this case the condition will only pass if all listed controllers
947 are available for use. Controllers unknown to systemd are ignored.
948 Valid controllers are cpu, cpuacct, io, blkio, memory, devices, and
949 pids.
950 If multiple conditions are specified, the unit will be executed if
952 all of them apply (i.e. a logical AND is applied). Condition checks
953 can be prefixed with a pipe symbol (|) in which case a condition
954 becomes a triggering condition. If at least one triggering
955 condition is defined for a unit, then the unit will be executed if
956 at least one of the triggering conditions apply and all of the
957 non-triggering conditions. If you prefix an argument with the pipe
958 symbol and an exclamation mark, the pipe symbol must be passed
959 first, the exclamation second. Except for
960 ConditionPathIsSymbolicLink=, all path checks follow symlinks. If
961 any of these options is assigned the empty string, the list of
962 conditions is reset completely, all previous condition settings (of
963 any kind) will have no effect.
964 AssertArchitecture=, AssertVirtualization=, AssertHost=,
966 AssertKernelCommandLine=, AssertKernelVersion=, AssertSecurity=,
967 AssertCapability=, AssertACPower=, AssertNeedsUpdate=,
968 AssertFirstBoot=, AssertPathExists=, AssertPathExistsGlob=,
969 AssertPathIsDirectory=, AssertPathIsSymbolicLink=,
970 AssertPathIsMountPoint=, AssertPathIsReadWrite=,
971 AssertDirectoryNotEmpty=, AssertFileNotEmpty=, AssertFileIsExecutable=,
972 AssertUser=, AssertGroup=, AssertControlGroupController=
973 Similar to the ConditionArchitecture=, ConditionVirtualization=,
974 ..., condition settings described above, these settings add
975 assertion checks to the start-up of the unit. However, unlike the
976 conditions settings, any assertion setting that is not met results
977 in failure of the start job (which means this is logged loudly).
978 Note that hitting a configured assertion does not cause the unit to
979 enter the "failed" state (or in fact result in any state change of
980 the unit), it affects only the job queued for it. Use assertion
981 expressions for units that cannot operate when specific
982 requirements are not met, and when this is something the
983 administrator or user should look into.
984 Note that neither assertion nor condition expressions result in
986 unit state changes. Also note that both are checked at the time the
987 job is to be executed, i.e. long after depending jobs and it itself
988 were queued. Thus, neither condition nor assertion expressions are
989 suitable for conditionalizing unit dependencies.
990 SourcePath=
992 A path to a configuration file this unit has been generated from.
993 This is primarily useful for implementation of generator tools that
994 convert configuration from an external configuration file format
995 into native unit files. This functionality should not be used in
996 normal units.
997
999 Unit settings that create a relationship with a second unit usually
1000 show up in properties of both units, for example in systemctl show
1001 output. In some cases the name of the property is the same as the name
1002 of the configuration setting, but not always. This table lists the
1003 properties that are shown on two units which are connected through some
1004 dependency, and shows which property on "source" unit corresponds to
1005 which property on the "target" unit.
1006 Table 3. Forward and reverse unit properties
1008 ┌──────────────────────┬───────────────────────┬─────────────────────┐
1009 │"Forward" property │ "Reverse" property │ Where used │
1010 ├──────────────────────┼───────────────────────┼─────────────────────┤
1011 │Before= │ After= │ Both are unit file │
1012 ├──────────────────────┼───────────────────────┤ options │
1013 │After= │ Before= │ │
1014 ├──────────────────────┼───────────────────────┼─────────────────────┤
1015 │Requires= │ RequiredBy= │ A unit file option; │
1016 │ │ │ an option in the │
1017 │ │ │ [Install] section │
1018 ├──────────────────────┼───────────────────────┼─────────────────────┤
1019 │Wants= │ WantedBy= │ A unit file option; │
1020 │ │ │ an option in the │
1021 │ │ │ [Install] section │
1022 ├──────────────────────┼───────────────────────┼─────────────────────┤
1023 │PartOf= │ ConsistsOf= │ A unit file option; │
1024 │ │ │ an automatic │
1025 │ │ │ property │
1026 ├──────────────────────┼───────────────────────┼─────────────────────┤
1027 │BindsTo= │ BoundBy= │ A unit file option; │
1028 │ │ │ an automatic │
1029 │ │ │ property │
1030 ├──────────────────────┼───────────────────────┼─────────────────────┤
1031 │Requisite= │ RequisiteOf= │ A unit file option; │
1032 │ │ │ an automatic │
1033 │ │ │ property │
1034 ├──────────────────────┼───────────────────────┼─────────────────────┤
1035 │Triggers= │ TriggeredBy= │ Automatic │
1036 │ │ │ properties, see │
1037 │ │ │ notes below │
1038 ├──────────────────────┼───────────────────────┼─────────────────────┤
1039 │Conflicts= │ ConflictedBy= │ A unit file option; │
1040 │ │ │ an automatic │
1041 │ │ │ property │
1042 ├──────────────────────┼───────────────────────┼─────────────────────┤
1043 │PropagatesReloadTo= │ ReloadPropagatedFrom= │ Both are unit file │
1044 ├──────────────────────┼───────────────────────┤ options │
1045 │ReloadPropagatedFrom= │ PropagatesReloadTo= │ │
1046 ├──────────────────────┼───────────────────────┼─────────────────────┤
1047 │Following= │ n/a │ An automatic │
1048 │ │ │ property │
1049 └──────────────────────┴───────────────────────┴─────────────────────┘
1050 Note: WantedBy= and RequiredBy= are used in the [Install] section to
1052 create symlinks in .wants/ and .requires/ directories. They cannot be
1053 used directly as a unit configuration setting.
1054 Note: ConsistsOf=, BoundBy=, RequisiteOf=, ConflictedBy= are created
1056 implicitly along with their reverse and cannot be specified directly.
1057 Note: Triggers= is created implicitly between a socket, path unit, or
1059 an automount unit, and the unit they activate. By default a unit with
1060 the same name is triggered, but this can be overridden using Sockets=,
1061 Service=, and Unit= settings. See systemd.service(5),
1062 systemd.socket(5), systemd.path(5), and systemd.automount(5) for
1063 details. TriggersBy= is created implicitly on the triggered unit.
1064 Note: Following= is used to group device aliases and points to the
1066 "primary" device unit that systemd is using to track device state,
1067 usually corresponding to a sysfs path. It does not show up in the
1068 "target" unit.
1069
1071 Unit files may include an "[Install]" section, which carries
1072 installation information for the unit. This section is not interpreted
1073 by systemd(1) during runtime; it is used by the enable and disable
1074 commands of the systemctl(1) tool during installation of a unit.
1075 Alias=
1077 A space-separated list of additional names this unit shall be
1078 installed under. The names listed here must have the same suffix
1079 (i.e. type) as the unit filename. This option may be specified more
1080 than once, in which case all listed names are used. At installation
1081 time, systemctl enable will create symlinks from these names to the
1082 unit filename. Note that not all unit types support such alias
1083 names, and this setting is not supported for them. Specifically,
1084 mount, slice, swap, and automount units do not support aliasing.
1085 WantedBy=, RequiredBy=
1087 This option may be used more than once, or a space-separated list
1088 of unit names may be given. A symbolic link is created in the
1089 .wants/ or .requires/ directory of each of the listed units when
1090 this unit is installed by systemctl enable. This has the effect
1091 that a dependency of type Wants= or Requires= is added from the
1092 listed unit to the current unit. The primary result is that the
1093 current unit will be started when the listed unit is started. See
1094 the description of Wants= and Requires= in the [Unit] section for
1095 details.
1096 WantedBy=foo.service in a service bar.service is mostly equivalent
1098 to Alias=foo.service.wants/bar.service in the same file. In case of
1099 template units, systemctl enable must be called with an instance
1100 name, and this instance will be added to the .wants/ or .requires/
1101 list of the listed unit. E.g. WantedBy=getty.target in a service
1102 getty@.service will result in systemctl enable getty@tty2.service
1103 creating a getty.target.wants/getty@tty2.service link to
1104 getty@.service.
1105 Also=
1107 Additional units to install/deinstall when this unit is
1108 installed/deinstalled. If the user requests
1109 installation/deinstallation of a unit with this option configured,
1110 systemctl enable and systemctl disable will automatically
1111 install/uninstall units listed in this option as well.
1112 This option may be used more than once, or a space-separated list
1114 of unit names may be given.
1115 DefaultInstance=
1117 In template unit files, this specifies for which instance the unit
1118 shall be enabled if the template is enabled without any explicitly
1119 set instance. This option has no effect in non-template unit files.
1120 The specified string must be usable as instance identifier.
1121 The following specifiers are interpreted in the Install section: %n,
1123 %N, %p, %i, %j, %g, %G, %U, %u, %m, %H, %b, %v. For their meaning see
1124 the next section.
1125
1127 Many settings resolve specifiers which may be used to write generic
1128 unit files referring to runtime or unit parameters that are replaced
1129 when the unit files are loaded. Specifiers must be known and resolvable
1130 for the setting to be valid. The following specifiers are understood:
1131 Table 4. Specifiers available in unit files
1133 ┌──────────┬─────────────────────┬─────────────────────┐
1134 │Specifier │ Meaning │ Details │
1135 ├──────────┼─────────────────────┼─────────────────────┤
1136 │"%b" │ Boot ID │ The boot ID of the │
1137 │ │ │ running system, │
1138 │ │ │ formatted as │
1139 │ │ │ string. See │
1140 │ │ │ random(4) for more │
1141 │ │ │ information. │
1142 ├──────────┼─────────────────────┼─────────────────────┤
1143 │"%C" │ Cache directory │ This is either │
1144 │ │ root │ /var/cache (for the │
1145 │ │ │ system manager) or │
1146 │ │ │ the path │
1147 │ │ │ "$XDG_CACHE_HOME" │
1148 │ │ │ resolves to (for │
1149 │ │ │ user managers). │
1150 ├──────────┼─────────────────────┼─────────────────────┤
1151 │"%E" │ Configuration │ This is either /etc │
1152 │ │ directory root │ (for the system │
1153 │ │ │ manager) or the │
1154 │ │ │ path │
1155 │ │ │ "$XDG_CONFIG_HOME" │
1156 │ │ │ resolves to (for │
1157 │ │ │ user managers). │
1158 ├──────────┼─────────────────────┼─────────────────────┤
1159 │"%f" │ Unescaped filename │ This is either the │
1160 │ │ │ unescaped instance │
1161 │ │ │ name (if │
1162 │ │ │ applicable) with / │
1163 │ │ │ prepended (if │
1164 │ │ │ applicable), or the │
1165 │ │ │ unescaped prefix │
1166 │ │ │ name prepended with │
1167 │ │ │ /. This implements │
1168 │ │ │ unescaping │
1169 │ │ │ according to the │
1170 │ │ │ rules for escaping │
1171 │ │ │ absolute file │
1172 │ │ │ system paths │
1173 │ │ │ discussed above. │
1174 ├──────────┼─────────────────────┼─────────────────────┤
1175 │"%h" │ User home directory │ This is the home │
1176 │ │ │ directory of the │
1177 │ │ │ user running the │
1178 │ │ │ service manager │
1179 │ │ │ instance. In case │
1180 │ │ │ of the system │
1181 │ │ │ manager this │
1182 │ │ │ resolves to │
1183 │ │ │ "/root". │
1184 ├──────────┼─────────────────────┼─────────────────────┤
1185 │"%H" │ Host name │ The hostname of the │
1186 │ │ │ running system at │
1187 │ │ │ the point in time │
1188 │ │ │ the unit │
1189 │ │ │ configuration is │
1190 │ │ │ loaded. │
1191 ├──────────┼─────────────────────┼─────────────────────┤
1192 │"%i" │ Instance name │ For instantiated │
1193 │ │ │ units this is the │
1194 │ │ │ string between the │
1195 │ │ │ first "@" character │
1196 │ │ │ and the type │
1197 │ │ │ suffix. Empty for │
1198 │ │ │ non-instantiated │
1199 │ │ │ units. │
1200 ├──────────┼─────────────────────┼─────────────────────┤
1201 │"%I" │ Unescaped instance │ Same as "%i", but │
1202 │ │ name │ with escaping │
1203 │ │ │ undone. │
1204 ├──────────┼─────────────────────┼─────────────────────┤
1205 │"%j" │ Final component of │ This is the string │
1206 │ │ the prefix │ between the last │
1207 │ │ │ "-" and the end of │
1208 │ │ │ the prefix name. If │
1209 │ │ │ there is no "-", │
1210 │ │ │ this is the same as │
1211 │ │ │ "%p". │
1212 ├──────────┼─────────────────────┼─────────────────────┤
1213 │"%J" │ Unescaped final │ Same as "%j", but │
1214 │ │ component of the │ with escaping │
1215 │ │ prefix │ undone. │
1216 ├──────────┼─────────────────────┼─────────────────────┤
1217 │"%L" │ Log directory root │ This is either │
1218 │ │ │ /var/log (for the │
1219 │ │ │ system manager) or │
1220 │ │ │ the path │
1221 │ │ │ "$XDG_CONFIG_HOME" │
1222 │ │ │ resolves to with │
1223 │ │ │ /log appended (for │
1224 │ │ │ user managers). │
1225 ├──────────┼─────────────────────┼─────────────────────┤
1226 │"%m" │ Machine ID │ The machine ID of │
1227 │ │ │ the running system, │
1228 │ │ │ formatted as │
1229 │ │ │ string. See │
1230 │ │ │ machine-id(5) for │
1231 │ │ │ more information. │
1232 ├──────────┼─────────────────────┼─────────────────────┤
1233 │"%n" │ Full unit name │ │
1234 ├──────────┼─────────────────────┼─────────────────────┤
1235 │"%N" │ Full unit name │ Same as "%n", but │
1236 │ │ │ with the type │
1237 │ │ │ suffix removed. │
1238 ├──────────┼─────────────────────┼─────────────────────┤
1239 │"%p" │ Prefix name │ For instantiated │
1240 │ │ │ units, this refers │
1241 │ │ │ to the string │
1242 │ │ │ before the first │
1243 │ │ │ "@" character of │
1244 │ │ │ the unit name. For │
1245 │ │ │ non-instantiated │
1246 │ │ │ units, same as │
1247 │ │ │ "%N". │
1248 ├──────────┼─────────────────────┼─────────────────────┤
1249 │"%P" │ Unescaped prefix │ Same as "%p", but │
1250 │ │ name │ with escaping │
1251 │ │ │ undone. │
1252 ├──────────┼─────────────────────┼─────────────────────┤
1253 │"%s" │ User shell │ This is the shell │
1254 │ │ │ of the user running │
1255 │ │ │ the service manager │
1256 │ │ │ instance. In case │
1257 │ │ │ of the system │
1258 │ │ │ manager this │
1259 │ │ │ resolves to │
1260 │ │ │ "/bin/sh". │
1261 ├──────────┼─────────────────────┼─────────────────────┤
1262 │"%S" │ State directory │ This is either │
1263 │ │ root │ /var/lib (for the │
1264 │ │ │ system manager) or │
1265 │ │ │ the path │
1266 │ │ │ "$XDG_CONFIG_HOME" │
1267 │ │ │ resolves to (for │
1268 │ │ │ user managers). │
1269 ├──────────┼─────────────────────┼─────────────────────┤
1270 │"%t" │ Runtime directory │ This is either /run │
1271 │ │ root │ (for the system │
1272 │ │ │ manager) or the │
1273 │ │ │ path │
1274 │ │ │ "$XDG_RUNTIME_DIR" │
1275 │ │ │ resolves to (for │
1276 │ │ │ user managers). │
1277 ├──────────┼─────────────────────┼─────────────────────┤
1278 │"%T" │ Directory for │ This is either /tmp │
1279 │ │ temporary files │ or the path │
1280 │ │ │ "$TMPDIR", "$TEMP" │
1281 │ │ │ or "$TMP" are set │
1282 │ │ │ to. │
1283 ├──────────┼─────────────────────┼─────────────────────┤
1284 │"%g" │ User group │ This is the name of │
1285 │ │ │ the group running │
1286 │ │ │ the service manager │
1287 │ │ │ instance. In case │
1288 │ │ │ of the system │
1289 │ │ │ manager this │
1290 │ │ │ resolves to "root". │
1291 ├──────────┼─────────────────────┼─────────────────────┤
1292 │"%G" │ User GID │ This is the numeric │
1293 │ │ │ GID of the user │
1294 │ │ │ running the service │
1295 │ │ │ manager instance. │
1296 │ │ │ In case of the │
1297 │ │ │ system manager this │
1298 │ │ │ resolves to "0". │
1299 ├──────────┼─────────────────────┼─────────────────────┤
1300 │"%u" │ User name │ This is the name of │
1301 │ │ │ the user running │
1302 │ │ │ the service manager │
1303 │ │ │ instance. In case │
1304 │ │ │ of the system │
1305 │ │ │ manager this │
1306 │ │ │ resolves to "root". │
1307 ├──────────┼─────────────────────┼─────────────────────┤
1308 │"%U" │ User UID │ This is the numeric │
1309 │ │ │ UID of the user │
1310 │ │ │ running the service │
1311 │ │ │ manager instance. │
1312 │ │ │ In case of the │
1313 │ │ │ system manager this │
1314 │ │ │ resolves to "0". │
1315 ├──────────┼─────────────────────┼─────────────────────┤
1316 │"%v" │ Kernel release │ Identical to uname │
1317 │ │ │ -r output │
1318 ├──────────┼─────────────────────┼─────────────────────┤
1319 │"%V" │ Directory for │ This is either │
1320 │ │ larger and │ /var/tmp or the │
1321 │ │ persistent │ path "$TMPDIR", │
1322 │ │ temporary files │ "$TEMP" or "$TMP" │
1323 │ │ │ are set to. │
1324 ├──────────┼─────────────────────┼─────────────────────┤
1325 │"%%" │ Single percent sign │ Use "%%" in place │
1326 │ │ │ of "%" to specify a │
1327 │ │ │ single percent │
1328 │ │ │ sign. │
1329 └──────────┴─────────────────────┴─────────────────────┘
1330
1332 Example 1. Allowing units to be enabled
1333 The following snippet (highlighted) allows a unit (e.g. foo.service)
1335 to be enabled via systemctl enable:
1336 [Unit]
1338 Description=Foo
1339 [Service]
1341 ExecStart=/usr/sbin/foo-daemon
1342 [Install]
1344 WantedBy=multi-user.target
1345 After running systemctl enable, a symlink
1347 /etc/systemd/system/multi-user.target.wants/foo.service linking to the
1348 actual unit will be created. It tells systemd to pull in the unit when
1349 starting multi-user.target. The inverse systemctl disable will remove
1350 that symlink again.
1351 Example 2. Overriding vendor settings
1353 There are two methods of overriding vendor settings in unit files:
1355 copying the unit file from /usr/lib/systemd/system to
1356 /etc/systemd/system and modifying the chosen settings. Alternatively,
1357 one can create a directory named unit.d/ within /etc/systemd/system and
1358 place a drop-in file name.conf there that only changes the specific
1359 settings one is interested in. Note that multiple such drop-in files
1360 are read if present, processed in lexicographic order of their
1361 filename.
1362 The advantage of the first method is that one easily overrides the
1364 complete unit, the vendor unit is not parsed at all anymore. It has the
1365 disadvantage that improvements to the unit file by the vendor are not
1366 automatically incorporated on updates.
1367 The advantage of the second method is that one only overrides the
1369 settings one specifically wants, where updates to the unit by the
1370 vendor automatically apply. This has the disadvantage that some future
1371 updates by the vendor might be incompatible with the local changes.
1372 This also applies for user instances of systemd, but with different
1374 locations for the unit files. See the section on unit load paths for
1375 further details.
1376 Suppose there is a vendor-supplied unit
1378 /usr/lib/systemd/system/httpd.service with the following contents:
1379 [Unit]
1381 Description=Some HTTP server
1382 After=remote-fs.target sqldb.service
1383 Requires=sqldb.service
1384 AssertPathExists=/srv/webserver
1385 [Service]
1387 Type=notify
1388 ExecStart=/usr/sbin/some-fancy-httpd-server
1389 Nice=5
1390 [Install]
1392 WantedBy=multi-user.target
1393 Now one wants to change some settings as an administrator: firstly, in
1395 the local setup, /srv/webserver might not exist, because the HTTP
1396 server is configured to use /srv/www instead. Secondly, the local
1397 configuration makes the HTTP server also depend on a memory cache
1398 service, memcached.service, that should be pulled in (Requires=) and
1399 also be ordered appropriately (After=). Thirdly, in order to harden the
1400 service a bit more, the administrator would like to set the PrivateTmp=
1401 setting (see systemd.exec(5) for details). And lastly, the
1402 administrator would like to reset the niceness of the service to its
1403 default value of 0.
1404 The first possibility is to copy the unit file to
1406 /etc/systemd/system/httpd.service and change the chosen settings:
1407 [Unit]
1409 Description=Some HTTP server
1410 After=remote-fs.target sqldb.service memcached.service
1411 Requires=sqldb.service memcached.service
1412 AssertPathExists=/srv/www
1413 [Service]
1415 Type=notify
1416 ExecStart=/usr/sbin/some-fancy-httpd-server
1417 Nice=0
1418 PrivateTmp=yes
1419 [Install]
1421 WantedBy=multi-user.target
1422 Alternatively, the administrator could create a drop-in file
1424 /etc/systemd/system/httpd.service.d/local.conf with the following
1425 contents:
1426 [Unit]
1428 After=memcached.service
1429 Requires=memcached.service
1430 # Reset all assertions and then re-add the condition we want
1431 AssertPathExists=
1432 AssertPathExists=/srv/www
1433 [Service]
1435 Nice=0
1436 PrivateTmp=yes
1437 Note that for drop-in files, if one wants to remove entries from a
1439 setting that is parsed as a list (and is not a dependency), such as
1440 AssertPathExists= (or e.g. ExecStart= in service units), one needs to
1441 first clear the list before re-adding all entries except the one that
1442 is to be removed. Dependencies (After=, etc.) cannot be reset to an
1443 empty list, so dependencies can only be added in drop-ins. If you want
1444 to remove dependencies, you have to override the entire unit.
1445
1447 systemd(1), systemctl(1), systemd-system.conf(5), systemd.special(7),
1448 systemd.service(5), systemd.socket(5), systemd.device(5),
1449 systemd.mount(5), systemd.automount(5), systemd.swap(5),
1450 systemd.target(5), systemd.path(5), systemd.timer(5), systemd.scope(5),
1451 systemd.slice(5), systemd.time(7), systemd-analyze(1), capabilities(7),
1452 systemd.directives(7), uname(1)
1453
1455 1. Interface Stability Promise
1456 https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise
1457systemd 241 SYSTEMD.UNIT(5)