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/system.attached/*
20 /run/systemd/system/*
21 /run/systemd/system.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 $XDG_CONFIG_DIRS/systemd/user/*
34 /etc/systemd/user/*
35 $XDG_RUNTIME_DIR/systemd/user/*
36 /run/systemd/user/*
37 $XDG_RUNTIME_DIR/systemd/generator/*
38 $XDG_DATA_HOME/systemd/user/*
39 $XDG_DATA_DIRS/systemd/user/*
40 ...
41 /usr/lib/systemd/user/*
42 $XDG_RUNTIME_DIR/systemd/generator.late/*
43
45 A unit file is a plain text ini-style file that encodes information
46 about a service, a socket, a device, a mount point, an automount point,
47 a swap file or partition, a start-up target, a watched file system
48 path, a timer controlled and supervised by systemd(1), a resource
49 management slice or a group of externally created processes. See
50 systemd.syntax(7) for a general description of the syntax.
51 This man page lists the common configuration options of all the unit
53 types. These options need to be configured in the [Unit] or [Install]
54 sections of the unit files.
55 In addition to the generic [Unit] and [Install] sections described
57 here, each unit may have a type-specific section, e.g. [Service] for a
58 service unit. See the respective man pages for more information:
59 systemd.service(5), systemd.socket(5), systemd.device(5),
60 systemd.mount(5), systemd.automount(5), systemd.swap(5),
61 systemd.target(5), systemd.path(5), systemd.timer(5), systemd.slice(5),
62 systemd.scope(5).
63 Unit files are loaded from a set of paths determined during
65 compilation, described in the next section.
66 Valid unit names consist of a "name prefix" and a dot and a suffix
68 specifying the unit type. The "unit prefix" must consist of one or more
69 valid characters (ASCII letters, digits, ":", "-", "_", ".", and "\").
70 The total length of the unit name including the suffix must not exceed
71 256 characters. The type suffix must be one of ".service", ".socket",
72 ".device", ".mount", ".automount", ".swap", ".target", ".path",
73 ".timer", ".slice", or ".scope".
74 Units names can be parameterized by a single argument called the
76 "instance name". The unit is then constructed based on a "template
77 file" which serves as the definition of multiple services or other
78 units. A template unit must have a single "@" at the end of the name
79 (right before the type suffix). The name of the full unit is formed by
80 inserting the instance name between "@" and the unit type suffix. In
81 the unit file itself, the instance parameter may be referred to using
82 "%i" and other specifiers, see below.
83 Unit files may contain additional options on top of those listed here.
85 If systemd encounters an unknown option, it will write a warning log
86 message but continue loading the unit. If an option or section name is
87 prefixed with X-, it is ignored completely by systemd. Options within
88 an ignored section do not need the prefix. Applications may use this to
89 include additional information in the unit files. To access those
90 options, applications need to parse the unit files on their own.
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 a
96 symlink, so when systemd is asked through D-Bus to load
97 dbus-org.freedesktop.network1.service, it'll load
98 systemd-networkd.service. As another example, default.target — the
99 default system target started at boot — is commonly symlinked (aliased)
100 to either multi-user.target or graphical.target to select what is
101 started by default. Alias names may be used in commands like disable,
102 start, stop, status, and similar, and in all unit dependency
103 directives, including Wants=, Requires=, Before=, After=. Aliases
104 cannot be used with the preset command.
105 Aliases obey the following restrictions: a unit of a certain type
107 (".service", ".socket", ...) can only be aliased by a name with the
108 same type suffix. A plain unit (not a template or an instance), may
109 only be aliased by a plain name. A template instance may only be
110 aliased by another template instance, and the instance part must be
111 identical. A template may be aliased by another template (in which case
112 the alias applies to all instances of the template). As a special case,
113 a template instance (e.g. "alias@inst.service") may be a symlink to
114 different template (e.g. "template@inst.service"). In that case, just
115 this specific instance is aliased, while other instances of the
116 template (e.g. "alias@foo.service", "alias@bar.service") are not
117 aliased. Those rule preserve the requirement that the instance (if any)
118 is always uniquely defined for a given unit and all its aliases.
119 Unit files may specify aliases through the Alias= directive in the
121 [Install] section. When the unit is enabled, symlinks will be created
122 for those names, and removed when the unit is disabled. For example,
123 reboot.target specifies Alias=ctrl-alt-del.target, so when enabled, the
124 symlink /etc/systemd/system/ctrl-alt-del.service pointing to the
125 reboot.target file will be created, and when Ctrl+Alt+Del is invoked,
126 systemd will look for the ctrl-alt-del.service and execute
127 reboot.service. systemd does not look at the [Install] section at all
128 during normal operation, so any directives in that section only have an
129 effect through the symlinks created during enablement.
130 Along with a unit file foo.service, the directory foo.service.wants/
132 may exist. All unit files symlinked from such a directory are
133 implicitly added as dependencies of type Wants= to the unit. Similar
134 functionality exists for Requires= type dependencies as well, the
135 directory suffix is .requires/ in this case. This functionality is
136 useful to hook units into the start-up of other units, without having
137 to modify their unit files. For details about the semantics of Wants=,
138 see below. The preferred way to create symlinks in the .wants/ or
139 .requires/ directory of a unit file is by embedding the dependency in
140 [Install] section of the target unit, and creating the symlink in the
141 file system with the enable or preset commands of systemctl(1).
142 Along with a unit file foo.service, a "drop-in" directory
144 foo.service.d/ may exist. All files with the suffix ".conf" from this
145 directory will be merged in the alphanumeric order and parsed after the
146 main unit file itself has been parsed. This is useful to alter or add
147 configuration settings for a unit, without having to modify unit files.
148 Each drop-in file must contain appropriate section headers. For
149 instantiated units, this logic will first look for the instance ".d/"
150 subdirectory (e.g. "foo@bar.service.d/") and read its ".conf" files,
151 followed by the template ".d/" subdirectory (e.g. "foo@.service.d/")
152 and the ".conf" files there. Moreover for unit names containing dashes
153 ("-"), the set of directories generated by repeatedly truncating the
154 unit name after all dashes is searched too. Specifically, for a unit
155 name foo-bar-baz.service not only the regular drop-in directory
156 foo-bar-baz.service.d/ is searched but also both foo-bar-.service.d/
157 and foo-.service.d/. This is useful for defining common drop-ins for a
158 set of related units, whose names begin with a common prefix. This
159 scheme is particularly useful for mount, automount and slice units,
160 whose systematic naming structure is built around dashes as component
161 separators. Note that equally named drop-in files further down the
162 prefix hierarchy override those further up, i.e.
163 foo-bar-.service.d/10-override.conf overrides
164 foo-.service.d/10-override.conf.
165 In cases of unit aliases (described above), dropins for the aliased
167 name and all aliases are loaded. In the example of default.target
168 aliasing graphical.target, default.target.d/, default.target.wants/,
169 default.target.requires/, graphical.target.d/, graphical.target.wants/,
170 graphical.target.requires/ would all be read. For templates, dropins
171 for the template, any template aliases, the template instance, and all
172 alias instances are read. When just a specific template instance is
173 aliased, then the dropins for the target template, the target template
174 instance, and the alias template instance are read.
175 In addition to /etc/systemd/system, the drop-in ".d/" directories for
177 system services can be placed in /usr/lib/systemd/system or
178 /run/systemd/system directories. Drop-in files in /etc/ take precedence
179 over those in /run/ which in turn take precedence over those in
180 /usr/lib/. Drop-in files under any of these directories take precedence
181 over unit files wherever located. Multiple drop-in files with different
182 names are applied in lexicographic order, regardless of which of the
183 directories they reside in.
184 Units also support a top-level drop-in with type.d/, where type may be
186 e.g. "service" or "socket", that allows altering or adding to the
187 settings of all corresponding unit files on the system. The formatting
188 and precedence of applying drop-in configurations follow what is
189 defined above. Files in type.d/ have lower precedence compared to files
190 in name-specific override directories. The usual rules apply: multiple
191 drop-in files with different names are applied in lexicographic order,
192 regardless of which of the directories they reside in, so a file in
193 type.d/ applies to a unit only if there are no drop-ins or masks with
194 that name in directories with higher precedence. See Examples.
195 Note that while systemd offers a flexible dependency system between
197 units it is recommended to use this functionality only sparingly and
198 instead rely on techniques such as bus-based or socket-based activation
199 which make dependencies implicit, resulting in a both simpler and more
200 flexible system.
201 As mentioned above, a unit may be instantiated from a template file.
203 This allows creation of multiple units from a single configuration
204 file. If systemd looks for a unit configuration file, it will first
205 search for the literal unit name in the file system. If that yields no
206 success and the unit name contains an "@" character, systemd will look
207 for a unit template that shares the same name but with the instance
208 string (i.e. the part between the "@" character and the suffix)
209 removed. Example: if a service getty@tty3.service is requested and no
210 file by that name is found, systemd will look for getty@.service and
211 instantiate a service from that configuration file if it is found.
212 To refer to the instance string from within the configuration file you
214 may use the special "%i" specifier in many of the configuration
215 options. See below for details.
216 If a unit file is empty (i.e. has the file size 0) or is symlinked to
218 /dev/null, its configuration will not be loaded and it appears with a
219 load state of "masked", and cannot be activated. Use this as an
220 effective way to fully disable a unit, making it impossible to start it
221 even manually.
222 The unit file format is covered by the Interface Portability and
224 Stability Promise[1].
225
227 Sometimes it is useful to convert arbitrary strings into unit names. To
228 facilitate this, a method of string escaping is used, in order to map
229 strings containing arbitrary byte values (except NUL) into valid unit
230 names and their restricted character set. A common special case are
231 unit names that reflect paths to objects in the file system hierarchy.
232 Example: a device unit dev-sda.device refers to a device with the
233 device node /dev/sda in the file system.
234 The escaping algorithm operates as follows: given a string, any "/"
236 character is replaced by "-", and all other characters which are not
237 ASCII alphanumerics, ":", "_" or "." are replaced by C-style "\x2d"
238 escapes. In addition, "." is replaced with such a C-style escape when
239 it would appear as the first character in the escaped string.
240 When the input qualifies as absolute file system path, this algorithm
242 is extended slightly: the path to the root directory "/" is encoded as
243 single dash "-". In addition, any leading, trailing or duplicate "/"
244 characters are removed from the string before transformation. Example:
245 /foo//bar/baz/ becomes "foo-bar-baz".
246 This escaping is fully reversible, as long as it is known whether the
248 escaped string was a path (the unescaping results are different for
249 paths and non-path strings). The systemd-escape(1) command may be used
250 to apply and reverse escaping on arbitrary strings. Use systemd-escape
251 --path to escape path strings, and systemd-escape without --path
252 otherwise.
253
255 Implicit Dependencies
256 A number of unit dependencies are implicitly established, depending on
257 unit type and unit configuration. These implicit dependencies can make
258 unit configuration file cleaner. For the implicit dependencies in each
259 unit type, please refer to section "Implicit Dependencies" in
260 respective man pages.
261 For example, service units with Type=dbus automatically acquire
263 dependencies of type Requires= and After= on dbus.socket. See
264 systemd.service(5) for details.
265 Default Dependencies
267 Default dependencies are similar to implicit dependencies, but can be
268 turned on and off by setting DefaultDependencies= to yes (the default)
269 and no, while implicit dependencies are always in effect. See section
270 "Default Dependencies" in respective man pages for the effect of
271 enabling DefaultDependencies= in each unit types.
272 For example, target units will complement all configured dependencies
274 of type Wants= or Requires= with dependencies of type After= unless
275 DefaultDependencies=no is set in the specified units. See
276 systemd.target(5) for details. Note that this behavior can be turned
277 off by setting DefaultDependencies=no.
278
280 Unit files are loaded from a set of paths determined during
281 compilation, described in the two tables below. Unit files found in
282 directories listed earlier override files with the same name in
283 directories lower in the list.
284 When the variable $SYSTEMD_UNIT_PATH is set, the contents of this
286 variable overrides the unit load path. If $SYSTEMD_UNIT_PATH ends with
287 an empty component (":"), the usual unit load path will be appended to
288 the contents of the variable.
289 Table 1. Load path when running in system mode (--system).
291 ┌──────────────────────────────┬────────────────────────────┐
292 │Path │ Description │
293 ├──────────────────────────────┼────────────────────────────┤
294 │/etc/systemd/system.control │ Persistent and transient │
295 ├──────────────────────────────┤ configuration created │
296 │/run/systemd/system.control │ using the dbus API │
297 ├──────────────────────────────┼────────────────────────────┤
298 │/run/systemd/transient │ Dynamic configuration for │
299 │ │ transient units │
300 ├──────────────────────────────┼────────────────────────────┤
301 │/run/systemd/generator.early │ Generated units with high │
302 │ │ priority (see early-dir in │
303 │ │ systemd.generator(7)) │
304 ├──────────────────────────────┼────────────────────────────┤
305 │/etc/systemd/system │ System units created by │
306 │ │ the administrator │
307 ├──────────────────────────────┼────────────────────────────┤
308 │/run/systemd/system │ Runtime units │
309 ├──────────────────────────────┼────────────────────────────┤
310 │/run/systemd/generator │ Generated units with │
311 │ │ medium priority (see │
312 │ │ normal-dir in │
313 │ │ systemd.generator(7)) │
314 ├──────────────────────────────┼────────────────────────────┤
315 │/usr/local/lib/systemd/system │ System units installed by │
316 │ │ the administrator │
317 ├──────────────────────────────┼────────────────────────────┤
318 │/usr/lib/systemd/system │ System units installed by │
319 │ │ the distribution package │
320 │ │ manager │
321 ├──────────────────────────────┼────────────────────────────┤
322 │/run/systemd/generator.late │ Generated units with low │
323 │ │ priority (see late-dir in │
324 │ │ systemd.generator(7)) │
325 └──────────────────────────────┴────────────────────────────┘
326 Table 2. Load path when running in user mode (--user).
328 ┌────────────────────────────────────────┬────────────────────────────┐
329 │Path │ Description │
330 ├────────────────────────────────────────┼────────────────────────────┤
331 │$XDG_CONFIG_HOME/systemd/user.control │ Persistent and transient │
332 │or │ configuration created │
333 │~/.config/systemd/user.control │ using the dbus API │
334 ├────────────────────────────────────────┤ ($XDG_CONFIG_HOME is used │
335 │$XDG_RUNTIME_DIR/systemd/user.control │ if set, ~/.config │
336 │ │ otherwise) │
337 ├────────────────────────────────────────┼────────────────────────────┤
338 │/run/systemd/transient │ Dynamic configuration for │
339 │ │ transient units │
340 ├────────────────────────────────────────┼────────────────────────────┤
341 │/run/systemd/generator.early │ Generated units with high │
342 │ │ priority (see early-dir in │
343 │ │ systemd.generator(7)) │
344 ├────────────────────────────────────────┼────────────────────────────┤
345 │$XDG_CONFIG_HOME/systemd/user or │ User configuration │
346 │$HOME/.config/systemd/user │ ($XDG_CONFIG_HOME is used │
347 │ │ if set, ~/.config │
348 │ │ otherwise) │
349 ├────────────────────────────────────────┼────────────────────────────┤
350 │$XDG_CONFIG_DIRS/systemd/user or │ Additional configuration │
351 │/etc/xdg/systemd/user │ directories as specified │
352 │ │ by the XDG base directory │
353 │ │ specification │
354 │ │ ($XDG_CONFIG_DIRS is used │
355 │ │ if set, /etc/xdg │
356 │ │ otherwise) │
357 ├────────────────────────────────────────┼────────────────────────────┤
358 │/etc/systemd/user │ User units created by the │
359 │ │ administrator │
360 ├────────────────────────────────────────┼────────────────────────────┤
361 │$XDG_RUNTIME_DIR/systemd/user │ Runtime units (only used │
362 │ │ when $XDG_RUNTIME_DIR is │
363 │ │ set) │
364 ├────────────────────────────────────────┼────────────────────────────┤
365 │/run/systemd/user │ Runtime units │
366 ├────────────────────────────────────────┼────────────────────────────┤
367 │$XDG_RUNTIME_DIR/systemd/generator │ Generated units with │
368 │ │ medium priority (see │
369 │ │ normal-dir in │
370 │ │ systemd.generator(7)) │
371 ├────────────────────────────────────────┼────────────────────────────┤
372 │$XDG_DATA_HOME/systemd/user or │ Units of packages that │
373 │$HOME/.local/share/systemd/user │ have been installed in the │
374 │ │ home directory │
375 │ │ ($XDG_DATA_HOME is used if │
376 │ │ set, ~/.local/share │
377 │ │ otherwise) │
378 ├────────────────────────────────────────┼────────────────────────────┤
379 │$XDG_DATA_DIRS/systemd/user or │ Additional data │
380 │/usr/local/share/systemd/user and │ directories as specified │
381 │/usr/share/systemd/user │ by the XDG base directory │
382 │ │ specification │
383 │ │ ($XDG_DATA_DIRS is used if │
384 │ │ set, /usr/local/share and │
385 │ │ /usr/share otherwise) │
386 ├────────────────────────────────────────┼────────────────────────────┤
387 │$dir/systemd/user for each $dir in │ Additional locations for │
388 │$XDG_DATA_DIRS │ installed user units, one │
389 │ │ for each entry in │
390 │ │ $XDG_DATA_DIRS │
391 ├────────────────────────────────────────┼────────────────────────────┤
392 │/usr/local/lib/systemd/user │ User units installed by │
393 │ │ the administrator │
394 ├────────────────────────────────────────┼────────────────────────────┤
395 │/usr/lib/systemd/user │ User units installed by │
396 │ │ the distribution package │
397 │ │ manager │
398 ├────────────────────────────────────────┼────────────────────────────┤
399 │$XDG_RUNTIME_DIR/systemd/generator.late │ Generated units with low │
400 │ │ priority (see late-dir in │
401 │ │ systemd.generator(7)) │
402 └────────────────────────────────────────┴────────────────────────────┘
403 The set of load paths for the user manager instance may be augmented or
405 changed using various environment variables. And environment variables
406 may in turn be set using environment generators, see
407 systemd.environment-generator(7). In particular, $XDG_DATA_HOME and
408 $XDG_DATA_DIRS may be easily set using systemd-environment-d-
409 generator(8). Thus, directories listed here are just the defaults. To
410 see the actual list that would be used based on compilation options and
411 current environment use
412 systemd-analyze --user unit-paths
414 Moreover, additional units might be loaded into systemd from
416 directories not on the unit load path by creating a symlink pointing to
417 a unit file in the directories. You can use systemctl link for this
418 operation. See systemctl(1) for its usage and precaution.
419
421 The system and service manager loads a unit's configuration
422 automatically when a unit is referenced for the first time. It will
423 automatically unload the unit configuration and state again when the
424 unit is not needed anymore ("garbage collection"). A unit may be
425 referenced through a number of different mechanisms:
426 1. Another loaded unit references it with a dependency such as After=,
428 Wants=, ...
429 2. The unit is currently starting, running, reloading or stopping.
431 3. The unit is currently in the failed state. (But see below.)
433 4. A job for the unit is pending.
435 5. The unit is pinned by an active IPC client program.
437 6. The unit is a special "perpetual" unit that is always active and
439 loaded. Examples for perpetual units are the root mount unit
440 -.mount or the scope unit init.scope that the service manager
441 itself lives in.
442 7. The unit has running processes associated with it.
444 The garbage collection logic may be altered with the CollectMode=
446 option, which allows configuration whether automatic unloading of units
447 that are in failed state is permissible, see below.
448 Note that when a unit's configuration and state is unloaded, all
450 execution results, such as exit codes, exit signals, resource
451 consumption and other statistics are lost, except for what is stored in
452 the log subsystem.
453 Use systemctl daemon-reload or an equivalent command to reload unit
455 configuration while the unit is already loaded. In this case all
456 configuration settings are flushed out and replaced with the new
457 configuration (which however might not be in effect immediately),
458 however all runtime state is saved/restored.
459
461 The unit file may include a [Unit] section, which carries generic
462 information about the unit that is not dependent on the type of unit:
463 Description=
465 A short human readable title of the unit. This may be used by
466 systemd (and other UIs) as a user-visible label for the unit, so
467 this string should identify the unit rather than describe it,
468 despite the name. This string also shouldn't just repeat the unit
469 name. "Apache2 Web Server" is a good example. Bad examples are
470 "high-performance light-weight HTTP server" (too generic) or
471 "Apache2" (meaningless for people who do not know Apache,
472 duplicates the unit name). systemd may use this string as a noun
473 in status messages ("Starting description...", "Started
474 description.", "Reached target description.", "Failed to start
475 description."), so it should be capitalized, and should not be a
476 full sentence, or a phrase with a continuous verb. Bad examples
477 include "exiting the container" or "updating the database once per
478 day.".
479 Documentation=
481 A space-separated list of URIs referencing documentation for this
482 unit or its configuration. Accepted are only URIs of the types
483 "http://", "https://", "file:", "info:", "man:". For more
484 information about the syntax of these URIs, see uri(7). The URIs
485 should be listed in order of relevance, starting with the most
486 relevant. It is a good idea to first reference documentation that
487 explains what the unit's purpose is, followed by how it is
488 configured, followed by any other related documentation. This
489 option may be specified more than once, in which case the specified
490 list of URIs is merged. If the empty string is assigned to this
491 option, the list is reset and all prior assignments will have no
492 effect.
493 Wants=
495 Configures (weak) requirement dependencies on other units. This
496 option may be specified more than once or multiple space-separated
497 units may be specified in one option in which case dependencies for
498 all listed names will be created. Dependencies of this type may
499 also be configured outside of the unit configuration file by adding
500 a symlink to a .wants/ directory accompanying the unit file. For
501 details, see above.
502 Units listed in this option will be started if the configuring unit
504 is. However, if the listed units fail to start or cannot be added
505 to the transaction, this has no impact on the validity of the
506 transaction as a whole, and this unit will still be started. This
507 is the recommended way to hook the start-up of one unit to the
508 start-up of another unit.
509 Note that requirement dependencies do not influence the order in
511 which services are started or stopped. This has to be configured
512 independently with the After= or Before= options. If unit
513 foo.service pulls in unit bar.service as configured with Wants= and
514 no ordering is configured with After= or Before=, then both units
515 will be started simultaneously and without any delay between them
516 if foo.service is activated.
517 Requires=
519 Similar to Wants=, but declares a stronger requirement dependency.
520 Dependencies of this type may also be configured by adding a
521 symlink to a .requires/ directory accompanying the unit file.
522 If this unit gets activated, the units listed will be activated as
524 well. If one of the other units fails to activate, and an ordering
525 dependency After= on the failing unit is set, this unit will not be
526 started. Besides, with or without specifying After=, this unit will
527 be stopped if one of the other units is explicitly stopped.
528 Often, it is a better choice to use Wants= instead of Requires= in
530 order to achieve a system that is more robust when dealing with
531 failing services.
532 Note that this dependency type does not imply that the other unit
534 always has to be in active state when this unit is running.
535 Specifically: failing condition checks (such as
536 ConditionPathExists=, ConditionPathIsSymbolicLink=, ... — see
537 below) do not cause the start job of a unit with a Requires=
538 dependency on it to fail. Also, some unit types may deactivate on
539 their own (for example, a service process may decide to exit
540 cleanly, or a device may be unplugged by the user), which is not
541 propagated to units having a Requires= dependency. Use the BindsTo=
542 dependency type together with After= to ensure that a unit may
543 never be in active state without a specific other unit also in
544 active state (see below).
545 Requisite=
547 Similar to Requires=. However, if the units listed here are not
548 started already, they will not be started and the starting of this
549 unit will fail immediately. Requisite= does not imply an ordering
550 dependency, even if both units are started in the same transaction.
551 Hence this setting should usually be combined with After=, to
552 ensure this unit is not started before the other unit.
553 When Requisite=b.service is used on a.service, this dependency will
555 show as RequisiteOf=a.service in property listing of b.service.
556 RequisiteOf= dependency cannot be specified directly.
557 BindsTo=
559 Configures requirement dependencies, very similar in style to
560 Requires=. However, this dependency type is stronger: in addition
561 to the effect of Requires= it declares that if the unit bound to is
562 stopped, this unit will be stopped too. This means a unit bound to
563 another unit that suddenly enters inactive state will be stopped
564 too. Units can suddenly, unexpectedly enter inactive state for
565 different reasons: the main process of a service unit might
566 terminate on its own choice, the backing device of a device unit
567 might be unplugged or the mount point of a mount unit might be
568 unmounted without involvement of the system and service manager.
569 When used in conjunction with After= on the same unit the behaviour
571 of BindsTo= is even stronger. In this case, the unit bound to
572 strictly has to be in active state for this unit to also be in
573 active state. This not only means a unit bound to another unit that
574 suddenly enters inactive state, but also one that is bound to
575 another unit that gets skipped due to a failed condition check
576 (such as ConditionPathExists=, ConditionPathIsSymbolicLink=, ... —
577 see below) will be stopped, should it be running. Hence, in many
578 cases it is best to combine BindsTo= with After=.
579 When BindsTo=b.service is used on a.service, this dependency will
581 show as BoundBy=a.service in property listing of b.service.
582 BoundBy= dependency cannot be specified directly.
583 PartOf=
585 Configures dependencies similar to Requires=, but limited to
586 stopping and restarting of units. When systemd stops or restarts
587 the units listed here, the action is propagated to this unit. Note
588 that this is a one-way dependency — changes to this unit do not
589 affect the listed units.
590 When PartOf=b.service is used on a.service, this dependency will
592 show as ConsistsOf=a.service in property listing of b.service.
593 ConsistsOf= dependency cannot be specified directly.
594 Upholds=
596 Configures dependencies similar to Wants=, but as long as this unit
597 is up, all units listed in Upholds= are started whenever found to
598 be inactive or failed, and no job is queued for them. While a
599 Wants= dependency on another unit has a one-time effect when this
600 units started, a Upholds= dependency on it has a continuous effect,
601 constantly restarting the unit if necessary. This is an alternative
602 to the Restart= setting of service units, to ensure they are kept
603 running whatever happens.
604 When Upholds=b.service is used on a.service, this dependency will
606 show as UpheldBy=a.service in the property listing of b.service.
607 The UpheldBy= dependency cannot be specified directly.
608 Conflicts=
610 A space-separated list of unit names. Configures negative
611 requirement dependencies. If a unit has a Conflicts= setting on
612 another unit, starting the former will stop the latter and vice
613 versa.
614 Note that this setting does not imply an ordering dependency,
616 similarly to the Wants= and Requires= dependencies described above.
617 This means that to ensure that the conflicting unit is stopped
618 before the other unit is started, an After= or Before= dependency
619 must be declared. It doesn't matter which of the two ordering
620 dependencies is used, because stop jobs are always ordered before
621 start jobs, see the discussion in Before=/After= below.
622 If unit A that conflicts with unit B is scheduled to be started at
624 the same time as B, the transaction will either fail (in case both
625 are required parts of the transaction) or be modified to be fixed
626 (in case one or both jobs are not a required part of the
627 transaction). In the latter case, the job that is not required will
628 be removed, or in case both are not required, the unit that
629 conflicts will be started and the unit that is conflicted is
630 stopped.
631 Before=, After=
633 These two settings expect a space-separated list of unit names.
634 They may be specified more than once, in which case dependencies
635 for all listed names are created.
636 Those two settings configure ordering dependencies between units.
638 If unit foo.service contains the setting Before=bar.service and
639 both units are being started, bar.service's start-up is delayed
640 until foo.service has finished starting up. After= is the inverse
641 of Before=, i.e. while Before= ensures that the configured unit is
642 started before the listed unit begins starting up, After= ensures
643 the opposite, that the listed unit is fully started up before the
644 configured unit is started.
645 When two units with an ordering dependency between them are shut
647 down, the inverse of the start-up order is applied. I.e. if a unit
648 is configured with After= on another unit, the former is stopped
649 before the latter if both are shut down. Given two units with any
650 ordering dependency between them, if one unit is shut down and the
651 other is started up, the shutdown is ordered before the start-up.
652 It doesn't matter if the ordering dependency is After= or Before=,
653 in this case. It also doesn't matter which of the two is shut down,
654 as long as one is shut down and the other is started up; the
655 shutdown is ordered before the start-up in all cases. If two units
656 have no ordering dependencies between them, they are shut down or
657 started up simultaneously, and no ordering takes place. It depends
658 on the unit type when precisely a unit has finished starting up.
659 Most importantly, for service units start-up is considered
660 completed for the purpose of Before=/After= when all its configured
661 start-up commands have been invoked and they either failed or
662 reported start-up success. Note that this does includes
663 ExecStartPost= (or ExecStopPost= for the shutdown case).
664 Note that those settings are independent of and orthogonal to the
666 requirement dependencies as configured by Requires=, Wants=,
667 Requisite=, or BindsTo=. It is a common pattern to include a unit
668 name in both the After= and Wants= options, in which case the unit
669 listed will be started before the unit that is configured with
670 these options.
671 Note that Before= dependencies on device units have no effect and
673 are not supported. Devices generally become available as a result
674 of an external hotplug event, and systemd creates the corresponding
675 device unit without delay.
676 OnFailure=
678 A space-separated list of one or more units that are activated when
679 this unit enters the "failed" state. A service unit using Restart=
680 enters the failed state only after the start limits are reached.
681 OnSuccess=
683 A space-separated list of one or more units that are activated when
684 this unit enters the "inactive" state.
685 PropagatesReloadTo=, ReloadPropagatedFrom=
687 A space-separated list of one or more units to which reload
688 requests from this unit shall be propagated to, or units from which
689 reload requests shall be propagated to this unit, respectively.
690 Issuing a reload request on a unit will automatically also enqueue
691 reload requests on all units that are linked to it using these two
692 settings.
693 PropagatesStopTo=, StopPropagatedFrom=
695 A space-separated list of one or more units to which stop requests
696 from this unit shall be propagated to, or units from which stop
697 requests shall be propagated to this unit, respectively. Issuing a
698 stop request on a unit will automatically also enqueue stop
699 requests on all units that are linked to it using these two
700 settings.
701 JoinsNamespaceOf=
703 For units that start processes (such as service units), lists one
704 or more other units whose network and/or temporary file namespace
705 to join. This only applies to unit types which support the
706 PrivateNetwork=, NetworkNamespacePath=, PrivateIPC=,
707 IPCNamespacePath=, and PrivateTmp= directives (see systemd.exec(5)
708 for details). If a unit that has this setting set is started, its
709 processes will see the same /tmp/, /var/tmp/, IPC namespace and
710 network namespace as one listed unit that is started. If multiple
711 listed units are already started, it is not defined which namespace
712 is joined. Note that this setting only has an effect if
713 PrivateNetwork=/NetworkNamespacePath=,
714 PrivateIPC=/IPCNamespacePath= and/or PrivateTmp= is enabled for
715 both the unit that joins the namespace and the unit whose namespace
716 is joined.
717 RequiresMountsFor=
719 Takes a space-separated list of absolute paths. Automatically adds
720 dependencies of type Requires= and After= for all mount units
721 required to access the specified path.
722 Mount points marked with noauto are not mounted automatically
724 through local-fs.target, but are still honored for the purposes of
725 this option, i.e. they will be pulled in by this unit.
726 OnFailureJobMode=
728 Takes a value of "fail", "replace", "replace-irreversibly",
729 "isolate", "flush", "ignore-dependencies" or "ignore-requirements".
730 Defaults to "replace". Specifies how the units listed in OnFailure=
731 will be enqueued. See systemctl(1)'s --job-mode= option for details
732 on the possible values. If this is set to "isolate", only a single
733 unit may be listed in OnFailure=.
734 IgnoreOnIsolate=
736 Takes a boolean argument. If true, this unit will not be stopped
737 when isolating another unit. Defaults to false for service, target,
738 socket, timer, and path units, and true for slice, scope, device,
739 swap, mount, and automount units.
740 StopWhenUnneeded=
742 Takes a boolean argument. If true, this unit will be stopped when
743 it is no longer used. Note that, in order to minimize the work to
744 be executed, systemd will not stop units by default unless they are
745 conflicting with other units, or the user explicitly requested
746 their shut down. If this option is set, a unit will be
747 automatically cleaned up if no other active unit requires it.
748 Defaults to false.
749 RefuseManualStart=, RefuseManualStop=
751 Takes a boolean argument. If true, this unit can only be activated
752 or deactivated indirectly. In this case, explicit start-up or
753 termination requested by the user is denied, however if it is
754 started or stopped as a dependency of another unit, start-up or
755 termination will succeed. This is mostly a safety feature to ensure
756 that the user does not accidentally activate units that are not
757 intended to be activated explicitly, and not accidentally
758 deactivate units that are not intended to be deactivated. These
759 options default to false.
760 AllowIsolate=
762 Takes a boolean argument. If true, this unit may be used with the
763 systemctl isolate command. Otherwise, this will be refused. It
764 probably is a good idea to leave this disabled except for target
765 units that shall be used similar to runlevels in SysV init systems,
766 just as a precaution to avoid unusable system states. This option
767 defaults to false.
768 DefaultDependencies=
770 Takes a boolean argument. If yes, (the default), a few default
771 dependencies will implicitly be created for the unit. The actual
772 dependencies created depend on the unit type. For example, for
773 service units, these dependencies ensure that the service is
774 started only after basic system initialization is completed and is
775 properly terminated on system shutdown. See the respective man
776 pages for details. Generally, only services involved with early
777 boot or late shutdown should set this option to no. It is highly
778 recommended to leave this option enabled for the majority of common
779 units. If set to no, this option does not disable all implicit
780 dependencies, just non-essential ones.
781 CollectMode=
783 Tweaks the "garbage collection" algorithm for this unit. Takes one
784 of inactive or inactive-or-failed. If set to inactive the unit will
785 be unloaded if it is in the inactive state and is not referenced by
786 clients, jobs or other units — however it is not unloaded if it is
787 in the failed state. In failed mode, failed units are not unloaded
788 until the user invoked systemctl reset-failed on them to reset the
789 failed state, or an equivalent command. This behaviour is altered
790 if this option is set to inactive-or-failed: in this case the unit
791 is unloaded even if the unit is in a failed state, and thus an
792 explicitly resetting of the failed state is not necessary. Note
793 that if this mode is used unit results (such as exit codes, exit
794 signals, consumed resources, ...) are flushed out immediately after
795 the unit completed, except for what is stored in the logging
796 subsystem. Defaults to inactive.
797 FailureAction=, SuccessAction=
799 Configure the action to take when the unit stops and enters a
800 failed state or inactive state. Takes one of none, reboot,
801 reboot-force, reboot-immediate, poweroff, poweroff-force,
802 poweroff-immediate, exit, and exit-force. In system mode, all
803 options are allowed. In user mode, only none, exit, and exit-force
804 are allowed. Both options default to none.
805 If none is set, no action will be triggered. reboot causes a
807 reboot following the normal shutdown procedure (i.e. equivalent to
808 systemctl reboot). reboot-force causes a forced reboot which will
809 terminate all processes forcibly but should cause no dirty file
810 systems on reboot (i.e. equivalent to systemctl reboot -f) and
811 reboot-immediate causes immediate execution of the reboot(2) system
812 call, which might result in data loss (i.e. equivalent to systemctl
813 reboot -ff). Similarly, poweroff, poweroff-force,
814 poweroff-immediate have the effect of powering down the system with
815 similar semantics. exit causes the manager to exit following the
816 normal shutdown procedure, and exit-force causes it terminate
817 without shutting down services. When exit or exit-force is used by
818 default the exit status of the main process of the unit (if this
819 applies) is returned from the service manager. However, this may be
820 overridden with FailureActionExitStatus=/SuccessActionExitStatus=,
821 see below.
822 FailureActionExitStatus=, SuccessActionExitStatus=
824 Controls the exit status to propagate back to an invoking container
825 manager (in case of a system service) or service manager (in case
826 of a user manager) when the FailureAction=/SuccessAction= are set
827 to exit or exit-force and the action is triggered. By default the
828 exit status of the main process of the triggering unit (if this
829 applies) is propagated. Takes a value in the range 0...255 or the
830 empty string to request default behaviour.
831 JobTimeoutSec=, JobRunningTimeoutSec=
833 JobTimeoutSec= specifies a timeout for the whole job that starts
834 running when the job is queued. JobRunningTimeoutSec= specifies a
835 timeout that starts running when the queued job is actually
836 started. If either limit is reached, the job will be cancelled, the
837 unit however will not change state or even enter the "failed" mode.
838 Both settings take a time span with the default unit of seconds,
840 but other units may be specified, see systemd.time(5). The default
841 is "infinity" (job timeouts disabled), except for device units
842 where JobRunningTimeoutSec= defaults to DefaultTimeoutStartSec=.
843 Note: these timeouts are independent from any unit-specific
845 timeouts (for example, the timeout set with TimeoutStartSec= in
846 service units). The job timeout has no effect on the unit itself.
847 Or in other words: unit-specific timeouts are useful to abort unit
848 state changes, and revert them. The job timeout set with this
849 option however is useful to abort only the job waiting for the unit
850 state to change.
851 JobTimeoutAction=, JobTimeoutRebootArgument=
853 JobTimeoutAction= optionally configures an additional action to
854 take when the timeout is hit, see description of JobTimeoutSec= and
855 JobRunningTimeoutSec= above. It takes the same values as
856 StartLimitAction=. Defaults to none.
857 JobTimeoutRebootArgument= configures an optional reboot string to
859 pass to the reboot(2) system call.
860 StartLimitIntervalSec=interval, StartLimitBurst=burst
862 Configure unit start rate limiting. Units which are started more
863 than burst times within an interval time span are not permitted to
864 start any more. Use StartLimitIntervalSec= to configure the
865 checking interval and StartLimitBurst= to configure how many starts
866 per interval are allowed.
867 interval is a time span with the default unit of seconds, but other
869 units may be specified, see systemd.time(5). Defaults to
870 DefaultStartLimitIntervalSec= in manager configuration file, and
871 may be set to 0 to disable any kind of rate limiting. burst is a
872 number and defaults to DefaultStartLimitBurst= in manager
873 configuration file.
874 These configuration options are particularly useful in conjunction
876 with the service setting Restart= (see systemd.service(5));
877 however, they apply to all kinds of starts (including manual), not
878 just those triggered by the Restart= logic.
879 Note that units which are configured for Restart=, and which reach
881 the start limit are not attempted to be restarted anymore; however,
882 they may still be restarted manually or from a timer or socket at a
883 later point, after the interval has passed. From that point on, the
884 restart logic is activated again. systemctl reset-failed will
885 cause the restart rate counter for a service to be flushed, which
886 is useful if the administrator wants to manually start a unit and
887 the start limit interferes with that. Rate-limiting is enforced
888 after any unit condition checks are executed, and hence unit
889 activations with failing conditions do not count towards the rate
890 limit.
891 When a unit is unloaded due to the garbage collection logic (see
893 above) its rate limit counters are flushed out too. This means that
894 configuring start rate limiting for a unit that is not referenced
895 continuously has no effect.
896 This setting does not apply to slice, target, device, and scope
898 units, since they are unit types whose activation may either never
899 fail, or may succeed only a single time.
900 StartLimitAction=
902 Configure an additional action to take if the rate limit configured
903 with StartLimitIntervalSec= and StartLimitBurst= is hit. Takes the
904 same values as the FailureAction=/SuccessAction= settings. If none
905 is set, hitting the rate limit will trigger no action except that
906 the start will not be permitted. Defaults to none.
907 RebootArgument=
909 Configure the optional argument for the reboot(2) system call if
910 StartLimitAction= or FailureAction= is a reboot action. This works
911 just like the optional argument to systemctl reboot command.
912 SourcePath=
914 A path to a configuration file this unit has been generated from.
915 This is primarily useful for implementation of generator tools that
916 convert configuration from an external configuration file format
917 into native unit files. This functionality should not be used in
918 normal units.
919 Conditions and Asserts
921 Unit files may also include a number of Condition...= and Assert...=
922 settings. Before the unit is started, systemd will verify that the
923 specified conditions and asserts are true. If not, the starting of the
924 unit will be (mostly silently) skipped (in case of conditions), or
925 aborted with an error message (in case of asserts). Failing conditions
926 or asserts will not result in the unit being moved into the "failed"
927 state. The conditions and asserts are checked at the time the queued
928 start job is to be executed. The ordering dependencies are still
929 respected, so other units are still pulled in and ordered as if this
930 unit was successfully activated, and the conditions and asserts are
931 executed the precise moment the unit would normally start and thus can
932 validate system state after the units ordered before completed
933 initialization. Use condition expressions for skipping units that do
934 not apply to the local system, for example because the kernel or
935 runtime environment doesn't require their functionality.
936 If multiple conditions are specified, the unit will be executed if all
938 of them apply (i.e. a logical AND is applied). Condition checks can use
939 a pipe symbol ("|") after the equals sign ("Condition...=|..."), which
940 causes the condition to become a triggering condition. If at least one
941 triggering condition is defined for a unit, then the unit will be
942 started if at least one of the triggering conditions of the unit
943 applies and all of the regular (i.e. non-triggering) conditions apply.
944 If you prefix an argument with the pipe symbol and an exclamation mark,
945 the pipe symbol must be passed first, the exclamation second. If any of
946 these options is assigned the empty string, the list of conditions is
947 reset completely, all previous condition settings (of any kind) will
948 have no effect.
949 The AssertArchitecture=, AssertVirtualization=, ... options are similar
951 to conditions but cause the start job to fail (instead of being
952 skipped). The failed check is logged. Units with failed conditions are
953 considered to be in a clean state and will be garbage collected if they
954 are not referenced. This means that when queried, the condition failure
955 may or may not show up in the state of the unit.
956 Note that neither assertion nor condition expressions result in unit
958 state changes. Also note that both are checked at the time the job is
959 to be executed, i.e. long after depending jobs and it itself were
960 queued. Thus, neither condition nor assertion expressions are suitable
961 for conditionalizing unit dependencies.
962 The condition verb of systemd-analyze(1) can be used to test condition
964 and assert expressions.
965 Except for ConditionPathIsSymbolicLink=, all path checks follow
967 symlinks.
968 ConditionArchitecture=
970 Check whether the system is running on a specific architecture.
971 Takes one of "x86", "x86-64", "ppc", "ppc-le", "ppc64", "ppc64-le",
972 "ia64", "parisc", "parisc64", "s390", "s390x", "sparc", "sparc64",
973 "mips", "mips-le", "mips64", "mips64-le", "alpha", "arm", "arm-be",
974 "arm64", "arm64-be", "sh", "sh64", "m68k", "tilegx", "cris", "arc",
975 "arc-be", or "native".
976 The architecture is determined from the information returned by
978 uname(2) and is thus subject to personality(2). Note that a
979 Personality= setting in the same unit file has no effect on this
980 condition. A special architecture name "native" is mapped to the
981 architecture the system manager itself is compiled for. The test
982 may be negated by prepending an exclamation mark.
983 ConditionFirmware=
985 Check whether the system's firmware is of a certain type. Possible
986 values are: "uefi" (for systems with EFI), "device-tree" (for
987 systems with a device tree) and "device-tree-compatible(xyz)" (for
988 systems with a device tree that is compatible to "xyz").
989 ConditionVirtualization=
991 Check whether the system is executed in a virtualized environment
992 and optionally test whether it is a specific implementation. Takes
993 either boolean value to check if being executed in any virtualized
994 environment, or one of "vm" and "container" to test against a
995 generic type of virtualization solution, or one of "qemu", "kvm",
996 "amazon", "zvm", "vmware", "microsoft", "oracle", "powervm", "xen",
997 "bochs", "uml", "bhyve", "qnx", "openvz", "lxc", "lxc-libvirt",
998 "systemd-nspawn", "docker", "podman", "rkt", "wsl", "proot",
999 "pouch", "acrn" to test against a specific implementation, or
1000 "private-users" to check whether we are running in a user
1001 namespace. See systemd-detect-virt(1) for a full list of known
1002 virtualization technologies and their identifiers. If multiple
1003 virtualization technologies are nested, only the innermost is
1004 considered. The test may be negated by prepending an exclamation
1005 mark.
1006 ConditionHost=
1008 ConditionHost= may be used to match against the hostname or machine
1009 ID of the host. This either takes a hostname string (optionally
1010 with shell style globs) which is tested against the locally set
1011 hostname as returned by gethostname(2), or a machine ID formatted
1012 as string (see machine-id(5)). The test may be negated by
1013 prepending an exclamation mark.
1014 ConditionKernelCommandLine=
1016 ConditionKernelCommandLine= may be used to check whether a specific
1017 kernel command line option is set (or if prefixed with the
1018 exclamation mark — unset). The argument must either be a single
1019 word, or an assignment (i.e. two words, separated by "="). In the
1020 former case the kernel command line is searched for the word
1021 appearing as is, or as left hand side of an assignment. In the
1022 latter case, the exact assignment is looked for with right and left
1023 hand side matching. This operates on the kernel command line
1024 communicated to userspace via /proc/cmdline, except when the
1025 service manager is invoked as payload of a container manager, in
1026 which case the command line of PID 1 is used instead (i.e.
1027 /proc/1/cmdline).
1028 ConditionKernelVersion=
1030 ConditionKernelVersion= may be used to check whether the kernel
1031 version (as reported by uname -r) matches a certain expression (or
1032 if prefixed with the exclamation mark does not match it). The
1033 argument must be a list of (potentially quoted) expressions. For
1034 each of the expressions, if it starts with one of "<", "<=", "=",
1035 "!=", ">=", ">" a relative version comparison is done, otherwise
1036 the specified string is matched with shell-style globs.
1037 Note that using the kernel version string is an unreliable way to
1039 determine which features are supported by a kernel, because of the
1040 widespread practice of backporting drivers, features, and fixes
1041 from newer upstream kernels into older versions provided by
1042 distributions. Hence, this check is inherently unportable and
1043 should not be used for units which may be used on different
1044 distributions.
1045 ConditionEnvironment=
1047 ConditionEnvironment= may be used to check whether a specific
1048 environment variable is set (or if prefixed with the exclamation
1049 mark — unset) in the service manager's environment block. The
1050 argument may be a single word, to check if the variable with this
1051 name is defined in the environment block, or an assignment
1052 ("name=value"), to check if the variable with this exact value is
1053 defined. Note that the environment block of the service manager
1054 itself is checked, i.e. not any variables defined with Environment=
1055 or EnvironmentFile=, as described above. This is particularly
1056 useful when the service manager runs inside a containerized
1057 environment or as per-user service manager, in order to check for
1058 variables passed in by the enclosing container manager or PAM.
1059 ConditionSecurity=
1061 ConditionSecurity= may be used to check whether the given security
1062 technology is enabled on the system. Currently, the recognized
1063 values are "selinux", "apparmor", "tomoyo", "ima", "smack",
1064 "audit", "uefi-secureboot" and "tpm2". The test may be negated by
1065 prepending an exclamation mark.
1066 ConditionCapability=
1068 Check whether the given capability exists in the capability
1069 bounding set of the service manager (i.e. this does not check
1070 whether capability is actually available in the permitted or
1071 effective sets, see capabilities(7) for details). Pass a capability
1072 name such as "CAP_MKNOD", possibly prefixed with an exclamation
1073 mark to negate the check.
1074 ConditionACPower=
1076 Check whether the system has AC power, or is exclusively battery
1077 powered at the time of activation of the unit. This takes a boolean
1078 argument. If set to "true", the condition will hold only if at
1079 least one AC connector of the system is connected to a power
1080 source, or if no AC connectors are known. Conversely, if set to
1081 "false", the condition will hold only if there is at least one AC
1082 connector known and all AC connectors are disconnected from a power
1083 source.
1084 ConditionNeedsUpdate=
1086 Takes one of /var/ or /etc/ as argument, possibly prefixed with a
1087 "!" (to invert the condition). This condition may be used to
1088 conditionalize units on whether the specified directory requires an
1089 update because /usr/'s modification time is newer than the stamp
1090 file .updated in the specified directory. This is useful to
1091 implement offline updates of the vendor operating system resources
1092 in /usr/ that require updating of /etc/ or /var/ on the next
1093 following boot. Units making use of this condition should order
1094 themselves before systemd-update-done.service(8), to make sure they
1095 run before the stamp file's modification time gets reset indicating
1096 a completed update.
1097 If the systemd.condition-needs-update= option is specified on the
1099 kernel command line (taking a boolean), it will override the result
1100 of this condition check, taking precedence over any file
1101 modification time checks. If the kernel command line option is
1102 used, systemd-update-done.service will not have immediate effect on
1103 any following ConditionNeedsUpdate= checks, until the system is
1104 rebooted where the kernel command line option is not specified
1105 anymore.
1106 Note that to make this scheme effective, the timestamp of /usr/
1108 should be explicitly updated after its contents are modified. The
1109 kernel will automatically update modification timestamp on a
1110 directory only when immediate children of a directory are modified;
1111 an modification of nested files will not automatically result in
1112 mtime of /usr/ being updated.
1113 Also note that if the update method includes a call to execute
1115 appropriate post-update steps itself, it should not touch the
1116 timestamp of /usr/. In a typical distribution packaging scheme,
1117 packages will do any required update steps as part of the
1118 installation or upgrade, to make package contents immediately
1119 usable. ConditionNeedsUpdate= should be used with other update
1120 mechanisms where such an immediate update does not happen.
1121 ConditionFirstBoot=
1123 Takes a boolean argument. This condition may be used to
1124 conditionalize units on whether the system is booting up for the
1125 first time. This roughly means that /etc/ is unpopulated (for
1126 details, see "First Boot Semantics" in machine-id(5)). This may be
1127 used to populate /etc/ on the first boot after factory reset, or
1128 when a new system instance boots up for the first time.
1129 For robustness, units with ConditionFirstBoot=yes should order
1131 themselves before first-boot-complete.target and pull in this
1132 passive target with Wants=. This ensures that in a case of an
1133 aborted first boot, these units will be re-run during the next
1134 system startup.
1135 If the systemd.condition-first-boot= option is specified on the
1137 kernel command line (taking a boolean), it will override the result
1138 of this condition check, taking precedence over /etc/machine-id
1139 existence checks.
1140 ConditionPathExists=
1142 Check for the existence of a file. If the specified absolute path
1143 name does not exist, the condition will fail. If the absolute path
1144 name passed to ConditionPathExists= is prefixed with an exclamation
1145 mark ("!"), the test is negated, and the unit is only started if
1146 the path does not exist.
1147 ConditionPathExistsGlob=
1149 ConditionPathExistsGlob= is similar to ConditionPathExists=, but
1150 checks for the existence of at least one file or directory matching
1151 the specified globbing pattern.
1152 ConditionPathIsDirectory=
1154 ConditionPathIsDirectory= is similar to ConditionPathExists= but
1155 verifies that a certain path exists and is a directory.
1156 ConditionPathIsSymbolicLink=
1158 ConditionPathIsSymbolicLink= is similar to ConditionPathExists= but
1159 verifies that a certain path exists and is a symbolic link.
1160 ConditionPathIsMountPoint=
1162 ConditionPathIsMountPoint= is similar to ConditionPathExists= but
1163 verifies that a certain path exists and is a mount point.
1164 ConditionPathIsReadWrite=
1166 ConditionPathIsReadWrite= is similar to ConditionPathExists= but
1167 verifies that the underlying file system is readable and writable
1168 (i.e. not mounted read-only).
1169 ConditionPathIsEncrypted=
1171 ConditionPathIsEncrypted= is similar to ConditionPathExists= but
1172 verifies that the underlying file system's backing block device is
1173 encrypted using dm-crypt/LUKS. Note that this check does not cover
1174 ext4 per-directory encryption, and only detects block level
1175 encryption. Moreover, if the specified path resides on a file
1176 system on top of a loopback block device, only encryption above the
1177 loopback device is detected. It is not detected whether the file
1178 system backing the loopback block device is encrypted.
1179 ConditionDirectoryNotEmpty=
1181 ConditionDirectoryNotEmpty= is similar to ConditionPathExists= but
1182 verifies that a certain path exists and is a non-empty directory.
1183 ConditionFileNotEmpty=
1185 ConditionFileNotEmpty= is similar to ConditionPathExists= but
1186 verifies that a certain path exists and refers to a regular file
1187 with a non-zero size.
1188 ConditionFileIsExecutable=
1190 ConditionFileIsExecutable= is similar to ConditionPathExists= but
1191 verifies that a certain path exists, is a regular file, and marked
1192 executable.
1193 ConditionUser=
1195 ConditionUser= takes a numeric "UID", a UNIX user name, or the
1196 special value "@system". This condition may be used to check
1197 whether the service manager is running as the given user. The
1198 special value "@system" can be used to check if the user id is
1199 within the system user range. This option is not useful for system
1200 services, as the system manager exclusively runs as the root user,
1201 and thus the test result is constant.
1202 ConditionGroup=
1204 ConditionGroup= is similar to ConditionUser= but verifies that the
1205 service manager's real or effective group, or any of its auxiliary
1206 groups, match the specified group or GID. This setting does not
1207 support the special value "@system".
1208 ConditionControlGroupController=
1210 Check whether given cgroup controllers (e.g. "cpu") are available
1211 for use on the system or whether the legacy v1 cgroup or the modern
1212 v2 cgroup hierarchy is used.
1213 Multiple controllers may be passed with a space separating them; in
1215 this case the condition will only pass if all listed controllers
1216 are available for use. Controllers unknown to systemd are ignored.
1217 Valid controllers are "cpu", "cpuacct", "io", "blkio", "memory",
1218 "devices", and "pids". Even if available in the kernel, a
1219 particular controller may not be available if it was disabled on
1220 the kernel command line with cgroup_disable=controller.
1221 Alternatively, two special strings "v1" and "v2" may be specified
1223 (without any controller names). "v2" will pass if the unified v2
1224 cgroup hierarchy is used, and "v1" will pass if the legacy v1
1225 hierarchy or the hybrid hierarchy are used (see the discussion of
1226 systemd.unified_cgroup_hierarchy and
1227 systemd.legacy_systemd_cgroup_controller in systemd.service(5) for
1228 more information).
1229 ConditionMemory=
1231 Verify that the specified amount of system memory is available to
1232 the current system. Takes a memory size in bytes as argument,
1233 optionally prefixed with a comparison operator "<", "<=", "=",
1234 "!=", ">=", ">". On bare-metal systems compares the amount of
1235 physical memory in the system with the specified size, adhering to
1236 the specified comparison operator. In containers compares the
1237 amount of memory assigned to the container instead.
1238 ConditionCPUs=
1240 Verify that the specified number of CPUs is available to the
1241 current system. Takes a number of CPUs as argument, optionally
1242 prefixed with a comparison operator "<", "<=", "=", "!=", ">=",
1243 ">". Compares the number of CPUs in the CPU affinity mask
1244 configured of the service manager itself with the specified number,
1245 adhering to the specified comparison operator. On physical systems
1246 the number of CPUs in the affinity mask of the service manager
1247 usually matches the number of physical CPUs, but in special and
1248 virtual environments might differ. In particular, in containers the
1249 affinity mask usually matches the number of CPUs assigned to the
1250 container and not the physically available ones.
1251 ConditionCPUFeature=
1253 Verify that a given CPU feature is available via the "CPUID"
1254 instruction. This condition only does something on i386 and x86-64
1255 processors. On other processors it is assumed that the CPU does not
1256 support the given feature. It checks the leaves "1", "7",
1257 "0x80000001", and "0x80000007". Valid values are: "fpu", "vme",
1258 "de", "pse", "tsc", "msr", "pae", "mce", "cx8", "apic", "sep",
1259 "mtrr", "pge", "mca", "cmov", "pat", "pse36", "clflush", "mmx",
1260 "fxsr", "sse", "sse2", "ht", "pni", "pclmul", "monitor", "ssse3",
1261 "fma3", "cx16", "sse4_1", "sse4_2", "movbe", "popcnt", "aes",
1262 "xsave", "osxsave", "avx", "f16c", "rdrand", "bmi1", "avx2",
1263 "bmi2", "rdseed", "adx", "sha_ni", "syscall", "rdtscp", "lm",
1264 "lahf_lm", "abm", "constant_tsc".
1265 ConditionOSRelease=
1267 Verify that a specific "key=value" pair is set in the host's os-
1268 release(5).
1269 Other than exact matching with "=", and "!=", relative comparisons
1271 are supported for versioned parameters (e.g. "VERSION_ID"). The
1272 comparator can be one of "<", "<=", "=", "!=", ">=" and ">".
1273 ConditionMemoryPressure=, ConditionCPUPressure=, ConditionIOPressure=
1275 Verify that the overall system (memory, CPU or IO) pressure is
1276 below or equal to a threshold. This setting takes a threshold value
1277 as argument. It can be specified as a simple percentage value,
1278 suffixed with "%", in which case the pressure will be measured as
1279 an average over the last five minutes before the attempt to start
1280 the unit is performed. Alternatively, the average timespan can also
1281 be specified using "/" as a separator, for example: "10%/1min". The
1282 supported timespans match what the kernel provides, and are limited
1283 to "10sec", "1min" and "5min". The "full" PSI will be checked
1284 first, and if not found "some" will be checked. For more details,
1285 see the documentation on PSI (Pressure Stall Information)[2].
1286 Optionally, the threshold value can be prefixed with the slice unit
1288 under which the pressure will be checked, followed by a ":". If the
1289 slice unit is not specified, the overall system pressure will be
1290 measured, instead of a particular cgroup's.
1291 AssertArchitecture=, AssertVirtualization=, AssertHost=,
1293 AssertKernelCommandLine=, AssertKernelVersion=, AssertEnvironment=,
1294 AssertSecurity=, AssertCapability=, AssertACPower=, AssertNeedsUpdate=,
1295 AssertFirstBoot=, AssertPathExists=, AssertPathExistsGlob=,
1296 AssertPathIsDirectory=, AssertPathIsSymbolicLink=,
1297 AssertPathIsMountPoint=, AssertPathIsReadWrite=,
1298 AssertPathIsEncrypted=, AssertDirectoryNotEmpty=, AssertFileNotEmpty=,
1299 AssertFileIsExecutable=, AssertUser=, AssertGroup=,
1300 AssertControlGroupController=, AssertMemory=, AssertCPUs=,
1301 AssertOSRelease=, AssertMemoryPressure=, AssertCPUPressure=,
1302 AssertIOPressure=
1303 Similar to the ConditionArchitecture=, ConditionVirtualization=,
1304 ..., condition settings described above, these settings add
1305 assertion checks to the start-up of the unit. However, unlike the
1306 conditions settings, any assertion setting that is not met results
1307 in failure of the start job (which means this is logged loudly).
1308 Note that hitting a configured assertion does not cause the unit to
1309 enter the "failed" state (or in fact result in any state change of
1310 the unit), it affects only the job queued for it. Use assertion
1311 expressions for units that cannot operate when specific
1312 requirements are not met, and when this is something the
1313 administrator or user should look into.
1314
1316 Unit settings that create a relationship with a second unit usually
1317 show up in properties of both units, for example in systemctl show
1318 output. In some cases the name of the property is the same as the name
1319 of the configuration setting, but not always. This table lists the
1320 properties that are shown on two units which are connected through some
1321 dependency, and shows which property on "source" unit corresponds to
1322 which property on the "target" unit.
1323 Table 3. Forward and reverse unit properties
1325 ┌──────────────────────┬───────────────────────┬─────────────────────────────────┐
1326 │"Forward" │ "Reverse" │ Where used │
1327 │property │ property │ │
1328 ├──────────────────────┼───────────────────────┼─────────────────────────────────┤
1329 │Before= │ After= │ │
1330 ├──────────────────────┼───────────────────────┤ [Unit] section │
1331 │After= │ Before= │ │
1332 ├──────────────────────┼───────────────────────┼─────────────────┬───────────────┤
1333 │Requires= │ RequiredBy= │ [Unit] section │ [Install] │
1334 │ │ │ │ section │
1335 ├──────────────────────┼───────────────────────┼─────────────────┼───────────────┤
1336 │Wants= │ WantedBy= │ [Unit] section │ [Install] │
1337 │ │ │ │ section │
1338 ├──────────────────────┼───────────────────────┼─────────────────┼───────────────┤
1339 │PartOf= │ ConsistsOf= │ [Unit] section │ an automatic │
1340 │ │ │ │ property │
1341 ├──────────────────────┼───────────────────────┼─────────────────┼───────────────┤
1342 │BindsTo= │ BoundBy= │ [Unit] section │ an automatic │
1343 │ │ │ │ property │
1344 ├──────────────────────┼───────────────────────┼─────────────────┼───────────────┤
1345 │Requisite= │ RequisiteOf= │ [Unit] section │ an automatic │
1346 │ │ │ │ property │
1347 ├──────────────────────┼───────────────────────┼─────────────────┴───────────────┤
1348 │Triggers= │ TriggeredBy= │ Automatic properties, see notes │
1349 │ │ │ below │
1350 ├──────────────────────┼───────────────────────┼─────────────────┬───────────────┤
1351 │Conflicts= │ ConflictedBy= │ [Unit] section │ an automatic │
1352 │ │ │ │ property │
1353 ├──────────────────────┼───────────────────────┼─────────────────┴───────────────┤
1354 │PropagatesReloadTo= │ ReloadPropagatedFrom= │ │
1355 ├──────────────────────┼───────────────────────┤ [Unit] section │
1356 │ReloadPropagatedFrom= │ PropagatesReloadTo= │ │
1357 ├──────────────────────┼───────────────────────┼─────────────────┬───────────────┤
1358 │Following= │ n/a │ An automatic │ │
1359 │ │ │ property │ │
1360 └──────────────────────┴───────────────────────┴─────────────────┴───────────────┘
1361 Note: WantedBy= and RequiredBy= are used in the [Install] section to
1363 create symlinks in .wants/ and .requires/ directories. They cannot be
1364 used directly as a unit configuration setting.
1365 Note: ConsistsOf=, BoundBy=, RequisiteOf=, ConflictedBy= are created
1367 implicitly along with their reverses and cannot be specified directly.
1368 Note: Triggers= is created implicitly between a socket, path unit, or
1370 an automount unit, and the unit they activate. By default a unit with
1371 the same name is triggered, but this can be overridden using Sockets=,
1372 Service=, and Unit= settings. See systemd.service(5),
1373 systemd.socket(5), systemd.path(5), and systemd.automount(5) for
1374 details. TriggeredBy= is created implicitly on the triggered unit.
1375 Note: Following= is used to group device aliases and points to the
1377 "primary" device unit that systemd is using to track device state,
1378 usually corresponding to a sysfs path. It does not show up in the
1379 "target" unit.
1380
1382 Unit files may include an [Install] section, which carries installation
1383 information for the unit. This section is not interpreted by systemd(1)
1384 during runtime; it is used by the enable and disable commands of the
1385 systemctl(1) tool during installation of a unit.
1386 Alias=
1388 A space-separated list of additional names this unit shall be
1389 installed under. The names listed here must have the same suffix
1390 (i.e. type) as the unit filename. This option may be specified more
1391 than once, in which case all listed names are used. At installation
1392 time, systemctl enable will create symlinks from these names to the
1393 unit filename. Note that not all unit types support such alias
1394 names, and this setting is not supported for them. Specifically,
1395 mount, slice, swap, and automount units do not support aliasing.
1396 WantedBy=, RequiredBy=
1398 This option may be used more than once, or a space-separated list
1399 of unit names may be given. A symbolic link is created in the
1400 .wants/ or .requires/ directory of each of the listed units when
1401 this unit is installed by systemctl enable. This has the effect
1402 that a dependency of type Wants= or Requires= is added from the
1403 listed unit to the current unit. The primary result is that the
1404 current unit will be started when the listed unit is started. See
1405 the description of Wants= and Requires= in the [Unit] section for
1406 details.
1407 WantedBy=foo.service in a service bar.service is mostly equivalent
1409 to Alias=foo.service.wants/bar.service in the same file. In case of
1410 template units, systemctl enable must be called with an instance
1411 name, and this instance will be added to the .wants/ or .requires/
1412 list of the listed unit. E.g. WantedBy=getty.target in a service
1413 getty@.service will result in systemctl enable getty@tty2.service
1414 creating a getty.target.wants/getty@tty2.service link to
1415 getty@.service.
1416 Also=
1418 Additional units to install/deinstall when this unit is
1419 installed/deinstalled. If the user requests
1420 installation/deinstallation of a unit with this option configured,
1421 systemctl enable and systemctl disable will automatically
1422 install/uninstall units listed in this option as well.
1423 This option may be used more than once, or a space-separated list
1425 of unit names may be given.
1426 DefaultInstance=
1428 In template unit files, this specifies for which instance the unit
1429 shall be enabled if the template is enabled without any explicitly
1430 set instance. This option has no effect in non-template unit files.
1431 The specified string must be usable as instance identifier.
1432 The following specifiers are interpreted in the Install section: %a,
1434 %b, %B, %g, %G, %H, %i, %j, %l, %m, %n, %N, %o, %p, %u, %U, %v, %w, %W,
1435 %%. For their meaning see the next section.
1436
1438 Many settings resolve specifiers which may be used to write generic
1439 unit files referring to runtime or unit parameters that are replaced
1440 when the unit files are loaded. Specifiers must be known and resolvable
1441 for the setting to be valid. The following specifiers are understood:
1442 Table 4. Specifiers available in unit files
1444 ┌──────────┬─────────────────────┬────────────────────────┐
1445 │Specifier │ Meaning │ Details │
1446 ├──────────┼─────────────────────┼────────────────────────┤
1447 │"%a" │ Architecture │ A short string │
1448 │ │ │ identifying the │
1449 │ │ │ architecture of the │
1450 │ │ │ local system. A │
1451 │ │ │ string such as x86, │
1452 │ │ │ x86-64 or arm64. │
1453 │ │ │ See the │
1454 │ │ │ architectures │
1455 │ │ │ defined for │
1456 │ │ │ ConditionArchitecture= │
1457 │ │ │ above for a full │
1458 │ │ │ list. │
1459 ├──────────┼─────────────────────┼────────────────────────┤
1460 │"%A" │ Operating system │ The operating system │
1461 │ │ image version │ image version │
1462 │ │ │ identifier of the │
1463 │ │ │ running system, as │
1464 │ │ │ read from the │
1465 │ │ │ IMAGE_VERSION= field │
1466 │ │ │ of /etc/os-release. If │
1467 │ │ │ not set, resolves to │
1468 │ │ │ an empty string. See │
1469 │ │ │ os-release(5) for more │
1470 │ │ │ information. │
1471 ├──────────┼─────────────────────┼────────────────────────┤
1472 │"%b" │ Boot ID │ The boot ID of the │
1473 │ │ │ running system, │
1474 │ │ │ formatted as string. │
1475 │ │ │ See random(4) for more │
1476 │ │ │ information. │
1477 ├──────────┼─────────────────────┼────────────────────────┤
1478 │"%B" │ Operating system │ The operating system │
1479 │ │ build ID │ build identifier of │
1480 │ │ │ the running system, as │
1481 │ │ │ read from the │
1482 │ │ │ BUILD_ID= field of │
1483 │ │ │ /etc/os-release. If │
1484 │ │ │ not set, resolves to │
1485 │ │ │ an empty string. See │
1486 │ │ │ os-release(5) for more │
1487 │ │ │ information. │
1488 ├──────────┼─────────────────────┼────────────────────────┤
1489 │"%C" │ Cache directory │ This is either │
1490 │ │ root │ /var/cache (for the │
1491 │ │ │ system manager) or the │
1492 │ │ │ path "$XDG_CACHE_HOME" │
1493 │ │ │ resolves to (for user │
1494 │ │ │ managers). │
1495 ├──────────┼─────────────────────┼────────────────────────┤
1496 │"%E" │ Configuration │ This is either /etc/ │
1497 │ │ directory root │ (for the system │
1498 │ │ │ manager) or the path │
1499 │ │ │ "$XDG_CONFIG_HOME" │
1500 │ │ │ resolves to (for user │
1501 │ │ │ managers). │
1502 ├──────────┼─────────────────────┼────────────────────────┤
1503 │"%f" │ Unescaped filename │ This is either the │
1504 │ │ │ unescaped instance │
1505 │ │ │ name (if applicable) │
1506 │ │ │ with / prepended (if │
1507 │ │ │ applicable), or the │
1508 │ │ │ unescaped prefix name │
1509 │ │ │ prepended with /. This │
1510 │ │ │ implements unescaping │
1511 │ │ │ according to the rules │
1512 │ │ │ for escaping absolute │
1513 │ │ │ file system paths │
1514 │ │ │ discussed above. │
1515 ├──────────┼─────────────────────┼────────────────────────┤
1516 │"%g" │ User group │ This is the name of │
1517 │ │ │ the group running the │
1518 │ │ │ service manager │
1519 │ │ │ instance. In case of │
1520 │ │ │ the system manager │
1521 │ │ │ this resolves to │
1522 │ │ │ "root". │
1523 ├──────────┼─────────────────────┼────────────────────────┤
1524 │"%G" │ User GID │ This is the numeric │
1525 │ │ │ GID of the user │
1526 │ │ │ running the service │
1527 │ │ │ manager instance. In │
1528 │ │ │ case of the system │
1529 │ │ │ manager this resolves │
1530 │ │ │ to "0". │
1531 ├──────────┼─────────────────────┼────────────────────────┤
1532 │"%h" │ User home directory │ This is the home │
1533 │ │ │ directory of the user │
1534 │ │ │ running the service │
1535 │ │ │ manager instance. In │
1536 │ │ │ case of the system │
1537 │ │ │ manager this resolves │
1538 │ │ │ to "/root". │
1539 │ │ │ │
1540 │ │ │ Note that this setting │
1541 │ │ │ is not influenced by │
1542 │ │ │ the User= setting │
1543 │ │ │ configurable in the │
1544 │ │ │ [Service] section of │
1545 │ │ │ the service unit. │
1546 ├──────────┼─────────────────────┼────────────────────────┤
1547 │"%H" │ Host name │ The hostname of the │
1548 │ │ │ running system at the │
1549 │ │ │ point in time the unit │
1550 │ │ │ configuration is │
1551 │ │ │ loaded. │
1552 ├──────────┼─────────────────────┼────────────────────────┤
1553 │"%i" │ Instance name │ For instantiated units │
1554 │ │ │ this is the string │
1555 │ │ │ between the first "@" │
1556 │ │ │ character and the type │
1557 │ │ │ suffix. Empty for │
1558 │ │ │ non-instantiated │
1559 │ │ │ units. │
1560 ├──────────┼─────────────────────┼────────────────────────┤
1561 │"%I" │ Unescaped instance │ Same as "%i", but with │
1562 │ │ name │ escaping undone. │
1563 ├──────────┼─────────────────────┼────────────────────────┤
1564 │"%j" │ Final component of │ This is the string │
1565 │ │ the prefix │ between the last "-" │
1566 │ │ │ and the end of the │
1567 │ │ │ prefix name. If there │
1568 │ │ │ is no "-", this is the │
1569 │ │ │ same as "%p". │
1570 ├──────────┼─────────────────────┼────────────────────────┤
1571 │"%J" │ Unescaped final │ Same as "%j", but with │
1572 │ │ component of the │ escaping undone. │
1573 │ │ prefix │ │
1574 ├──────────┼─────────────────────┼────────────────────────┤
1575 │"%l" │ Short host name │ The hostname of the │
1576 │ │ │ running system at the │
1577 │ │ │ point in time the unit │
1578 │ │ │ configuration is │
1579 │ │ │ loaded, truncated at │
1580 │ │ │ the first dot to │
1581 │ │ │ remove any domain │
1582 │ │ │ component. │
1583 ├──────────┼─────────────────────┼────────────────────────┤
1584 │"%L" │ Log directory root │ This is either │
1585 │ │ │ /var/log (for the │
1586 │ │ │ system manager) or the │
1587 │ │ │ path │
1588 │ │ │ "$XDG_CONFIG_HOME" │
1589 │ │ │ resolves to with /log │
1590 │ │ │ appended (for user │
1591 │ │ │ managers). │
1592 ├──────────┼─────────────────────┼────────────────────────┤
1593 │"%m" │ Machine ID │ The machine ID of the │
1594 │ │ │ running system, │
1595 │ │ │ formatted as string. │
1596 │ │ │ See machine-id(5) for │
1597 │ │ │ more information. │
1598 ├──────────┼─────────────────────┼────────────────────────┤
1599 │"%M" │ Operating system │ The operating system │
1600 │ │ image identifier │ image identifier of │
1601 │ │ │ the running system, as │
1602 │ │ │ read from the │
1603 │ │ │ IMAGE_ID= field of │
1604 │ │ │ /etc/os-release. If │
1605 │ │ │ not set, resolves to │
1606 │ │ │ an empty string. See │
1607 │ │ │ os-release(5) for more │
1608 │ │ │ information. │
1609 ├──────────┼─────────────────────┼────────────────────────┤
1610 │"%n" │ Full unit name │ │
1611 ├──────────┼─────────────────────┼────────────────────────┤
1612 │"%N" │ Full unit name │ Same as "%n", but with │
1613 │ │ │ the type suffix │
1614 │ │ │ removed. │
1615 ├──────────┼─────────────────────┼────────────────────────┤
1616 │"%o" │ Operating system ID │ The operating system │
1617 │ │ │ identifier of the │
1618 │ │ │ running system, as │
1619 │ │ │ read from the ID= │
1620 │ │ │ field of │
1621 │ │ │ /etc/os-release. See │
1622 │ │ │ os-release(5) for more │
1623 │ │ │ information. │
1624 ├──────────┼─────────────────────┼────────────────────────┤
1625 │"%p" │ Prefix name │ For instantiated │
1626 │ │ │ units, this refers to │
1627 │ │ │ the string before the │
1628 │ │ │ first "@" character of │
1629 │ │ │ the unit name. For │
1630 │ │ │ non-instantiated │
1631 │ │ │ units, same as "%N". │
1632 ├──────────┼─────────────────────┼────────────────────────┤
1633 │"%P" │ Unescaped prefix │ Same as "%p", but with │
1634 │ │ name │ escaping undone. │
1635 ├──────────┼─────────────────────┼────────────────────────┤
1636 │"%s" │ User shell │ This is the shell of │
1637 │ │ │ the user running the │
1638 │ │ │ service manager │
1639 │ │ │ instance. In case of │
1640 │ │ │ the system manager │
1641 │ │ │ this resolves to │
1642 │ │ │ "/bin/sh". │
1643 ├──────────┼─────────────────────┼────────────────────────┤
1644 │"%S" │ State directory │ This is either │
1645 │ │ root │ /var/lib (for the │
1646 │ │ │ system manager) or the │
1647 │ │ │ path │
1648 │ │ │ "$XDG_CONFIG_HOME" │
1649 │ │ │ resolves to (for user │
1650 │ │ │ managers). │
1651 ├──────────┼─────────────────────┼────────────────────────┤
1652 │"%t" │ Runtime directory │ This is either /run/ │
1653 │ │ root │ (for the system │
1654 │ │ │ manager) or the path │
1655 │ │ │ "$XDG_RUNTIME_DIR" │
1656 │ │ │ resolves to (for user │
1657 │ │ │ managers). │
1658 ├──────────┼─────────────────────┼────────────────────────┤
1659 │"%T" │ Directory for │ This is either /tmp or │
1660 │ │ temporary files │ the path "$TMPDIR", │
1661 │ │ │ "$TEMP" or "$TMP" are │
1662 │ │ │ set to. (Note that the │
1663 │ │ │ directory may be │
1664 │ │ │ specified without a │
1665 │ │ │ trailing slash.) │
1666 ├──────────┼─────────────────────┼────────────────────────┤
1667 │"%u" │ User name │ This is the name of │
1668 │ │ │ the user running the │
1669 │ │ │ service manager │
1670 │ │ │ instance. In case of │
1671 │ │ │ the system manager │
1672 │ │ │ this resolves to │
1673 │ │ │ "root". │
1674 │ │ │ │
1675 │ │ │ Note that this setting │
1676 │ │ │ is not influenced by │
1677 │ │ │ the User= setting │
1678 │ │ │ configurable in the │
1679 │ │ │ [Service] section of │
1680 │ │ │ the service unit. │
1681 ├──────────┼─────────────────────┼────────────────────────┤
1682 │"%U" │ User UID │ This is the numeric │
1683 │ │ │ UID of the user │
1684 │ │ │ running the service │
1685 │ │ │ manager instance. In │
1686 │ │ │ case of the system │
1687 │ │ │ manager this resolves │
1688 │ │ │ to "0". │
1689 │ │ │ │
1690 │ │ │ Note that this setting │
1691 │ │ │ is not influenced by │
1692 │ │ │ the User= setting │
1693 │ │ │ configurable in the │
1694 │ │ │ [Service] section of │
1695 │ │ │ the service unit. │
1696 ├──────────┼─────────────────────┼────────────────────────┤
1697 │"%v" │ Kernel release │ Identical to uname -r │
1698 │ │ │ output. │
1699 ├──────────┼─────────────────────┼────────────────────────┤
1700 │"%V" │ Directory for │ This is either │
1701 │ │ larger and │ /var/tmp or the path │
1702 │ │ persistent │ "$TMPDIR", "$TEMP" or │
1703 │ │ temporary files │ "$TMP" are set to. │
1704 │ │ │ (Note that the │
1705 │ │ │ directory may be │
1706 │ │ │ specified without a │
1707 │ │ │ trailing slash.) │
1708 ├──────────┼─────────────────────┼────────────────────────┤
1709 │"%w" │ Operating system │ The operating system │
1710 │ │ version ID │ version identifier of │
1711 │ │ │ the running system, as │
1712 │ │ │ read from the │
1713 │ │ │ VERSION_ID= field of │
1714 │ │ │ /etc/os-release. If │
1715 │ │ │ not set, resolves to │
1716 │ │ │ an empty string. See │
1717 │ │ │ os-release(5) for more │
1718 │ │ │ information. │
1719 ├──────────┼─────────────────────┼────────────────────────┤
1720 │"%W" │ Operating system │ The operating system │
1721 │ │ variant ID │ variant identifier of │
1722 │ │ │ the running system, as │
1723 │ │ │ read from the │
1724 │ │ │ VARIANT_ID= field of │
1725 │ │ │ /etc/os-release. If │
1726 │ │ │ not set, resolves to │
1727 │ │ │ an empty string. See │
1728 │ │ │ os-release(5) for more │
1729 │ │ │ information. │
1730 ├──────────┼─────────────────────┼────────────────────────┤
1731 │"%%" │ Single percent sign │ Use "%%" in place of │
1732 │ │ │ "%" to specify a │
1733 │ │ │ single percent sign. │
1734 └──────────┴─────────────────────┴────────────────────────┘
1735
1737 Example 1. Allowing units to be enabled
1738 The following snippet (highlighted) allows a unit (e.g. foo.service)
1740 to be enabled via systemctl enable:
1741 [Unit]
1743 Description=Foo
1744 [Service]
1746 ExecStart=/usr/sbin/foo-daemon
1747 [Install]
1749 WantedBy=multi-user.target
1750 After running systemctl enable, a symlink
1752 /etc/systemd/system/multi-user.target.wants/foo.service linking to the
1753 actual unit will be created. It tells systemd to pull in the unit when
1754 starting multi-user.target. The inverse systemctl disable will remove
1755 that symlink again.
1756 Example 2. Overriding vendor settings
1758 There are two methods of overriding vendor settings in unit files:
1760 copying the unit file from /usr/lib/systemd/system to
1761 /etc/systemd/system and modifying the chosen settings. Alternatively,
1762 one can create a directory named unit.d/ within /etc/systemd/system and
1763 place a drop-in file name.conf there that only changes the specific
1764 settings one is interested in. Note that multiple such drop-in files
1765 are read if present, processed in lexicographic order of their
1766 filename.
1767 The advantage of the first method is that one easily overrides the
1769 complete unit, the vendor unit is not parsed at all anymore. It has the
1770 disadvantage that improvements to the unit file by the vendor are not
1771 automatically incorporated on updates.
1772 The advantage of the second method is that one only overrides the
1774 settings one specifically wants, where updates to the unit by the
1775 vendor automatically apply. This has the disadvantage that some future
1776 updates by the vendor might be incompatible with the local changes.
1777 This also applies for user instances of systemd, but with different
1779 locations for the unit files. See the section on unit load paths for
1780 further details.
1781 Suppose there is a vendor-supplied unit
1783 /usr/lib/systemd/system/httpd.service with the following contents:
1784 [Unit]
1786 Description=Some HTTP server
1787 After=remote-fs.target sqldb.service
1788 Requires=sqldb.service
1789 AssertPathExists=/srv/webserver
1790 [Service]
1792 Type=notify
1793 ExecStart=/usr/sbin/some-fancy-httpd-server
1794 Nice=5
1795 [Install]
1797 WantedBy=multi-user.target
1798 Now one wants to change some settings as an administrator: firstly, in
1800 the local setup, /srv/webserver might not exist, because the HTTP
1801 server is configured to use /srv/www instead. Secondly, the local
1802 configuration makes the HTTP server also depend on a memory cache
1803 service, memcached.service, that should be pulled in (Requires=) and
1804 also be ordered appropriately (After=). Thirdly, in order to harden the
1805 service a bit more, the administrator would like to set the PrivateTmp=
1806 setting (see systemd.exec(5) for details). And lastly, the
1807 administrator would like to reset the niceness of the service to its
1808 default value of 0.
1809 The first possibility is to copy the unit file to
1811 /etc/systemd/system/httpd.service and change the chosen settings:
1812 [Unit]
1814 Description=Some HTTP server
1815 After=remote-fs.target sqldb.service memcached.service
1816 Requires=sqldb.service memcached.service
1817 AssertPathExists=/srv/www
1818 [Service]
1820 Type=notify
1821 ExecStart=/usr/sbin/some-fancy-httpd-server
1822 Nice=0
1823 PrivateTmp=yes
1824 [Install]
1826 WantedBy=multi-user.target
1827 Alternatively, the administrator could create a drop-in file
1829 /etc/systemd/system/httpd.service.d/local.conf with the following
1830 contents:
1831 [Unit]
1833 After=memcached.service
1834 Requires=memcached.service
1835 # Reset all assertions and then re-add the condition we want
1836 AssertPathExists=
1837 AssertPathExists=/srv/www
1838 [Service]
1840 Nice=0
1841 PrivateTmp=yes
1842 Note that for drop-in files, if one wants to remove entries from a
1844 setting that is parsed as a list (and is not a dependency), such as
1845 AssertPathExists= (or e.g. ExecStart= in service units), one needs to
1846 first clear the list before re-adding all entries except the one that
1847 is to be removed. Dependencies (After=, etc.) cannot be reset to an
1848 empty list, so dependencies can only be added in drop-ins. If you want
1849 to remove dependencies, you have to override the entire unit.
1850 Example 3. Top level drop-ins with template units
1852 Top level per-type drop-ins can be used to change some aspect of all
1854 units of a particular type. For example by creating the
1855 /etc/systemd/system/service.d/ directory with a drop-in file, the
1856 contents of the drop-in file can be applied to all service units. We
1857 can take this further by having the top-level drop-in instantiate a
1858 secondary helper unit. Consider for example the following set of units
1859 and drop-in files where we install an OnFailure= dependency for all
1860 service units.
1861 /etc/systemd/system/failure-handler@.service:
1863 [Unit]
1865 Description=My failure handler for %i
1866 [Service]
1868 Type=oneshot
1869 # Perform some special action for when %i exits unexpectedly.
1870 ExecStart=/usr/sbin/myfailurehandler %i
1871 We can then add an instance of failure-handler@.service as an
1874 OnFailure= dependency for all service units.
1875 /etc/systemd/system/service.d/10-all.conf:
1877 [Unit]
1879 OnFailure=failure-handler@%N.service
1880 Now, after running systemctl daemon-reload all services will have
1883 acquired an OnFailure= dependency on failure-handler@%N.service. The
1884 template instance units will also have gained the dependency which
1885 results in the creation of a recursive dependency chain. systemd will
1886 try to detect these recursive dependency chains where a template unit
1887 directly and recursively depends on itself and will remove such
1888 dependencies automatically if it finds them. If systemd doesn't detect
1889 the recursive dependency chain, we can break the chain ourselves by
1890 disabling the drop-in for the template instance units via a symlink to
1891 /dev/null:
1892 mkdir /etc/systemd/system/failure-handler@.service.d/
1894 ln -s /dev/null /etc/systemd/system/failure-handler@.service.d/10-all.conf
1895 systemctl daemon-reload
1896 This ensures that if a failure-handler@.service instance fails it will
1899 not trigger an instance named failure-handler@failure-handler.service.
1900
1902 systemd(1), systemctl(1), systemd-system.conf(5), systemd.special(7),
1903 systemd.service(5), systemd.socket(5), systemd.device(5),
1904 systemd.mount(5), systemd.automount(5), systemd.swap(5),
1905 systemd.target(5), systemd.path(5), systemd.timer(5), systemd.scope(5),
1906 systemd.slice(5), systemd.time(7), systemd-analyze(1), capabilities(7),
1907 systemd.directives(7), uname(1)
1908
1910 1. Interface Portability and Stability Promise
1911 https://systemd.io/PORTABILITY_AND_STABILITY/
1912 2. PSI (Pressure Stall Information)
1914 https://www.kernel.org/doc/html/latest/accounting/psi.html
1915systemd 250 SYSTEMD.UNIT(5)