Debian Codegraph @

upstream/mageia-cauldron/man5/systemd.exec.5

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