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