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