Debian Codegraph @

upstream/fedora-44/man5/systemd.exec.5

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