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