Debian Codegraph @

upstream/debian-trixie/man5/systemd.exec.5

raw
1 '\" t
2 .TH "SYSTEMD\&.EXEC" "5" "" "systemd 257.13" "systemd.exec"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd.exec \- Execution environment configuration
24 .SH "SYNOPSIS"
25 .PP
26 \fIservice\fR\&.service,
27 \fIsocket\fR\&.socket,
28 \fImount\fR\&.mount,
29 \fIswap\fR\&.swap
30 .SH "DESCRIPTION"
31 .PP
32 Unit configuration files for services, sockets, mount points, and swap devices share a subset of configuration options which define the execution environment of spawned processes\&.
33 .PP
34 This man page lists the configuration options shared by these four unit types\&. See
35 \fBsystemd.unit\fR(5)
36 for the common options of all unit configuration files, and
37 \fBsystemd.service\fR(5),
38 \fBsystemd.socket\fR(5),
39 \fBsystemd.swap\fR(5), and
40 \fBsystemd.mount\fR(5)
41 for more information on the specific unit configuration files\&. The execution specific configuration options are configured in the [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type\&.
42 .PP
43 In addition, options which control resources through Linux Control Groups (cgroups) are listed in
44 \fBsystemd.resource-control\fR(5)\&. Those options complement options listed here\&.
45 .SH "IMPLICIT DEPENDENCIES"
46 .PP
47 A few execution parameters result in additional, automatic dependencies to be added:
48 .sp
49 .RS 4
50 .ie n \{\
51 \h'-04'\(bu\h'+03'\c
52 .\}
53 .el \{\
54 .sp -1
55 .IP \(bu 2.3
56 .\}
57 Units with
58 \fIWorkingDirectory=\fR,
59 \fIRootDirectory=\fR,
60 \fIRootImage=\fR,
61 \fIRuntimeDirectory=\fR,
62 \fIStateDirectory=\fR,
63 \fICacheDirectory=\fR,
64 \fILogsDirectory=\fR
65 or
66 \fIConfigurationDirectory=\fR
67 set automatically gain dependencies of type
68 \fIRequires=\fR
69 and
70 \fIAfter=\fR
71 on all mount units required to access the specified paths\&. This is equivalent to having them listed explicitly in
72 \fIRequiresMountsFor=\fR\&.
73 .RE
74 .sp
75 .RS 4
76 .ie n \{\
77 \h'-04'\(bu\h'+03'\c
78 .\}
79 .el \{\
80 .sp -1
81 .IP \(bu 2.3
82 .\}
83 Similarly, units with
84 \fIPrivateTmp=\fR
85 enabled automatically get mount unit dependencies for all mounts required to access
86 /tmp/
87 and
88 /var/tmp/\&. They will also gain an automatic
89 \fIAfter=\fR
90 dependency on
91 \fBsystemd-tmpfiles-setup.service\fR(8)\&.
92 .RE
93 .sp
94 .RS 4
95 .ie n \{\
96 \h'-04'\(bu\h'+03'\c
97 .\}
98 .el \{\
99 .sp -1
100 .IP \(bu 2.3
101 .\}
102 Units whose standard output or error output is connected to
103 \fBjournal\fR
104 or
105 \fBkmsg\fR
106 (or their combinations with console output, see below) automatically acquire dependencies of type
107 \fIAfter=\fR
108 on
109 systemd\-journald\&.socket\&.
110 .RE
111 .sp
112 .RS 4
113 .ie n \{\
114 \h'-04'\(bu\h'+03'\c
115 .\}
116 .el \{\
117 .sp -1
118 .IP \(bu 2.3
119 .\}
120 Units using
121 \fILogNamespace=\fR
122 will automatically gain ordering and requirement dependencies on the two socket units associated with
123 systemd\-journald@\&.service
124 instances\&.
125 .RE
126 .SH "PATHS"
127 .PP
128 The following settings may be used to change a service\*(Aqs view of the filesystem\&. Please note that the paths must be absolute and must not contain a
129 "\&.\&."
130 path component\&.
131 .PP
132 \fIExecSearchPath=\fR
133 .RS 4
134 Takes a colon separated list of absolute paths relative to which the executable used by the
135 \fIExec*=\fR
136 (e\&.g\&.
137 \fIExecStart=\fR,
138 \fIExecStop=\fR, etc\&.) properties can be found\&.
139 \fIExecSearchPath=\fR
140 overrides
141 \fI$PATH\fR
142 if
143 \fI$PATH\fR
144 is not supplied by the user through
145 \fIEnvironment=\fR,
146 \fIEnvironmentFile=\fR
147 or
148 \fIPassEnvironment=\fR\&. Assigning an empty string removes previous assignments and setting
149 \fIExecSearchPath=\fR
150 to a value multiple times will append to the previous setting\&.
151 .sp
152 Added in version 250\&.
153 .RE
154 .PP
155 \fIWorkingDirectory=\fR
156 .RS 4
157 Takes a directory path relative to the service\*(Aqs root directory specified by
158 \fIRootDirectory=\fR, or the special value
159 "~"\&. Sets the working directory for executed processes\&. If set to
160 "~", the home directory of the user specified in
161 \fIUser=\fR
162 is used\&. If not set, defaults to the root directory when systemd is running as a system instance and the respective user\*(Aqs home directory if run as user\&. If the setting is prefixed with the
163 "\-"
164 character, a missing working directory is not considered fatal\&. If
165 \fIRootDirectory=\fR/\fIRootImage=\fR
166 is not set, then
167 \fIWorkingDirectory=\fR
168 is relative to the root of the system running the service manager\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&.
169 .RE
170 .PP
171 \fIRootDirectory=\fR
172 .RS 4
173 Takes a directory path relative to the host\*(Aqs root directory (i\&.e\&. the root of the system running the service manager)\&. Sets the root directory for executed processes, with the
174 \fBpivot_root\fR(2)
175 or
176 \fBchroot\fR(2)
177 system call\&. If this is used, it must be ensured that the process binary and all its auxiliary files are available in the new root\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&.
178 .sp
179 The
180 \fIMountAPIVFS=\fR
181 and
182 \fIPrivateUsers=\fR
183 settings are particularly useful in conjunction with
184 \fIRootDirectory=\fR\&. For details, see below\&.
185 .sp
186 If
187 \fIRootDirectory=\fR/\fIRootImage=\fR
188 are used together with
189 \fINotifyAccess=\fR
190 the notification socket is automatically mounted from the host into the root environment, to ensure the notification interface can work correctly\&.
191 .sp
192 Note that services using
193 \fIRootDirectory=\fR/\fIRootImage=\fR
194 will not be able to log via the syslog or journal protocols to the host logging infrastructure, unless the relevant sockets are mounted from the host, specifically:
195 .sp
196 The host\*(Aqs
197 \fBos-release\fR(5)
198 file will be made available for the service (read\-only) as
199 /run/host/os\-release\&. It will be updated automatically on soft reboot (see:
200 \fBsystemd-soft-reboot.service\fR(8)), in case the service is configured to survive it\&.
201 .PP
202 \fBExample\ \&1.\ \&Mounting logging sockets into root environment\fR
203 .sp
204 .if n \{\
205 .RS 4
206 .\}
207 .nf
208 BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout
209 .fi
210 .if n \{\
211 .RE
212 .\}
213
214 In place of the directory path a
215 "\&.v/"
216 versioned directory may be specified, see
217 \fBsystemd.v\fR(7)
218 for details\&.
219 .sp
220 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
221 \fIPrivateUsers=\fR
222 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
223 "kernel\&.unprivileged_userns_clone="
224 sysctl)\&.
225 .RE
226 .PP
227 \fIRootImage=\fR
228 .RS 4
229 Takes a path to a block device node or regular file as argument\&. This call is similar to
230 \fIRootDirectory=\fR
231 however mounts a file system hierarchy from a block device node or loopback file instead of a directory\&. The device node or file system image file needs to contain a file system without a partition table, or a file system within an MBR/MS\-DOS or GPT partition table with only a single Linux\-compatible partition, or a set of file systems within a GPT partition table that follows the
232 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
233 .sp
234 When
235 \fIDevicePolicy=\fR
236 is set to
237 "closed"
238 or
239 "strict", or set to
240 "auto"
241 and
242 \fIDeviceAllow=\fR
243 is set, then this setting adds
244 /dev/loop\-control
245 with
246 \fBrw\fR
247 mode,
248 "block\-loop"
249 and
250 "block\-blkext"
251 with
252 \fBrwm\fR
253 mode to
254 \fIDeviceAllow=\fR\&. See
255 \fBsystemd.resource-control\fR(5)
256 for the details about
257 \fIDevicePolicy=\fR
258 or
259 \fIDeviceAllow=\fR\&. Also, see
260 \fIPrivateDevices=\fR
261 below, as it may change the setting of
262 \fIDevicePolicy=\fR\&.
263 .sp
264 Units making use of
265 \fIRootImage=\fR
266 automatically gain an
267 \fIAfter=\fR
268 dependency on
269 systemd\-udevd\&.service\&.
270 .sp
271 The host\*(Aqs
272 \fBos-release\fR(5)
273 file will be made available for the service (read\-only) as
274 /run/host/os\-release\&. It will be updated automatically on soft reboot (see:
275 \fBsystemd-soft-reboot.service\fR(8)), in case the service is configured to survive it\&.
276 .sp
277 In place of the image path a
278 "\&.v/"
279 versioned directory may be specified, see
280 \fBsystemd.v\fR(7)
281 for details\&.
282 .sp
283 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
284 .sp
285 Added in version 233\&.
286 .RE
287 .PP
288 \fIRootImageOptions=\fR
289 .RS 4
290 Takes a comma\-separated list of mount options that will be used on disk images specified by
291 \fIRootImage=\fR\&. Optionally a partition name can be prefixed, followed by colon, in case the image has multiple partitions, otherwise partition name
292 "root"
293 is implied\&. Options for multiple partitions can be specified in a single line with space separators\&. Assigning an empty string removes previous assignments\&. Duplicated options are ignored\&. For a list of valid mount options, please refer to
294 \fBmount\fR(8)\&.
295 .sp
296 Valid partition names follow the
297 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2:
298 \fBroot\fR,
299 \fBusr\fR,
300 \fBhome\fR,
301 \fBsrv\fR,
302 \fBesp\fR,
303 \fBxbootldr\fR,
304 \fBtmp\fR,
305 \fBvar\fR\&.
306 .sp
307 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
308 .sp
309 Added in version 247\&.
310 .RE
311 .PP
312 \fIRootEphemeral=\fR
313 .RS 4
314 Takes a boolean argument\&. If enabled, executed processes will run in an ephemeral copy of the root directory or root image\&. The ephemeral copy is placed in
315 /var/lib/systemd/ephemeral\-trees/
316 while the service is active and is cleaned up when the service is stopped or restarted\&. If
317 \fIRootDirectory=\fR
318 is used and the root directory is a subvolume, the ephemeral copy will be created by making a snapshot of the subvolume\&.
319 .sp
320 To make sure making ephemeral copies can be made efficiently, the root directory or root image should be located on the same filesystem as
321 /var/lib/systemd/ephemeral\-trees/\&. When using
322 \fIRootEphemeral=\fR
323 with root directories,
324 \fBbtrfs\fR(5)
325 should be used as the filesystem and the root directory should ideally be a subvolume which
326 \fBsystemd\fR
327 can snapshot to make the ephemeral copy\&. For root images, a filesystem with support for reflinks should be used to ensure an efficient ephemeral copy\&.
328 .sp
329 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
330 .sp
331 Added in version 254\&.
332 .RE
333 .PP
334 \fIRootHash=\fR
335 .RS 4
336 Takes a data integrity (dm\-verity) root hash specified in hexadecimal, or the path to a file containing a root hash in ASCII hexadecimal format\&. This option enables data integrity checks using dm\-verity, if the used image contains the appropriate integrity data (see above) or if
337 \fIRootVerity=\fR
338 is used\&. The specified hash must match the root hash of integrity data, and is usually at least 256 bits (and hence 64 formatted hexadecimal characters) long (in case of SHA256 for example)\&. If this option is not specified, but the image file carries the
339 "user\&.verity\&.roothash"
340 extended file attribute (see
341 \fBxattr\fR(7)), then the root hash is read from it, also as formatted hexadecimal characters\&. If the extended file attribute is not found (or is not supported by the underlying file system), but a file with the
342 \&.roothash
343 suffix is found next to the image file, bearing otherwise the same name (except if the image has the
344 \&.raw
345 suffix, in which case the root hash file must not have it in its name), the root hash is read from it and automatically used, also as formatted hexadecimal characters\&.
346 .sp
347 If the disk image contains a separate
348 /usr/
349 partition it may also be Verity protected, in which case the root hash may configured via an extended attribute
350 "user\&.verity\&.usrhash"
351 or a
352 \&.usrhash
353 file adjacent to the disk image\&. There\*(Aqs currently no option to configure the root hash for the
354 /usr/
355 file system via the unit file directly\&.
356 .sp
357 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
358 .sp
359 Added in version 246\&.
360 .RE
361 .PP
362 \fIRootHashSignature=\fR
363 .RS 4
364 Takes a PKCS7 signature of the
365 \fIRootHash=\fR
366 option as a path to a DER\-encoded signature file, or as an ASCII base64 string encoding of a DER\-encoded signature prefixed by
367 "base64:"\&. The dm\-verity volume will only be opened if the signature of the root hash is valid and signed by a public key present in the kernel keyring\&. If this option is not specified, but a file with the
368 \&.roothash\&.p7s
369 suffix is found next to the image file, bearing otherwise the same name (except if the image has the
370 \&.raw
371 suffix, in which case the signature file must not have it in its name), the signature is read from it and automatically used\&.
372 .sp
373 If the disk image contains a separate
374 /usr/
375 partition it may also be Verity protected, in which case the signature for the root hash may configured via a
376 \&.usrhash\&.p7s
377 file adjacent to the disk image\&. There\*(Aqs currently no option to configure the root hash signature for the
378 /usr/
379 via the unit file directly\&.
380 .sp
381 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
382 .sp
383 Added in version 246\&.
384 .RE
385 .PP
386 \fIRootVerity=\fR
387 .RS 4
388 Takes the path to a data integrity (dm\-verity) file\&. This option enables data integrity checks using dm\-verity, if
389 \fIRootImage=\fR
390 is used and a root\-hash is passed and if the used image itself does not contain the integrity data\&. The integrity data must be matched by the root hash\&. If this option is not specified, but a file with the
391 \&.verity
392 suffix is found next to the image file, bearing otherwise the same name (except if the image has the
393 \&.raw
394 suffix, in which case the verity data file must not have it in its name), the verity data is read from it and automatically used\&.
395 .sp
396 This option is supported only for disk images that contain a single file system, without an enveloping partition table\&. Images that contain a GPT partition table should instead include both root file system and matching Verity data in the same image, implementing the
397 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
398 .sp
399 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
400 .sp
401 Added in version 246\&.
402 .RE
403 .PP
404 \fIRootImagePolicy=\fR, \fIMountImagePolicy=\fR, \fIExtensionImagePolicy=\fR
405 .RS 4
406 Takes an image policy string as per
407 \fBsystemd.image-policy\fR(7)
408 to use when mounting the disk images (DDI) specified in
409 \fIRootImage=\fR,
410 \fIMountImage=\fR,
411 \fIExtensionImage=\fR, respectively\&. If not specified the following policy string is the default for
412 \fIRootImagePolicy=\fR
413 and
414 \fIMountImagePolicy\fR:
415 .sp
416 .if n \{\
417 .RS 4
418 .\}
419 .nf
420 root=verity+signed+encrypted+unprotected+absent: \e
421 usr=verity+signed+encrypted+unprotected+absent: \e
422 home=encrypted+unprotected+absent: \e
423 srv=encrypted+unprotected+absent: \e
424 tmp=encrypted+unprotected+absent: \e
425 var=encrypted+unprotected+absent
426 .fi
427 .if n \{\
428 .RE
429 .\}
430 .sp
431 The default policy for
432 \fIExtensionImagePolicy=\fR
433 is:
434 .sp
435 .if n \{\
436 .RS 4
437 .\}
438 .nf
439 root=verity+signed+encrypted+unprotected+absent: \e
440 usr=verity+signed+encrypted+unprotected+absent
441 .fi
442 .if n \{\
443 .RE
444 .\}
445 .sp
446 Added in version 254\&.
447 .RE
448 .PP
449 \fIMountAPIVFS=\fR
450 .RS 4
451 Takes a boolean argument\&. If on, a private mount namespace for the unit\*(Aqs processes is created and the API file systems
452 /proc/,
453 /sys/,
454 /dev/
455 and
456 /run/
457 (as an empty
458 "tmpfs") are mounted inside of it, unless they are already mounted\&. Note that this option has no effect unless used in conjunction with
459 \fIRootDirectory=\fR/\fIRootImage=\fR
460 as these four mounts are generally mounted in the host anyway, and unless the root directory is changed, the private mount namespace will be a 1:1 copy of the host\*(Aqs, and include these four mounts\&. Note that the
461 /dev/
462 file system of the host is bind mounted if this option is used without
463 \fIPrivateDevices=\fR\&. To run the service with a private, minimal version of
464 /dev/, combine this option with
465 \fIPrivateDevices=\fR\&.
466 .sp
467 In order to allow propagating mounts at runtime in a safe manner,
468 /run/systemd/propagate/
469 on the host will be used to set up new mounts, and
470 /run/host/incoming/
471 in the private namespace will be used as an intermediate step to store them before being moved to the final mount point\&.
472 .sp
473 Added in version 233\&.
474 .RE
475 .PP
476 \fIBindLogSockets=\fR
477 .RS 4
478 Takes a boolean argument\&. If true, sockets from
479 \fBsystemd-journald.socket\fR(8)
480 will be bind mounted into the mount namespace\&. This is particularly useful when a different instance of
481 /run/
482 is employed, to make sure processes running in the namespace can still make use of
483 \fBsd-journal\fR(3)\&.
484 .sp
485 This option is implied when
486 \fILogNamespace=\fR
487 is used, when
488 \fIMountAPIVFS=yes\fR, or when
489 \fIPrivateDevices=yes\fR
490 is used in conjunction with either
491 \fIRootDirectory=\fR
492 or
493 \fIRootImage=\fR\&.
494 .sp
495 Added in version 257\&.
496 .RE
497 .PP
498 \fIProtectProc=\fR
499 .RS 4
500 Takes one of
501 "noaccess",
502 "invisible",
503 "ptraceable"
504 or
505 "default"
506 (which it defaults to)\&. When set, this controls the
507 "hidepid="
508 mount option of the
509 "procfs"
510 instance for the unit that controls which directories with process metainformation (/proc/\fIPID\fR) are visible and accessible: when set to
511 "noaccess"
512 the ability to access most of other users\*(Aq process metadata in
513 /proc/
514 is taken away for processes of the service\&. When set to
515 "invisible"
516 processes owned by other users are hidden from
517 /proc/\&. If
518 "ptraceable"
519 all processes that cannot be
520 \fBptrace()\fR\*(Aqed by a process are hidden to it\&. If
521 "default"
522 no restrictions on
523 /proc/
524 access or visibility are made\&. For further details see
525 \m[blue]\fBThe /proc Filesystem\fR\m[]\&\s-2\u[2]\d\s+2\&. It is generally recommended to run most system services with this option set to
526 "invisible"\&. This option is implemented via file system namespacing, and thus cannot be used with services that shall be able to install mount points in the host file system hierarchy\&. Note that the root user is unaffected by this option, so to be effective it has to be used together with
527 \fIUser=\fR
528 or
529 \fIDynamicUser=yes\fR, and also without the
530 "CAP_SYS_PTRACE"
531 capability, which also allows a process to bypass this feature\&. It cannot be used for services that need to access metainformation about other users\*(Aq processes\&. This option implies
532 \fIMountAPIVFS=\fR\&.
533 .sp
534 If the kernel does not support per\-mount point
535 \fBhidepid=\fR
536 mount options this setting remains without effect, and the unit\*(Aqs processes will be able to access and see other process as if the option was not used\&.
537 .sp
538 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
539 .sp
540 Added in version 247\&.
541 .RE
542 .PP
543 \fIProcSubset=\fR
544 .RS 4
545 Takes one of
546 "all"
547 (the default) and
548 "pid"\&. If
549 "pid", all files and directories not directly associated with process management and introspection are made invisible in the
550 /proc/
551 file system configured for the unit\*(Aqs processes\&. This controls the
552 "subset="
553 mount option of the
554 "procfs"
555 instance for the unit\&. For further details see
556 \m[blue]\fBThe /proc Filesystem\fR\m[]\&\s-2\u[2]\d\s+2\&. Note that Linux exposes various kernel APIs via
557 /proc/, which are made unavailable with this setting\&. Since these APIs are used frequently this option is useful only in a few, specific cases, and is not suitable for most non\-trivial programs\&.
558 .sp
559 Much like
560 \fIProtectProc=\fR
561 above, this is implemented via file system mount namespacing, and hence the same restrictions apply: it is only available to system services, it disables mount propagation to the host mount table, and it implies
562 \fIMountAPIVFS=\fR\&. Also, like
563 \fIProtectProc=\fR
564 this setting is gracefully disabled if the used kernel does not support the
565 "subset="
566 mount option of
567 "procfs"\&.
568 .sp
569 Added in version 247\&.
570 .RE
571 .PP
572 \fIBindPaths=\fR, \fIBindReadOnlyPaths=\fR
573 .RS 4
574 Configures unit\-specific bind mounts\&. A bind mount makes a particular file or directory available at an additional place in the unit\*(Aqs view of the file system\&. Any bind mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&. This option expects a whitespace separated list of bind mount definitions\&. Each definition consists of a colon\-separated triple of source path, destination path and option string, where the latter two are optional\&. If only a source path is specified the source and destination is taken to be the same\&. The option string may be either
575 "rbind"
576 or
577 "norbind"
578 for configuring a recursive or non\-recursive bind mount\&. If the destination path is omitted, the option string must be omitted too\&. Each bind mount definition may be prefixed with
579 "\-", in which case it will be ignored when its source path does not exist\&.
580 .sp
581 \fIBindPaths=\fR
582 creates regular writable bind mounts (unless the source file system mount is already marked read\-only), while
583 \fIBindReadOnlyPaths=\fR
584 creates read\-only bind mounts\&. These settings may be used more than once, each usage appends to the unit\*(Aqs list of bind mounts\&. If the empty string is assigned to either of these two options the entire list of bind mounts defined prior to this is reset\&. Note that in this case both read\-only and regular bind mounts are reset, regardless which of the two settings is used\&.
585 .sp
586 Using this option implies that a mount namespace is allocated for the unit, i\&.e\&. it implies the effect of
587 \fIPrivateMounts=\fR
588 (see below)\&.
589 .sp
590 This option is particularly useful when
591 \fIRootDirectory=\fR/\fIRootImage=\fR
592 is used\&. In this case the source path refers to a path on the host file system, while the destination path refers to a path below the root directory of the unit\&.
593 .sp
594 Note that the destination directory must exist or systemd must be able to create it\&. Thus, it is not possible to use those options for mount points nested underneath paths specified in
595 \fIInaccessiblePaths=\fR, or under
596 /home/
597 and other protected directories if
598 \fIProtectHome=yes\fR
599 is specified\&.
600 \fITemporaryFileSystem=\fR
601 with
602 ":ro"
603 or
604 \fIProtectHome=tmpfs\fR
605 should be used instead\&.
606 .sp
607 Added in version 233\&.
608 .RE
609 .PP
610 \fIMountImages=\fR
611 .RS 4
612 This setting is similar to
613 \fIRootImage=\fR
614 in that it mounts a file system hierarchy from a block device node or loopback file, but the destination directory can be specified as well as mount options\&. This option expects a whitespace separated list of mount definitions\&. Each definition consists of a colon\-separated tuple of source path and destination definitions, optionally followed by another colon and a list of mount options\&.
615 .sp
616 Mount options may be defined as a single comma\-separated list of options, in which case they will be implicitly applied to the root partition on the image, or a series of colon\-separated tuples of partition name and mount options\&. Valid partition names and mount options are the same as for
617 \fIRootImageOptions=\fR
618 setting described above\&.
619 .sp
620 Each mount definition may be prefixed with
621 "\-", in which case it will be ignored when its source path does not exist\&. The source argument is a path to a block device node or regular file\&. If source or destination contain a
622 ":", it needs to be escaped as
623 "\e:"\&. The device node or file system image file needs to follow the same rules as specified for
624 \fIRootImage=\fR\&. Any mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&.
625 .sp
626 These settings may be used more than once, each usage appends to the unit\*(Aqs list of mount paths\&. If the empty string is assigned, the entire list of mount paths defined prior to this is reset\&.
627 .sp
628 Note that the destination directory must exist or systemd must be able to create it\&. Thus, it is not possible to use those options for mount points nested underneath paths specified in
629 \fIInaccessiblePaths=\fR, or under
630 /home/
631 and other protected directories if
632 \fIProtectHome=yes\fR
633 is specified\&.
634 .sp
635 When
636 \fIDevicePolicy=\fR
637 is set to
638 "closed"
639 or
640 "strict", or set to
641 "auto"
642 and
643 \fIDeviceAllow=\fR
644 is set, then this setting adds
645 /dev/loop\-control
646 with
647 \fBrw\fR
648 mode,
649 "block\-loop"
650 and
651 "block\-blkext"
652 with
653 \fBrwm\fR
654 mode to
655 \fIDeviceAllow=\fR\&. See
656 \fBsystemd.resource-control\fR(5)
657 for the details about
658 \fIDevicePolicy=\fR
659 or
660 \fIDeviceAllow=\fR\&. Also, see
661 \fIPrivateDevices=\fR
662 below, as it may change the setting of
663 \fIDevicePolicy=\fR\&.
664 .sp
665 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
666 .sp
667 Added in version 247\&.
668 .RE
669 .PP
670 \fIExtensionImages=\fR
671 .RS 4
672 This setting is similar to
673 \fIMountImages=\fR
674 in that it mounts a file system hierarchy from a block device node or loopback file, but instead of providing a destination path, an overlay will be set up\&. This option expects a whitespace separated list of mount definitions\&. Each definition consists of a source path, optionally followed by a colon and a list of mount options\&.
675 .sp
676 A read\-only OverlayFS will be set up on top of
677 /usr/
678 and
679 /opt/
680 hierarchies for sysext images and
681 /etc/
682 hierarchy for confext images\&. The order in which the images are listed will determine the order in which the overlay is laid down: images specified first to last will result in overlayfs layers bottom to top\&.
683 .sp
684 Mount options may be defined as a single comma\-separated list of options, in which case they will be implicitly applied to the root partition on the image, or a series of colon\-separated tuples of partition name and mount options\&. Valid partition names and mount options are the same as for
685 \fIRootImageOptions=\fR
686 setting described above\&.
687 .sp
688 Each mount definition may be prefixed with
689 "\-", in which case it will be ignored when its source path does not exist\&. The source argument is a path to a block device node or regular file\&. If the source path contains a
690 ":", it needs to be escaped as
691 "\e:"\&. The device node or file system image file needs to follow the same rules as specified for
692 \fIRootImage=\fR\&. Any mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&.
693 .sp
694 These settings may be used more than once, each usage appends to the unit\*(Aqs list of image paths\&. If the empty string is assigned, the entire list of mount paths defined prior to this is reset\&.
695 .sp
696 Each sysext image must carry a
697 /usr/lib/extension\-release\&.d/extension\-release\&.IMAGE
698 file while each confext image must carry a
699 /etc/extension\-release\&.d/extension\-release\&.IMAGE
700 file, with the appropriate metadata which matches
701 \fIRootImage=\fR/\fIRootDirectory=\fR
702 or the host\&. See:
703 \fBos-release\fR(5)\&. To disable the safety check that the extension\-release file name matches the image file name, the
704 \fIx\-systemd\&.relax\-extension\-release\-check\fR
705 mount option may be appended\&.
706 .sp
707 When
708 \fIDevicePolicy=\fR
709 is set to
710 "closed"
711 or
712 "strict", or set to
713 "auto"
714 and
715 \fIDeviceAllow=\fR
716 is set, then this setting adds
717 /dev/loop\-control
718 with
719 \fBrw\fR
720 mode,
721 "block\-loop"
722 and
723 "block\-blkext"
724 with
725 \fBrwm\fR
726 mode to
727 \fIDeviceAllow=\fR\&. See
728 \fBsystemd.resource-control\fR(5)
729 for the details about
730 \fIDevicePolicy=\fR
731 or
732 \fIDeviceAllow=\fR\&. Also, see
733 \fIPrivateDevices=\fR
734 below, as it may change the setting of
735 \fIDevicePolicy=\fR\&.
736 .sp
737 In place of the image path a
738 "\&.v/"
739 versioned directory may be specified, see
740 \fBsystemd.v\fR(7)
741 for details\&.
742 .sp
743 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
744 .sp
745 Added in version 248\&.
746 .RE
747 .PP
748 \fIExtensionDirectories=\fR
749 .RS 4
750 This setting is similar to
751 \fIBindReadOnlyPaths=\fR
752 in that it mounts a file system hierarchy from a directory, but instead of providing a destination path, an overlay will be set up\&. This option expects a whitespace separated list of source directories\&.
753 .sp
754 A read\-only OverlayFS will be set up on top of
755 /usr/
756 and
757 /opt/
758 hierarchies for sysext images and
759 /etc/
760 hierarchy for confext images\&. The order in which the directories are listed will determine the order in which the overlay is laid down: directories specified first to last will result in overlayfs layers bottom to top\&.
761 .sp
762 Each directory listed in
763 \fIExtensionDirectories=\fR
764 may be prefixed with
765 "\-", in which case it will be ignored when its source path does not exist\&. Any mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&.
766 .sp
767 These settings may be used more than once, each usage appends to the unit\*(Aqs list of directories paths\&. If the empty string is assigned, the entire list of mount paths defined prior to this is reset\&.
768 .sp
769 Each sysext directory must contain a
770 /usr/lib/extension\-release\&.d/extension\-release\&.IMAGE
771 file while each confext directory must carry a
772 /etc/extension\-release\&.d/extension\-release\&.IMAGE
773 file, with the appropriate metadata which matches
774 \fIRootImage=\fR/\fIRootDirectory=\fR
775 or the host\&. See:
776 \fBos-release\fR(5)\&.
777 .sp
778 Note that usage from user units requires overlayfs support in unprivileged user namespaces, which was first introduced in kernel v5\&.11\&.
779 .sp
780 In place of the directory path a
781 "\&.v/"
782 versioned directory may be specified, see
783 \fBsystemd.v\fR(7)
784 for details\&.
785 .sp
786 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
787 \fIPrivateUsers=\fR
788 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
789 "kernel\&.unprivileged_userns_clone="
790 sysctl)\&.
791 .sp
792 Added in version 251\&.
793 .RE
794 .SH "USER/GROUP IDENTITY"
795 .PP
796 These options are only available for system services and are not supported for services running in per\-user instances of the service manager\&.
797 .PP
798 \fIUser=\fR, \fIGroup=\fR
799 .RS 4
800 Set the UNIX user or group that the processes are executed as, respectively\&. Takes a single user or group name, or a numeric ID as argument\&. For system services (services run by the system service manager, i\&.e\&. managed by PID 1) and for user services of the root user (services managed by root\*(Aqs instance of
801 \fBsystemd \-\-user\fR), the default is
802 "root", but
803 \fIUser=\fR
804 may be used to specify a different user\&. For user services of any other user, switching user identity is not permitted, hence the only valid setting is the same user the user\*(Aqs service manager is running as\&. If no group is set, the default group of the user is used\&. This setting does not affect commands whose command line is prefixed with
805 "+"\&.
806 .sp
807 Note that this enforces only weak restrictions on the user/group name syntax, but will generate warnings in many cases where user/group names do not adhere to the following rules: the specified name should consist only of the characters a\-z, A\-Z, 0\-9,
808 "_"
809 and
810 "\-", except for the first character which must be one of a\-z, A\-Z and
811 "_"
812 (i\&.e\&. digits and
813 "\-"
814 are not permitted as first character)\&. The user/group name must have at least one character, and at most 31\&. These restrictions are made in order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux systems\&. For further details on the names accepted and the names warned about see
815 \m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[3]\d\s+2\&.
816 .sp
817 When used in conjunction with
818 \fIDynamicUser=\fR
819 the user/group name specified is dynamically allocated at the time the service is started, and released at the time the service is stopped \(em unless it is already allocated statically (see below)\&. If
820 \fIDynamicUser=\fR
821 is not used the specified user and group must have been created statically in the user database no later than the moment the service is started, for example using the
822 \fBsysusers.d\fR(5)
823 facility, which is applied at boot or package install time\&. If the user does not exist by then program invocation will fail\&.
824 .sp
825 If the
826 \fIUser=\fR
827 setting is used the supplementary group list is initialized from the specified user\*(Aqs default group list, as defined in the system\*(Aqs user and group database\&. Additional groups may be configured through the
828 \fISupplementaryGroups=\fR
829 setting (see below)\&.
830 .RE
831 .PP
832 \fIDynamicUser=\fR
833 .RS 4
834 Takes a boolean parameter\&. If set, a UNIX user and group pair is allocated dynamically when the unit is started, and released as soon as it is stopped\&. The user and group will not be added to
835 /etc/passwd
836 or
837 /etc/group, but are managed transiently during runtime\&. The
838 \fBnss-systemd\fR(8)
839 glibc NSS module provides integration of these dynamic users/groups into the system\*(Aqs user and group databases\&. The user and group name to use may be configured via
840 \fIUser=\fR
841 and
842 \fIGroup=\fR
843 (see above)\&. If these options are not used and dynamic user/group allocation is enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name\&. If the unit name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a hash of it is used\&. If a statically allocated user or group of the configured name already exists, it is used and no dynamic user/group is allocated\&. Note that if
844 \fIUser=\fR
845 is specified and the static group with the name exists, then it is required that the static user with the name already exists\&. Similarly, if
846 \fIGroup=\fR
847 is specified and the static user with the name exists, then it is required that the static group with the name already exists\&. Dynamic users/groups are allocated from the UID/GID range 61184\&...65519\&. It is recommended to avoid this range for regular system or login users\&. At any point in time each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in use\&. However, UID/GIDs are recycled after a unit is terminated\&. Care should be taken that any processes running as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to these files or directories\&. If
848 \fIDynamicUser=\fR
849 is enabled,
850 \fIRemoveIPC=\fR
851 is implied (and cannot be turned off)\&. This ensures that the lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic user/group\&. Since
852 /tmp/
853 and
854 /var/tmp/
855 are usually the only world\-writable directories on a system, unless
856 \fIPrivateTmp=\fR
857 is manually set to
858 "true",
859 "disconnected"
860 would be implied\&. This ensures that a unit making use of dynamic user/group allocation cannot leave files around after unit termination\&. Furthermore
861 \fINoNewPrivileges=\fR
862 and
863 \fIRestrictSUIDSGID=\fR
864 are implicitly enabled (and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID files or directories\&. Moreover
865 \fIProtectSystem=strict\fR
866 and
867 \fIProtectHome=read\-only\fR
868 are implied, thus prohibiting the service to write to arbitrary file system locations\&. In order to allow the service to write to certain directories, they have to be allow\-listed using
869 \fIReadWritePaths=\fR, but care must be taken so that UID/GID recycling does not create security issues involving files created by the service\&. Use
870 \fIRuntimeDirectory=\fR
871 (see below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and removed automatically when the unit is terminated\&. Use
872 \fIStateDirectory=\fR,
873 \fICacheDirectory=\fR
874 and
875 \fILogsDirectory=\fR
876 in order to assign a set of writable directories for specific purposes to the service in a way that they are protected from vulnerabilities due to UID reuse (see below)\&. If this option is enabled, care should be taken that the unit\*(Aqs processes do not get access to directories outside of these explicitly configured and managed ones\&. Specifically, do not use
877 \fIBindPaths=\fR
878 and be careful with
879 \fBAF_UNIX\fR
880 file descriptor passing for directory file descriptors, as this would permit processes to create files or directories owned by the dynamic user/group that are not subject to the lifecycle and access guarantees of the service\&. Note that this option is currently incompatible with D\-Bus policies, thus a service using this option may currently not allocate a D\-Bus service name (note that this does not affect calling into other D\-Bus services)\&. Defaults to off\&.
881 .sp
882 Added in version 232\&.
883 .RE
884 .PP
885 \fISupplementaryGroups=\fR
886 .RS 4
887 Sets the supplementary Unix groups the processes are executed as\&. This takes a space\-separated list of group names or IDs\&. This option may be specified more than once, in which case all listed groups are set as supplementary groups\&. When the empty string is assigned, the list of supplementary groups is reset, and all assignments prior to this one will have no effect\&. In any way, this option does not override, but extends the list of supplementary groups configured in the system group database for the user\&. This does not affect commands prefixed with
888 "+"\&.
889 .RE
890 .PP
891 \fISetLoginEnvironment=\fR
892 .RS 4
893 Takes a boolean parameter that controls whether to set the
894 \fI$HOME\fR,
895 \fI$LOGNAME\fR, and
896 \fI$SHELL\fR
897 environment variables\&. If not set, this defaults to true if
898 \fIUser=\fR,
899 \fIDynamicUser=\fR
900 or
901 \fIPAMName=\fR
902 are set, false otherwise\&. If set to true, the variables will always be set for system services, i\&.e\&. even when the default user
903 "root"
904 is used\&. If set to false, the mentioned variables are not set by the service manager, no matter whether
905 \fIUser=\fR,
906 \fIDynamicUser=\fR, or
907 \fIPAMName=\fR
908 are used or not\&. This option normally has no effect on services of the per\-user service manager, since in that case these variables are typically inherited from user manager\*(Aqs own environment anyway\&.
909 .sp
910 Added in version 255\&.
911 .RE
912 .PP
913 \fIPAMName=\fR
914 .RS 4
915 Sets the PAM service name to set up a session as\&. If set, the executed process will be registered as a PAM session under the specified service name\&. This is only useful in conjunction with the
916 \fIUser=\fR
917 setting, and is otherwise ignored\&. If not set, no PAM session will be opened for the executed processes\&. See
918 \fBpam\fR(8)
919 for details\&.
920 .sp
921 Note that for each unit making use of this option a PAM session handler process will be maintained as part of the unit and stays around as long as the unit is active, to ensure that appropriate actions can be taken when the unit and hence the PAM session terminates\&. This process is named
922 "(sd\-pam)"
923 and is an immediate child process of the unit\*(Aqs main process\&.
924 .sp
925 Note that when this option is used for a unit it is very likely (depending on PAM configuration) that the main unit process will be migrated to its own session scope unit when it is activated\&. This process will hence be associated with two units: the unit it was originally started from (and for which
926 \fIPAMName=\fR
927 was configured), and the session scope unit\&. Any child processes of that process will however be associated with the session scope unit only\&. This has implications when used in combination with
928 \fINotifyAccess=\fR\fBall\fR, as these child processes will not be able to affect changes in the original unit through notification messages\&. These messages will be considered belonging to the session scope unit and not the original unit\&. It is hence not recommended to use
929 \fIPAMName=\fR
930 in combination with
931 \fINotifyAccess=\fR\fBall\fR\&.
932 .RE
933 .SH "CAPABILITIES"
934 .PP
935 These options are only available for system services, or for services running in per\-user instances of the service manager in which case
936 \fIPrivateUsers=\fR
937 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
938 "kernel\&.unprivileged_userns_clone="
939 sysctl)\&.
940 .PP
941 \fICapabilityBoundingSet=\fR
942 .RS 4
943 Controls which capabilities to include in the capability bounding set for the executed process\&. See
944 \fBcapabilities\fR(7)
945 for details\&. Takes a whitespace\-separated list of capability names, e\&.g\&.
946 \fBCAP_SYS_ADMIN\fR,
947 \fBCAP_DAC_OVERRIDE\fR,
948 \fBCAP_SYS_PTRACE\fR\&. Capabilities listed will be included in the bounding set, all others are removed\&. If the list of capabilities is prefixed with
949 "~", all but the listed capabilities will be included, the effect of the assignment inverted\&. Note that this option also affects the respective capabilities in the effective, permitted and inheritable capability sets\&. If this option is not used, the capability bounding set is not modified on process execution, hence no limits on the capabilities of the process are enforced\&. This option may appear more than once, in which case the bounding sets are merged by
950 \fBOR\fR, or by
951 \fBAND\fR
952 if the lines are prefixed with
953 "~"
954 (see below)\&. If the empty string is assigned to this option, the bounding set is reset to the empty capability set, and all prior settings have no effect\&. If set to
955 "~"
956 (without any further argument), the bounding set is reset to the full set of available capabilities, also undoing any previous settings\&. This does not affect commands prefixed with
957 "+"\&.
958 .sp
959 Use
960 \fBsystemd-analyze\fR(1)\*(Aqs
961 \fBcapability\fR
962 command to retrieve a list of capabilities defined on the local system\&.
963 .sp
964 Example: if a unit has the following,
965 .sp
966 .if n \{\
967 .RS 4
968 .\}
969 .nf
970 CapabilityBoundingSet=CAP_A CAP_B
971 CapabilityBoundingSet=CAP_B CAP_C
972 .fi
973 .if n \{\
974 .RE
975 .\}
976 .sp
977 then
978 \fBCAP_A\fR,
979 \fBCAP_B\fR, and
980 \fBCAP_C\fR
981 are set\&. If the second line is prefixed with
982 "~", e\&.g\&.,
983 .sp
984 .if n \{\
985 .RS 4
986 .\}
987 .nf
988 CapabilityBoundingSet=CAP_A CAP_B
989 CapabilityBoundingSet=~CAP_B CAP_C
990 .fi
991 .if n \{\
992 .RE
993 .\}
994 .sp
995 then, only
996 \fBCAP_A\fR
997 is set\&.
998 .RE
999 .PP
1000 \fIAmbientCapabilities=\fR
1001 .RS 4
1002 Controls which capabilities to include in the ambient capability set for the executed process\&. Takes a whitespace\-separated list of capability names, e\&.g\&.
1003 \fBCAP_SYS_ADMIN\fR,
1004 \fBCAP_DAC_OVERRIDE\fR,
1005 \fBCAP_SYS_PTRACE\fR\&. This option may appear more than once, in which case the ambient capability sets are merged (see the above examples in
1006 \fICapabilityBoundingSet=\fR)\&. If the list of capabilities is prefixed with
1007 "~", all but the listed capabilities will be included, the effect of the assignment inverted\&. If the empty string is assigned to this option, the ambient capability set is reset to the empty capability set, and all prior settings have no effect\&. If set to
1008 "~"
1009 (without any further argument), the ambient capability set is reset to the full set of available capabilities, also undoing any previous settings\&. Note that adding capabilities to the ambient capability set adds them to the process\*(Aqs inherited capability set\&.
1010 .sp
1011 Ambient capability sets are useful if you want to execute a process as a non\-privileged user but still want to give it some capabilities\&. Note that in this case option
1012 \fBkeep\-caps\fR
1013 is automatically added to
1014 \fISecureBits=\fR
1015 to retain the capabilities over the user change\&.
1016 \fIAmbientCapabilities=\fR
1017 does not affect commands prefixed with
1018 "+"\&.
1019 .sp
1020 Added in version 229\&.
1021 .RE
1022 .SH "SECURITY"
1023 .PP
1024 \fINoNewPrivileges=\fR
1025 .RS 4
1026 Takes a boolean argument\&. If true, ensures that the service process and all its children can never gain new privileges through
1027 \fBexecve()\fR
1028 (e\&.g\&. via setuid or setgid bits, or filesystem capabilities)\&. This is the simplest and most effective way to ensure that a process and its children can never elevate privileges again\&. Defaults to false\&. In case the service will be run in a new mount namespace anyway and SELinux is disabled, all file systems are mounted with
1029 \fBMS_NOSUID\fR
1030 flag\&. Also see
1031 \m[blue]\fBNo New Privileges Flag\fR\m[]\&\s-2\u[4]\d\s+2\&.
1032 .sp
1033 Note that this setting only has an effect on the unit\*(Aqs processes themselves (or any processes directly or indirectly forked off them)\&. It has no effect on processes potentially invoked on request of them through tools such as
1034 \fBat\fR(1),
1035 \fBcrontab\fR(1),
1036 \fBsystemd-run\fR(1), or arbitrary IPC services\&.
1037 .sp
1038 Added in version 187\&.
1039 .RE
1040 .PP
1041 \fISecureBits=\fR
1042 .RS 4
1043 Controls the secure bits set for the executed process\&. Takes a space\-separated combination of options from the following list:
1044 \fBkeep\-caps\fR,
1045 \fBkeep\-caps\-locked\fR,
1046 \fBno\-setuid\-fixup\fR,
1047 \fBno\-setuid\-fixup\-locked\fR,
1048 \fBnoroot\fR, and
1049 \fBnoroot\-locked\fR\&. This option may appear more than once, in which case the secure bits are ORed\&. If the empty string is assigned to this option, the bits are reset to 0\&. This does not affect commands prefixed with
1050 "+"\&. See
1051 \fBcapabilities\fR(7)
1052 for details\&.
1053 .RE
1054 .SH "MANDATORY ACCESS CONTROL"
1055 .PP
1056 \fISELinuxContext=\fR
1057 .RS 4
1058 Set the SELinux security context of the executed process\&. If set, this will override the automated domain transition\&. However, the policy still needs to authorize the transition\&. This directive is ignored if SELinux is disabled\&. If prefixed by
1059 "\-", failing to set the SELinux security context will be ignored, but it is still possible that the subsequent
1060 \fBexecve()\fR
1061 may fail if the policy does not allow the transition for the non\-overridden context\&. This does not affect commands prefixed with
1062 "+"\&. See
1063 \fBsetexeccon\fR(3)
1064 for details\&.
1065 .sp
1066 Added in version 209\&.
1067 .RE
1068 .PP
1069 \fIAppArmorProfile=\fR
1070 .RS 4
1071 Takes a profile name as argument\&. The process executed by the unit will switch to this profile when started\&. Profiles must already be loaded in the kernel, or the unit will fail\&. If prefixed by
1072 "\-", all errors will be ignored\&. This setting has no effect if AppArmor is not enabled\&. This setting does not affect commands prefixed with
1073 "+"\&.
1074 .sp
1075 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
1076 .sp
1077 Added in version 210\&.
1078 .RE
1079 .PP
1080 \fISmackProcessLabel=\fR
1081 .RS 4
1082 Takes a
1083 \fBSMACK64\fR
1084 security label as argument\&. The process executed by the unit will be started under this label and SMACK will decide whether the process is allowed to run or not, based on it\&. The process will continue to run under the label specified here unless the executable has its own
1085 \fBSMACK64EXEC\fR
1086 label, in which case the process will transition to run under that label\&. When not specified, the label that systemd is running under is used\&. This directive is ignored if SMACK is disabled\&.
1087 .sp
1088 The value may be prefixed by
1089 "\-", in which case all errors will be ignored\&. An empty value may be specified to unset previous assignments\&. This does not affect commands prefixed with
1090 "+"\&.
1091 .sp
1092 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
1093 .sp
1094 Added in version 218\&.
1095 .RE
1096 .SH "PROCESS PROPERTIES"
1097 .PP
1098 \fILimitCPU=\fR, \fILimitFSIZE=\fR, \fILimitDATA=\fR, \fILimitSTACK=\fR, \fILimitCORE=\fR, \fILimitRSS=\fR, \fILimitNOFILE=\fR, \fILimitAS=\fR, \fILimitNPROC=\fR, \fILimitMEMLOCK=\fR, \fILimitLOCKS=\fR, \fILimitSIGPENDING=\fR, \fILimitMSGQUEUE=\fR, \fILimitNICE=\fR, \fILimitRTPRIO=\fR, \fILimitRTTIME=\fR
1099 .RS 4
1100 Set soft and hard limits on various resources for executed processes\&. See
1101 \fBsetrlimit\fR(2)
1102 for details on the process resource limit concept\&. Process resource limits may be specified in two formats: either as single value to set a specific soft and hard limit to the same value, or as colon\-separated pair
1103 \fBsoft:hard\fR
1104 to set both limits individually (e\&.g\&.
1105 "LimitAS=4G:16G")\&. Use the string
1106 \fBinfinity\fR
1107 to configure no limit on a specific resource\&. The multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits measured in bytes (e\&.g\&.
1108 "LimitAS=16G")\&. For the limits referring to time values, the usual time units ms, s, min, h and so on may be used (see
1109 \fBsystemd.time\fR(7)
1110 for details)\&. Note that if no time unit is specified for
1111 \fILimitCPU=\fR
1112 the default unit of seconds is implied, while for
1113 \fILimitRTTIME=\fR
1114 the default unit of microseconds is implied\&. Also, note that the effective granularity of the limits might influence their enforcement\&. For example, time limits specified for
1115 \fILimitCPU=\fR
1116 will be rounded up implicitly to multiples of 1s\&. For
1117 \fILimitNICE=\fR
1118 the value may be specified in two syntaxes: if prefixed with
1119 "+"
1120 or
1121 "\-", the value is understood as regular Linux nice value in the range \-20\&...19\&. If not prefixed like this the value is understood as raw resource limit parameter in the range 0\&...40 (with 0 being equivalent to 1)\&.
1122 .sp
1123 Note that most process resource limits configured with these options are per\-process, and processes may fork in order to acquire a new set of resources that are accounted independently of the original process, and may thus escape limits set\&. Also note that
1124 \fILimitRSS=\fR
1125 is not implemented on Linux, and setting it has no effect\&. Often it is advisable to prefer the resource controls listed in
1126 \fBsystemd.resource-control\fR(5)
1127 over these per\-process limits, as they apply to services as a whole, may be altered dynamically at runtime, and are generally more expressive\&. For example,
1128 \fIMemoryMax=\fR
1129 is a more powerful (and working) replacement for
1130 \fILimitRSS=\fR\&.
1131 .sp
1132 Note that
1133 \fILimitNPROC=\fR
1134 will limit the number of processes from one (real) UID and not the number of processes started (forked) by the service\&. Therefore the limit is cumulative for all processes running under the same UID\&. Please also note that the
1135 \fILimitNPROC=\fR
1136 will not be enforced if the service is running as root (and not dropping privileges)\&. Due to these limitations,
1137 \fITasksMax=\fR
1138 (see
1139 \fBsystemd.resource-control\fR(5)) is typically a better choice than
1140 \fILimitNPROC=\fR\&.
1141 .sp
1142 Resource limits not configured explicitly for a unit default to the value configured in the various
1143 \fIDefaultLimitCPU=\fR,
1144 \fIDefaultLimitFSIZE=\fR, \&... options available in
1145 \fBsystemd-system.conf\fR(5), and \(en if not configured there \(en the kernel or per\-user defaults, as defined by the OS (the latter only for user services, see below)\&.
1146 .sp
1147 For system units these resource limits may be chosen freely\&. When these settings are configured in a user service (i\&.e\&. a service run by the per\-user instance of the service manager) they cannot be used to raise the limits above those set for the user manager itself when it was first invoked, as the user\*(Aqs service manager generally lacks the privileges to do so\&. In user context these configuration options are hence only useful to lower the limits passed in or to raise the soft limit to the maximum of the hard limit as configured for the user\&. To raise the user\*(Aqs limits further, the available configuration mechanisms differ between operating systems, but typically require privileges\&. In most cases it is possible to configure higher per\-user resource limits via PAM or by setting limits on the system service encapsulating the user\*(Aqs service manager, i\&.e\&. the user\*(Aqs instance of
1148 user@\&.service\&. After making such changes, make sure to restart the user\*(Aqs service manager\&.
1149 .sp
1150 .it 1 an-trap
1151 .nr an-no-space-flag 1
1152 .nr an-break-flag 1
1153 .br
1154 .B Table\ \&1.\ \&Resource limit directives, their equivalent ulimit shell commands and the unit used
1155 .TS
1156 allbox tab(:);
1157 lB lB lB lB.
1158 T{
1159 Directive
1160 T}:T{
1161 \fBulimit\fR equivalent
1162 T}:T{
1163 Unit
1164 T}:T{
1165 Notes
1166 T}
1167 .T&
1168 l l l l
1169 l l l l
1170 l l l l
1171 l l l l
1172 l l l l
1173 l l l l
1174 l l l l
1175 l l l l
1176 l l l l
1177 l l l l
1178 l l l l
1179 l l l l
1180 l l l l
1181 l l l l
1182 l l l l
1183 l l l l.
1184 T{
1185 LimitCPU=
1186 T}:T{
1187 ulimit \-t
1188 T}:T{
1189 Seconds
1190 T}:T{
1191 \-
1192 T}
1193 T{
1194 LimitFSIZE=
1195 T}:T{
1196 ulimit \-f
1197 T}:T{
1198 Bytes
1199 T}:T{
1200 \-
1201 T}
1202 T{
1203 LimitDATA=
1204 T}:T{
1205 ulimit \-d
1206 T}:T{
1207 Bytes
1208 T}:T{
1209 Do not use\&. This limits the allowed address range, not memory use! Defaults to unlimited and should not be lowered\&. To limit memory use, see \fIMemoryMax=\fR in \fBsystemd.resource-control\fR(5)\&.
1210 T}
1211 T{
1212 LimitSTACK=
1213 T}:T{
1214 ulimit \-s
1215 T}:T{
1216 Bytes
1217 T}:T{
1218 \-
1219 T}
1220 T{
1221 LimitCORE=
1222 T}:T{
1223 ulimit \-c
1224 T}:T{
1225 Bytes
1226 T}:T{
1227 \-
1228 T}
1229 T{
1230 LimitRSS=
1231 T}:T{
1232 ulimit \-m
1233 T}:T{
1234 Bytes
1235 T}:T{
1236 Do not use\&. No effect on Linux\&.
1237 T}
1238 T{
1239 LimitNOFILE=
1240 T}:T{
1241 ulimit \-n
1242 T}:T{
1243 Number of File Descriptors
1244 T}:T{
1245 Do not use\&. Be careful when raising the soft limit above 1024, since \fBselect\fR(2) cannot function with file descriptors above 1023 on Linux\&. Nowadays, the hard limit defaults to 524288, a very high value compared to historical defaults\&. Typically applications should increase their soft limit to the hard limit on their own, if they are OK with working with file descriptors above 1023, i\&.e\&. do not use \fBselect\fR(2)\&. Note that file descriptors are nowadays accounted like any other form of memory, thus there should not be any need to lower the hard limit\&. Use \fIMemoryMax=\fR to control overall service memory use, including file descriptor memory\&.
1246 T}
1247 T{
1248 LimitAS=
1249 T}:T{
1250 ulimit \-v
1251 T}:T{
1252 Bytes
1253 T}:T{
1254 Do not use\&. This limits the allowed address range, not memory use! Defaults to unlimited and should not be lowered\&. To limit memory use, see \fIMemoryMax=\fR in \fBsystemd.resource-control\fR(5)\&.
1255 T}
1256 T{
1257 LimitNPROC=
1258 T}:T{
1259 ulimit \-u
1260 T}:T{
1261 Number of Processes
1262 T}:T{
1263 This limit is enforced based on the number of processes belonging to the user\&. Typically it is better to track processes per service, i\&.e\&. use \fITasksMax=\fR, see \fBsystemd.resource-control\fR(5)\&.
1264 T}
1265 T{
1266 LimitMEMLOCK=
1267 T}:T{
1268 ulimit \-l
1269 T}:T{
1270 Bytes
1271 T}:T{
1272 \-
1273 T}
1274 T{
1275 LimitLOCKS=
1276 T}:T{
1277 ulimit \-x
1278 T}:T{
1279 Number of Locks
1280 T}:T{
1281 \-
1282 T}
1283 T{
1284 LimitSIGPENDING=
1285 T}:T{
1286 ulimit \-i
1287 T}:T{
1288 Number of Queued Signals
1289 T}:T{
1290 \-
1291 T}
1292 T{
1293 LimitMSGQUEUE=
1294 T}:T{
1295 ulimit \-q
1296 T}:T{
1297 Bytes
1298 T}:T{
1299 \-
1300 T}
1301 T{
1302 LimitNICE=
1303 T}:T{
1304 ulimit \-e
1305 T}:T{
1306 Nice Level
1307 T}:T{
1308 \-
1309 T}
1310 T{
1311 LimitRTPRIO=
1312 T}:T{
1313 ulimit \-r
1314 T}:T{
1315 Realtime Priority
1316 T}:T{
1317 \-
1318 T}
1319 T{
1320 LimitRTTIME=
1321 T}:T{
1322 ulimit \-R
1323 T}:T{
1324 Microseconds
1325 T}:T{
1326 \-
1327 T}
1328 .TE
1329 .sp 1
1330 .RE
1331 .PP
1332 \fIUMask=\fR
1333 .RS 4
1334 Controls the file mode creation mask\&. Takes an access mode in octal notation\&. See
1335 \fBumask\fR(2)
1336 for details\&. Defaults to 0022 for system units\&. For user units the default value is inherited from the per\-user service manager (whose default is in turn inherited from the system service manager, and thus typically also is 0022 \(em unless overridden by a PAM module)\&. In order to change the per\-user mask for all user services, consider setting the
1337 \fIUMask=\fR
1338 setting of the user\*(Aqs
1339 user@\&.service
1340 system service instance\&. The per\-user umask may also be set via the
1341 \fIumask\fR
1342 field of a user\*(Aqs
1343 \m[blue]\fBJSON User Record\fR\m[]\&\s-2\u[5]\d\s+2
1344 (for users managed by
1345 \fBsystemd-homed.service\fR(8)
1346 this field may be controlled via
1347 \fBhomectl \-\-umask=\fR)\&. It may also be set via a PAM module, such as
1348 \fBpam_umask\fR(8)\&.
1349 .RE
1350 .PP
1351 \fICoredumpFilter=\fR
1352 .RS 4
1353 Controls which types of memory mappings will be saved if the process dumps core (using the
1354 /proc/\fIpid\fR/coredump_filter
1355 file)\&. Takes a whitespace\-separated combination of mapping type names or numbers (with the default base 16)\&. Mapping type names are
1356 \fBprivate\-anonymous\fR,
1357 \fBshared\-anonymous\fR,
1358 \fBprivate\-file\-backed\fR,
1359 \fBshared\-file\-backed\fR,
1360 \fBelf\-headers\fR,
1361 \fBprivate\-huge\fR,
1362 \fBshared\-huge\fR,
1363 \fBprivate\-dax\fR,
1364 \fBshared\-dax\fR, and the special values
1365 \fBall\fR
1366 (all types) and
1367 \fBdefault\fR
1368 (the kernel default of
1369 "\fBprivate\-anonymous\fR \fBshared\-anonymous\fR \fBelf\-headers\fR \fBprivate\-huge\fR")\&. See
1370 \fBcore\fR(5)
1371 for the meaning of the mapping types\&. When specified multiple times, all specified masks are ORed\&. When not set, or if the empty value is assigned, the inherited value is not changed\&.
1372 .PP
1373 \fBExample\ \&2.\ \&Add DAX pages to the dump filter\fR
1374 .sp
1375 .if n \{\
1376 .RS 4
1377 .\}
1378 .nf
1379 CoredumpFilter=default private\-dax shared\-dax
1380 .fi
1381 .if n \{\
1382 .RE
1383 .\}
1384
1385 Added in version 246\&.
1386 .RE
1387 .PP
1388 \fIKeyringMode=\fR
1389 .RS 4
1390 Controls how the kernel session keyring is set up for the service (see
1391 \fBsession-keyring\fR(7)
1392 for details on the session keyring)\&. Takes one of
1393 \fBinherit\fR,
1394 \fBprivate\fR,
1395 \fBshared\fR\&. If set to
1396 \fBinherit\fR
1397 no special keyring setup is done, and the kernel\*(Aqs default behaviour is applied\&. If
1398 \fBprivate\fR
1399 is used a new session keyring is allocated when a service process is invoked, and it is not linked up with any user keyring\&. This is the recommended setting for system services, as this ensures that multiple services running under the same system user ID (in particular the root user) do not share their key material among each other\&. If
1400 \fBshared\fR
1401 is used a new session keyring is allocated as for
1402 \fBprivate\fR, but the user keyring of the user configured with
1403 \fIUser=\fR
1404 is linked into it, so that keys assigned to the user may be requested by the unit\*(Aqs processes\&. In this mode multiple units running processes under the same user ID may share key material\&. Unless
1405 \fBinherit\fR
1406 is selected the unique invocation ID for the unit (see below) is added as a protected key by the name
1407 "invocation_id"
1408 to the newly created session keyring\&. Defaults to
1409 \fBprivate\fR
1410 for services of the system service manager and to
1411 \fBinherit\fR
1412 for non\-service units and for services of the user service manager\&.
1413 .sp
1414 Added in version 235\&.
1415 .RE
1416 .PP
1417 \fIOOMScoreAdjust=\fR
1418 .RS 4
1419 Sets the adjustment value for the Linux kernel\*(Aqs Out\-Of\-Memory (OOM) killer score for executed processes\&. Takes an integer between \-1000 (to disable OOM killing of processes of this unit) and 1000 (to make killing of processes of this unit under memory pressure very likely)\&. See
1420 \m[blue]\fBThe /proc Filesystem\fR\m[]\&\s-2\u[6]\d\s+2
1421 for details\&. If not specified defaults to the OOM score adjustment level of the service manager itself, which is normally at 0\&.
1422 .sp
1423 Use the
1424 \fIOOMPolicy=\fR
1425 setting of service units to configure how the service manager shall react to the kernel OOM killer or
1426 \fBsystemd\-oomd\fR
1427 terminating a process of the service\&. See
1428 \fBsystemd.service\fR(5)
1429 for details\&.
1430 .RE
1431 .PP
1432 \fITimerSlackNSec=\fR
1433 .RS 4
1434 Sets the timer slack in nanoseconds for the executed processes\&. The timer slack controls the accuracy of wake\-ups triggered by timers\&. See
1435 \fBprctl\fR(2)
1436 for more information\&. Note that in contrast to most other time span definitions this parameter takes an integer value in nano\-seconds if no unit is specified\&. The usual time units are understood too\&.
1437 .RE
1438 .PP
1439 \fIPersonality=\fR
1440 .RS 4
1441 Controls which kernel architecture
1442 \fBuname\fR(2)
1443 shall report, when invoked by unit processes\&. Takes one of the architecture identifiers
1444 \fBarm64\fR,
1445 \fBarm64\-be\fR,
1446 \fBarm\fR,
1447 \fBarm\-be\fR,
1448 \fBx86\fR,
1449 \fBx86\-64\fR,
1450 \fBppc\fR,
1451 \fBppc\-le\fR,
1452 \fBppc64\fR,
1453 \fBppc64\-le\fR,
1454 \fBs390\fR
1455 or
1456 \fBs390x\fR\&. Which personality architectures are supported depends on the kernel\*(Aqs native architecture\&. Usually the 64\-bit versions of the various system architectures support their immediate 32\-bit personality architecture counterpart, but no others\&. For example,
1457 \fBx86\-64\fR
1458 systems support the
1459 \fBx86\-64\fR
1460 and
1461 \fBx86\fR
1462 personalities but no others\&. The personality feature is useful when running 32\-bit services on a 64\-bit host system\&. If not specified, the personality is left unmodified and thus reflects the personality of the host system\*(Aqs kernel\&. This option is not useful on architectures for which only one native word width was ever available, such as
1463 \fBm68k\fR
1464 (32\-bit only) or
1465 \fBalpha\fR
1466 (64\-bit only)\&.
1467 .sp
1468 Added in version 209\&.
1469 .RE
1470 .PP
1471 \fIIgnoreSIGPIPE=\fR
1472 .RS 4
1473 Takes a boolean argument\&. If true,
1474 \fBSIGPIPE\fR
1475 is ignored in the executed process\&. Defaults to true since
1476 \fBSIGPIPE\fR
1477 is generally only useful in shell pipelines\&.
1478 .RE
1479 .SH "SCHEDULING"
1480 .PP
1481 \fINice=\fR
1482 .RS 4
1483 Sets the default nice level (scheduling priority) for executed processes\&. Takes an integer between \-20 (highest priority) and 19 (lowest priority)\&. In case of resource contention, smaller values mean more resources will be made available to the unit\*(Aqs processes, larger values mean less resources will be made available\&. See
1484 \fBsetpriority\fR(2)
1485 for details\&.
1486 .RE
1487 .PP
1488 \fICPUSchedulingPolicy=\fR
1489 .RS 4
1490 Sets the CPU scheduling policy for executed processes\&. Takes one of
1491 \fBother\fR,
1492 \fBbatch\fR,
1493 \fBidle\fR,
1494 \fBfifo\fR
1495 or
1496 \fBrr\fR\&. See
1497 \fBsched_setscheduler\fR(2)
1498 for details\&.
1499 .RE
1500 .PP
1501 \fICPUSchedulingPriority=\fR
1502 .RS 4
1503 Sets the CPU scheduling priority for executed processes\&. The available priority range depends on the selected CPU scheduling policy (see above)\&. For real\-time scheduling policies an integer between 1 (lowest priority) and 99 (highest priority) can be used\&. In case of CPU resource contention, smaller values mean less CPU time is made available to the service, larger values mean more\&. See
1504 \fBsched_setscheduler\fR(2)
1505 for details\&.
1506 .RE
1507 .PP
1508 \fICPUSchedulingResetOnFork=\fR
1509 .RS 4
1510 Takes a boolean argument\&. If true, elevated CPU scheduling priorities and policies will be reset when the executed processes call
1511 \fBfork\fR(2), and can hence not leak into child processes\&. See
1512 \fBsched_setscheduler\fR(2)
1513 for details\&. Defaults to false\&.
1514 .RE
1515 .PP
1516 \fICPUAffinity=\fR
1517 .RS 4
1518 Controls the CPU affinity of the executed processes\&. Takes a list of CPU indices or ranges separated by either whitespace or commas\&. Alternatively, takes a special "numa" value in which case systemd automatically derives allowed CPU range based on the value of
1519 \fINUMAMask=\fR
1520 option\&. CPU ranges are specified by the lower and upper CPU indices separated by a dash\&. This option may be specified more than once, in which case the specified CPU affinity masks are merged\&. If the empty string is assigned, the mask is reset, all assignments prior to this will have no effect\&. See
1521 \fBsched_setaffinity\fR(2)
1522 for details\&.
1523 .RE
1524 .PP
1525 \fINUMAPolicy=\fR
1526 .RS 4
1527 Controls the NUMA memory policy of the executed processes\&. Takes a policy type, one of:
1528 \fBdefault\fR,
1529 \fBpreferred\fR,
1530 \fBbind\fR,
1531 \fBinterleave\fR
1532 and
1533 \fBlocal\fR\&. A list of NUMA nodes that should be associated with the policy must be specified in
1534 \fINUMAMask=\fR\&. For more details on each policy please see,
1535 \fBset_mempolicy\fR(2)\&. For overall overview of NUMA support in Linux see,
1536 \fBnuma\fR(7)\&.
1537 .sp
1538 Added in version 243\&.
1539 .RE
1540 .PP
1541 \fINUMAMask=\fR
1542 .RS 4
1543 Controls the NUMA node list which will be applied alongside with selected NUMA policy\&. Takes a list of NUMA nodes and has the same syntax as a list of CPUs for
1544 \fICPUAffinity=\fR
1545 option or special "all" value which will include all available NUMA nodes in the mask\&. Note that the list of NUMA nodes is not required for
1546 \fBdefault\fR
1547 and
1548 \fBlocal\fR
1549 policies and for
1550 \fBpreferred\fR
1551 policy we expect a single NUMA node\&.
1552 .sp
1553 Added in version 243\&.
1554 .RE
1555 .PP
1556 \fIIOSchedulingClass=\fR
1557 .RS 4
1558 Sets the I/O scheduling class for executed processes\&. Takes one of the strings
1559 \fBrealtime\fR,
1560 \fBbest\-effort\fR
1561 or
1562 \fBidle\fR\&. The kernel\*(Aqs default scheduling class is
1563 \fBbest\-effort\fR
1564 at a priority of 4\&. If the empty string is assigned to this option, all prior assignments to both
1565 \fIIOSchedulingClass=\fR
1566 and
1567 \fIIOSchedulingPriority=\fR
1568 have no effect\&. See
1569 \fBioprio_set\fR(2)
1570 for details\&.
1571 .RE
1572 .PP
1573 \fIIOSchedulingPriority=\fR
1574 .RS 4
1575 Sets the I/O scheduling priority for executed processes\&. Takes an integer between 0 (highest priority) and 7 (lowest priority)\&. In case of I/O contention, smaller values mean more I/O bandwidth is made available to the unit\*(Aqs processes, larger values mean less bandwidth\&. The available priorities depend on the selected I/O scheduling class (see above)\&. If the empty string is assigned to this option, all prior assignments to both
1576 \fIIOSchedulingClass=\fR
1577 and
1578 \fIIOSchedulingPriority=\fR
1579 have no effect\&. For the kernel\*(Aqs default scheduling class (\fBbest\-effort\fR) this defaults to 4\&. See
1580 \fBioprio_set\fR(2)
1581 for details\&.
1582 .RE
1583 .SH "SANDBOXING"
1584 .PP
1585 The following sandboxing options are an effective way to limit the exposure of the system towards the unit\*(Aqs processes\&. It is recommended to turn on as many of these options for each unit as is possible without negatively affecting the process\*(Aq ability to operate\&. Note that many of these sandboxing features are gracefully turned off on systems where the underlying security mechanism is not available\&. For example,
1586 \fIProtectSystem=\fR
1587 has no effect if the kernel is built without file system namespacing or if the service manager runs in a container manager that makes file system namespacing unavailable to its payload\&. Similarly,
1588 \fIRestrictRealtime=\fR
1589 has no effect on systems that lack support for SECCOMP system call filtering, or in containers where support for this is turned off\&.
1590 .PP
1591 Also note that some sandboxing functionality is generally not available in user services (i\&.e\&. services run by the per\-user service manager)\&. Specifically, the various settings requiring file system namespacing support (such as
1592 \fIProtectSystem=\fR) are not available, as the underlying kernel functionality is only accessible to privileged processes\&. However, most namespacing settings, that will not work on their own in user services, will work when used in conjunction with
1593 \fIPrivateUsers=\fR\fBtrue\fR\&.
1594 .PP
1595 Note that the various options that turn directories read\-only (such as
1596 \fIProtectSystem=\fR,
1597 \fIReadOnlyPaths=\fR, \&...) do not affect the ability for programs to connect to and communicate with
1598 \fBAF_UNIX\fR
1599 sockets in these directories\&. These options cannot be used to lock down access to IPC services hence\&.
1600 .PP
1601 \fIProtectSystem=\fR
1602 .RS 4
1603 Takes a boolean argument or the special values
1604 "full"
1605 or
1606 "strict"\&. If true, mounts the
1607 /usr/
1608 and the boot loader directories (/boot
1609 and
1610 /efi) read\-only for processes invoked by this unit\&. If set to
1611 "full", the
1612 /etc/
1613 directory is mounted read\-only, too\&. If set to
1614 "strict"
1615 the entire file system hierarchy is mounted read\-only, except for the API file system subtrees
1616 /dev/,
1617 /proc/
1618 and
1619 /sys/
1620 (protect these directories using
1621 \fIPrivateDevices=\fR,
1622 \fIProtectKernelTunables=\fR,
1623 \fIProtectControlGroups=\fR)\&. This setting ensures that any modification of the vendor\-supplied operating system (and optionally its configuration, and local mounts) is prohibited for the service\&. It is recommended to enable this setting for all long\-running services, unless they are involved with system updates or need to modify the operating system in other ways\&. If this option is used,
1624 \fIReadWritePaths=\fR
1625 may be used to exclude specific directories from being made read\-only\&. Similar,
1626 \fIStateDirectory=\fR,
1627 \fILogsDirectory=\fR, \&... and related directory settings (see below) also exclude the specific directories from the effect of
1628 \fIProtectSystem=\fR\&. This setting is implied if
1629 \fIDynamicUser=\fR
1630 is set\&. This setting cannot ensure protection in all cases\&. In general it has the same limitations as
1631 \fIReadOnlyPaths=\fR, see below\&. Defaults to off\&.
1632 .sp
1633 Note that if
1634 \fIProtectSystem=\fR
1635 is set to
1636 "strict"
1637 and
1638 \fIPrivateTmp=\fR
1639 is enabled, then
1640 /tmp/
1641 and
1642 /var/tmp/
1643 will be writable\&.
1644 .sp
1645 Added in version 214\&.
1646 .RE
1647 .PP
1648 \fIProtectHome=\fR
1649 .RS 4
1650 Takes a boolean argument or the special values
1651 "read\-only"
1652 or
1653 "tmpfs"\&. If true, the directories
1654 /home/,
1655 /root, and
1656 /run/user
1657 are made inaccessible and empty for processes invoked by this unit\&. If set to
1658 "read\-only", the three directories are made read\-only instead\&. If set to
1659 "tmpfs", temporary file systems are mounted on the three directories in read\-only mode\&. The value
1660 "tmpfs"
1661 is useful to hide home directories not relevant to the processes invoked by the unit, while still allowing necessary directories to be made visible when listed in
1662 \fIBindPaths=\fR
1663 or
1664 \fIBindReadOnlyPaths=\fR\&.
1665 .sp
1666 Setting this to
1667 "yes"
1668 is mostly equivalent to setting the three directories in
1669 \fIInaccessiblePaths=\fR\&. Similarly,
1670 "read\-only"
1671 is mostly equivalent to
1672 \fIReadOnlyPaths=\fR, and
1673 "tmpfs"
1674 is mostly equivalent to
1675 \fITemporaryFileSystem=\fR
1676 with
1677 ":ro"\&.
1678 .sp
1679 It is recommended to enable this setting for all long\-running services (in particular network\-facing ones), to ensure they cannot get access to private user data, unless the services actually require access to the user\*(Aqs private data\&. This setting is implied if
1680 \fIDynamicUser=\fR
1681 is set\&. This setting cannot ensure protection in all cases\&. In general it has the same limitations as
1682 \fIReadOnlyPaths=\fR, see below\&.
1683 .sp
1684 Note that this setting provides no protection if home directories are placed at a non\-standard location, i\&.e\&. outside of the hierarchies listed above\&.
1685 .sp
1686 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
1687 \fIPrivateUsers=\fR
1688 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
1689 "kernel\&.unprivileged_userns_clone="
1690 sysctl)\&.
1691 .sp
1692 Added in version 214\&.
1693 .RE
1694 .PP
1695 \fIRuntimeDirectory=\fR, \fIStateDirectory=\fR, \fICacheDirectory=\fR, \fILogsDirectory=\fR, \fIConfigurationDirectory=\fR
1696 .RS 4
1697 These options take a whitespace\-separated list of directory names\&. The specified directory names must be relative, and may not include
1698 "\&.\&."\&. If set, when the unit is started, one or more directories by the specified names will be created (including their parents) below the locations defined in the following table\&. Also, the corresponding environment variable will be defined with the full paths of the directories\&. If multiple directories are set, then in the environment variable the paths are concatenated with colon (":")\&.
1699 .sp
1700 If
1701 \fIDynamicUser=\fR
1702 is used, and if the kernel version supports
1703 \m[blue]\fBid\-mapped mounts\fR\m[]\&\s-2\u[7]\d\s+2, the specified directories will be owned by "nobody" in the host namespace and will be mapped to (and will be owned by) the service\*(Aqs UID/GID in its own namespace\&. For backward compatibility, existing directories created without id\-mapped mounts will be kept untouched\&.
1704 .sp
1705 .it 1 an-trap
1706 .nr an-no-space-flag 1
1707 .nr an-break-flag 1
1708 .br
1709 .B Table\ \&2.\ \&Automatic directory creation and environment variables
1710 .TS
1711 allbox tab(:);
1712 lB lB lB lB.
1713 T{
1714 Directory
1715 T}:T{
1716 Below path for system units
1717 T}:T{
1718 Below path for user units
1719 T}:T{
1720 Environment variable set
1721 T}
1722 .T&
1723 l l l l
1724 l l l l
1725 l l l l
1726 l l l l
1727 l l l l.
1728 T{
1729 \fIRuntimeDirectory=\fR
1730 T}:T{
1731 /run/
1732 T}:T{
1733 \fI$XDG_RUNTIME_DIR\fR
1734 T}:T{
1735 \fI$RUNTIME_DIRECTORY\fR
1736 T}
1737 T{
1738 \fIStateDirectory=\fR
1739 T}:T{
1740 /var/lib/
1741 T}:T{
1742 \fI$XDG_STATE_HOME\fR
1743 T}:T{
1744 \fI$STATE_DIRECTORY\fR
1745 T}
1746 T{
1747 \fICacheDirectory=\fR
1748 T}:T{
1749 /var/cache/
1750 T}:T{
1751 \fI$XDG_CACHE_HOME\fR
1752 T}:T{
1753 \fI$CACHE_DIRECTORY\fR
1754 T}
1755 T{
1756 \fILogsDirectory=\fR
1757 T}:T{
1758 /var/log/
1759 T}:T{
1760 \fI$XDG_STATE_HOME\fR/log/
1761 T}:T{
1762 \fI$LOGS_DIRECTORY\fR
1763 T}
1764 T{
1765 \fIConfigurationDirectory=\fR
1766 T}:T{
1767 /etc/
1768 T}:T{
1769 \fI$XDG_CONFIG_HOME\fR
1770 T}:T{
1771 \fI$CONFIGURATION_DIRECTORY\fR
1772 T}
1773 .TE
1774 .sp 1
1775 In case of
1776 \fIRuntimeDirectory=\fR
1777 the innermost subdirectories are removed when the unit is stopped\&. It is possible to preserve the specified directories in this case if
1778 \fIRuntimeDirectoryPreserve=\fR
1779 is configured to
1780 \fBrestart\fR
1781 or
1782 \fByes\fR
1783 (see below)\&. The directories specified with
1784 \fIStateDirectory=\fR,
1785 \fICacheDirectory=\fR,
1786 \fILogsDirectory=\fR,
1787 \fIConfigurationDirectory=\fR
1788 are not removed when the unit is stopped\&.
1789 .sp
1790 Except in case of
1791 \fIConfigurationDirectory=\fR, the innermost specified directories will be owned by the user and group specified in
1792 \fIUser=\fR
1793 and
1794 \fIGroup=\fR\&. If the specified directories already exist and their owning user or group do not match the configured ones, all files and directories below the specified directories as well as the directories themselves will have their file ownership recursively changed to match what is configured\&. As an optimization, if the specified directories are already owned by the right user and group, files and directories below of them are left as\-is, even if they do not match what is requested\&. The innermost specified directories will have their access mode adjusted to the what is specified in
1795 \fIRuntimeDirectoryMode=\fR,
1796 \fIStateDirectoryMode=\fR,
1797 \fICacheDirectoryMode=\fR,
1798 \fILogsDirectoryMode=\fR
1799 and
1800 \fIConfigurationDirectoryMode=\fR\&.
1801 .sp
1802 These options imply
1803 \fIBindPaths=\fR
1804 for the specified paths\&. When combined with
1805 \fIRootDirectory=\fR
1806 or
1807 \fIRootImage=\fR
1808 these paths always reside on the host and are mounted from there into the unit\*(Aqs file system namespace\&.
1809 .sp
1810 If
1811 \fIDynamicUser=\fR
1812 is used, the logic for
1813 \fICacheDirectory=\fR,
1814 \fILogsDirectory=\fR
1815 and
1816 \fIStateDirectory=\fR
1817 is slightly altered: the directories are created below
1818 /var/cache/private,
1819 /var/log/private
1820 and
1821 /var/lib/private, respectively, which are host directories made inaccessible to unprivileged users, which ensures that access to these directories cannot be gained through dynamic user ID recycling\&. Symbolic links are created to hide this difference in behaviour\&. Both from perspective of the host and from inside the unit, the relevant directories hence always appear directly below
1822 /var/cache,
1823 /var/log
1824 and
1825 /var/lib\&.
1826 .sp
1827 Use
1828 \fIRuntimeDirectory=\fR
1829 to manage one or more runtime directories for the unit and bind their lifetime to the daemon runtime\&. This is particularly useful for unprivileged daemons that cannot create runtime directories in
1830 /run/
1831 due to lack of privileges, and to make sure the runtime directory is cleaned up automatically after use\&. For runtime directories that require more complex or different configuration or lifetime guarantees, please consider using
1832 \fBtmpfiles.d\fR(5)\&.
1833 .sp
1834 \fIRuntimeDirectory=\fR,
1835 \fIStateDirectory=\fR,
1836 \fICacheDirectory=\fR
1837 and
1838 \fILogsDirectory=\fR
1839 optionally support two more parameters, separated by
1840 ":"\&. The second parameter will be interpreted as a destination path that will be created as a symlink to the directory\&. The symlinks will be created after any
1841 \fIBindPaths=\fR
1842 or
1843 \fITemporaryFileSystem=\fR
1844 options have been set up, to make ephemeral symlinking possible\&. The same source can have multiple symlinks, by using the same first parameter, but a different second parameter\&. The third parameter is a flags field, and since v257 can take a value of
1845 \fBro\fR
1846 to make the directory read only for the service\&. This is also supported for
1847 \fIConfigurationDirectory=\fR\&. If multiple symlinks are set up, the directory will be read only if at least one is configured to be read only\&. To pass a flag without a destination symlink, the second parameter can be empty, for example:
1848 .sp
1849 .if n \{\
1850 .RS 4
1851 .\}
1852 .nf
1853 ConfigurationDirectory=foo::ro
1854 .fi
1855 .if n \{\
1856 .RE
1857 .\}
1858 .sp
1859 The directories defined by these options are always created under the standard paths used by systemd (/var/,
1860 /run/,
1861 /etc/, \&...)\&. If the service needs directories in a different location, a different mechanism has to be used to create them\&.
1862 .sp
1863 \fBtmpfiles.d\fR(5)
1864 provides functionality that overlaps with these options\&. Using these options is recommended, because the lifetime of the directories is tied directly to the lifetime of the unit, and it is not necessary to ensure that the
1865 tmpfiles\&.d
1866 configuration is executed before the unit is started\&.
1867 .sp
1868 To remove any of the directories created by these settings, use the
1869 \fBsystemctl clean \&...\fR
1870 command on the relevant units, see
1871 \fBsystemctl\fR(1)
1872 for details\&.
1873 .sp
1874 Example: if a system service unit has the following,
1875 .sp
1876 .if n \{\
1877 .RS 4
1878 .\}
1879 .nf
1880 RuntimeDirectory=foo/bar baz
1881 .fi
1882 .if n \{\
1883 .RE
1884 .\}
1885 .sp
1886 the service manager creates
1887 /run/foo
1888 (if it does not exist),
1889 /run/foo/bar, and
1890 /run/baz\&. The directories
1891 /run/foo/bar
1892 and
1893 /run/baz
1894 except
1895 /run/foo
1896 are owned by the user and group specified in
1897 \fIUser=\fR
1898 and
1899 \fIGroup=\fR, and removed when the service is stopped\&.
1900 .sp
1901 Example: if a system service unit has the following,
1902 .sp
1903 .if n \{\
1904 .RS 4
1905 .\}
1906 .nf
1907 RuntimeDirectory=foo/bar
1908 StateDirectory=aaa/bbb ccc
1909 .fi
1910 .if n \{\
1911 .RE
1912 .\}
1913 .sp
1914 then the environment variable
1915 "RUNTIME_DIRECTORY"
1916 is set with
1917 "/run/foo/bar", and
1918 "STATE_DIRECTORY"
1919 is set with
1920 "/var/lib/aaa/bbb:/var/lib/ccc"\&.
1921 .sp
1922 Example: if a system service unit has the following,
1923 .sp
1924 .if n \{\
1925 .RS 4
1926 .\}
1927 .nf
1928 RuntimeDirectory=foo:bar foo:baz
1929 .fi
1930 .if n \{\
1931 .RE
1932 .\}
1933 .sp
1934 the service manager creates
1935 /run/foo
1936 (if it does not exist), and
1937 /run/bar
1938 plus
1939 /run/baz
1940 as symlinks to
1941 /run/foo\&.
1942 .sp
1943 Added in version 211\&.
1944 .RE
1945 .PP
1946 \fIRuntimeDirectoryMode=\fR, \fIStateDirectoryMode=\fR, \fICacheDirectoryMode=\fR, \fILogsDirectoryMode=\fR, \fIConfigurationDirectoryMode=\fR
1947 .RS 4
1948 Specifies the access mode of the directories specified in
1949 \fIRuntimeDirectory=\fR,
1950 \fIStateDirectory=\fR,
1951 \fICacheDirectory=\fR,
1952 \fILogsDirectory=\fR, or
1953 \fIConfigurationDirectory=\fR, respectively, as an octal number\&. Defaults to
1954 \fB0755\fR\&. See "Permissions" in
1955 \fBpath_resolution\fR(7)
1956 for a discussion of the meaning of permission bits\&.
1957 .sp
1958 Added in version 234\&.
1959 .RE
1960 .PP
1961 \fIRuntimeDirectoryPreserve=\fR
1962 .RS 4
1963 Takes a boolean argument or
1964 \fBrestart\fR\&. If set to
1965 \fBno\fR
1966 (the default), the directories specified in
1967 \fIRuntimeDirectory=\fR
1968 are always removed when the service stops\&. If set to
1969 \fBrestart\fR
1970 the directories are preserved when the service is both automatically and manually restarted\&. Here, the automatic restart means the operation specified in
1971 \fIRestart=\fR, and manual restart means the one triggered by
1972 \fBsystemctl restart foo\&.service\fR\&. If set to
1973 \fByes\fR, then the directories are not removed when the service is stopped\&. Note that since the runtime directory
1974 /run/
1975 is a mount point of
1976 "tmpfs", then for system services the directories specified in
1977 \fIRuntimeDirectory=\fR
1978 are removed when the system is rebooted\&.
1979 .sp
1980 Added in version 235\&.
1981 .RE
1982 .PP
1983 \fITimeoutCleanSec=\fR
1984 .RS 4
1985 Configures a timeout on the clean\-up operation requested through
1986 \fBsystemctl clean \&...\fR, see
1987 \fBsystemctl\fR(1)
1988 for details\&. Takes the usual time values and defaults to
1989 \fBinfinity\fR, i\&.e\&. by default no timeout is applied\&. If a timeout is configured the clean operation will be aborted forcibly when the timeout is reached, potentially leaving resources on disk\&.
1990 .sp
1991 Added in version 244\&.
1992 .RE
1993 .PP
1994 \fIReadWritePaths=\fR, \fIReadOnlyPaths=\fR, \fIInaccessiblePaths=\fR, \fIExecPaths=\fR, \fINoExecPaths=\fR
1995 .RS 4
1996 Sets up a new file system namespace for executed processes\&. These options may be used to limit access a process has to the file system\&. Each setting takes a space\-separated list of paths relative to the host\*(Aqs root directory (i\&.e\&. the system running the service manager)\&. Note that if paths contain symlinks, they are resolved relative to the root directory set with
1997 \fIRootDirectory=\fR/\fIRootImage=\fR\&.
1998 .sp
1999 Paths listed in
2000 \fIReadWritePaths=\fR
2001 are accessible from within the namespace with the same access modes as from outside of it\&. Paths listed in
2002 \fIReadOnlyPaths=\fR
2003 are accessible for reading only, writing will be refused even if the usual file access controls would permit this\&. Nest
2004 \fIReadWritePaths=\fR
2005 inside of
2006 \fIReadOnlyPaths=\fR
2007 in order to provide writable subdirectories within read\-only directories\&. Use
2008 \fIReadWritePaths=\fR
2009 in order to allow\-list specific paths for write access if
2010 \fIProtectSystem=strict\fR
2011 is used\&. Note that
2012 \fIReadWritePaths=\fR
2013 cannot be used to gain write access to a file system whose superblock is mounted read\-only\&. On Linux, for each mount point write access is granted only if the mount point itself
2014 \fIand\fR
2015 the file system superblock backing it are not marked read\-only\&.
2016 \fIReadWritePaths=\fR
2017 only controls the former, not the latter, hence a read\-only file system superblock remains protected\&.
2018 .sp
2019 Paths listed in
2020 \fIInaccessiblePaths=\fR
2021 will be made inaccessible for processes inside the namespace along with everything below them in the file system hierarchy\&. This may be more restrictive than desired, because it is not possible to nest
2022 \fIReadWritePaths=\fR,
2023 \fIReadOnlyPaths=\fR,
2024 \fIBindPaths=\fR, or
2025 \fIBindReadOnlyPaths=\fR
2026 inside it\&. For a more flexible option, see
2027 \fITemporaryFileSystem=\fR\&.
2028 .sp
2029 Content in paths listed in
2030 \fINoExecPaths=\fR
2031 are not executable even if the usual file access controls would permit this\&. Nest
2032 \fIExecPaths=\fR
2033 inside of
2034 \fINoExecPaths=\fR
2035 in order to provide executable content within non\-executable directories\&.
2036 .sp
2037 Non\-directory paths may be specified as well\&. These options may be specified more than once, in which case all paths listed will have limited access from within the namespace\&. If the empty string is assigned to this option, the specific list is reset, and all prior assignments have no effect\&.
2038 .sp
2039 Paths in
2040 \fIReadWritePaths=\fR,
2041 \fIReadOnlyPaths=\fR,
2042 \fIInaccessiblePaths=\fR,
2043 \fIExecPaths=\fR
2044 and
2045 \fINoExecPaths=\fR
2046 may be prefixed with
2047 "\-", in which case they will be ignored when they do not exist\&. If prefixed with
2048 "+"
2049 the paths are taken relative to the root directory of the unit, as configured with
2050 \fIRootDirectory=\fR/\fIRootImage=\fR, instead of relative to the root directory of the host (see above)\&. When combining
2051 "\-"
2052 and
2053 "+"
2054 on the same path make sure to specify
2055 "\-"
2056 first, and
2057 "+"
2058 second\&.
2059 .sp
2060 Note that these settings will disconnect propagation of mounts from the unit\*(Aqs processes to the host\&. This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace\&. For
2061 \fIReadWritePaths=\fR
2062 and
2063 \fIReadOnlyPaths=\fR, propagation in the other direction is not affected, i\&.e\&. mounts created on the host generally appear in the unit processes\*(Aq namespace, and mounts removed on the host also disappear there too\&. In particular, note that mount propagation from host to unit will result in unmodified mounts to be created in the unit\*(Aqs namespace, i\&.e\&. writable mounts appearing on the host will be writable in the unit\*(Aqs namespace too, even when propagated below a path marked with
2064 \fIReadOnlyPaths=\fR! Restricting access with these options hence does not extend to submounts of a directory that are created later on\&. This means the lock\-down offered by that setting is not complete, and does not offer full protection\&.
2065 .sp
2066 Note that the effect of these settings may be undone by privileged processes\&. In order to set up an effective sandboxed environment for a unit it is thus recommended to combine these settings with either
2067 \fICapabilityBoundingSet=~CAP_SYS_ADMIN\fR
2068 or
2069 \fISystemCallFilter=~@mount\fR\&.
2070 .sp
2071 Please be extra careful when applying these options to API file systems (a list of them could be found in
2072 \fIMountAPIVPS=\fR), since they may be required for basic system functionalities\&. Moreover,
2073 /run/
2074 needs to be writable for setting up mount namespace and propagation\&.
2075 .sp
2076 Simple allow\-list example using these directives:
2077 .sp
2078 .if n \{\
2079 .RS 4
2080 .\}
2081 .nf
2082 [Service]
2083 ReadOnlyPaths=/
2084 ReadWritePaths=/var /run
2085 InaccessiblePaths=\-/lost+found
2086 NoExecPaths=/
2087 ExecPaths=/usr/sbin/my_daemon /usr/lib /usr/lib64
2088 .fi
2089 .if n \{\
2090 .RE
2091 .\}
2092 .sp
2093 These options are only available for system services, or for services running in per\-user instances of the service manager in which case
2094 \fIPrivateUsers=\fR
2095 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2096 "kernel\&.unprivileged_userns_clone="
2097 sysctl)\&.
2098 .sp
2099 Added in version 231\&.
2100 .RE
2101 .PP
2102 \fITemporaryFileSystem=\fR
2103 .RS 4
2104 Takes a space\-separated list of mount points for temporary file systems (tmpfs)\&. If set, a new file system namespace is set up for executed processes, and a temporary file system is mounted on each mount point\&. This option may be specified more than once, in which case temporary file systems are mounted on all listed mount points\&. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect\&. Each mount point may optionally be suffixed with a colon (":") and mount options such as
2105 "size=10%"
2106 or
2107 "ro"\&. By default, each temporary file system is mounted with
2108 "nodev,strictatime,mode=0755"\&. These can be disabled by explicitly specifying the corresponding mount options, e\&.g\&.,
2109 "dev"
2110 or
2111 "nostrictatime"\&.
2112 .sp
2113 This is useful to hide files or directories not relevant to the processes invoked by the unit, while necessary files or directories can be still accessed by combining with
2114 \fIBindPaths=\fR
2115 or
2116 \fIBindReadOnlyPaths=\fR:
2117 .sp
2118 Example: if a unit has the following,
2119 .sp
2120 .if n \{\
2121 .RS 4
2122 .\}
2123 .nf
2124 TemporaryFileSystem=/var:ro
2125 BindReadOnlyPaths=/var/lib/systemd
2126 .fi
2127 .if n \{\
2128 .RE
2129 .\}
2130 .sp
2131 then the invoked processes by the unit cannot see any files or directories under
2132 /var/
2133 except for
2134 /var/lib/systemd
2135 or its contents\&.
2136 .sp
2137 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2138 \fIPrivateUsers=\fR
2139 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2140 "kernel\&.unprivileged_userns_clone="
2141 sysctl)\&.
2142 .sp
2143 Added in version 238\&.
2144 .RE
2145 .PP
2146 \fIPrivateTmp=\fR
2147 .RS 4
2148 Takes a boolean argument, or
2149 "disconnected"\&. If enabled, a new file system namespace will be set up for the executed processes, and
2150 /tmp/
2151 and
2152 /var/tmp/
2153 directories inside it are not shared with processes outside of the namespace, plus all temporary files created by a service in these directories will be removed after the service is stopped\&. If
2154 "true", the backing storage of the private temporary directories will remain on the host\*(Aqs
2155 /tmp/
2156 and
2157 /var/tmp/
2158 directories\&. If
2159 "disconnected", the directories will be backed by a completely new tmpfs instance, meaning that the storage is fully disconnected from the host namespace\&. Defaults to false\&.
2160 .sp
2161 This setting is useful to secure access to temporary files of the process, but makes sharing between processes via
2162 /tmp/
2163 or
2164 /var/tmp/
2165 impossible\&. If not set to
2166 "disconnected", it is possible to run two or more units within the same private
2167 /tmp/
2168 and
2169 /var/tmp/
2170 namespace by using the
2171 \fIJoinsNamespaceOf=\fR
2172 directive, see
2173 \fBsystemd.unit\fR(5)
2174 for details\&. This setting is implied if
2175 \fIDynamicUser=\fR
2176 is set\&. For this setting, the same restrictions regarding mount propagation and privileges apply as for
2177 \fIReadOnlyPaths=\fR
2178 and related calls, see above\&. If set to
2179 "true"
2180 (as opposed to
2181 "disconnected"), this has the side effect of adding
2182 \fIRequires=\fR
2183 and
2184 \fIAfter=\fR
2185 dependencies on all mount units necessary to access
2186 /tmp/
2187 and
2188 /var/tmp/
2189 on the host\&. Moreover an implicitly
2190 \fIAfter=\fR
2191 ordering on
2192 \fBsystemd-tmpfiles-setup.service\fR(8)
2193 is added\&.
2194 .sp
2195 Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&.
2196 .sp
2197 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2198 \fIPrivateUsers=\fR
2199 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2200 "kernel\&.unprivileged_userns_clone="
2201 sysctl)\&.
2202 .RE
2203 .PP
2204 \fIPrivateDevices=\fR
2205 .RS 4
2206 Takes a boolean argument\&. If true, sets up a new
2207 /dev/
2208 mount for the executed processes and only adds API pseudo devices such as
2209 /dev/null,
2210 /dev/zero
2211 or
2212 /dev/random
2213 (as well as the pseudo TTY subsystem) to it, but no physical devices such as
2214 /dev/sda, system memory
2215 /dev/mem, system ports
2216 /dev/port
2217 and others\&. This is useful to turn off physical device access by the executed process\&. Defaults to false\&.
2218 .sp
2219 Enabling this option will install a system call filter to block low\-level I/O system calls that are grouped in the
2220 \fI@raw\-io\fR
2221 set, remove
2222 \fBCAP_MKNOD\fR
2223 and
2224 \fBCAP_SYS_RAWIO\fR
2225 from the capability bounding set for the unit, and set
2226 \fIDevicePolicy=closed\fR
2227 (see
2228 \fBsystemd.resource-control\fR(5)
2229 for details)\&. Note that using this setting will disconnect propagation of mounts from the service to the host (propagation in the opposite direction continues to work)\&. This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace\&. The new
2230 /dev/
2231 will be mounted read\-only and \*(Aqnoexec\*(Aq\&. The latter may break old programs which try to set up executable memory by using
2232 \fBmmap\fR(2)
2233 of
2234 /dev/zero
2235 instead of using
2236 \fBMAP_ANON\fR\&. For this setting the same restrictions regarding mount propagation and privileges apply as for
2237 \fIReadOnlyPaths=\fR
2238 and related calls, see above\&.
2239 .sp
2240 Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&.
2241 .sp
2242 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2243 \fIPrivateUsers=\fR
2244 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2245 "kernel\&.unprivileged_userns_clone="
2246 sysctl)\&.
2247 .sp
2248 When access to some but not all devices must be possible, the
2249 \fIDeviceAllow=\fR
2250 setting might be used instead\&. See
2251 \fBsystemd.resource-control\fR(5)\&.
2252 .sp
2253 Added in version 209\&.
2254 .RE
2255 .PP
2256 \fIPrivateNetwork=\fR
2257 .RS 4
2258 Takes a boolean argument\&. If true, sets up a new network namespace for the executed processes and configures only the loopback network device
2259 "lo"
2260 inside it\&. No other network devices will be available to the executed process\&. This is useful to turn off network access by the executed process\&. Defaults to false\&. It is possible to run two or more units within the same private network namespace by using the
2261 \fIJoinsNamespaceOf=\fR
2262 directive, see
2263 \fBsystemd.unit\fR(5)
2264 for details\&. Note that this option will disconnect all socket families from the host, including
2265 \fBAF_NETLINK\fR
2266 and
2267 \fBAF_UNIX\fR\&. Effectively, for
2268 \fBAF_NETLINK\fR
2269 this means that device configuration events received from
2270 \fBsystemd-udevd.service\fR(8)
2271 are not delivered to the unit\*(Aqs processes\&. And for
2272 \fBAF_UNIX\fR
2273 this has the effect that
2274 \fBAF_UNIX\fR
2275 sockets in the abstract socket namespace of the host will become unavailable to the unit\*(Aqs processes (however, those located in the file system will continue to be accessible)\&.
2276 .sp
2277 Note that the implementation of this setting might be impossible (for example if network namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&.
2278 .sp
2279 When this option is enabled,
2280 \fIPrivateMounts=\fR
2281 is implied unless it is explicitly disabled, and
2282 /sys
2283 will be remounted to associate it with the new network namespace\&.
2284 .sp
2285 When this option is used on a socket unit any sockets bound on behalf of this unit will be bound within a private network namespace\&. This may be combined with
2286 \fIJoinsNamespaceOf=\fR
2287 to listen on sockets inside of network namespaces of other services\&.
2288 .sp
2289 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2290 \fIPrivateUsers=\fR
2291 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2292 "kernel\&.unprivileged_userns_clone="
2293 sysctl)\&.
2294 .RE
2295 .PP
2296 \fINetworkNamespacePath=\fR
2297 .RS 4
2298 Takes an absolute file system path referring to a Linux network namespace pseudo\-file (i\&.e\&. a file like
2299 /proc/$PID/ns/net
2300 or a bind mount or symlink to one)\&. When set the invoked processes are added to the network namespace referenced by that path\&. The path has to point to a valid namespace file at the moment the processes are forked off\&. If this option is used
2301 \fIPrivateNetwork=\fR
2302 has no effect\&. If this option is used together with
2303 \fIJoinsNamespaceOf=\fR
2304 then it only has an effect if this unit is started before any of the listed units that have
2305 \fIPrivateNetwork=\fR
2306 or
2307 \fINetworkNamespacePath=\fR
2308 configured, as otherwise the network namespace of those units is reused\&.
2309 .sp
2310 When this option is enabled,
2311 \fIPrivateMounts=\fR
2312 is implied unless it is explicitly disabled, and
2313 /sys
2314 will be remounted to associate it with the new network namespace\&.
2315 .sp
2316 When this option is used on a socket unit any sockets bound on behalf of this unit will be bound within the specified network namespace\&.
2317 .sp
2318 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2319 \fIPrivateUsers=\fR
2320 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2321 "kernel\&.unprivileged_userns_clone="
2322 sysctl)\&.
2323 .sp
2324 Added in version 242\&.
2325 .RE
2326 .PP
2327 \fIPrivateIPC=\fR
2328 .RS 4
2329 Takes a boolean argument\&. If true, sets up a new IPC namespace for the executed processes\&. Each IPC namespace has its own set of System V IPC identifiers and its own POSIX message queue file system\&. This is useful to avoid name clash of IPC identifiers\&. Defaults to false\&. It is possible to run two or more units within the same private IPC namespace by using the
2330 \fIJoinsNamespaceOf=\fR
2331 directive, see
2332 \fBsystemd.unit\fR(5)
2333 for details\&.
2334 .sp
2335 Note that IPC namespacing does not have an effect on
2336 \fBAF_UNIX\fR
2337 sockets, which are the most common form of IPC used on Linux\&. Instead,
2338 \fBAF_UNIX\fR
2339 sockets in the file system are subject to mount namespacing, and those in the abstract namespace are subject to network namespacing\&. IPC namespacing only has an effect on SysV IPC (which is mostly legacy) as well as POSIX message queues (for which
2340 \fBAF_UNIX\fR/\fBSOCK_SEQPACKET\fR
2341 sockets are typically a better replacement)\&. IPC namespacing also has no effect on POSIX shared memory (which is subject to mount namespacing) either\&. See
2342 \fBipc_namespaces\fR(7)
2343 for the details\&.
2344 .sp
2345 Note that the implementation of this setting might be impossible (for example if IPC namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&.
2346 .sp
2347 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2348 \fIPrivateUsers=\fR
2349 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2350 "kernel\&.unprivileged_userns_clone="
2351 sysctl)\&.
2352 .sp
2353 Added in version 248\&.
2354 .RE
2355 .PP
2356 \fIIPCNamespacePath=\fR
2357 .RS 4
2358 Takes an absolute file system path referring to a Linux IPC namespace pseudo\-file (i\&.e\&. a file like
2359 /proc/$PID/ns/ipc
2360 or a bind mount or symlink to one)\&. When set the invoked processes are added to the network namespace referenced by that path\&. The path has to point to a valid namespace file at the moment the processes are forked off\&. If this option is used
2361 \fIPrivateIPC=\fR
2362 has no effect\&. If this option is used together with
2363 \fIJoinsNamespaceOf=\fR
2364 then it only has an effect if this unit is started before any of the listed units that have
2365 \fIPrivateIPC=\fR
2366 or
2367 \fIIPCNamespacePath=\fR
2368 configured, as otherwise the network namespace of those units is reused\&.
2369 .sp
2370 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2371 \fIPrivateUsers=\fR
2372 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2373 "kernel\&.unprivileged_userns_clone="
2374 sysctl)\&.
2375 .sp
2376 Added in version 248\&.
2377 .RE
2378 .PP
2379 \fIMemoryKSM=\fR
2380 .RS 4
2381 Takes a boolean argument\&. When set, it enables KSM (kernel samepage merging) for the processes\&. KSM is a memory\-saving de\-duplication feature\&. Anonymous memory pages with identical content can be replaced by a single write\-protected page\&. This feature should only be enabled for jobs that share the same security domain\&. For details, see
2382 \m[blue]\fBKernel Samepage Merging\fR\m[]\&\s-2\u[8]\d\s+2
2383 in the kernel documentation\&.
2384 .sp
2385 Note that this functionality might not be available, for example if KSM is disabled in the kernel, or the kernel does not support controlling KSM at the process level through
2386 \fBprctl\fR(2)\&.
2387 .sp
2388 Added in version 254\&.
2389 .RE
2390 .PP
2391 \fIPrivatePIDs=\fR
2392 .RS 4
2393 Takes a boolean argument\&. Defaults to false\&. If enabled, sets up a new PID namespace for the executed processes\&. Each executed process is now PID 1 \- the init process \- in the new namespace\&.
2394 /proc/
2395 is mounted such that only processes in the PID namespace are visible\&. If
2396 \fIPrivatePIDs=\fR
2397 is set,
2398 \fIMountAPIVFS=yes\fR
2399 is implied\&.
2400 .sp
2401 \fIPrivatePIDs=\fR
2402 is only supported for service units\&. This setting is not supported with
2403 \fIType=forking\fR
2404 since the kernel will kill all processes in the PID namespace if the init process terminates\&.
2405 .sp
2406 This setting will be ignored if the kernel does not support PID namespaces\&.
2407 .sp
2408 Note unprivileged user services (i\&.e\&. a service run by the per\-user instance of the service manager) will fail with
2409 \fIPrivatePIDs=yes\fR
2410 if
2411 /proc/
2412 is masked (i\&.e\&.
2413 /proc/kmsg
2414 is over\-mounted with
2415 \fBtmpfs\fR
2416 like
2417 \fBsystemd-nspawn\fR(1)
2418 does)\&. This is due to a kernel restriction not allowing unprivileged user namespaces to mount a less restrictive instance of
2419 /proc/\&.
2420 .sp
2421 Added in version 257\&.
2422 .RE
2423 .PP
2424 \fIPrivateUsers=\fR
2425 .RS 4
2426 Takes a boolean argument or one of
2427 "self"
2428 or
2429 "identity"\&. Defaults to false\&. If enabled, sets up a new user namespace for the executed processes and configures a user and group mapping\&. If set to a true value or
2430 "self", a minimal user and group mapping is configured that maps the
2431 "root"
2432 user and group as well as the unit\*(Aqs own user and group to themselves and everything else to the
2433 "nobody"
2434 user and group\&. This is useful to securely detach the user and group databases used by the unit from the rest of the system, and thus to create an effective sandbox environment\&. All files, directories, processes, IPC objects and other resources owned by users/groups not equaling
2435 "root"
2436 or the unit\*(Aqs own will stay visible from within the unit but appear owned by the
2437 "nobody"
2438 user and group\&.
2439 .sp
2440 If the parameter is
2441 "identity", user namespacing is set up with an identity mapping for the first 65536 UIDs/GIDs\&. Any UIDs/GIDs above 65536 will be mapped to the
2442 "nobody"
2443 user and group, respectively\&. While this does not provide UID/GID isolation, since all UIDs/GIDs are chosen identically it does provide process capability isolation, and hence is often a good choice if proper user namespacing with distinct UID maps is not appropriate\&.
2444 .sp
2445 If this mode is enabled, all unit processes are run without privileges in the host user namespace (regardless if the unit\*(Aqs own user/group is
2446 "root"
2447 or not)\&. Specifically this means that the process will have zero process capabilities on the host\*(Aqs user namespace, but full capabilities within the service\*(Aqs user namespace\&. Settings such as
2448 \fICapabilityBoundingSet=\fR
2449 will affect only the latter, and there\*(Aqs no way to acquire additional capabilities in the host\*(Aqs user namespace\&.
2450 .sp
2451 When this setting is set up by a per\-user instance of the service manager, the mapping of the
2452 "root"
2453 user and group to itself is omitted (unless the user manager is root)\&. Additionally, in the per\-user instance manager case, the user namespace will be set up before most other namespaces\&. This means that combining
2454 \fIPrivateUsers=\fR\fBtrue\fR
2455 with other namespaces will enable use of features not normally supported by the per\-user instances of the service manager\&.
2456 .sp
2457 This setting is particularly useful in conjunction with
2458 \fIRootDirectory=\fR/\fIRootImage=\fR, as the need to synchronize the user and group databases in the root directory and on the host is reduced, as the only users and groups who need to be matched are
2459 "root",
2460 "nobody"
2461 and the unit\*(Aqs own user and group\&.
2462 .sp
2463 Note that the implementation of this setting might be impossible (for example if user namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&.
2464 .sp
2465 Added in version 232\&.
2466 .RE
2467 .PP
2468 \fIProtectHostname=\fR
2469 .RS 4
2470 Takes a boolean argument\&. When set, sets up a new UTS namespace for the executed processes\&. In addition, changing hostname or domainname is prevented\&. Defaults to off\&.
2471 .sp
2472 Note that the implementation of this setting might be impossible (for example if UTS namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&.
2473 .sp
2474 Note that when this option is enabled for a service hostname changes no longer propagate from the system into the service, it is hence not suitable for services that need to take notice of system hostname changes dynamically\&.
2475 .sp
2476 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2477 \fIPrivateUsers=\fR
2478 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2479 "kernel\&.unprivileged_userns_clone="
2480 sysctl)\&.
2481 .sp
2482 Added in version 242\&.
2483 .RE
2484 .PP
2485 \fIProtectClock=\fR
2486 .RS 4
2487 Takes a boolean argument\&. If set, writes to the hardware clock or system clock will be denied\&. Defaults to off\&. Enabling this option removes
2488 \fBCAP_SYS_TIME\fR
2489 and
2490 \fBCAP_WAKE_ALARM\fR
2491 from the capability bounding set for this unit, installs a system call filter to block calls that can set the clock, and
2492 \fIDeviceAllow=char\-rtc r\fR
2493 is implied\&. Note that the system calls are blocked altogether, the filter does not take into account that some of the calls can be used to read the clock state with some parameter combinations\&. Effectively,
2494 /dev/rtc0,
2495 /dev/rtc1, etc\&. are made read\-only to the service\&. See
2496 \fBsystemd.resource-control\fR(5)
2497 for the details about
2498 \fIDeviceAllow=\fR\&.
2499 .sp
2500 It is recommended to turn this on for most services that do not need modify the clock or check its state\&.
2501 .sp
2502 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2503 \fIPrivateUsers=\fR
2504 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2505 "kernel\&.unprivileged_userns_clone="
2506 sysctl)\&.
2507 .sp
2508 Added in version 245\&.
2509 .RE
2510 .PP
2511 \fIProtectKernelTunables=\fR
2512 .RS 4
2513 Takes a boolean argument\&. If true, kernel variables accessible through
2514 /proc/sys/,
2515 /sys/,
2516 /proc/sysrq\-trigger,
2517 /proc/latency_stats,
2518 /proc/acpi,
2519 /proc/timer_stats,
2520 /proc/fs
2521 and
2522 /proc/irq
2523 will be made read\-only and
2524 /proc/kallsyms
2525 as well as
2526 /proc/kcore
2527 will be inaccessible to all processes of the unit\&. Usually, tunable kernel variables should be initialized only at boot\-time, for example with the
2528 \fBsysctl.d\fR(5)
2529 mechanism\&. Few services need to write to these at runtime; it is hence recommended to turn this on for most services\&. For this setting the same restrictions regarding mount propagation and privileges apply as for
2530 \fIReadOnlyPaths=\fR
2531 and related calls, see above\&. Defaults to off\&. Note that this option does not prevent indirect changes to kernel tunables affected by IPC calls to other processes\&. However,
2532 \fIInaccessiblePaths=\fR
2533 may be used to make relevant IPC file system objects inaccessible\&. If
2534 \fIProtectKernelTunables=\fR
2535 is set,
2536 \fIMountAPIVFS=yes\fR
2537 is implied\&.
2538 .sp
2539 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2540 \fIPrivateUsers=\fR
2541 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2542 "kernel\&.unprivileged_userns_clone="
2543 sysctl)\&.
2544 .sp
2545 Added in version 232\&.
2546 .RE
2547 .PP
2548 \fIProtectKernelModules=\fR
2549 .RS 4
2550 Takes a boolean argument\&. If true, explicit module loading will be denied\&. This allows module load and unload operations to be turned off on modular kernels\&. It is recommended to turn this on for most services that do not need special file systems or extra kernel modules to work\&. Defaults to off\&. Enabling this option removes
2551 \fBCAP_SYS_MODULE\fR
2552 from the capability bounding set for the unit, and installs a system call filter to block module system calls, also
2553 /usr/lib/modules
2554 is made inaccessible\&. For this setting the same restrictions regarding mount propagation and privileges apply as for
2555 \fIReadOnlyPaths=\fR
2556 and related calls, see above\&. Note that limited automatic module loading due to user configuration or kernel mapping tables might still happen as side effect of requested user operations, both privileged and unprivileged\&. To disable module auto\-load feature please see
2557 \fBsysctl.d\fR(5)
2558 \fBkernel\&.modules_disabled\fR
2559 mechanism and
2560 /proc/sys/kernel/modules_disabled
2561 documentation\&.
2562 .sp
2563 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2564 \fIPrivateUsers=\fR
2565 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2566 "kernel\&.unprivileged_userns_clone="
2567 sysctl)\&.
2568 .sp
2569 Added in version 232\&.
2570 .RE
2571 .PP
2572 \fIProtectKernelLogs=\fR
2573 .RS 4
2574 Takes a boolean argument\&. If true, access to the kernel log ring buffer will be denied\&. It is recommended to turn this on for most services that do not need to read from or write to the kernel log ring buffer\&. Enabling this option removes
2575 \fBCAP_SYSLOG\fR
2576 from the capability bounding set for this unit, and installs a system call filter to block the
2577 \fBsyslog\fR(2)
2578 system call (not to be confused with the libc API
2579 \fBsyslog\fR(3)
2580 for userspace logging)\&. The kernel exposes its log buffer to userspace via
2581 /dev/kmsg
2582 and
2583 /proc/kmsg\&. If enabled, these are made inaccessible to all the processes in the unit\&.
2584 .sp
2585 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2586 \fIPrivateUsers=\fR
2587 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2588 "kernel\&.unprivileged_userns_clone="
2589 sysctl)\&.
2590 .sp
2591 Added in version 244\&.
2592 .RE
2593 .PP
2594 \fIProtectControlGroups=\fR
2595 .RS 4
2596 Takes a boolean argument or the special values
2597 "private"
2598 or
2599 "strict"\&. If true, the Linux Control Groups (\fBcgroups\fR(7)) hierarchies accessible through
2600 /sys/fs/cgroup/
2601 will be made read\-only to all processes of the unit\&. If set to
2602 "private", the unit will run in a cgroup namespace with a private writable mount of
2603 /sys/fs/cgroup/\&. If set to
2604 "strict", the unit will run in a cgroup namespace with a private read\-only mount of
2605 /sys/fs/cgroup/\&. Defaults to off\&. If
2606 \fIProtectControlGroups=\fR
2607 is set,
2608 \fIMountAPIVFS=yes\fR
2609 is implied\&. Note
2610 "private"
2611 and
2612 "strict"
2613 are downgraded to false and true respectively unless the system is using the unified control group hierarchy and the kernel supports cgroup namespaces\&.
2614 .sp
2615 Except for container managers no services should require write access to the control groups hierarchies; it is hence recommended to set
2616 \fIProtectControlGroups=\fR
2617 to true or
2618 "strict"
2619 for most services\&. For this setting the same restrictions regarding mount propagation and privileges apply as for
2620 \fIReadOnlyPaths=\fR
2621 and related settings, see above\&.
2622 .sp
2623 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
2624 .sp
2625 Added in version 232\&.
2626 .RE
2627 .PP
2628 \fIRestrictAddressFamilies=\fR
2629 .RS 4
2630 Restricts the set of socket address families accessible to the processes of this unit\&. Takes
2631 "none", or a space\-separated list of address family names to allow\-list, such as
2632 \fBAF_UNIX\fR,
2633 \fBAF_INET\fR
2634 or
2635 \fBAF_INET6\fR\&. When
2636 "none"
2637 is specified, then all address families will be denied\&. When prefixed with
2638 "~"
2639 the listed address families will be applied as deny list, otherwise as allow list\&.
2640 .sp
2641 By default, no restrictions apply, all address families are accessible to processes\&. If assigned the empty string, any previous address family restriction changes are undone\&. This setting does not affect commands prefixed with
2642 "+"\&.
2643 .sp
2644 Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive network protocols, such as
2645 \fBAF_PACKET\fR\&. Note that in most cases, the local
2646 \fBAF_UNIX\fR
2647 address family should be included in the configured allow list as it is frequently used for local communication, including for
2648 \fBsyslog\fR(2)
2649 logging\&.
2650 .sp
2651 Note that this restricts access to the
2652 \fBsocket\fR(2)
2653 system call only\&. Sockets passed into the process by other means (for example, by using socket activation with socket units, see
2654 \fBsystemd.socket\fR(5)) are unaffected\&. Also, sockets created with
2655 \fBsocketpair()\fR
2656 (which creates connected AF_UNIX sockets) or the
2657 \fBio_uring\fR(7)
2658 functions, are not affected\&. Thus, it is recommended to combined this setting with
2659 \fISystemCallFilter=@service\fR, to only allow a limited subset of system calls\&.
2660 .sp
2661 Note that this option is limited to some ABIs, in particular x86\-64, but currently has no effect on 32\-bit x86, s390, s390x, mips, mips\-le, ppc, ppc\-le, ppc64, or ppc64\-le, and is ignored\&. On systems supporting multiple ABIs (such as x86/x86\-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option\&. Specifically, it is recommended to combine this option with
2662 \fISystemCallArchitectures=native\fR
2663 or similar\&.
2664 .sp
2665 Added in version 211\&.
2666 .RE
2667 .PP
2668 \fIRestrictFileSystems=\fR
2669 .RS 4
2670 Restricts the set of filesystems processes of this unit can open files on\&. Takes a space\-separated list of filesystem names\&. Any filesystem listed is made accessible to the unit\*(Aqs processes, access to filesystem types not listed is prohibited (allow\-listing)\&. If the first character of the list is
2671 "~", the effect is inverted: access to the filesystems listed is prohibited (deny\-listing)\&. If the empty string is assigned, access to filesystems is not restricted\&.
2672 .sp
2673 If you specify both types of this option (i\&.e\&. allow\-listing and deny\-listing), the first encountered will take precedence and will dictate the default action (allow access to the filesystem or deny it)\&. Then the next occurrences of this option will add or delete the listed filesystems from the set of the restricted filesystems, depending on its type and the default action\&.
2674 .sp
2675 Example: if a unit has the following,
2676 .sp
2677 .if n \{\
2678 .RS 4
2679 .\}
2680 .nf
2681 RestrictFileSystems=ext4 tmpfs
2682 RestrictFileSystems=ext2 ext4
2683 .fi
2684 .if n \{\
2685 .RE
2686 .\}
2687 .sp
2688 then access to
2689 \fBext4\fR,
2690 \fBtmpfs\fR, and
2691 \fBext2\fR
2692 is allowed and access to other filesystems is denied\&.
2693 .sp
2694 Example: if a unit has the following,
2695 .sp
2696 .if n \{\
2697 .RS 4
2698 .\}
2699 .nf
2700 RestrictFileSystems=ext4 tmpfs
2701 RestrictFileSystems=~ext4
2702 .fi
2703 .if n \{\
2704 .RE
2705 .\}
2706 .sp
2707 then only access
2708 \fBtmpfs\fR
2709 is allowed\&.
2710 .sp
2711 Example: if a unit has the following,
2712 .sp
2713 .if n \{\
2714 .RS 4
2715 .\}
2716 .nf
2717 RestrictFileSystems=~ext4 tmpfs
2718 RestrictFileSystems=ext4
2719 .fi
2720 .if n \{\
2721 .RE
2722 .\}
2723 .sp
2724 then only access to
2725 \fBtmpfs\fR
2726 is denied\&.
2727 .sp
2728 As the number of possible filesystems is large, predefined sets of filesystems are provided\&. A set starts with
2729 "@"
2730 character, followed by name of the set\&.
2731 .sp
2732 .it 1 an-trap
2733 .nr an-no-space-flag 1
2734 .nr an-break-flag 1
2735 .br
2736 .B Table\ \&3.\ \&Currently predefined filesystem sets
2737 .TS
2738 allbox tab(:);
2739 lB lB.
2740 T{
2741 Set
2742 T}:T{
2743 Description
2744 T}
2745 .T&
2746 l l
2747 l l
2748 l l
2749 l l
2750 l l
2751 l l
2752 l l
2753 l l.
2754 T{
2755 @basic\-api
2756 T}:T{
2757 Basic filesystem API\&.
2758 T}
2759 T{
2760 @auxiliary\-api
2761 T}:T{
2762 Auxiliary filesystem API\&.
2763 T}
2764 T{
2765 @common\-block
2766 T}:T{
2767 Common block device filesystems\&.
2768 T}
2769 T{
2770 @historical\-block
2771 T}:T{
2772 Historical block device filesystems\&.
2773 T}
2774 T{
2775 @network
2776 T}:T{
2777 Well\-known network filesystems\&.
2778 T}
2779 T{
2780 @privileged\-api
2781 T}:T{
2782 Privileged filesystem API\&.
2783 T}
2784 T{
2785 @temporary
2786 T}:T{
2787 Temporary filesystems: tmpfs, ramfs\&.
2788 T}
2789 T{
2790 @known
2791 T}:T{
2792 All known filesystems defined by the kernel\&. This list is defined statically in systemd based on a kernel version that was available when this systemd version was released\&. It will become progressively more out\-of\-date as the kernel is updated\&.
2793 T}
2794 .TE
2795 .sp 1
2796 Use
2797 \fBsystemd-analyze\fR(1)\*(Aqs
2798 \fBfilesystems\fR
2799 command to retrieve a list of filesystems defined on the local system\&.
2800 .sp
2801 Note that this setting might not be supported on some systems (for example if the LSM eBPF hook is not enabled in the underlying kernel or if not using the unified control group hierarchy)\&. In that case this setting has no effect\&.
2802 .sp
2803 This option cannot be bypassed by prefixing
2804 "+"
2805 to the executable path in the service unit, as it applies to the whole control group\&.
2806 .sp
2807 Added in version 250\&.
2808 .RE
2809 .PP
2810 \fIRestrictNamespaces=\fR
2811 .RS 4
2812 Restricts access to Linux namespace functionality for the processes of this unit\&. For details about Linux namespaces, see
2813 \fBnamespaces\fR(7)\&. Either takes a boolean argument, or a space\-separated list of namespace type identifiers\&. If false (the default), no restrictions on namespace creation and switching are made\&. If true, access to any kind of namespacing is prohibited\&. Otherwise, a space\-separated list of namespace type identifiers must be specified, consisting of any combination of:
2814 \fBcgroup\fR,
2815 \fBipc\fR,
2816 \fBnet\fR,
2817 \fBmnt\fR,
2818 \fBpid\fR,
2819 \fBuser\fR
2820 and
2821 \fButs\fR\&. Any namespace type listed is made accessible to the unit\*(Aqs processes, access to namespace types not listed is prohibited (allow\-listing)\&. By prepending the list with a single tilde character ("~") the effect may be inverted: only the listed namespace types will be made inaccessible, all unlisted ones are permitted (deny\-listing)\&. If the empty string is assigned, the default namespace restrictions are applied, which is equivalent to false\&. This option may appear more than once, in which case the namespace types are merged by
2822 \fBOR\fR, or by
2823 \fBAND\fR
2824 if the lines are prefixed with
2825 "~"
2826 (see examples below)\&. Internally, this setting limits access to the
2827 \fBunshare\fR(2),
2828 \fBclone\fR(2)
2829 and
2830 \fBsetns\fR(2)
2831 system calls, taking the specified flags parameters into account\&. Note that \(em if this option is used \(em in addition to restricting creation and switching of the specified types of namespaces (or all of them, if true) access to the
2832 \fBsetns()\fR
2833 system call with a zero flags parameter is prohibited\&. This setting is only supported on x86, x86\-64, mips, mips\-le, mips64, mips64\-le, mips64\-n32, mips64\-le\-n32, ppc64, ppc64\-le, s390 and s390x, and enforces no restrictions on other architectures\&.
2834 .sp
2835 Example: if a unit has the following,
2836 .sp
2837 .if n \{\
2838 .RS 4
2839 .\}
2840 .nf
2841 RestrictNamespaces=cgroup ipc
2842 RestrictNamespaces=cgroup net
2843 .fi
2844 .if n \{\
2845 .RE
2846 .\}
2847 .sp
2848 then
2849 \fBcgroup\fR,
2850 \fBipc\fR, and
2851 \fBnet\fR
2852 are set\&. If the second line is prefixed with
2853 "~", e\&.g\&.,
2854 .sp
2855 .if n \{\
2856 .RS 4
2857 .\}
2858 .nf
2859 RestrictNamespaces=cgroup ipc
2860 RestrictNamespaces=~cgroup net
2861 .fi
2862 .if n \{\
2863 .RE
2864 .\}
2865 .sp
2866 then, only
2867 \fBipc\fR
2868 is set\&.
2869 .sp
2870 Added in version 233\&.
2871 .RE
2872 .PP
2873 \fILockPersonality=\fR
2874 .RS 4
2875 Takes a boolean argument\&. If set, locks down the
2876 \fBpersonality\fR(2)
2877 system call so that the kernel execution domain may not be changed from the default or the personality selected with
2878 \fIPersonality=\fR
2879 directive\&. This may be useful to improve security, because odd personality emulations may be poorly tested and source of vulnerabilities\&.
2880 .sp
2881 Added in version 235\&.
2882 .RE
2883 .PP
2884 \fIMemoryDenyWriteExecute=\fR
2885 .RS 4
2886 Takes a boolean argument\&. If set, attempts to create memory mappings that are writable and executable at the same time, or to change existing memory mappings to become executable, or mapping shared memory segments as executable, are prohibited\&. Specifically, a system call filter is added (or preferably, an equivalent kernel check is enabled with
2887 \fBprctl\fR(2)) that rejects
2888 \fBmmap\fR(2)
2889 system calls with both
2890 \fBPROT_EXEC\fR
2891 and
2892 \fBPROT_WRITE\fR
2893 set,
2894 \fBmprotect\fR(2)
2895 or
2896 \fBpkey_mprotect\fR(2)
2897 system calls with
2898 \fBPROT_EXEC\fR
2899 set and
2900 \fBshmat\fR(2)
2901 system calls with
2902 \fBSHM_EXEC\fR
2903 set\&. Note that this option is incompatible with programs and libraries that generate program code dynamically at runtime, including JIT execution engines, executable stacks, and code "trampoline" feature of various C compilers\&. This option improves service security, as it makes harder for software exploits to change running code dynamically\&. However, the protection can be circumvented, if the service can write to a filesystem, which is not mounted with
2904 \fBnoexec\fR
2905 (such as
2906 /dev/shm), or it can use
2907 \fBmemfd_create()\fR\&. This can be prevented by making such file systems inaccessible to the service (e\&.g\&.
2908 \fIInaccessiblePaths=/dev/shm\fR) and installing further system call filters (\fISystemCallFilter=~memfd_create\fR)\&. Note that this feature is fully available on x86\-64, and partially on x86\&. Specifically, the
2909 \fBshmat()\fR
2910 protection is not available on x86\&. Note that on systems supporting multiple ABIs (such as x86/x86\-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option\&. Specifically, it is recommended to combine this option with
2911 \fISystemCallArchitectures=native\fR
2912 or similar\&.
2913 .sp
2914 Added in version 231\&.
2915 .RE
2916 .PP
2917 \fIRestrictRealtime=\fR
2918 .RS 4
2919 Takes a boolean argument\&. If set, any attempts to enable realtime scheduling in a process of the unit are refused\&. This restricts access to realtime task scheduling policies such as
2920 \fBSCHED_FIFO\fR,
2921 \fBSCHED_RR\fR
2922 or
2923 \fBSCHED_DEADLINE\fR\&. See
2924 \fBsched\fR(7)
2925 for details about these scheduling policies\&. Realtime scheduling policies may be used to monopolize CPU time for longer periods of time, and may hence be used to lock up or otherwise trigger Denial\-of\-Service situations on the system\&. It is hence recommended to restrict access to realtime scheduling to the few programs that actually require them\&. Defaults to off\&.
2926 .sp
2927 Added in version 231\&.
2928 .RE
2929 .PP
2930 \fIRestrictSUIDSGID=\fR
2931 .RS 4
2932 Takes a boolean argument\&. If set, any attempts to set the set\-user\-ID (SUID) or set\-group\-ID (SGID) bits on files or directories will be denied (for details on these bits see
2933 \fBinode\fR(7))\&. As the SUID/SGID bits are mechanisms to elevate privileges, and allow users to acquire the identity of other users, it is recommended to restrict creation of SUID/SGID files to the few programs that actually require them\&. Note that this restricts marking of any type of file system object with these bits, including both regular files and directories (where the SGID is a different meaning than for files, see documentation)\&. This option is implied if
2934 \fIDynamicUser=\fR
2935 is enabled\&. Defaults to off\&.
2936 .sp
2937 Added in version 242\&.
2938 .RE
2939 .PP
2940 \fIRemoveIPC=\fR
2941 .RS 4
2942 Takes a boolean parameter\&. If set, all System V and POSIX IPC objects owned by the user and group the processes of this unit are run as are removed when the unit is stopped\&. This setting only has an effect if at least one of
2943 \fIUser=\fR,
2944 \fIGroup=\fR
2945 and
2946 \fIDynamicUser=\fR
2947 are used\&. It has no effect on IPC objects owned by the root user\&. Specifically, this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues\&. If multiple units use the same user or group the IPC objects are removed when the last of these units is stopped\&. This setting is implied if
2948 \fIDynamicUser=\fR
2949 is set\&.
2950 .sp
2951 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
2952 .sp
2953 Added in version 232\&.
2954 .RE
2955 .PP
2956 \fIPrivateMounts=\fR
2957 .RS 4
2958 Takes a boolean parameter\&. If set, the processes of this unit will be run in their own private file system (mount) namespace with all mount propagation from the processes towards the host\*(Aqs main file system namespace turned off\&. This means any file system mount points established or removed by the unit\*(Aqs processes will be private to them and not be visible to the host\&. However, file system mount points established or removed on the host will be propagated to the unit\*(Aqs processes\&. See
2959 \fBmount_namespaces\fR(7)
2960 for details on file system namespaces\&. Defaults to off\&.
2961 .sp
2962 When turned on, this executes three operations for each invoked process: a new
2963 \fBCLONE_NEWNS\fR
2964 namespace is created, after which all existing mounts are remounted to
2965 \fBMS_SLAVE\fR
2966 to disable propagation from the unit\*(Aqs processes to the host (but leaving propagation in the opposite direction in effect)\&. Finally, the mounts are remounted again to the propagation mode configured with
2967 \fIMountFlags=\fR, see below\&.
2968 .sp
2969 File system namespaces are set up individually for each process forked off by the service manager\&. Mounts established in the namespace of the process created by
2970 \fIExecStartPre=\fR
2971 will hence be cleaned up automatically as soon as that process exits and will not be available to subsequent processes forked off for
2972 \fIExecStart=\fR
2973 (and similar applies to the various other commands configured for units)\&. Similarly,
2974 \fIJoinsNamespaceOf=\fR
2975 does not permit sharing kernel mount namespaces between units, it only enables sharing of the
2976 /tmp/
2977 and
2978 /var/tmp/
2979 directories\&.
2980 .sp
2981 Other file system namespace unit settings \(em
2982 \fIPrivateTmp=\fR,
2983 \fIPrivateDevices=\fR,
2984 \fIProtectSystem=\fR,
2985 \fIProtectHome=\fR,
2986 \fIReadOnlyPaths=\fR,
2987 \fIInaccessiblePaths=\fR,
2988 \fIReadWritePaths=\fR,
2989 \fIBindPaths=\fR,
2990 \fIBindReadOnlyPaths=\fR, \&... \(em also enable file system namespacing in a fashion equivalent to this option\&. Hence it is primarily useful to explicitly request this behaviour if none of the other settings are used\&.
2991 .sp
2992 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
2993 \fIPrivateUsers=\fR
2994 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
2995 "kernel\&.unprivileged_userns_clone="
2996 sysctl)\&.
2997 .sp
2998 Added in version 239\&.
2999 .RE
3000 .PP
3001 \fIMountFlags=\fR
3002 .RS 4
3003 Takes a mount propagation setting:
3004 \fBshared\fR,
3005 \fBslave\fR
3006 or
3007 \fBprivate\fR, which controls whether file system mount points in the file system namespaces set up for this unit\*(Aqs processes will receive or propagate mounts and unmounts from other file system namespaces\&. See
3008 \fBmount\fR(2)
3009 for details on mount propagation, and the three propagation flags in particular\&.
3010 .sp
3011 This setting only controls the
3012 \fIfinal\fR
3013 propagation setting in effect on all mount points of the file system namespace created for each process of this unit\&. Other file system namespacing unit settings (see the discussion in
3014 \fIPrivateMounts=\fR
3015 above) will implicitly disable mount and unmount propagation from the unit\*(Aqs processes towards the host by changing the propagation setting of all mount points in the unit\*(Aqs file system namespace to
3016 \fBslave\fR
3017 first\&. Setting this option to
3018 \fBshared\fR
3019 does not reestablish propagation in that case\&.
3020 .sp
3021 If not set \(en but file system namespaces are enabled through another file system namespace unit setting \(en
3022 \fBshared\fR
3023 mount propagation is used, but \(em as mentioned \(em as
3024 \fBslave\fR
3025 is applied first, propagation from the unit\*(Aqs processes to the host is still turned off\&.
3026 .sp
3027 It is not recommended to use
3028 \fBprivate\fR
3029 mount propagation for units, as this means temporary mounts (such as removable media) of the host will stay mounted and thus indefinitely busy in forked off processes, as unmount propagation events will not be received by the file system namespace of the unit\&.
3030 .sp
3031 Usually, it is best to leave this setting unmodified, and use higher level file system namespacing options instead, in particular
3032 \fIPrivateMounts=\fR, see above\&.
3033 .sp
3034 This option is only available for system services, or for services running in per\-user instances of the service manager in which case
3035 \fIPrivateUsers=\fR
3036 is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the
3037 "kernel\&.unprivileged_userns_clone="
3038 sysctl)\&.
3039 .RE
3040 .SH "SYSTEM CALL FILTERING"
3041 .PP
3042 \fISystemCallFilter=\fR
3043 .RS 4
3044 Takes a space\-separated list of system call names or system call groups\&. If this setting is used, system calls executed by the unit processes except for the listed ones will result in the system call being denied (allow\-listing)\&. If the first character of the list is
3045 "~", the effect is inverted: only the listed system calls will be denied (deny\-listing)\&. This option may be specified more than once, in which case the filter masks are merged\&. If the empty string is assigned, the filter is reset, all prior assignments will have no effect\&.
3046 .sp
3047 Commands prefixed with
3048 "+"
3049 are not subject to filtering\&. The
3050 \fBexecve()\fR,
3051 \fBexit()\fR,
3052 \fBexit_group()\fR,
3053 \fBgetrlimit()\fR,
3054 \fBrt_sigreturn()\fR,
3055 \fBsigreturn()\fR
3056 system calls and the system calls for querying time and sleeping are implicitly allow\-listed and do not need to be listed explicitly\&.
3057 .sp
3058 The default action when a system call is denied is to terminate the processes with a
3059 \fBSIGSYS\fR
3060 signal\&. This can changed using
3061 \fISystemCallErrorNumber=\fR, see below\&. In addition, deny\-listed system calls and system call groups may optionally be suffixed with a colon (":") and an argument in the same format as
3062 \fISystemCallErrorNumber=\fR, to take this action when the matching system call is made\&. This takes precedence over the action specified in
3063 \fISystemCallErrorNumber=\fR\&.
3064 .sp
3065 This feature makes use of the Secure Computing Mode 2 interfaces of the kernel (\*(Aqseccomp filtering\*(Aq) and is useful for enforcing a minimal sandboxing environment\&.
3066 .sp
3067 Note that on systems supporting multiple ABIs (such as x86/x86\-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option\&. Specifically, it is recommended to combine this option with
3068 \fISystemCallArchitectures=native\fR
3069 or similar\&.
3070 .sp
3071 Note that strict system call filters may impact execution and error handling code paths of the service invocation\&. Specifically, access to the
3072 \fBexecve()\fR
3073 system call is required for the execution of the service binary \(em if it is blocked service invocation will necessarily fail\&. Also, if execution of the service binary fails for some reason (for example: missing service executable), the error handling logic might require access to an additional set of system calls in order to process and log this failure correctly\&. It might be necessary to temporarily disable system call filters in order to allow debugging of such failures\&.
3074 .sp
3075 If you specify both types of this option (i\&.e\&. allow\-listing and deny\-listing), the first encountered will take precedence and will dictate the default action (termination or approval of a system call)\&. Then the next occurrences of this option will add or delete the listed system calls from the set of the filtered system calls, depending of its type and the default action\&. (For example, if you have started with an allow list rule for
3076 \fBread()\fR
3077 and
3078 \fBwrite()\fR, and right after it add a deny list rule for
3079 \fBwrite()\fR, then
3080 \fBwrite()\fR
3081 will be removed from the set\&.)
3082 .sp
3083 As the number of possible system calls is large, predefined groups of system calls are provided\&. A group starts with
3084 "@"
3085 character, followed by name of the set\&.
3086 .sp
3087 .it 1 an-trap
3088 .nr an-no-space-flag 1
3089 .nr an-break-flag 1
3090 .br
3091 .B Table\ \&4.\ \&Currently predefined system call sets
3092 .TS
3093 allbox tab(:);
3094 lB lB.
3095 T{
3096 Set
3097 T}:T{
3098 Description
3099 T}
3100 .T&
3101 l l
3102 l l
3103 l l
3104 l l
3105 l l
3106 l l
3107 l l
3108 l l
3109 l l
3110 l l
3111 l l
3112 l l
3113 l l
3114 l l
3115 l l
3116 l l
3117 l l
3118 l l
3119 l l
3120 l l
3121 l l
3122 l l
3123 l l
3124 l l
3125 l l
3126 l l
3127 l l
3128 l l
3129 l l.
3130 T{
3131 @aio
3132 T}:T{
3133 Asynchronous I/O (\fBio_setup\fR(2), \fBio_submit\fR(2), and related calls)
3134 T}
3135 T{
3136 @basic\-io
3137 T}:T{
3138 System calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing (\fBread\fR(2), \fBwrite\fR(2), and related calls)
3139 T}
3140 T{
3141 @chown
3142 T}:T{
3143 Changing file ownership (\fBchown\fR(2), \fBfchownat\fR(2), and related calls)
3144 T}
3145 T{
3146 @clock
3147 T}:T{
3148 System calls for changing the system clock (\fBadjtimex\fR(2), \fBsettimeofday\fR(2), and related calls)
3149 T}
3150 T{
3151 @cpu\-emulation
3152 T}:T{
3153 System calls for CPU emulation functionality (\fBvm86\fR(2) and related calls)
3154 T}
3155 T{
3156 @debug
3157 T}:T{
3158 Debugging, performance monitoring and tracing functionality (\fBptrace\fR(2), \fBperf_event_open\fR(2) and related calls)
3159 T}
3160 T{
3161 @file\-system
3162 T}:T{
3163 File system operations: opening, creating files and directories for read and write, renaming and removing them, reading file properties, or creating hard and symbolic links
3164 T}
3165 T{
3166 @io\-event
3167 T}:T{
3168 Event loop system calls (\fBpoll\fR(2), \fBselect\fR(2), \fBepoll\fR(7), \fBeventfd\fR(2) and related calls)
3169 T}
3170 T{
3171 @ipc
3172 T}:T{
3173 Pipes, SysV IPC, POSIX Message Queues and other IPC (\fBmq_overview\fR(7), \fBsvipc\fR(7))
3174 T}
3175 T{
3176 @keyring
3177 T}:T{
3178 Kernel keyring access (\fBkeyctl\fR(2) and related calls)
3179 T}
3180 T{
3181 @memlock
3182 T}:T{
3183 Locking of memory in RAM (\fBmlock\fR(2), \fBmlockall\fR(2) and related calls)
3184 T}
3185 T{
3186 @module
3187 T}:T{
3188 Loading and unloading of kernel modules (\fBinit_module\fR(2), \fBdelete_module\fR(2) and related calls)
3189 T}
3190 T{
3191 @mount
3192 T}:T{
3193 Mounting and unmounting of file systems (\fBmount\fR(2), \fBchroot\fR(2), and related calls)
3194 T}
3195 T{
3196 @network\-io
3197 T}:T{
3198 Socket I/O (including local AF_UNIX): \fBsocket\fR(7), \fBunix\fR(7)
3199 T}
3200 T{
3201 @obsolete
3202 T}:T{
3203 Unusual, obsolete or unimplemented (\fBcreate_module\fR(2), \fBgtty\fR(2), \&...)
3204 T}
3205 T{
3206 @pkey
3207 T}:T{
3208 System calls that deal with memory protection keys (\fBpkeys\fR(7))
3209 T}
3210 T{
3211 @privileged
3212 T}:T{
3213 All system calls which need super\-user capabilities (\fBcapabilities\fR(7))
3214 T}
3215 T{
3216 @process
3217 T}:T{
3218 Process control, execution, namespacing operations (\fBclone\fR(2), \fBkill\fR(2), \fBnamespaces\fR(7), \&...)
3219 T}
3220 T{
3221 @raw\-io
3222 T}:T{
3223 Raw I/O port access (\fBioperm\fR(2), \fBiopl\fR(2), \fBpciconfig_read()\fR, \&...)
3224 T}
3225 T{
3226 @reboot
3227 T}:T{
3228 System calls for rebooting and reboot preparation (\fBreboot\fR(2), \fBkexec()\fR, \&...)
3229 T}
3230 T{
3231 @resources
3232 T}:T{
3233 System calls for changing resource limits, memory and scheduling parameters (\fBsetrlimit\fR(2), \fBsetpriority\fR(2), \&...)
3234 T}
3235 T{
3236 @sandbox
3237 T}:T{
3238 System calls for sandboxing programs (\fBseccomp\fR(2), Landlock system calls, \&...)
3239 T}
3240 T{
3241 @setuid
3242 T}:T{
3243 System calls for changing user ID and group ID credentials, (\fBsetuid\fR(2), \fBsetgid\fR(2), \fBsetresuid\fR(2), \&...)
3244 T}
3245 T{
3246 @signal
3247 T}:T{
3248 System calls for manipulating and handling process signals (\fBsignal\fR(2), \fBsigprocmask\fR(2), \&...)
3249 T}
3250 T{
3251 @swap
3252 T}:T{
3253 System calls for enabling/disabling swap devices (\fBswapon\fR(2), \fBswapoff\fR(2))
3254 T}
3255 T{
3256 @sync
3257 T}:T{
3258 Synchronizing files and memory to disk (\fBfsync\fR(2), \fBmsync\fR(2), and related calls)
3259 T}
3260 T{
3261 @system\-service
3262 T}:T{
3263 A reasonable set of system calls used by common system services, excluding any special purpose calls\&. This is the recommended starting point for allow\-listing system calls for system services, as it contains what is typically needed by system services, but excludes overly specific interfaces\&. For example, the following APIs are excluded: "@clock", "@mount", "@swap", "@reboot"\&.
3264 T}
3265 T{
3266 @timer
3267 T}:T{
3268 System calls for scheduling operations by time (\fBalarm\fR(2), \fBtimer_create\fR(2), \&...)
3269 T}
3270 T{
3271 @known
3272 T}:T{
3273 All system calls defined by the kernel\&. This list is defined statically in systemd based on a kernel version that was available when this systemd version was released\&. It will become progressively more out\-of\-date as the kernel is updated\&.
3274 T}
3275 .TE
3276 .sp 1
3277 Note, that as new system calls are added to the kernel, additional system calls might be added to the groups above\&. Contents of the sets may also change between systemd versions\&. In addition, the list of system calls depends on the kernel version and architecture for which systemd was compiled\&. Use
3278 \fBsystemd\-analyze\ \&syscall\-filter\fR
3279 to list the actual list of system calls in each filter\&.
3280 .sp
3281 Generally, allow\-listing system calls (rather than deny\-listing) is the safer mode of operation\&. It is recommended to enforce system call allow lists for all long\-running system services\&. Specifically, the following lines are a relatively safe basic choice for the majority of system services:
3282 .sp
3283 .if n \{\
3284 .RS 4
3285 .\}
3286 .nf
3287 [Service]
3288 SystemCallFilter=@system\-service
3289 SystemCallErrorNumber=EPERM
3290 .fi
3291 .if n \{\
3292 .RE
3293 .\}
3294 .sp
3295 Note that various kernel system calls are defined redundantly: there are multiple system calls for executing the same operation\&. For example, the
3296 \fBpidfd_send_signal()\fR
3297 system call may be used to execute operations similar to what can be done with the older
3298 \fBkill()\fR
3299 system call, hence blocking the latter without the former only provides weak protection\&. Since new system calls are added regularly to the kernel as development progresses, keeping system call deny lists comprehensive requires constant work\&. It is thus recommended to use allow\-listing instead, which offers the benefit that new system calls are by default implicitly blocked until the allow list is updated\&.
3300 .sp
3301 Also note that a number of system calls are required to be accessible for the dynamic linker to work\&. The dynamic linker is required for running most regular programs (specifically: all dynamic ELF binaries, which is how most distributions build packaged programs)\&. This means that blocking these system calls (which include
3302 \fBopen()\fR,
3303 \fBopenat()\fR
3304 or
3305 \fBmmap()\fR) will make most programs typically shipped with generic distributions unusable\&.
3306 .sp
3307 It is recommended to combine the file system namespacing related options with
3308 \fISystemCallFilter=~@mount\fR, in order to prohibit the unit\*(Aqs processes to undo the mappings\&. Specifically these are the options
3309 \fIPrivateTmp=\fR,
3310 \fIPrivateDevices=\fR,
3311 \fIProtectSystem=\fR,
3312 \fIProtectHome=\fR,
3313 \fIProtectKernelTunables=\fR,
3314 \fIProtectControlGroups=\fR,
3315 \fIProtectKernelLogs=\fR,
3316 \fIProtectClock=\fR,
3317 \fIReadOnlyPaths=\fR,
3318 \fIInaccessiblePaths=\fR
3319 and
3320 \fIReadWritePaths=\fR\&.
3321 .sp
3322 Added in version 187\&.
3323 .RE
3324 .PP
3325 \fISystemCallErrorNumber=\fR
3326 .RS 4
3327 Takes an
3328 "errno"
3329 error number (between 1 and 4095) or errno name such as
3330 \fBEPERM\fR,
3331 \fBEACCES\fR
3332 or
3333 \fBEUCLEAN\fR, to return when the system call filter configured with
3334 \fISystemCallFilter=\fR
3335 is triggered, instead of terminating the process immediately\&. See
3336 \fBerrno\fR(3)
3337 for a full list of error codes\&. When this setting is not used, or when the empty string or the special setting
3338 "kill"
3339 is assigned, the process will be terminated immediately when the filter is triggered\&.
3340 .sp
3341 Added in version 209\&.
3342 .RE
3343 .PP
3344 \fISystemCallArchitectures=\fR
3345 .RS 4
3346 Takes a space\-separated list of architecture identifiers to include in the system call filter\&. The known architecture identifiers are the same as for
3347 \fIConditionArchitecture=\fR
3348 described in
3349 \fBsystemd.unit\fR(5), as well as
3350 \fBx32\fR,
3351 \fBmips64\-n32\fR,
3352 \fBmips64\-le\-n32\fR, and the special identifier
3353 \fBnative\fR\&. The special identifier
3354 \fBnative\fR
3355 implicitly maps to the native architecture of the system (or more precisely: to the architecture the system manager is compiled for)\&. By default, this option is set to the empty list, i\&.e\&. no filtering is applied\&.
3356 .sp
3357 If this setting is used, processes of this unit will only be permitted to call native system calls, and system calls of the specified architectures\&. For the purposes of this option, the x32 architecture is treated as including x86\-64 system calls\&. However, this setting still fulfills its purpose, as explained below, on x32\&.
3358 .sp
3359 System call filtering is not equally effective on all architectures\&. For example, on x86 filtering of network socket\-related calls is not possible, due to ABI limitations \(em a limitation that x86\-64 does not have, however\&. On systems supporting multiple ABIs at the same time \(em such as x86/x86\-64 \(em it is hence recommended to limit the set of permitted system call architectures so that secondary ABIs may not be used to circumvent the restrictions applied to the native ABI of the system\&. In particular, setting
3360 \fISystemCallArchitectures=native\fR
3361 is a good choice for disabling non\-native ABIs\&.
3362 .sp
3363 System call architectures may also be restricted system\-wide via the
3364 \fISystemCallArchitectures=\fR
3365 option in the global configuration\&. See
3366 \fBsystemd-system.conf\fR(5)
3367 for details\&.
3368 .sp
3369 Added in version 209\&.
3370 .RE
3371 .PP
3372 \fISystemCallLog=\fR
3373 .RS 4
3374 Takes a space\-separated list of system call names\&. If this setting is used, all system calls executed by the unit processes for the listed ones will be logged\&. If the first character of the list is
3375 "~", the effect is inverted: all system calls except the listed system calls will be logged\&. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel (\*(Aqseccomp filtering\*(Aq) and is useful for auditing or setting up a minimal sandboxing environment\&. This option may be specified more than once, in which case the filter masks are merged\&. If the empty string is assigned, the filter is reset, all prior assignments will have no effect\&. This does not affect commands prefixed with
3376 "+"\&.
3377 .sp
3378 Added in version 247\&.
3379 .RE
3380 .SH "ENVIRONMENT"
3381 .PP
3382 \fIEnvironment=\fR
3383 .RS 4
3384 Sets environment variables for executed processes\&. Each line is unquoted using the rules described in "Quoting" section in
3385 \fBsystemd.syntax\fR(7)
3386 and becomes a list of variable assignments\&. If you need to assign a value containing spaces or the equals sign to a variable, put quotes around the whole assignment\&. Variable expansion is not performed inside the strings and the
3387 "$"
3388 character has no special meaning\&. Specifier expansion is performed, see the "Specifiers" section in
3389 \fBsystemd.unit\fR(5)\&.
3390 .sp
3391 This option may be specified more than once, in which case all listed variables will be set\&. If the same variable is listed twice, the later setting will override the earlier setting\&. If the empty string is assigned to this option, the list of environment variables is reset, all prior assignments have no effect\&.
3392 .sp
3393 The names of the variables can contain ASCII letters, digits, and the underscore character\&. Variable names cannot be empty or start with a digit\&. In variable values, most characters are allowed, but non\-printable characters are currently rejected\&.
3394 .sp
3395 Example:
3396 .sp
3397 .if n \{\
3398 .RS 4
3399 .\}
3400 .nf
3401 Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"
3402 .fi
3403 .if n \{\
3404 .RE
3405 .\}
3406 .sp
3407 gives three variables
3408 "VAR1",
3409 "VAR2",
3410 "VAR3"
3411 with the values
3412 "word1 word2",
3413 "word3",
3414 "$word 5 6"\&.
3415 .sp
3416 See
3417 \fBenviron\fR(7)
3418 for details about environment variables\&.
3419 .sp
3420 Note that environment variables are not suitable for passing secrets (such as passwords, key material, \&...) to service processes\&. Environment variables set for a unit are exposed to unprivileged clients via D\-Bus IPC, and generally not understood as being data that requires protection\&. Moreover, environment variables are propagated down the process tree, including across security boundaries (such as setuid/setgid executables), and hence might leak to processes that should not have access to the secret data\&. Use
3421 \fILoadCredential=\fR,
3422 \fILoadCredentialEncrypted=\fR
3423 or
3424 \fISetCredentialEncrypted=\fR
3425 (see below) to pass data to unit processes securely\&.
3426 .RE
3427 .PP
3428 \fIEnvironmentFile=\fR
3429 .RS 4
3430 Similar to
3431 \fIEnvironment=\fR, but reads the environment variables from a text file\&. The text file should contain newline\-separated variable assignments\&. Empty lines, lines without an
3432 "="
3433 separator, or lines starting with
3434 ";"
3435 or
3436 "#"
3437 will be ignored, which may be used for commenting\&. The file must be encoded with UTF\-8\&. Valid characters are
3438 \m[blue]\fBunicode scalar values\fR\m[]\&\s-2\u[9]\d\s+2
3439 other than
3440 \m[blue]\fBunicode noncharacters\fR\m[]\&\s-2\u[10]\d\s+2,
3441 \fBU+0000\fR
3442 \fBNUL\fR, and
3443 \fBU+FEFF\fR
3444 \m[blue]\fBunicode byte order mark\fR\m[]\&\s-2\u[11]\d\s+2\&. Control codes other than
3445 \fBNUL\fR
3446 are allowed\&.
3447 .sp
3448 In the file, an unquoted value after the
3449 "="
3450 is parsed with the same backslash\-escape rules as
3451 \m[blue]\fBPOSIX shell unquoted text\fR\m[]\&\s-2\u[12]\d\s+2, but unlike in a shell, interior whitespace is preserved and quotes after the first non\-whitespace character are preserved\&. Leading and trailing whitespace (space, tab, carriage return) is discarded, but interior whitespace within the line is preserved verbatim\&. A line ending with a backslash will be continued to the following one, with the newline itself discarded\&. A backslash
3452 "\e"
3453 followed by any character other than newline will preserve the following character, so that
3454 "\e\e"
3455 will become the value
3456 "\e"\&.
3457 .sp
3458 In the file, a
3459 "\*(Aq"\-quoted value after the
3460 "="
3461 can span multiple lines and contain any character verbatim other than single quote, like
3462 \m[blue]\fBPOSIX shell single\-quoted text\fR\m[]\&\s-2\u[13]\d\s+2\&. No backslash\-escape sequences are recognized\&. Leading and trailing whitespace outside of the single quotes is discarded\&.
3463 .sp
3464 In the file, a
3465 """\-quoted value after the
3466 "="
3467 can span multiple lines, and the same escape sequences are recognized as in
3468 \m[blue]\fBPOSIX shell double\-quoted text\fR\m[]\&\s-2\u[14]\d\s+2\&. Backslash ("\e") followed by any of
3469 ""\e`$"
3470 will preserve that character\&. A backslash followed by newline is a line continuation, and the newline itself is discarded\&. A backslash followed by any other character is ignored; both the backslash and the following character are preserved verbatim\&. Leading and trailing whitespace outside of the double quotes is discarded\&.
3471 .sp
3472 The argument passed should be an absolute filename or wildcard expression, optionally prefixed with
3473 "\-", which indicates that if the file does not exist, it will not be read and no error or warning message is logged\&. This option may be specified more than once in which case all specified files are read\&. If the empty string is assigned to this option, the list of file to read is reset, all prior assignments have no effect\&.
3474 .sp
3475 The files listed with this directive will be read shortly before the process is executed (more specifically, after all processes from a previous unit state terminated\&. This means you can generate these files in one unit state, and read it with this option in the next\&. The files are read from the file system of the service manager, before any file system changes like bind mounts take place)\&.
3476 .sp
3477 Settings from these files override settings made with
3478 \fIEnvironment=\fR\&. If the same variable is set twice from these files, the files will be read in the order they are specified and the later setting will override the earlier setting\&.
3479 .RE
3480 .PP
3481 \fIPassEnvironment=\fR
3482 .RS 4
3483 Pass environment variables set for the system service manager to executed processes\&. Takes a space\-separated list of variable names\&. This option may be specified more than once, in which case all listed variables will be passed\&. If the empty string is assigned to this option, the list of environment variables to pass is reset, all prior assignments have no effect\&. Variables specified that are not set for the system manager will not be passed and will be silently ignored\&. Note that this option is only relevant for the system service manager, as system services by default do not automatically inherit any environment variables set for the service manager itself\&. However, in case of the user service manager all environment variables are passed to the executed processes anyway, hence this option is without effect for the user service manager\&.
3484 .sp
3485 Variables set for invoked processes due to this setting are subject to being overridden by those configured with
3486 \fIEnvironment=\fR
3487 or
3488 \fIEnvironmentFile=\fR\&.
3489 .sp
3490 Example:
3491 .sp
3492 .if n \{\
3493 .RS 4
3494 .\}
3495 .nf
3496 PassEnvironment=VAR1 VAR2 VAR3
3497 .fi
3498 .if n \{\
3499 .RE
3500 .\}
3501 .sp
3502 passes three variables
3503 "VAR1",
3504 "VAR2",
3505 "VAR3"
3506 with the values set for those variables in PID1\&.
3507 .sp
3508 See
3509 \fBenviron\fR(7)
3510 for details about environment variables\&.
3511 .sp
3512 Added in version 228\&.
3513 .RE
3514 .PP
3515 \fIUnsetEnvironment=\fR
3516 .RS 4
3517 Explicitly unset environment variable assignments that would normally be passed from the service manager to invoked processes of this unit\&. Takes a space\-separated list of variable names or variable assignments\&. This option may be specified more than once, in which case all listed variables/assignments will be unset\&. If the empty string is assigned to this option, the list of environment variables/assignments to unset is reset\&. If a variable assignment is specified (that is: a variable name, followed by
3518 "=", followed by its value), then any environment variable matching this precise assignment is removed\&. If a variable name is specified (that is a variable name without any following
3519 "="
3520 or value), then any assignment matching the variable name, regardless of its value is removed\&. Note that the effect of
3521 \fIUnsetEnvironment=\fR
3522 is applied as final step when the environment list passed to executed processes is compiled\&. That means it may undo assignments from any configuration source, including assignments made through
3523 \fIEnvironment=\fR
3524 or
3525 \fIEnvironmentFile=\fR, inherited from the system manager\*(Aqs global set of environment variables, inherited via
3526 \fIPassEnvironment=\fR, set by the service manager itself (such as
3527 \fI$NOTIFY_SOCKET\fR
3528 and such), or set by a PAM module (in case
3529 \fIPAMName=\fR
3530 is used)\&.
3531 .sp
3532 See "Environment Variables in Spawned Processes" below for a description of how those settings combine to form the inherited environment\&. See
3533 \fBenviron\fR(7)
3534 for general information about environment variables\&.
3535 .sp
3536 Added in version 235\&.
3537 .RE
3538 .SH "LOGGING AND STANDARD INPUT/OUTPUT"
3539 .PP
3540 \fIStandardInput=\fR
3541 .RS 4
3542 Controls where file descriptor 0 (STDIN) of the executed processes is connected to\&. Takes one of
3543 \fBnull\fR,
3544 \fBtty\fR,
3545 \fBtty\-force\fR,
3546 \fBtty\-fail\fR,
3547 \fBdata\fR,
3548 \fBfile:\fR\fB\fIpath\fR\fR,
3549 \fBsocket\fR
3550 or
3551 \fBfd:\fR\fB\fIname\fR\fR\&.
3552 .sp
3553 If
3554 \fBnull\fR
3555 is selected, standard input will be connected to
3556 /dev/null, i\&.e\&. all read attempts by the process will result in immediate EOF\&.
3557 .sp
3558 If
3559 \fBtty\fR
3560 is selected, standard input is connected to a TTY (as configured by
3561 \fITTYPath=\fR, see below) and the executed process becomes the controlling process of the terminal\&. If the terminal is already being controlled by another process, the executed process waits until the current controlling process releases the terminal\&.
3562 .sp
3563 \fBtty\-force\fR
3564 is similar to
3565 \fBtty\fR, but the executed process is forcefully and immediately made the controlling process of the terminal, potentially removing previous controlling processes from the terminal\&.
3566 .sp
3567 \fBtty\-fail\fR
3568 is similar to
3569 \fBtty\fR, but if the terminal already has a controlling process start\-up of the executed process fails\&.
3570 .sp
3571 The
3572 \fBdata\fR
3573 option may be used to configure arbitrary textual or binary data to pass via standard input to the executed process\&. The data to pass is configured via
3574 \fIStandardInputText=\fR/\fIStandardInputData=\fR
3575 (see below)\&. Note that the actual file descriptor type passed (memory file, regular file, UNIX pipe, \&...) might depend on the kernel and available privileges\&. In any case, the file descriptor is read\-only, and when read returns the specified data followed by EOF\&.
3576 .sp
3577 The
3578 \fBfile:\fR\fB\fIpath\fR\fR
3579 option may be used to connect a specific file system object to standard input\&. An absolute path following the
3580 ":"
3581 character is expected, which may refer to a regular file, a FIFO or special file\&. If an
3582 \fBAF_UNIX\fR
3583 socket in the file system is specified, a stream socket is connected to it\&. The latter is useful for connecting standard input of processes to arbitrary system services\&.
3584 .sp
3585 The
3586 \fBsocket\fR
3587 option is valid in socket\-activated services only, and requires the relevant socket unit file (see
3588 \fBsystemd.socket\fR(5)
3589 for details) to have
3590 \fIAccept=yes\fR
3591 set, or to specify a single socket only\&. If this option is set, standard input will be connected to the socket the service was activated from, which is primarily useful for compatibility with daemons designed for use with the traditional
3592 \fBinetd\fR(8)
3593 socket activation daemon (\fI$LISTEN_FDS\fR
3594 (and related) environment variables are not passed when
3595 \fBsocket\fR
3596 value is configured)\&.
3597 .sp
3598 The
3599 \fBfd:\fR\fB\fIname\fR\fR
3600 option connects standard input to a specific, named file descriptor provided by a socket unit\&. The name may be specified as part of this option, following a
3601 ":"
3602 character (e\&.g\&.
3603 "fd:foobar")\&. If no name is specified, the name
3604 "stdin"
3605 is implied (i\&.e\&.
3606 "fd"
3607 is equivalent to
3608 "fd:stdin")\&. At least one socket unit defining the specified name must be provided via the
3609 \fISockets=\fR
3610 option, and the file descriptor name may differ from the name of its containing socket unit\&. If multiple matches are found, the first one will be used\&. See
3611 \fIFileDescriptorName=\fR
3612 in
3613 \fBsystemd.socket\fR(5)
3614 for more details about named file descriptors and their ordering\&.
3615 .sp
3616 This setting defaults to
3617 \fBnull\fR, unless
3618 \fIStandardInputText=\fR/\fIStandardInputData=\fR
3619 are set, in which case it defaults to
3620 \fBdata\fR\&.
3621 .RE
3622 .PP
3623 \fIStandardOutput=\fR
3624 .RS 4
3625 Controls where file descriptor 1 (stdout) of the executed processes is connected to\&. Takes one of
3626 \fBinherit\fR,
3627 \fBnull\fR,
3628 \fBtty\fR,
3629 \fBjournal\fR,
3630 \fBkmsg\fR,
3631 \fBjournal+console\fR,
3632 \fBkmsg+console\fR,
3633 \fBfile:\fR\fB\fIpath\fR\fR,
3634 \fBappend:\fR\fB\fIpath\fR\fR,
3635 \fBtruncate:\fR\fB\fIpath\fR\fR,
3636 \fBsocket\fR
3637 or
3638 \fBfd:\fR\fB\fIname\fR\fR\&.
3639 .sp
3640 \fBinherit\fR
3641 duplicates the file descriptor of standard input for standard output\&.
3642 .sp
3643 \fBnull\fR
3644 connects standard output to
3645 /dev/null, i\&.e\&. everything written to it will be lost\&.
3646 .sp
3647 \fBtty\fR
3648 connects standard output to a tty (as configured via
3649 \fITTYPath=\fR, see below)\&. If the TTY is used for output only, the executed process will not become the controlling process of the terminal, and will not fail or wait for other processes to release the terminal\&. Note: if a unit tries to print multiple lines to a TTY during bootup or shutdown, then there\*(Aqs a chance that those lines will be broken up by status messages\&.
3650 \fBSetShowStatus()\fR
3651 can be used to prevent this problem\&. See
3652 \fBorg.freedesktop.systemd1\fR(5)
3653 for details\&.
3654 .sp
3655 \fBjournal\fR
3656 connects standard output with the journal, which is accessible via
3657 \fBjournalctl\fR(1)\&. Note that everything that is written to kmsg (see below) is implicitly stored in the journal as well, the specific option listed below is hence a superset of this one\&. (Also note that any external, additional syslog daemons receive their log data from the journal, too, hence this is the option to use when logging shall be processed with such a daemon\&.)
3658 .sp
3659 \fBkmsg\fR
3660 connects standard output with the kernel log buffer which is accessible via
3661 \fBdmesg\fR(1), in addition to the journal\&. The journal daemon might be configured to send all logs to kmsg anyway, in which case this option is no different from
3662 \fBjournal\fR\&.
3663 .sp
3664 \fBjournal+console\fR
3665 and
3666 \fBkmsg+console\fR
3667 work in a similar way as the two options above but copy the output to the system console as well\&.
3668 .sp
3669 The
3670 \fBfile:\fR\fB\fIpath\fR\fR
3671 option may be used to connect a specific file system object to standard output\&. The semantics are similar to the same option of
3672 \fIStandardInput=\fR, see above\&. If
3673 \fIpath\fR
3674 refers to a regular file on the filesystem, it is opened (created if it does not exist yet using privileges of the user executing the systemd process) for writing at the beginning of the file, but without truncating it\&. If standard input and output are directed to the same file path, it is opened only once \(em for reading as well as writing \(em and duplicated\&. This is particularly useful when the specified path refers to an
3675 \fBAF_UNIX\fR
3676 socket in the file system, as in that case only a single stream connection is created for both input and output\&.
3677 .sp
3678 \fBappend:\fR\fB\fIpath\fR\fR
3679 is similar to
3680 \fBfile:\fR\fB\fIpath\fR\fR
3681 above, but it opens the file in append mode\&.
3682 .sp
3683 \fBtruncate:\fR\fB\fIpath\fR\fR
3684 is similar to
3685 \fBfile:\fR\fB\fIpath\fR\fR
3686 above, but it truncates the file when opening it\&. For units with multiple command lines, e\&.g\&.
3687 \fIType=oneshot\fR
3688 services with multiple
3689 \fIExecStart=\fR, or services with
3690 \fIExecCondition=\fR,
3691 \fIExecStartPre=\fR
3692 or
3693 \fIExecStartPost=\fR, the output file is reopened and therefore re\-truncated for each command line\&. If the output file is truncated while another process still has the file open, e\&.g\&. by an
3694 \fIExecReload=\fR
3695 running concurrently with an
3696 \fIExecStart=\fR, and the other process continues writing to the file without adjusting its offset, then the space between the file pointers of the two processes may be filled with
3697 \fBNUL\fR
3698 bytes, producing a sparse file\&. Thus,
3699 \fBtruncate:\fR\fB\fIpath\fR\fR
3700 is typically only useful for units where only one process runs at a time, such as services with a single
3701 \fIExecStart=\fR
3702 and no
3703 \fIExecStartPost=\fR,
3704 \fIExecReload=\fR,
3705 \fIExecStop=\fR
3706 or similar\&.
3707 .sp
3708 \fBsocket\fR
3709 connects standard output to a socket acquired via socket activation\&. The semantics are similar to the same option of
3710 \fIStandardInput=\fR, see above\&.
3711 .sp
3712 The
3713 \fBfd:\fR\fB\fIname\fR\fR
3714 option connects standard output to a specific, named file descriptor provided by a socket unit\&. A name may be specified as part of this option, following a
3715 ":"
3716 character (e\&.g\&.
3717 "fd:\fIfoobar\fR")\&. If no name is specified, the name
3718 "stdout"
3719 is implied (i\&.e\&.
3720 "fd"
3721 is equivalent to
3722 "fd:stdout")\&. At least one socket unit defining the specified name must be provided via the
3723 \fISockets=\fR
3724 option, and the file descriptor name may differ from the name of its containing socket unit\&. If multiple matches are found, the first one will be used\&. See
3725 \fIFileDescriptorName=\fR
3726 in
3727 \fBsystemd.socket\fR(5)
3728 for more details about named descriptors and their ordering\&.
3729 .sp
3730 If the standard output (or error output, see below) of a unit is connected to the journal or the kernel log buffer, the unit will implicitly gain a dependency of type
3731 \fIAfter=\fR
3732 on
3733 systemd\-journald\&.socket
3734 (also see the "Implicit Dependencies" section above)\&. Also note that in this case stdout (or stderr, see below) will be an
3735 \fBAF_UNIX\fR
3736 stream socket, and not a pipe or FIFO that can be reopened\&. This means when executing shell scripts the construct
3737 \fBecho "hello" > /dev/stderr\fR
3738 for writing text to stderr will not work\&. To mitigate this use the construct
3739 \fBecho "hello" >&2\fR
3740 instead, which is mostly equivalent and avoids this pitfall\&.
3741 .sp
3742 If
3743 \fIStandardInput=\fR
3744 is set to one of
3745 \fBtty\fR,
3746 \fBtty\-force\fR,
3747 \fBtty\-fail\fR,
3748 \fBsocket\fR, or
3749 \fBfd:\fR\fB\fIname\fR\fR, this setting defaults to
3750 \fBinherit\fR\&.
3751 .sp
3752 In other cases, this setting defaults to the value set with
3753 \fIDefaultStandardOutput=\fR
3754 in
3755 \fBsystemd-system.conf\fR(5), which defaults to
3756 \fBjournal\fR\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&.
3757 .RE
3758 .PP
3759 \fIStandardError=\fR
3760 .RS 4
3761 Controls where file descriptor 2 (stderr) of the executed processes is connected to\&. The available options are identical to those of
3762 \fIStandardOutput=\fR, with some exceptions: if set to
3763 \fBinherit\fR
3764 the file descriptor used for standard output is duplicated for standard error, while
3765 \fBfd:\fR\fB\fIname\fR\fR
3766 will use a default file descriptor name of
3767 "stderr"\&.
3768 .sp
3769 This setting defaults to the value set with
3770 \fIDefaultStandardError=\fR
3771 in
3772 \fBsystemd-system.conf\fR(5), which defaults to
3773 \fBinherit\fR\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&.
3774 .RE
3775 .PP
3776 \fIStandardInputText=\fR, \fIStandardInputData=\fR
3777 .RS 4
3778 Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to the executed processes\&. These settings have no effect unless
3779 \fIStandardInput=\fR
3780 is set to
3781 \fBdata\fR
3782 (which is the default if
3783 \fIStandardInput=\fR
3784 is not set otherwise, but
3785 \fIStandardInputText=\fR/\fIStandardInputData=\fR
3786 is)\&. Use this option to embed process input data directly in the unit file\&.
3787 .sp
3788 \fIStandardInputText=\fR
3789 accepts arbitrary textual data\&. C\-style escapes for special characters as well as the usual
3790 "%"\-specifiers are resolved\&. Each time this setting is used the specified text is appended to the per\-unit data buffer, followed by a newline character (thus every use appends a new line to the end of the buffer)\&. Note that leading and trailing whitespace of lines configured with this option is removed\&. If an empty line is specified the buffer is cleared (hence, in order to insert an empty line, add an additional
3791 "\en"
3792 to the end or beginning of a line)\&.
3793 .sp
3794 \fIStandardInputData=\fR
3795 accepts arbitrary binary data, encoded in
3796 \m[blue]\fBBase64\fR\m[]\&\s-2\u[15]\d\s+2\&. No escape sequences or specifiers are resolved\&. Any whitespace in the encoded version is ignored during decoding\&.
3797 .sp
3798 Note that
3799 \fIStandardInputText=\fR
3800 and
3801 \fIStandardInputData=\fR
3802 operate on the same data buffer, and may be mixed in order to configure both binary and textual data for the same input stream\&. The textual or binary data is joined strictly in the order the settings appear in the unit file\&. Assigning an empty string to either will reset the data buffer\&.
3803 .sp
3804 Please keep in mind that in order to maintain readability long unit file settings may be split into multiple lines, by suffixing each line (except for the last) with a
3805 "\e"
3806 character (see
3807 \fBsystemd.unit\fR(5)
3808 for details)\&. This is particularly useful for large data configured with these two options\&. Example:
3809 .sp
3810 .if n \{\
3811 .RS 4
3812 .\}
3813 .nf
3814 \&...
3815 StandardInput=data
3816 StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZXMgYW5kIHNvIGRv \e
3817 IEkKQSBmdWxsIGNvbW1pdG1lbnQncyB3aGF0IEnigLJtIHRoaW5raW5nIG9mCllvdSB3b3VsZG4n \e
3818 dCBnZXQgdGhpcyBmcm9tIGFueSBvdGhlciBndXkKSSBqdXN0IHdhbm5hIHRlbGwgeW91IGhvdyBJ \e
3819 J20gZmVlbGluZwpHb3R0YSBtYWtlIHlvdSB1bmRlcnN0YW5kCgpOZXZlciBnb25uYSBnaXZlIHlv \e
3820 dSB1cApOZXZlciBnb25uYSBsZXQgeW91IGRvd24KTmV2ZXIgZ29ubmEgcnVuIGFyb3VuZCBhbmQg \e
3821 ZGVzZXJ0IHlvdQpOZXZlciBnb25uYSBtYWtlIHlvdSBjcnkKTmV2ZXIgZ29ubmEgc2F5IGdvb2Ri \e
3822 eWUKTmV2ZXIgZ29ubmEgdGVsbCBhIGxpZSBhbmQgaHVydCB5b3UK
3823 \&...
3824 .fi
3825 .if n \{\
3826 .RE
3827 .\}
3828 .sp
3829 Added in version 236\&.
3830 .RE
3831 .PP
3832 \fILogLevelMax=\fR
3833 .RS 4
3834 Configures filtering by log level of log messages generated by this unit\&. Takes a
3835 \fBsyslog\fR
3836 log level, one of
3837 \fBemerg\fR
3838 (lowest log level, only highest priority messages),
3839 \fBalert\fR,
3840 \fBcrit\fR,
3841 \fBerr\fR,
3842 \fBwarning\fR,
3843 \fBnotice\fR,
3844 \fBinfo\fR,
3845 \fBdebug\fR
3846 (highest log level, also lowest priority messages)\&. See
3847 \fBsyslog\fR(3)
3848 for details\&. By default no filtering is applied (i\&.e\&. the default maximum log level is
3849 \fBdebug\fR)\&. Use this option to configure the logging system to drop log messages of a specific service above the specified level\&. For example, set
3850 \fILogLevelMax=\fR\fBinfo\fR
3851 in order to turn off debug logging of a particularly chatty unit\&. Note that the configured level is applied to any log messages written by any of the processes belonging to this unit, as well as any log messages written by the system manager process (PID 1) in reference to this unit, sent via any supported logging protocol\&. The filtering is applied early in the logging pipeline, before any kind of further processing is done\&. Moreover, messages which pass through this filter successfully might still be dropped by filters applied at a later stage in the logging subsystem\&. For example,
3852 \fIMaxLevelStore=\fR
3853 configured in
3854 \fBjournald.conf\fR(5)
3855 might prohibit messages of higher log levels to be stored on disk, even though the per\-unit
3856 \fILogLevelMax=\fR
3857 permitted it to be processed\&.
3858 .sp
3859 Added in version 236\&.
3860 .RE
3861 .PP
3862 \fILogExtraFields=\fR
3863 .RS 4
3864 Configures additional log metadata fields to include in all log records generated by processes associated with this unit, including systemd\&. This setting takes one or more journal field assignments in the format
3865 "FIELD=VALUE"
3866 separated by whitespace\&. See
3867 \fBsystemd.journal-fields\fR(7)
3868 for details on the journal field concept\&. Even though the underlying journal implementation permits binary field values, this setting accepts only valid UTF\-8 values\&. To include space characters in a journal field value, enclose the assignment in double quotes (")\&.
3869 The usual specifiers are expanded in all assignments (see below)\&. Note that this setting is not only useful for attaching additional metadata to log records of a unit, but given that all fields and values are indexed may also be used to implement cross\-unit log record matching\&. Assign an empty string to reset the list\&.
3870 .sp
3871 Note that this functionality is currently only available in system services, not in per\-user services\&.
3872 .sp
3873 Added in version 236\&.
3874 .RE
3875 .PP
3876 \fILogRateLimitIntervalSec=\fR, \fILogRateLimitBurst=\fR
3877 .RS 4
3878 Configures the rate limiting that is applied to log messages generated by this unit\&. If, in the time interval defined by
3879 \fILogRateLimitIntervalSec=\fR, more messages than specified in
3880 \fILogRateLimitBurst=\fR
3881 are logged by a service, all further messages within the interval are dropped until the interval is over\&. A message about the number of dropped messages is generated\&. The time specification for
3882 \fILogRateLimitIntervalSec=\fR
3883 may be specified in the following units: "s", "min", "h", "ms", "us"\&. See
3884 \fBsystemd.time\fR(7)
3885 for details\&. The default settings are set by
3886 \fIRateLimitIntervalSec=\fR
3887 and
3888 \fIRateLimitBurst=\fR
3889 configured in
3890 \fBjournald.conf\fR(5)\&. Note that this only applies to log messages that are processed by the logging subsystem, i\&.e\&. by
3891 \fBsystemd-journald.service\fR(8)\&. This means that if you connect a service\*(Aqs stderr directly to a file via
3892 \fIStandardOutput=file:\&...\fR
3893 or a similar setting, the rate limiting will not be applied to messages written that way (but it will be enforced for messages generated via
3894 \fBsyslog\fR(3)
3895 and similar functions)\&.
3896 .sp
3897 Added in version 240\&.
3898 .RE
3899 .PP
3900 \fILogFilterPatterns=\fR
3901 .RS 4
3902 Define an extended regular expression to filter log messages based on the
3903 \fIMESSAGE=\fR
3904 field of the structured message\&. If the first character of the pattern is
3905 "~", log entries matching the pattern should be discarded\&. This option takes a single pattern as an argument but can be used multiple times to create a list of allowed and denied patterns\&. If the empty string is assigned, the filter is reset, and all prior assignments will have no effect\&.
3906 .sp
3907 Because the
3908 "~"
3909 character is used to define denied patterns, it must be replaced with
3910 "\ex7e"
3911 to allow a message starting with
3912 "~"\&. For example,
3913 "~foobar"
3914 would add a pattern matching
3915 "foobar"
3916 to the deny list, while
3917 "\ex7efoobar"
3918 would add a pattern matching
3919 "~foobar"
3920 to the allow list\&.
3921 .sp
3922 Log messages are tested against denied patterns (if any), then against allowed patterns (if any)\&. If a log message matches any of the denied patterns, it is discarded immediately without considering allowed patterns\&. Remaining log messages are tested against allowed patterns\&. Messages matching against none of the allowed pattern are discarded\&. If no allowed patterns are defined, then all messages are processed directly after going through denied filters\&.
3923 .sp
3924 Filtering is based on the unit for which
3925 \fILogFilterPatterns=\fR
3926 is defined, meaning log messages coming from
3927 \fBsystemd\fR(1)
3928 about the unit are not taken into account\&. Filtered log messages will not be forwarded to traditional syslog daemons, the kernel log buffer (kmsg), the systemd console, or sent as wall messages to all logged\-in users\&.
3929 .sp
3930 Note that this functionality is currently only available in system services, not in per\-user services\&.
3931 .sp
3932 Added in version 253\&.
3933 .RE
3934 .PP
3935 \fILogNamespace=\fR
3936 .RS 4
3937 Run the unit\*(Aqs processes in the specified journal namespace\&. Expects a short user\-defined string identifying the namespace\&. If not used the processes of the service are run in the default journal namespace, i\&.e\&. their log stream is collected and processed by
3938 systemd\-journald\&.service\&. If this option is used any log data generated by processes of this unit (regardless if via the
3939 \fBsyslog()\fR, journal native logging or stdout/stderr logging) is collected and processed by an instance of the
3940 systemd\-journald@\&.service
3941 template unit, which manages the specified namespace\&. The log data is stored in a data store independent from the default log namespace\*(Aqs data store\&. See
3942 \fBsystemd-journald.service\fR(8)
3943 for details about journal namespaces\&.
3944 .sp
3945 Internally, journal namespaces are implemented through Linux mount namespacing and over\-mounting the directory that contains the relevant
3946 \fBAF_UNIX\fR
3947 sockets used for logging in the unit\*(Aqs mount namespace\&. Since mount namespaces are used this setting disconnects propagation of mounts from the unit\*(Aqs processes to the host, similarly to how
3948 \fIReadOnlyPaths=\fR
3949 and similar settings describe above work\&. Journal namespaces may hence not be used for services that need to establish mount points on the host\&.
3950 .sp
3951 When this option is used the unit will automatically gain ordering and requirement dependencies on the two socket units associated with the
3952 systemd\-journald@\&.service
3953 instance so that they are automatically established prior to the unit starting up\&. Note that when this option is used log output of this service does not appear in the regular
3954 \fBjournalctl\fR(1)
3955 output, unless the
3956 \fB\-\-namespace=\fR
3957 option is used\&.
3958 .sp
3959 This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&.
3960 .sp
3961 Added in version 245\&.
3962 .RE
3963 .PP
3964 \fISyslogIdentifier=\fR
3965 .RS 4
3966 Sets the process name ("\fBsyslog\fR
3967 tag") to prefix log lines sent to the logging system or the kernel log buffer with\&. If not set, defaults to the process name of the executed process\&. This option is only useful when
3968 \fIStandardOutput=\fR
3969 or
3970 \fIStandardError=\fR
3971 are set to
3972 \fBjournal\fR
3973 or
3974 \fBkmsg\fR
3975 (or to the same settings in combination with
3976 \fB+console\fR) and only applies to log messages written to stdout or stderr\&.
3977 .RE
3978 .PP
3979 \fISyslogFacility=\fR
3980 .RS 4
3981 Sets the
3982 \fBsyslog\fR
3983 facility identifier to use when logging\&. One of
3984 \fBkern\fR,
3985 \fBuser\fR,
3986 \fBmail\fR,
3987 \fBdaemon\fR,
3988 \fBauth\fR,
3989 \fBsyslog\fR,
3990 \fBlpr\fR,
3991 \fBnews\fR,
3992 \fBuucp\fR,
3993 \fBcron\fR,
3994 \fBauthpriv\fR,
3995 \fBftp\fR,
3996 \fBlocal0\fR,
3997 \fBlocal1\fR,
3998 \fBlocal2\fR,
3999 \fBlocal3\fR,
4000 \fBlocal4\fR,
4001 \fBlocal5\fR,
4002 \fBlocal6\fR
4003 or
4004 \fBlocal7\fR\&. See
4005 \fBsyslog\fR(3)
4006 for details\&. This option is only useful when
4007 \fIStandardOutput=\fR
4008 or
4009 \fIStandardError=\fR
4010 are set to
4011 \fBjournal\fR
4012 or
4013 \fBkmsg\fR
4014 (or to the same settings in combination with
4015 \fB+console\fR), and only applies to log messages written to stdout or stderr\&. Defaults to
4016 \fBdaemon\fR\&.
4017 .RE
4018 .PP
4019 \fISyslogLevel=\fR
4020 .RS 4
4021 The default
4022 \fBsyslog\fR
4023 log level to use when logging to the logging system or the kernel log buffer\&. One of
4024 \fBemerg\fR,
4025 \fBalert\fR,
4026 \fBcrit\fR,
4027 \fBerr\fR,
4028 \fBwarning\fR,
4029 \fBnotice\fR,
4030 \fBinfo\fR,
4031 \fBdebug\fR\&. See
4032 \fBsyslog\fR(3)
4033 for details\&. This option is only useful when
4034 \fIStandardOutput=\fR
4035 or
4036 \fIStandardError=\fR
4037 are set to
4038 \fBjournal\fR
4039 or
4040 \fBkmsg\fR
4041 (or to the same settings in combination with
4042 \fB+console\fR), and only applies to log messages written to stdout or stderr\&. Note that individual lines output by executed processes may be prefixed with a different log level which can be used to override the default log level specified here\&. The interpretation of these prefixes may be disabled with
4043 \fISyslogLevelPrefix=\fR, see below\&. For details, see
4044 \fBsd-daemon\fR(3)\&. Defaults to
4045 \fBinfo\fR\&.
4046 .RE
4047 .PP
4048 \fISyslogLevelPrefix=\fR
4049 .RS 4
4050 Takes a boolean argument\&. If true and
4051 \fIStandardOutput=\fR
4052 or
4053 \fIStandardError=\fR
4054 are set to
4055 \fBjournal\fR
4056 or
4057 \fBkmsg\fR
4058 (or to the same settings in combination with
4059 \fB+console\fR), log lines written by the executed process that are prefixed with a log level will be processed with this log level set but the prefix removed\&. If set to false, the interpretation of these prefixes is disabled and the logged lines are passed on as\-is\&. This only applies to log messages written to stdout or stderr\&. For details about this prefixing see
4060 \fBsd-daemon\fR(3)\&. Defaults to true\&.
4061 .RE
4062 .PP
4063 \fITTYPath=\fR
4064 .RS 4
4065 Sets the terminal device node to use if standard input, output, or error are connected to a TTY (see above)\&. Defaults to
4066 /dev/console\&.
4067 .RE
4068 .PP
4069 \fITTYReset=\fR
4070 .RS 4
4071 Reset the terminal device specified with
4072 \fITTYPath=\fR
4073 before and after execution\&. This does not erase the screen (see
4074 \fITTYVTDisallocate=\fR
4075 below for that)\&. Defaults to
4076 "no"\&.
4077 .RE
4078 .PP
4079 \fITTYVHangup=\fR
4080 .RS 4
4081 Disconnect all clients which have opened the terminal device specified with
4082 \fITTYPath=\fR
4083 before and after execution\&. Defaults to
4084 "no"\&.
4085 .RE
4086 .PP
4087 \fITTYColumns=\fR, \fITTYRows=\fR
4088 .RS 4
4089 Configure the size of the TTY specified with
4090 \fITTYPath=\fR\&. If unset or set to the empty string, it is attempted to retrieve the dimensions of the terminal screen via ANSI sequences, and if that fails the kernel defaults (typically 80x24) are used\&.
4091 .sp
4092 Added in version 250\&.
4093 .RE
4094 .PP
4095 \fITTYVTDisallocate=\fR
4096 .RS 4
4097 If the terminal device specified with
4098 \fITTYPath=\fR
4099 is a virtual console terminal, try to deallocate the TTY before and after execution\&. This ensures that the screen and scrollback buffer is cleared\&. If the terminal device is of any other type of TTY an attempt is made to clear the screen via ANSI sequences\&. Defaults to
4100 "no"\&.
4101 .RE
4102 .SH "CREDENTIALS"
4103 .PP
4104 \fILoadCredential=\fR\fIID\fR[:\fIPATH\fR], \fILoadCredentialEncrypted=\fR\fIID\fR[:\fIPATH\fR]
4105 .RS 4
4106 Pass a credential to the unit\&. Credentials are limited\-size binary or textual objects that may be passed to unit processes\&. They are primarily used for passing cryptographic keys (both public and private) or certificates, user account information or identity information from host to services\&. The data is accessible from the unit\*(Aqs processes via the file system, at a read\-only location that (if possible and permitted) is backed by non\-swappable memory\&. The data is only accessible to the user associated with the unit, via the
4107 \fIUser=\fR/\fIDynamicUser=\fR
4108 settings (as well as the superuser)\&. When available, the location of credentials is exported as the
4109 \fI$CREDENTIALS_DIRECTORY\fR
4110 environment variable to the unit\*(Aqs processes\&.
4111 .sp
4112 The
4113 \fILoadCredential=\fR
4114 setting takes a textual ID to use as name for a credential plus a file system path, separated by a colon\&. The ID must be a short ASCII string suitable as filename in the filesystem, and may be chosen freely by the user\&. If the specified path is absolute it is opened as regular file and the credential data is read from it\&. If the absolute path refers to an
4115 \fBAF_UNIX\fR
4116 stream socket in the file system a connection is made to it (only once at unit start\-up) and the credential data read from the connection, providing an easy IPC integration point for dynamically transferring credentials from other services\&.
4117 .sp
4118 If the specified path is not absolute and itself qualifies as valid credential identifier it is attempted to find a credential that the service manager itself received under the specified name \(em which may be used to propagate credentials from an invoking environment (e\&.g\&. a container manager that invoked the service manager) into a service\&. If no matching system credential is found, the directories
4119 /etc/credstore/,
4120 /run/credstore/
4121 and
4122 /usr/lib/credstore/
4123 are searched for files under the credential\*(Aqs name \(em which hence are recommended locations for credential data on disk\&. If
4124 \fILoadCredentialEncrypted=\fR
4125 is used
4126 /run/credstore\&.encrypted/,
4127 /etc/credstore\&.encrypted/, and
4128 /usr/lib/credstore\&.encrypted/
4129 are searched as well\&.
4130 .sp
4131 If the file system path is omitted it is chosen identical to the credential name, i\&.e\&. this is a terse way to declare credentials to inherit from the service manager into a service\&. This option may be used multiple times, each time defining an additional credential to pass to the unit\&.
4132 .sp
4133 Note that if the path is not specified or a valid credential identifier is given, i\&.e\&. in the above two cases, a missing credential is not considered fatal\&.
4134 .sp
4135 If an absolute path referring to a directory is specified, every file in that directory (recursively) will be loaded as a separate credential\&. The ID for each credential will be the provided ID suffixed with
4136 "_$FILENAME"
4137 (e\&.g\&.,
4138 "Key_file1")\&. When loading from a directory, symlinks will be ignored\&.
4139 .sp
4140 The contents of the file/socket may be arbitrary binary or textual data, including newline characters and
4141 \fBNUL\fR
4142 bytes\&.
4143 .sp
4144 The
4145 \fILoadCredentialEncrypted=\fR
4146 setting is identical to
4147 \fILoadCredential=\fR, except that the credential data is decrypted and authenticated before being passed on to the executed processes\&. Specifically, the referenced path should refer to a file or socket with an encrypted credential, as implemented by
4148 \fBsystemd-creds\fR(1)\&. This credential is loaded, decrypted, authenticated and then passed to the application in plaintext form, in the same way a regular credential specified via
4149 \fILoadCredential=\fR
4150 would be\&. A credential configured this way may be symmetrically encrypted/authenticated with a secret key derived from the system\*(Aqs TPM2 security chip, or with a secret key stored in
4151 /var/lib/systemd/credentials\&.secret, or with both\&. Using encrypted and authenticated credentials improves security as credentials are not stored in plaintext and only authenticated and decrypted into plaintext the moment a service requiring them is started\&. Moreover, credentials may be bound to the local hardware and installations, so that they cannot easily be analyzed offline, or be generated externally\&. When
4152 \fIDevicePolicy=\fR
4153 is set to
4154 "closed"
4155 or
4156 "strict", or set to
4157 "auto"
4158 and
4159 \fIDeviceAllow=\fR
4160 is set, or
4161 \fIPrivateDevices=\fR
4162 is set, then this setting adds
4163 /dev/tpmrm0
4164 with
4165 \fBrw\fR
4166 mode to
4167 \fIDeviceAllow=\fR\&. See
4168 \fBsystemd.resource-control\fR(5)
4169 for the details about
4170 \fIDevicePolicy=\fR
4171 or
4172 \fIDeviceAllow=\fR\&.
4173 .sp
4174 Note that encrypted credentials targeted for services of the per\-user service manager must be encrypted with
4175 \fBsystemd\-creds encrypt \-\-user\fR, and those for the system service manager without the
4176 \fB\-\-user\fR
4177 switch\&. Encrypted credentials are always targeted to a specific user or the system as a whole, and it is ensured that per\-user service managers cannot decrypt secrets intended for the system or for other users\&.
4178 .sp
4179 The credential files/IPC sockets must be accessible to the service manager, but do not have to be directly accessible to the unit\*(Aqs processes: the credential data is read and copied into separate, read\-only copies for the unit that are accessible to appropriately privileged processes\&. This is particularly useful in combination with
4180 \fIDynamicUser=\fR
4181 as this way privileged data can be made available to processes running under a dynamic UID (i\&.e\&. not a previously known one) without having to open up access to all users\&.
4182 .sp
4183 In order to reference the path a credential may be read from within a
4184 \fIExecStart=\fR
4185 command line use
4186 "${CREDENTIALS_DIRECTORY}/mycred", e\&.g\&.
4187 "ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred"\&. In order to reference the path a credential may be read from within a
4188 \fIEnvironment=\fR
4189 line use
4190 "%d/mycred", e\&.g\&.
4191 "Environment=MYCREDPATH=%d/mycred"\&. For system services the path may also be referenced as
4192 "/run/credentials/\fIUNITNAME\fR"
4193 in cases where no interpolation is possible, e\&.g\&. configuration files of software that does not yet support credentials natively\&.
4194 \fI$CREDENTIALS_DIRECTORY\fR
4195 is considered the primary interface to look for credentials, though, since it also works for user services\&.
4196 .sp
4197 Currently, an accumulated credential size limit of 1 MB per unit is enforced\&.
4198 .sp
4199 The service manager itself may receive system credentials that can be propagated to services from a hosting container manager or VM hypervisor\&. See the
4200 \m[blue]\fBContainer Interface\fR\m[]\&\s-2\u[16]\d\s+2
4201 documentation for details about the former\&. For the latter, pass
4202 \m[blue]\fBDMI/SMBIOS\fR\m[]\&\s-2\u[17]\d\s+2
4203 OEM string table entries (field type 11) with a prefix of
4204 "io\&.systemd\&.credential:"
4205 or
4206 "io\&.systemd\&.credential\&.binary:"\&. In both cases a key/value pair separated by
4207 "="
4208 is expected, in the latter case the right\-hand side is Base64 decoded when parsed (thus permitting binary data to be passed in)\&. Example
4209 \m[blue]\fBqemu\fR\m[]\&\s-2\u[18]\d\s+2
4210 switch:
4211 "\-smbios type=11,value=io\&.systemd\&.credential:xx=yy", or
4212 "\-smbios type=11,value=io\&.systemd\&.credential\&.binary:rick=TmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXA="\&. Alternatively, use the
4213 \fBqemu\fR
4214 "fw_cfg"
4215 node
4216 "opt/io\&.systemd\&.credentials/"\&. Example
4217 \fBqemu\fR
4218 switch:
4219 "\-fw_cfg name=opt/io\&.systemd\&.credentials/mycred,string=supersecret"\&. They may also be passed from the UEFI firmware environment via
4220 \fBsystemd-stub\fR(7), from the initrd (see
4221 \fBsystemd\fR(1)), or be specified on the kernel command line using the
4222 "systemd\&.set_credential="
4223 and
4224 "systemd\&.set_credential_binary="
4225 switches (see
4226 \fBsystemd\fR(1)
4227 \(en this is not recommended since unprivileged userspace can read the kernel command line)\&.
4228 .sp
4229 If referencing an
4230 \fBAF_UNIX\fR
4231 stream socket to connect to, the connection will originate from an abstract namespace socket, that includes information about the unit and the credential ID in its socket name\&. Use
4232 \fBgetpeername\fR(2)
4233 to query this information\&. The returned socket name is formatted as
4234 \fBNUL\fR
4235 \fIRANDOM\fR
4236 "/unit/"
4237 \fIUNIT\fR
4238 "/"
4239 \fIID\fR, i\&.e\&. a
4240 \fBNUL\fR
4241 byte (as required for abstract namespace socket names), followed by a random string (consisting of alphadecimal characters), followed by the literal string
4242 "/unit/", followed by the requesting unit name, followed by the literal character
4243 "/", followed by the textual credential ID requested\&. Example:
4244 "\e0adf9d86b6eda275e/unit/foobar\&.service/credx"
4245 in case the credential
4246 "credx"
4247 is requested for a unit
4248 "foobar\&.service"\&. This functionality is useful for using a single listening socket to serve credentials to multiple consumers\&.
4249 .sp
4250 For further information see
4251 \m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[19]\d\s+2
4252 documentation\&.
4253 .sp
4254 Added in version 247\&.
4255 .RE
4256 .PP
4257 \fIImportCredential=\fR\fIGLOB\fR
4258 .RS 4
4259 Pass one or more credentials to the unit\&. Takes a credential name for which we will attempt to find a credential that the service manager itself received under the specified name \(em which may be used to propagate credentials from an invoking environment (e\&.g\&. a container manager that invoked the service manager) into a service\&. If the credential name is a glob, all credentials matching the glob are passed to the unit\&. Matching credentials are searched for in the system credentials, the encrypted system credentials, and under
4260 /etc/credstore/,
4261 /run/credstore/,
4262 /usr/lib/credstore/,
4263 /run/credstore\&.encrypted/,
4264 /etc/credstore\&.encrypted/, and
4265 /usr/lib/credstore\&.encrypted/
4266 in that order\&. When multiple credentials of the same name are found, the first one found is used\&.
4267 .sp
4268 The globbing expression implements a restrictive subset of
4269 \fBglob\fR(7): only a single trailing
4270 "*"
4271 wildcard may be specified\&. Both
4272 "?"
4273 and
4274 "[]"
4275 wildcards are not permitted, nor are
4276 "*"
4277 wildcards anywhere except at the end of the glob expression\&.
4278 .sp
4279 Optionally, the credential name or glob may be followed by a colon followed by a rename pattern\&. If specified, all credentials matching the credential name or glob are renamed according to the given pattern\&. For example, if
4280 "ImportCredential=my\&.original\&.cred:my\&.renamed\&.cred"
4281 is specified, the service manager will read the
4282 "my\&.original\&.cred"
4283 credential and make it available as the
4284 "my\&.renamed\&.cred"
4285 credential to the service\&. Similarly, if
4286 "ImportCredential=my\&.original\&.*:my\&.renamed\&."
4287 is specified, the service manager will read all credentials starting with
4288 "my\&.original\&."
4289 and make them available as
4290 "my\&.renamed\&.xxx"
4291 to the service\&.
4292 .sp
4293 If
4294 \fIImportCredential=\fR
4295 is specified multiple times and multiple credentials end up with the same name after renaming, the first one is kept and later ones are dropped\&.
4296 .sp
4297 When multiple credentials of the same name are found, credentials found by
4298 \fILoadCredential=\fR
4299 and
4300 \fILoadCredentialEncrypted=\fR
4301 take priority over credentials found by
4302 \fIImportCredential=\fR\&.
4303 .sp
4304 Added in version 254\&.
4305 .RE
4306 .PP
4307 \fISetCredential=\fR\fIID\fR:\fIVALUE\fR, \fISetCredentialEncrypted=\fR\fIID\fR:\fIVALUE\fR
4308 .RS 4
4309 The
4310 \fISetCredential=\fR
4311 setting is similar to
4312 \fILoadCredential=\fR
4313 but accepts a literal value to use as data for the credential, instead of a file system path to read the data from\&. Do not use this option for data that is supposed to be secret, as it is accessible to unprivileged processes via IPC\&. It\*(Aqs only safe to use this for user IDs, public key material and similar non\-sensitive data\&. For everything else use
4314 \fILoadCredential=\fR\&. In order to embed binary data into the credential data use C\-style escaping (i\&.e\&.
4315 "\en"
4316 to embed a newline, or
4317 "\ex00"
4318 to embed a
4319 \fBNUL\fR
4320 byte)\&.
4321 .sp
4322 The
4323 \fISetCredentialEncrypted=\fR
4324 setting is identical to
4325 \fISetCredential=\fR
4326 but expects an encrypted credential in literal form as value\&. This allows embedding confidential credentials securely directly in unit files\&. Use
4327 \fBsystemd-creds\fR(1)\*(Aq
4328 \fB\-p\fR
4329 switch to generate suitable
4330 \fISetCredentialEncrypted=\fR
4331 lines directly from plaintext credentials\&. For further details see
4332 \fILoadCredentialEncrypted=\fR
4333 above\&.
4334 .sp
4335 When multiple credentials of the same name are found, credentials found by
4336 \fILoadCredential=\fR,
4337 \fILoadCredentialEncrypted=\fR
4338 and
4339 \fIImportCredential=\fR
4340 take priority over credentials found by
4341 \fISetCredential=\fR\&. As such,
4342 \fISetCredential=\fR
4343 will act as default if no credentials are found by any of the former\&. In this case not being able to retrieve the credential from the path specified in
4344 \fILoadCredential=\fR
4345 or
4346 \fILoadCredentialEncrypted=\fR
4347 is not considered fatal\&.
4348 .sp
4349 Added in version 247\&.
4350 .RE
4351 .SH "SYSTEM V COMPATIBILITY"
4352 .PP
4353 \fIUtmpIdentifier=\fR
4354 .RS 4
4355 Takes a four character identifier string for an
4356 \fButmp\fR(5)
4357 and wtmp entry for this service\&. This should only be set for services such as
4358 \fBgetty\fR
4359 implementations (such as
4360 \fBagetty\fR(8)) where utmp/wtmp entries must be created and cleared before and after execution, or for services that shall be executed as if they were run by a
4361 \fBgetty\fR
4362 process (see below)\&. If the configured string is longer than four characters, it is truncated and the terminal four characters are used\&. This setting interprets %I style string replacements\&. This setting is unset by default, i\&.e\&. no utmp/wtmp entries are created or cleaned up for this service\&.
4363 .RE
4364 .PP
4365 \fIUtmpMode=\fR
4366 .RS 4
4367 Takes one of
4368 "init",
4369 "login"
4370 or
4371 "user"\&. If
4372 \fIUtmpIdentifier=\fR
4373 is set, controls which type of
4374 \fButmp\fR(5)/wtmp entries for this service are generated\&. This setting has no effect unless
4375 \fIUtmpIdentifier=\fR
4376 is set too\&. If
4377 "init"
4378 is set, only an
4379 \fBINIT_PROCESS\fR
4380 entry is generated and the invoked process must implement a
4381 \fBgetty\fR\-compatible utmp/wtmp logic\&. If
4382 "login"
4383 is set, first an
4384 \fBINIT_PROCESS\fR
4385 entry, followed by a
4386 \fBLOGIN_PROCESS\fR
4387 entry is generated\&. In this case, the invoked process must implement a
4388 \fBlogin\fR(1)\-compatible utmp/wtmp logic\&. If
4389 "user"
4390 is set, first an
4391 \fBINIT_PROCESS\fR
4392 entry, then a
4393 \fBLOGIN_PROCESS\fR
4394 entry and finally a
4395 \fBUSER_PROCESS\fR
4396 entry is generated\&. In this case, the invoked process may be any process that is suitable to be run as session leader\&. Defaults to
4397 "init"\&.
4398 .sp
4399 Added in version 225\&.
4400 .RE
4401 .SH "ENVIRONMENT VARIABLES IN SPAWNED PROCESSES"
4402 .PP
4403 Processes started by the service manager are executed with an environment variable block assembled from multiple sources\&. Processes started by the system service manager generally do not inherit environment variables set for the service manager itself (but this may be altered via
4404 \fIPassEnvironment=\fR), but processes started by the user service manager instances generally do inherit all environment variables set for the service manager itself\&.
4405 .PP
4406 For each invoked process the list of environment variables set is compiled from the following sources:
4407 .sp
4408 .RS 4
4409 .ie n \{\
4410 \h'-04'\(bu\h'+03'\c
4411 .\}
4412 .el \{\
4413 .sp -1
4414 .IP \(bu 2.3
4415 .\}
4416 Variables globally configured for the service manager, using the
4417 \fIDefaultEnvironment=\fR
4418 setting in
4419 \fBsystemd-system.conf\fR(5), the kernel command line option
4420 \fIsystemd\&.setenv=\fR
4421 understood by
4422 \fBsystemd\fR(1), or via
4423 \fBsystemctl\fR(1)
4424 \fBset\-environment\fR
4425 verb\&.
4426 .RE
4427 .sp
4428 .RS 4
4429 .ie n \{\
4430 \h'-04'\(bu\h'+03'\c
4431 .\}
4432 .el \{\
4433 .sp -1
4434 .IP \(bu 2.3
4435 .\}
4436 Variables defined by the service manager itself (see the list below)\&.
4437 .RE
4438 .sp
4439 .RS 4
4440 .ie n \{\
4441 \h'-04'\(bu\h'+03'\c
4442 .\}
4443 .el \{\
4444 .sp -1
4445 .IP \(bu 2.3
4446 .\}
4447 Variables set in the service manager\*(Aqs own environment variable block (subject to
4448 \fIPassEnvironment=\fR
4449 for the system service manager)\&.
4450 .RE
4451 .sp
4452 .RS 4
4453 .ie n \{\
4454 \h'-04'\(bu\h'+03'\c
4455 .\}
4456 .el \{\
4457 .sp -1
4458 .IP \(bu 2.3
4459 .\}
4460 Variables set via
4461 \fIEnvironment=\fR
4462 in the unit file\&.
4463 .RE
4464 .sp
4465 .RS 4
4466 .ie n \{\
4467 \h'-04'\(bu\h'+03'\c
4468 .\}
4469 .el \{\
4470 .sp -1
4471 .IP \(bu 2.3
4472 .\}
4473 Variables read from files specified via
4474 \fIEnvironmentFile=\fR
4475 in the unit file\&.
4476 .RE
4477 .sp
4478 .RS 4
4479 .ie n \{\
4480 \h'-04'\(bu\h'+03'\c
4481 .\}
4482 .el \{\
4483 .sp -1
4484 .IP \(bu 2.3
4485 .\}
4486 Variables set by any PAM modules in case
4487 \fIPAMName=\fR
4488 is in effect, cf\&.\ \&\fBpam_env\fR(8)\&.
4489 .RE
4490 .PP
4491 If the same environment variable is set by multiple of these sources, the later source \(em according to the order of the list above \(em wins\&. Note that as the final step all variables listed in
4492 \fIUnsetEnvironment=\fR
4493 are removed from the compiled environment variable list, immediately before it is passed to the executed process\&.
4494 .PP
4495 The general philosophy is to expose a small curated list of environment variables to processes\&. Services started by the system manager (PID 1) will be started, without additional service\-specific configuration, with just a few environment variables\&. The user manager inherits environment variables as any other system service, but in addition may receive additional environment variables from PAM, and, typically, additional imported variables when the user starts a graphical session\&. It is recommended to keep the environment blocks in both the system and user managers lean\&. Importing all variables inherited by the graphical session or by one of the user shells is strongly discouraged\&.
4496 .PP
4497 Hint:
4498 \fBsystemd\-run \-P env\fR
4499 and
4500 \fBsystemd\-run \-\-user \-P env\fR
4501 print the effective system and user service environment blocks\&.
4502 .SS "Environment Variables Set or Propagated by the Service Manager"
4503 .PP
4504 The following environment variables are propagated by the service manager or generated internally for each invoked process:
4505 .PP
4506 \fI$PATH\fR
4507 .RS 4
4508 Colon\-separated list of directories to use when launching executables\&.
4509 \fBsystemd\fR
4510 uses a fixed value of
4511 "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
4512 in the system manager\&. In case of the user manager, a different path may be configured by the distribution\&. It is recommended to not rely on the order of entries, and have only one program with a given name in
4513 \fI$PATH\fR\&.
4514 .sp
4515 Added in version 208\&.
4516 .RE
4517 .PP
4518 \fI$LANG\fR
4519 .RS 4
4520 Locale\&. Can be set in
4521 \fBlocale.conf\fR(5)
4522 or on the kernel command line (see
4523 \fBsystemd\fR(1)
4524 and
4525 \fBkernel-command-line\fR(7))\&.
4526 .sp
4527 Added in version 208\&.
4528 .RE
4529 .PP
4530 \fI$USER\fR, \fI$LOGNAME\fR, \fI$HOME\fR, \fI$SHELL\fR
4531 .RS 4
4532 User name (twice), home directory, and the login shell\&.
4533 \fI$USER\fR
4534 is set unconditionally, while
4535 \fI$HOME\fR,
4536 \fI$LOGNAME\fR, and
4537 \fI$SHELL\fR
4538 are only set for the units that have
4539 \fIUser=\fR
4540 set and
4541 \fISetLoginEnvironment=\fR
4542 unset or set to true\&. For user services, these variables are typically inherited from the user manager itself\&. See
4543 \fBpasswd\fR(5)\&.
4544 .sp
4545 Added in version 208\&.
4546 .RE
4547 .PP
4548 \fI$INVOCATION_ID\fR
4549 .RS 4
4550 Contains a randomized, unique 128\-bit ID identifying each runtime cycle of the unit, formatted as 32 character hexadecimal string\&. A new ID is assigned each time the unit changes from an inactive state into an activating or active state, and may be used to identify this specific runtime cycle, in particular in data stored offline, such as the journal\&. The same ID is passed to all processes run as part of the unit\&.
4551 .sp
4552 Added in version 232\&.
4553 .RE
4554 .PP
4555 \fI$XDG_RUNTIME_DIR\fR
4556 .RS 4
4557 The directory to use for runtime objects (such as IPC objects) and volatile state\&. Set for all services run by the user
4558 \fBsystemd\fR
4559 instance, as well as any system services that use
4560 \fIPAMName=\fR
4561 with a PAM stack that includes
4562 \fBpam_systemd\fR\&. See below and
4563 \fBpam_systemd\fR(8)
4564 for more information\&.
4565 .sp
4566 Added in version 208\&.
4567 .RE
4568 .PP
4569 \fI$RUNTIME_DIRECTORY\fR, \fI$STATE_DIRECTORY\fR, \fI$CACHE_DIRECTORY\fR, \fI$LOGS_DIRECTORY\fR, \fI$CONFIGURATION_DIRECTORY\fR
4570 .RS 4
4571 Absolute paths to the directories defined with
4572 \fIRuntimeDirectory=\fR,
4573 \fIStateDirectory=\fR,
4574 \fICacheDirectory=\fR,
4575 \fILogsDirectory=\fR, and
4576 \fIConfigurationDirectory=\fR
4577 when those settings are used\&.
4578 .sp
4579 Added in version 244\&.
4580 .RE
4581 .PP
4582 \fI$CREDENTIALS_DIRECTORY\fR
4583 .RS 4
4584 An absolute path to the per\-unit directory with credentials configured via
4585 \fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR\&. The directory is marked read\-only and is placed in unswappable memory (if supported and permitted), and is only accessible to the UID associated with the unit via
4586 \fIUser=\fR
4587 or
4588 \fIDynamicUser=\fR
4589 (and the superuser)\&.
4590 .sp
4591 Added in version 247\&.
4592 .RE
4593 .PP
4594 \fI$MAINPID\fR
4595 .RS 4
4596 The PID of the unit\*(Aqs main process if it is known\&. This is only set for control processes as invoked by
4597 \fIExecReload=\fR
4598 and similar\&.
4599 .sp
4600 Added in version 209\&.
4601 .RE
4602 .PP
4603 \fI$MANAGERPID\fR
4604 .RS 4
4605 The PID of the user
4606 \fBsystemd\fR
4607 instance, set for processes spawned by it\&.
4608 .sp
4609 Added in version 208\&.
4610 .RE
4611 .PP
4612 \fI$LISTEN_FDS\fR, \fI$LISTEN_PID\fR, \fI$LISTEN_FDNAMES\fR
4613 .RS 4
4614 Information about file descriptors passed to a service for socket activation\&. See
4615 \fBsd_listen_fds\fR(3)\&.
4616 .sp
4617 Added in version 208\&.
4618 .RE
4619 .PP
4620 \fI$NOTIFY_SOCKET\fR
4621 .RS 4
4622 The socket
4623 \fBsd_notify()\fR
4624 talks to\&. See
4625 \fBsd_notify\fR(3)\&.
4626 .sp
4627 Added in version 229\&.
4628 .RE
4629 .PP
4630 \fI$WATCHDOG_PID\fR, \fI$WATCHDOG_USEC\fR
4631 .RS 4
4632 Information about watchdog keep\-alive notifications\&. See
4633 \fBsd_watchdog_enabled\fR(3)\&.
4634 .sp
4635 Added in version 229\&.
4636 .RE
4637 .PP
4638 \fI$SYSTEMD_EXEC_PID\fR
4639 .RS 4
4640 The PID of the unit process (e\&.g\&. process invoked by
4641 \fIExecStart=\fR)\&. The child process can use this information to determine whether the process is directly invoked by the service manager or indirectly as a child of another process by comparing this value with the current PID (similarly to the scheme used in
4642 \fBsd_listen_fds\fR(3)
4643 with
4644 \fI$LISTEN_PID\fR
4645 and
4646 \fI$LISTEN_FDS\fR)\&.
4647 .sp
4648 Added in version 248\&.
4649 .RE
4650 .PP
4651 \fI$TERM\fR
4652 .RS 4
4653 Terminal type, set only for units connected to a terminal (\fIStandardInput=tty\fR,
4654 \fIStandardOutput=tty\fR, or
4655 \fIStandardError=tty\fR)\&. See
4656 \fBtermcap\fR(5)\&.
4657 .sp
4658 Added in version 209\&.
4659 .RE
4660 .PP
4661 \fI$LOG_NAMESPACE\fR
4662 .RS 4
4663 Contains the name of the selected logging namespace when the
4664 \fILogNamespace=\fR
4665 service setting is used\&.
4666 .sp
4667 Added in version 246\&.
4668 .RE
4669 .PP
4670 \fI$JOURNAL_STREAM\fR
4671 .RS 4
4672 If the standard output or standard error output of the executed processes are connected to the journal (for example, by setting
4673 \fIStandardError=journal\fR)
4674 \fI$JOURNAL_STREAM\fR
4675 contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a colon (":")\&. This permits invoked processes to safely detect whether their standard output or standard error output are connected to the journal\&. The device and inode numbers of the file descriptors should be compared with the values set in the environment variable to determine whether the process output is still connected to the journal\&. Note that it is generally not sufficient to only check whether
4676 \fI$JOURNAL_STREAM\fR
4677 is set at all as services might invoke external processes replacing their standard output or standard error output, without unsetting the environment variable\&.
4678 .sp
4679 If both standard output and standard error of the executed processes are connected to the journal via a stream socket, this environment variable will contain information about the standard error stream, as that\*(Aqs usually the preferred destination for log data\&. (Note that typically the same stream is used for both standard output and standard error, hence very likely the environment variable contains device and inode information matching both stream file descriptors\&.)
4680 .sp
4681 This environment variable is primarily useful to allow services to optionally upgrade their used log protocol to the native journal protocol (using
4682 \fBsd_journal_print\fR(3)
4683 and other functions) if their standard output or standard error output is connected to the journal anyway, thus enabling delivery of structured metadata along with logged messages\&.
4684 .sp
4685 Added in version 231\&.
4686 .RE
4687 .PP
4688 \fI$SERVICE_RESULT\fR
4689 .RS 4
4690 Only used for the service unit type\&. This environment variable is passed to all
4691 \fIExecStop=\fR
4692 and
4693 \fIExecStopPost=\fR
4694 processes, and encodes the service "result"\&. Currently, the following values are defined:
4695 .sp
4696 .it 1 an-trap
4697 .nr an-no-space-flag 1
4698 .nr an-break-flag 1
4699 .br
4700 .B Table\ \&5.\ \&Defined \fI$SERVICE_RESULT\fR values
4701 .TS
4702 allbox tab(:);
4703 lB lB.
4704 T{
4705 Value
4706 T}:T{
4707 Meaning
4708 T}
4709 .T&
4710 l l
4711 l l
4712 l l
4713 l l
4714 l l
4715 l l
4716 l l
4717 l l
4718 l l
4719 l l
4720 l l.
4721 T{
4722 "success"
4723 T}:T{
4724 The service ran successfully and exited cleanly\&.
4725 T}
4726 T{
4727 "protocol"
4728 T}:T{
4729 A protocol violation occurred: the service did not take the steps required by its unit configuration (specifically what is configured in its \fIType=\fR setting)\&.
4730 T}
4731 T{
4732 "timeout"
4733 T}:T{
4734 One of the steps timed out\&.
4735 T}
4736 T{
4737 "exit\-code"
4738 T}:T{
4739 Service process exited with a non\-zero exit code; see \fI$EXIT_CODE\fR below for the actual exit code returned\&.
4740 T}
4741 T{
4742 "signal"
4743 T}:T{
4744 A service process was terminated abnormally by a signal, without dumping core\&. See \fI$EXIT_CODE\fR below for the actual signal causing the termination\&.
4745 T}
4746 T{
4747 "core\-dump"
4748 T}:T{
4749 A service process terminated abnormally with a signal and dumped core\&. See \fI$EXIT_CODE\fR below for the signal causing the termination\&.
4750 T}
4751 T{
4752 "watchdog"
4753 T}:T{
4754 Watchdog keep\-alive ping was enabled for the service, but the deadline was missed\&.
4755 T}
4756 T{
4757 "exec\-condition"
4758 T}:T{
4759 Service did not run because \fIExecCondition=\fR failed (that is its command exited with an exit status of 1 through 254 (inclusive))\&.
4760 T}
4761 T{
4762 "oom\-kill"
4763 T}:T{
4764 A service process was terminated by the Out\-Of\-Memory (OOM) killer\&.
4765 T}
4766 T{
4767 "start\-limit\-hit"
4768 T}:T{
4769 A start limit was defined for the unit and it was hit, causing the unit to fail to start\&. See \fBsystemd.unit\fR(5)\*(Aqs \fIStartLimitIntervalSec=\fR and \fIStartLimitBurst=\fR for details\&.
4770 T}
4771 T{
4772 "resources"
4773 T}:T{
4774 A catch\-all condition in case a system operation failed\&.
4775 T}
4776 .TE
4777 .sp 1
4778 This environment variable is useful to monitor failure or successful termination of a service\&. Even though this variable is available in both
4779 \fIExecStop=\fR
4780 and
4781 \fIExecStopPost=\fR, it is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services that managed to start up correctly, and the latter covers both services that failed during their start\-up and those which failed during their runtime\&.
4782 .sp
4783 Added in version 232\&.
4784 .RE
4785 .PP
4786 \fI$EXIT_CODE\fR, \fI$EXIT_STATUS\fR
4787 .RS 4
4788 Only defined for the service unit type\&. These environment variables are passed to all
4789 \fIExecStop=\fR,
4790 \fIExecStopPost=\fR
4791 processes and contain exit status/code information of the main process of the service\&. For the precise definition of the exit code and status, see
4792 \fBwait\fR(2)\&.
4793 \fI$EXIT_CODE\fR
4794 is one of
4795 "exited",
4796 "killed",
4797 "dumped"\&.
4798 \fI$EXIT_STATUS\fR
4799 contains the numeric exit code formatted as string if
4800 \fI$EXIT_CODE\fR
4801 is
4802 "exited", and the signal name in all other cases\&. Note that these environment variables are only set if the service manager succeeded to start and identify the main process of the service\&.
4803 .sp
4804 .it 1 an-trap
4805 .nr an-no-space-flag 1
4806 .nr an-break-flag 1
4807 .br
4808 .B Table\ \&6.\ \&Summary of possible service result variable values
4809 .TS
4810 allbox tab(:);
4811 lB lB lB.
4812 T{
4813 \fI$SERVICE_RESULT\fR
4814 T}:T{
4815 \fI$EXIT_CODE\fR
4816 T}:T{
4817 \fI$EXIT_STATUS\fR
4818 T}
4819 .T&
4820 lt lt l
4821 ^ lt l
4822 lt lt l
4823 ^ l l
4824 lt lt l
4825 ^ lt l
4826 lt lt l
4827 lt lt l
4828 lt lt l
4829 lt l l
4830 ^ l l
4831 ^ l l
4832 lt l l
4833 lt lt l
4834 l l l
4835 l l l
4836 l s s.
4837 T{
4838 "success"
4839 T}:T{
4840 "killed"
4841 T}:T{
4842 "HUP", "INT", "TERM", "PIPE"
4843 T}
4844 :T{
4845 "exited"
4846 T}:T{
4847 "0"
4848 T}
4849 T{
4850 "protocol"
4851 T}:T{
4852 not set
4853 T}:T{
4854 not set
4855 T}
4856 :T{
4857 "exited"
4858 T}:T{
4859 "0"
4860 T}
4861 T{
4862 "timeout"
4863 T}:T{
4864 "killed"
4865 T}:T{
4866 "TERM", "KILL"
4867 T}
4868 :T{
4869 "exited"
4870 T}:T{
4871 "0", "1", "2", "3", \&..., "255"
4872 T}
4873 T{
4874 "exit\-code"
4875 T}:T{
4876 "exited"
4877 T}:T{
4878 "1", "2", "3", \&..., "255"
4879 T}
4880 T{
4881 "signal"
4882 T}:T{
4883 "killed"
4884 T}:T{
4885 "HUP", "INT", "KILL", \&...
4886 T}
4887 T{
4888 "core\-dump"
4889 T}:T{
4890 "dumped"
4891 T}:T{
4892 "ABRT", "SEGV", "QUIT", \&...
4893 T}
4894 T{
4895 "watchdog"
4896 T}:T{
4897 "dumped"
4898 T}:T{
4899 "ABRT"
4900 T}
4901 :T{
4902 "killed"
4903 T}:T{
4904 "TERM", "KILL"
4905 T}
4906 :T{
4907 "exited"
4908 T}:T{
4909 "0", "1", "2", "3", \&..., "255"
4910 T}
4911 T{
4912 "exec\-condition"
4913 T}:T{
4914 "exited"
4915 T}:T{
4916 "1", "2", "3", "4", \&..., "254"
4917 T}
4918 T{
4919 "oom\-kill"
4920 T}:T{
4921 "killed"
4922 T}:T{
4923 "TERM", "KILL"
4924 T}
4925 T{
4926 "start\-limit\-hit"
4927 T}:T{
4928 not set
4929 T}:T{
4930 not set
4931 T}
4932 T{
4933 "resources"
4934 T}:T{
4935 any of the above
4936 T}:T{
4937 any of the above
4938 T}
4939 T{
4940 Note: the process may be also terminated by a signal not sent by systemd\&. In particular the process may send an arbitrary signal to itself in a handler for any of the non\-maskable signals\&. Nevertheless, in the "timeout" and "watchdog" rows above only the signals that systemd sends have been included\&. Moreover, using \fISuccessExitStatus=\fR additional exit statuses may be declared to indicate clean termination, which is not reflected by this table\&.
4941 T}
4942 .TE
4943 .sp 1
4944 Added in version 232\&.
4945 .RE
4946 .PP
4947 \fI$MONITOR_SERVICE_RESULT\fR, \fI$MONITOR_EXIT_CODE\fR, \fI$MONITOR_EXIT_STATUS\fR, \fI$MONITOR_INVOCATION_ID\fR, \fI$MONITOR_UNIT\fR
4948 .RS 4
4949 Only defined for the service unit type\&. Those environment variables are passed to all
4950 \fIExecStart=\fR
4951 and
4952 \fIExecStartPre=\fR
4953 processes which run in services triggered by
4954 \fIOnFailure=\fR
4955 or
4956 \fIOnSuccess=\fR
4957 dependencies\&.
4958 .sp
4959 Variables
4960 \fI$MONITOR_SERVICE_RESULT\fR,
4961 \fI$MONITOR_EXIT_CODE\fR
4962 and
4963 \fI$MONITOR_EXIT_STATUS\fR
4964 take the same values as for
4965 \fIExecStop=\fR
4966 and
4967 \fIExecStopPost=\fR
4968 processes\&. Variables
4969 \fI$MONITOR_INVOCATION_ID\fR
4970 and
4971 \fI$MONITOR_UNIT\fR
4972 are set to the invocation id and unit name of the service which triggered the dependency\&.
4973 .sp
4974 Note that when multiple services specify the same unit as their
4975 \fIOnFailure=\fR
4976 or
4977 \fIOnSuccess=\fR
4978 handler, those variables will
4979 \fInot\fR
4980 be passed\&. Consider using a template handler unit for that case instead:
4981 "OnFailure=\fIhandler\fR@%n\&.service"
4982 for non\-templated units, or
4983 "OnFailure=\fIhandler\fR@%p\-%i\&.service"
4984 for templated units\&.
4985 .sp
4986 Added in version 251\&.
4987 .RE
4988 .PP
4989 \fI$PIDFILE\fR
4990 .RS 4
4991 The path to the configured PID file, in case the process is forked off on behalf of a service that uses the
4992 \fIPIDFile=\fR
4993 setting, see
4994 \fBsystemd.service\fR(5)
4995 for details\&. Service code may use this environment variable to automatically generate a PID file at the location configured in the unit file\&. This field is set to an absolute path in the file system\&.
4996 .sp
4997 Added in version 242\&.
4998 .RE
4999 .PP
5000 \fI$REMOTE_ADDR\fR, \fI$REMOTE_PORT\fR
5001 .RS 4
5002 If this is a unit started via per\-connection socket activation (i\&.e\&. via a socket unit with
5003 \fIAccept=yes\fR), these environment variables contain information about the remote peer of the socket connection\&.
5004 .sp
5005 For IPv4 and IPv6 connections,
5006 \fI$REMOTE_ADDR\fR
5007 contains the IP address, and
5008 \fI$REMOTE_PORT\fR
5009 contains the port number of the remote peer\&.
5010 .sp
5011 For
5012 \fBAF_UNIX\fR
5013 socket connections,
5014 \fI$REMOTE_ADDR\fR
5015 contains either the remote socket\*(Aqs file system path starting with a slash ("/"), its address in the abstract namespace starting with an at symbol ("@"), or is unset in case of an unnamed socket\&.
5016 \fI$REMOTE_PORT\fR
5017 is not set for
5018 \fBAF_UNIX\fR
5019 sockets\&.
5020 .sp
5021 Added in version 220\&.
5022 .RE
5023 .PP
5024 \fI$TRIGGER_UNIT\fR, \fI$TRIGGER_PATH\fR, \fI$TRIGGER_TIMER_REALTIME_USEC\fR, \fI$TRIGGER_TIMER_MONOTONIC_USEC\fR
5025 .RS 4
5026 If the unit was activated dynamically (e\&.g\&.: a corresponding path unit or timer unit), the unit that triggered it and other type\-dependent information will be passed via these variables\&. Note that this information is provided in a best\-effort way\&. For example, multiple triggers happening one after another will be coalesced and only one will be reported, with no guarantee as to which one it will be\&. Because of this, in most cases this variable will be primarily informational, i\&.e\&. useful for debugging purposes, is lossy, and should not be relied upon to propagate a comprehensive reason for activation\&.
5027 .sp
5028 Added in version 252\&.
5029 .RE
5030 .PP
5031 \fI$MEMORY_PRESSURE_WATCH\fR, \fI$MEMORY_PRESSURE_WRITE\fR
5032 .RS 4
5033 If memory pressure monitoring is enabled for this service unit, the path to watch and the data to write into it\&. See
5034 \m[blue]\fBMemory Pressure Handling\fR\m[]\&\s-2\u[20]\d\s+2
5035 for details about these variables and the service protocol data they convey\&.
5036 .sp
5037 Added in version 254\&.
5038 .RE
5039 .PP
5040 \fI$FDSTORE\fR
5041 .RS 4
5042 The maximum number of file descriptors that may be stored in the manager for the service\&. This variable is set when the file descriptor store is enabled for the service, i\&.e\&.
5043 \fIFileDescriptorStoreMax=\fR
5044 is set to a non\-zero value (see
5045 \fBsystemd.service\fR(5)
5046 for details)\&. Applications may check this environment variable before sending file descriptors to the service manager via
5047 \fBsd_pid_notify_with_fds\fR(3)\&.
5048 .sp
5049 Added in version 254\&.
5050 .RE
5051 .PP
5052 \fI$DEBUG_INVOCATION\fR
5053 .RS 4
5054 If
5055 \fIRestartMode=debug\fR
5056 is set, and a previous attempt at starting the unit failed, this variable will be passed to the service to indicate that additional logging should be enabled at startup\&. See
5057 \fBsystemd.service\fR(5)
5058 for more details\&.
5059 .sp
5060 Added in version 257\&.
5061 .RE
5062 .PP
5063 For system services, when
5064 \fIPAMName=\fR
5065 is enabled and
5066 \fBpam_systemd\fR
5067 is part of the selected PAM stack, additional environment variables defined by systemd may be set for services\&. Specifically, these are
5068 \fI$XDG_SEAT\fR,
5069 \fI$XDG_VTNR\fR, see
5070 \fBpam_systemd\fR(8)
5071 for details\&.
5072 .SH "PROCESS EXIT CODES"
5073 .PP
5074 When invoking a unit process the service manager possibly fails to apply the execution parameters configured with the settings above\&. In that case the already created service process will exit with a non\-zero exit code before the configured command line is executed\&. (Or in other words, the child process possibly exits with these error codes, after having been created by the
5075 \fBfork\fR(2)
5076 system call, but before the matching
5077 \fBexecve\fR(2)
5078 system call is called\&.) Specifically, exit codes defined by the C library, by the LSB specification and by the systemd service manager itself are used\&.
5079 .PP
5080 The following basic service exit codes are defined by the C library\&.
5081 .sp
5082 .it 1 an-trap
5083 .nr an-no-space-flag 1
5084 .nr an-break-flag 1
5085 .br
5086 .B Table\ \&7.\ \&Basic C library exit codes
5087 .TS
5088 allbox tab(:);
5089 lB lB lB.
5090 T{
5091 Exit Code
5092 T}:T{
5093 Symbolic Name
5094 T}:T{
5095 Description
5096 T}
5097 .T&
5098 l l l
5099 l l l.
5100 T{
5101 0
5102 T}:T{
5103 \fBEXIT_SUCCESS\fR
5104 T}:T{
5105 Generic success code\&.
5106 T}
5107 T{
5108 1
5109 T}:T{
5110 \fBEXIT_FAILURE\fR
5111 T}:T{
5112 Generic failure or unspecified error\&.
5113 T}
5114 .TE
5115 .sp 1
5116 .PP
5117 The following service exit codes are defined by the
5118 \m[blue]\fBLSB specification\fR\m[]\&\s-2\u[21]\d\s+2\&.
5119 .sp
5120 .it 1 an-trap
5121 .nr an-no-space-flag 1
5122 .nr an-break-flag 1
5123 .br
5124 .B Table\ \&8.\ \&LSB service exit codes
5125 .TS
5126 allbox tab(:);
5127 lB lB lB.
5128 T{
5129 Exit Code
5130 T}:T{
5131 Symbolic Name
5132 T}:T{
5133 Description
5134 T}
5135 .T&
5136 l l l
5137 l l l
5138 l l l
5139 l l l
5140 l l l
5141 l l l.
5142 T{
5143 2
5144 T}:T{
5145 \fBEXIT_INVALIDARGUMENT\fR
5146 T}:T{
5147 Invalid or excess arguments\&.
5148 T}
5149 T{
5150 3
5151 T}:T{
5152 \fBEXIT_NOTIMPLEMENTED\fR
5153 T}:T{
5154 Unimplemented feature\&.
5155 T}
5156 T{
5157 4
5158 T}:T{
5159 \fBEXIT_NOPERMISSION\fR
5160 T}:T{
5161 The user has insufficient privileges\&.
5162 T}
5163 T{
5164 5
5165 T}:T{
5166 \fBEXIT_NOTINSTALLED\fR
5167 T}:T{
5168 The program is not installed\&.
5169 T}
5170 T{
5171 6
5172 T}:T{
5173 \fBEXIT_NOTCONFIGURED\fR
5174 T}:T{
5175 The program is not configured\&.
5176 T}
5177 T{
5178 7
5179 T}:T{
5180 \fBEXIT_NOTRUNNING\fR
5181 T}:T{
5182 The program is not running\&.
5183 T}
5184 .TE
5185 .sp 1
5186 .PP
5187 The LSB specification suggests that error codes 200 and above are reserved for implementations\&. Some of them are used by the service manager to indicate problems during process invocation:
5188 .sp
5189 .it 1 an-trap
5190 .nr an-no-space-flag 1
5191 .nr an-break-flag 1
5192 .br
5193 .B Table\ \&9.\ \&systemd\-specific exit codes
5194 .TS
5195 allbox tab(:);
5196 lB lB lB.
5197 T{
5198 Exit Code
5199 T}:T{
5200 Symbolic Name
5201 T}:T{
5202 Description
5203 T}
5204 .T&
5205 l l l
5206 l l l
5207 l l l
5208 l l l
5209 l l l
5210 l l l
5211 l l l
5212 l l l
5213 l l l
5214 l l l
5215 l l l
5216 l l l
5217 l l l
5218 l l l
5219 l l l
5220 l l l
5221 l l l
5222 l l l
5223 l l l
5224 l l l
5225 l l l
5226 l l l
5227 l l l
5228 l l l
5229 l l l
5230 l l l
5231 l l l
5232 l l l
5233 l l l
5234 l l l
5235 l l l
5236 l l l
5237 l l l
5238 l l l
5239 l l l
5240 l l l
5241 l l l
5242 l l l
5243 l l l
5244 l l l
5245 l l l
5246 l l l
5247 l l l.
5248 T{
5249 200
5250 T}:T{
5251 \fBEXIT_CHDIR\fR
5252 T}:T{
5253 Changing to the requested working directory failed\&. See \fIWorkingDirectory=\fR above\&.
5254 T}
5255 T{
5256 201
5257 T}:T{
5258 \fBEXIT_NICE\fR
5259 T}:T{
5260 Failed to set up process scheduling priority (nice level)\&. See \fINice=\fR above\&.
5261 T}
5262 T{
5263 202
5264 T}:T{
5265 \fBEXIT_FDS\fR
5266 T}:T{
5267 Failed to close unwanted file descriptors, or to adjust passed file descriptors\&.
5268 T}
5269 T{
5270 203
5271 T}:T{
5272 \fBEXIT_EXEC\fR
5273 T}:T{
5274 The actual process execution failed (specifically, the \fBexecve\fR(2) system call)\&. Most likely this is caused by a missing or non\-accessible executable file\&.
5275 T}
5276 T{
5277 204
5278 T}:T{
5279 \fBEXIT_MEMORY\fR
5280 T}:T{
5281 Failed to perform an action due to memory shortage\&.
5282 T}
5283 T{
5284 205
5285 T}:T{
5286 \fBEXIT_LIMITS\fR
5287 T}:T{
5288 Failed to adjust resource limits\&. See \fILimitCPU=\fR and related settings above\&.
5289 T}
5290 T{
5291 206
5292 T}:T{
5293 \fBEXIT_OOM_ADJUST\fR
5294 T}:T{
5295 Failed to adjust the OOM setting\&. See \fIOOMScoreAdjust=\fR above\&.
5296 T}
5297 T{
5298 207
5299 T}:T{
5300 \fBEXIT_SIGNAL_MASK\fR
5301 T}:T{
5302 Failed to set process signal mask\&.
5303 T}
5304 T{
5305 208
5306 T}:T{
5307 \fBEXIT_STDIN\fR
5308 T}:T{
5309 Failed to set up standard input\&. See \fIStandardInput=\fR above\&.
5310 T}
5311 T{
5312 209
5313 T}:T{
5314 \fBEXIT_STDOUT\fR
5315 T}:T{
5316 Failed to set up standard output\&. See \fIStandardOutput=\fR above\&.
5317 T}
5318 T{
5319 210
5320 T}:T{
5321 \fBEXIT_CHROOT\fR
5322 T}:T{
5323 Failed to change root directory (\fBchroot\fR(2))\&. See \fIRootDirectory=\fR/\fIRootImage=\fR above\&.
5324 T}
5325 T{
5326 211
5327 T}:T{
5328 \fBEXIT_IOPRIO\fR
5329 T}:T{
5330 Failed to set up IO scheduling priority\&. See \fIIOSchedulingClass=\fR/\fIIOSchedulingPriority=\fR above\&.
5331 T}
5332 T{
5333 212
5334 T}:T{
5335 \fBEXIT_TIMERSLACK\fR
5336 T}:T{
5337 Failed to set up timer slack\&. See \fITimerSlackNSec=\fR above\&.
5338 T}
5339 T{
5340 213
5341 T}:T{
5342 \fBEXIT_SECUREBITS\fR
5343 T}:T{
5344 Failed to set process secure bits\&. See \fISecureBits=\fR above\&.
5345 T}
5346 T{
5347 214
5348 T}:T{
5349 \fBEXIT_SETSCHEDULER\fR
5350 T}:T{
5351 Failed to set up CPU scheduling\&. See \fICPUSchedulingPolicy=\fR/\fICPUSchedulingPriority=\fR above\&.
5352 T}
5353 T{
5354 215
5355 T}:T{
5356 \fBEXIT_CPUAFFINITY\fR
5357 T}:T{
5358 Failed to set up CPU affinity\&. See \fICPUAffinity=\fR above\&.
5359 T}
5360 T{
5361 216
5362 T}:T{
5363 \fBEXIT_GROUP\fR
5364 T}:T{
5365 Failed to determine or change group credentials\&. See \fIGroup=\fR/\fISupplementaryGroups=\fR above\&.
5366 T}
5367 T{
5368 217
5369 T}:T{
5370 \fBEXIT_USER\fR
5371 T}:T{
5372 Failed to determine or change user credentials, or to set up user namespacing\&. See \fIUser=\fR/\fIPrivateUsers=\fR above\&.
5373 T}
5374 T{
5375 218
5376 T}:T{
5377 \fBEXIT_CAPABILITIES\fR
5378 T}:T{
5379 Failed to drop capabilities, or apply ambient capabilities\&. See \fICapabilityBoundingSet=\fR/\fIAmbientCapabilities=\fR above\&.
5380 T}
5381 T{
5382 219
5383 T}:T{
5384 \fBEXIT_CGROUP\fR
5385 T}:T{
5386 Setting up the service control group failed\&.
5387 T}
5388 T{
5389 220
5390 T}:T{
5391 \fBEXIT_SETSID\fR
5392 T}:T{
5393 Failed to create new process session\&.
5394 T}
5395 T{
5396 221
5397 T}:T{
5398 \fBEXIT_CONFIRM\fR
5399 T}:T{
5400 Execution has been cancelled by the user\&. See the \fIsystemd\&.confirm_spawn=\fR kernel command line setting on \fBkernel-command-line\fR(7) for details\&.
5401 T}
5402 T{
5403 222
5404 T}:T{
5405 \fBEXIT_STDERR\fR
5406 T}:T{
5407 Failed to set up standard error output\&. See \fIStandardError=\fR above\&.
5408 T}
5409 T{
5410 224
5411 T}:T{
5412 \fBEXIT_PAM\fR
5413 T}:T{
5414 Failed to set up PAM session\&. See \fIPAMName=\fR above\&.
5415 T}
5416 T{
5417 225
5418 T}:T{
5419 \fBEXIT_NETWORK\fR
5420 T}:T{
5421 Failed to set up network namespacing\&. See \fIPrivateNetwork=\fR above\&.
5422 T}
5423 T{
5424 226
5425 T}:T{
5426 \fBEXIT_NAMESPACE\fR
5427 T}:T{
5428 Failed to set up mount, UTS, or IPC namespacing\&. See \fIReadOnlyPaths=\fR, \fIProtectHostname=\fR, \fIPrivateIPC=\fR, and related settings above\&.
5429 T}
5430 T{
5431 227
5432 T}:T{
5433 \fBEXIT_NO_NEW_PRIVILEGES\fR
5434 T}:T{
5435 Failed to disable new privileges\&. See \fINoNewPrivileges=yes\fR above\&.
5436 T}
5437 T{
5438 228
5439 T}:T{
5440 \fBEXIT_SECCOMP\fR
5441 T}:T{
5442 Failed to apply system call filters\&. See \fISystemCallFilter=\fR and related settings above\&.
5443 T}
5444 T{
5445 229
5446 T}:T{
5447 \fBEXIT_SELINUX_CONTEXT\fR
5448 T}:T{
5449 Determining or changing SELinux context failed\&. See \fISELinuxContext=\fR above\&.
5450 T}
5451 T{
5452 230
5453 T}:T{
5454 \fBEXIT_PERSONALITY\fR
5455 T}:T{
5456 Failed to set up an execution domain (personality)\&. See \fIPersonality=\fR above\&.
5457 T}
5458 T{
5459 231
5460 T}:T{
5461 \fBEXIT_APPARMOR_PROFILE\fR
5462 T}:T{
5463 Failed to prepare changing AppArmor profile\&. See \fIAppArmorProfile=\fR above\&.
5464 T}
5465 T{
5466 232
5467 T}:T{
5468 \fBEXIT_ADDRESS_FAMILIES\fR
5469 T}:T{
5470 Failed to restrict address families\&. See \fIRestrictAddressFamilies=\fR above\&.
5471 T}
5472 T{
5473 233
5474 T}:T{
5475 \fBEXIT_RUNTIME_DIRECTORY\fR
5476 T}:T{
5477 Setting up runtime directory failed\&. See \fIRuntimeDirectory=\fR and related settings above\&.
5478 T}
5479 T{
5480 235
5481 T}:T{
5482 \fBEXIT_CHOWN\fR
5483 T}:T{
5484 Failed to adjust socket ownership\&. Used for socket units only\&.
5485 T}
5486 T{
5487 236
5488 T}:T{
5489 \fBEXIT_SMACK_PROCESS_LABEL\fR
5490 T}:T{
5491 Failed to set SMACK label\&. See \fISmackProcessLabel=\fR above\&.
5492 T}
5493 T{
5494 237
5495 T}:T{
5496 \fBEXIT_KEYRING\fR
5497 T}:T{
5498 Failed to set up kernel keyring\&.
5499 T}
5500 T{
5501 238
5502 T}:T{
5503 \fBEXIT_STATE_DIRECTORY\fR
5504 T}:T{
5505 Failed to set up unit\*(Aqs state directory\&. See \fIStateDirectory=\fR above\&.
5506 T}
5507 T{
5508 239
5509 T}:T{
5510 \fBEXIT_CACHE_DIRECTORY\fR
5511 T}:T{
5512 Failed to set up unit\*(Aqs cache directory\&. See \fICacheDirectory=\fR above\&.
5513 T}
5514 T{
5515 240
5516 T}:T{
5517 \fBEXIT_LOGS_DIRECTORY\fR
5518 T}:T{
5519 Failed to set up unit\*(Aqs logging directory\&. See \fILogsDirectory=\fR above\&.
5520 T}
5521 T{
5522 241
5523 T}:T{
5524 \fBEXIT_CONFIGURATION_DIRECTORY\fR
5525 T}:T{
5526 Failed to set up unit\*(Aqs configuration directory\&. See \fIConfigurationDirectory=\fR above\&.
5527 T}
5528 T{
5529 242
5530 T}:T{
5531 \fBEXIT_NUMA_POLICY\fR
5532 T}:T{
5533 Failed to set up unit\*(Aqs NUMA memory policy\&. See \fINUMAPolicy=\fR and \fINUMAMask=\fR above\&.
5534 T}
5535 T{
5536 243
5537 T}:T{
5538 \fBEXIT_CREDENTIALS\fR
5539 T}:T{
5540 Failed to set up unit\*(Aqs credentials\&. See \fIImportCredential=\fR, \fILoadCredential=\fR and \fISetCredential=\fR above\&.
5541 T}
5542 T{
5543 245
5544 T}:T{
5545 \fBEXIT_BPF\fR
5546 T}:T{
5547 Failed to apply BPF restrictions\&. See \fIRestrictFileSystems=\fR above\&.
5548 T}
5549 .TE
5550 .sp 1
5551 .PP
5552 Finally, the BSD operating systems define a set of exit codes, typically defined on Linux systems too:
5553 .sp
5554 .it 1 an-trap
5555 .nr an-no-space-flag 1
5556 .nr an-break-flag 1
5557 .br
5558 .B Table\ \&10.\ \&BSD exit codes
5559 .TS
5560 allbox tab(:);
5561 lB lB lB.
5562 T{
5563 Exit Code
5564 T}:T{
5565 Symbolic Name
5566 T}:T{
5567 Description
5568 T}
5569 .T&
5570 l l l
5571 l l l
5572 l l l
5573 l l l
5574 l l l
5575 l l l
5576 l l l
5577 l l l
5578 l l l
5579 l l l
5580 l l l
5581 l l l
5582 l l l
5583 l l l
5584 l l l.
5585 T{
5586 64
5587 T}:T{
5588 \fBEX_USAGE\fR
5589 T}:T{
5590 Command line usage error
5591 T}
5592 T{
5593 65
5594 T}:T{
5595 \fBEX_DATAERR\fR
5596 T}:T{
5597 Data format error
5598 T}
5599 T{
5600 66
5601 T}:T{
5602 \fBEX_NOINPUT\fR
5603 T}:T{
5604 Cannot open input
5605 T}
5606 T{
5607 67
5608 T}:T{
5609 \fBEX_NOUSER\fR
5610 T}:T{
5611 Addressee unknown
5612 T}
5613 T{
5614 68
5615 T}:T{
5616 \fBEX_NOHOST\fR
5617 T}:T{
5618 Host name unknown
5619 T}
5620 T{
5621 69
5622 T}:T{
5623 \fBEX_UNAVAILABLE\fR
5624 T}:T{
5625 Service unavailable
5626 T}
5627 T{
5628 70
5629 T}:T{
5630 \fBEX_SOFTWARE\fR
5631 T}:T{
5632 internal software error
5633 T}
5634 T{
5635 71
5636 T}:T{
5637 \fBEX_OSERR\fR
5638 T}:T{
5639 System error (e\&.g\&., cannot fork)
5640 T}
5641 T{
5642 72
5643 T}:T{
5644 \fBEX_OSFILE\fR
5645 T}:T{
5646 Critical OS file missing
5647 T}
5648 T{
5649 73
5650 T}:T{
5651 \fBEX_CANTCREAT\fR
5652 T}:T{
5653 Cannot create (user) output file
5654 T}
5655 T{
5656 74
5657 T}:T{
5658 \fBEX_IOERR\fR
5659 T}:T{
5660 Input/output error
5661 T}
5662 T{
5663 75
5664 T}:T{
5665 \fBEX_TEMPFAIL\fR
5666 T}:T{
5667 Temporary failure; user is invited to retry
5668 T}
5669 T{
5670 76
5671 T}:T{
5672 \fBEX_PROTOCOL\fR
5673 T}:T{
5674 Remote error in protocol
5675 T}
5676 T{
5677 77
5678 T}:T{
5679 \fBEX_NOPERM\fR
5680 T}:T{
5681 Permission denied
5682 T}
5683 T{
5684 78
5685 T}:T{
5686 \fBEX_CONFIG\fR
5687 T}:T{
5688 Configuration error
5689 T}
5690 .TE
5691 .sp 1
5692 .SH "EXAMPLES"
5693 .PP
5694 \fBExample\ \&3.\ \&\fI$MONITOR_\fR\fI\fI*\fR\fR usage\fR
5695 .PP
5696 A service
5697 myfailer\&.service
5698 which can trigger an
5699 \fIOnFailure=\fR
5700 dependency\&.
5701 .sp
5702 .if n \{\
5703 .RS 4
5704 .\}
5705 .nf
5706 [Unit]
5707 Description=Service which can trigger an OnFailure= dependency
5708 OnFailure=myhandler\&.service
5709
5710 [Service]
5711 ExecStart=/bin/myprogram
5712 .fi
5713 .if n \{\
5714 .RE
5715 .\}
5716 .PP
5717 A service
5718 mysuccess\&.service
5719 which can trigger an
5720 \fIOnSuccess=\fR
5721 dependency\&.
5722 .sp
5723 .if n \{\
5724 .RS 4
5725 .\}
5726 .nf
5727 [Unit]
5728 Description=Service which can trigger an OnSuccess= dependency
5729 OnSuccess=myhandler\&.service
5730
5731 [Service]
5732 ExecStart=/bin/mysecondprogram
5733 .fi
5734 .if n \{\
5735 .RE
5736 .\}
5737 .PP
5738 A service
5739 myhandler\&.service
5740 which can be triggered by any of the above services\&.
5741 .sp
5742 .if n \{\
5743 .RS 4
5744 .\}
5745 .nf
5746 [Unit]
5747 Description=Acts on service failing or succeeding
5748
5749 [Service]
5750 ExecStart=/bin/bash \-c "echo $MONITOR_SERVICE_RESULT $MONITOR_EXIT_CODE $MONITOR_EXIT_STATUS $MONITOR_INVOCATION_ID $MONITOR_UNIT"
5751 .fi
5752 .if n \{\
5753 .RE
5754 .\}
5755 .PP
5756 If
5757 myfailer\&.service
5758 were to run and exit in failure, then
5759 myhandler\&.service
5760 would be triggered and the monitor variables would be set as follows:
5761 .sp
5762 .if n \{\
5763 .RS 4
5764 .\}
5765 .nf
5766 MONITOR_SERVICE_RESULT=exit\-code
5767 MONITOR_EXIT_CODE=exited
5768 MONITOR_EXIT_STATUS=1
5769 MONITOR_INVOCATION_ID=cc8fdc149b2b4ca698d4f259f4054236
5770 MONITOR_UNIT=myfailer\&.service
5771 .fi
5772 .if n \{\
5773 .RE
5774 .\}
5775 .PP
5776 If
5777 mysuccess\&.service
5778 were to run and exit in success, then
5779 myhandler\&.service
5780 would be triggered and the monitor variables would be set as follows:
5781 .sp
5782 .if n \{\
5783 .RS 4
5784 .\}
5785 .nf
5786 MONITOR_SERVICE_RESULT=success
5787 MONITOR_EXIT_CODE=exited
5788 MONITOR_EXIT_STATUS=0
5789 MONITOR_INVOCATION_ID=6ab9af147b8c4a3ebe36e7a5f8611697
5790 MONITOR_UNIT=mysuccess\&.service
5791 .fi
5792 .if n \{\
5793 .RE
5794 .\}
5795 .SH "SEE ALSO"
5796 .PP
5797 \fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd-analyze\fR(1), \fBjournalctl\fR(1), \fBsystemd-system.conf\fR(5), \fBsystemd.unit\fR(5), \fBsystemd.service\fR(5), \fBsystemd.socket\fR(5), \fBsystemd.swap\fR(5), \fBsystemd.mount\fR(5), \fBsystemd.kill\fR(5), \fBsystemd.resource-control\fR(5), \fBsystemd.time\fR(7), \fBsystemd.directives\fR(7), \fBtmpfiles.d\fR(5), \fBexec\fR(3), \fBfork\fR(2)
5798 .SH "NOTES"
5799 .IP " 1." 4
5800 Discoverable Partitions Specification
5801 .RS 4
5802 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
5803 .RE
5804 .IP " 2." 4
5805 The /proc Filesystem
5806 .RS 4
5807 \%https://docs.kernel.org/filesystems/proc.html#mount-options
5808 .RE
5809 .IP " 3." 4
5810 User/Group Name Syntax
5811 .RS 4
5812 \%https://systemd.io/USER_NAMES
5813 .RE
5814 .IP " 4." 4
5815 No New Privileges Flag
5816 .RS 4
5817 \%https://docs.kernel.org/userspace-api/no_new_privs.html
5818 .RE
5819 .IP " 5." 4
5820 JSON User Record
5821 .RS 4
5822 \%https://systemd.io/USER_RECORD
5823 .RE
5824 .IP " 6." 4
5825 The /proc Filesystem
5826 .RS 4
5827 \%https://docs.kernel.org/filesystems/proc.html
5828 .RE
5829 .IP " 7." 4
5830 id-mapped mounts
5831 .RS 4
5832 \%https://lwn.net/Articles/896255/
5833 .RE
5834 .IP " 8." 4
5835 Kernel Samepage Merging
5836 .RS 4
5837 \%https://docs.kernel.org/admin-guide/mm/ksm.html
5838 .RE
5839 .IP " 9." 4
5840 unicode scalar values
5841 .RS 4
5842 \%https://www.unicode.org/glossary/#unicode_scalar_value
5843 .RE
5844 .IP "10." 4
5845 unicode noncharacters
5846 .RS 4
5847 \%https://www.unicode.org/glossary/#noncharacter
5848 .RE
5849 .IP "11." 4
5850 unicode byte order mark
5851 .RS 4
5852 \%https://www.unicode.org/glossary/#byte_order_mark
5853 .RE
5854 .IP "12." 4
5855 POSIX shell unquoted text
5856 .RS 4
5857 \%https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01
5858 .RE
5859 .IP "13." 4
5860 POSIX shell single-quoted text
5861 .RS 4
5862 \%https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02
5863 .RE
5864 .IP "14." 4
5865 POSIX shell double-quoted text
5866 .RS 4
5867 \%https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03
5868 .RE
5869 .IP "15." 4
5870 Base64
5871 .RS 4
5872 \%https://tools.ietf.org/html/rfc2045#section-6.8
5873 .RE
5874 .IP "16." 4
5875 Container Interface
5876 .RS 4
5877 \%https://systemd.io/CONTAINER_INTERFACE
5878 .RE
5879 .IP "17." 4
5880 DMI/SMBIOS
5881 .RS 4
5882 \%https://www.dmtf.org/standards/smbios
5883 .RE
5884 .IP "18." 4
5885 qemu
5886 .RS 4
5887 \%https://www.qemu.org/docs/master/system/index.html
5888 .RE
5889 .IP "19." 4
5890 System and Service Credentials
5891 .RS 4
5892 \%https://systemd.io/CREDENTIALS
5893 .RE
5894 .IP "20." 4
5895 Memory Pressure Handling
5896 .RS 4
5897 \%https://systemd.io/MEMORY_PRESSURE
5898 .RE
5899 .IP "21." 4
5900 LSB specification
5901 .RS 4
5902 \%https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
5903 .RE