1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="systemd.exec" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 <refentryinfo> 8 <title>systemd.exec</title> 9 <productname>systemd</productname> 10 </refentryinfo> 11 12 <refmeta> 13 <refentrytitle>systemd.exec</refentrytitle> 14 <manvolnum>5</manvolnum> 15 </refmeta> 16 17 <refnamediv> 18 <refname>systemd.exec</refname> 19 <refpurpose>Execution environment configuration</refpurpose> 20 </refnamediv> 21 22 <refsynopsisdiv> 23 <para><filename><replaceable>service</replaceable>.service</filename>, 24 <filename><replaceable>socket</replaceable>.socket</filename>, 25 <filename><replaceable>mount</replaceable>.mount</filename>, 26 <filename><replaceable>swap</replaceable>.swap</filename></para> 27 </refsynopsisdiv> 28 29 <refsect1> 30 <title>Description</title> 31 32 <para>Unit configuration files for services, sockets, mount points, and swap devices share a subset of 33 configuration options which define the execution environment of spawned processes.</para> 34 35 <para>This man page lists the configuration options shared by these four unit types. See 36 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the common 37 options of all unit configuration files, and 38 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 39 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 40 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and 41 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more 42 information on the specific unit configuration files. The execution specific configuration options are configured 43 in the [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type.</para> 44 45 <para>In addition, options which control resources through Linux Control Groups (cgroups) are listed in 46 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 47 Those options complement options listed here.</para> 48 </refsect1> 49 50 <refsect1> 51 <title>Implicit Dependencies</title> 52 53 <para>A few execution parameters result in additional, automatic dependencies to be added:</para> 54 55 <itemizedlist> 56 <listitem><para>Units with <varname>WorkingDirectory=</varname>, <varname>RootDirectory=</varname>, 57 <varname>RootImage=</varname>, <varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>, 58 <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname> or 59 <varname>ConfigurationDirectory=</varname> set automatically gain dependencies of type 60 <varname>Requires=</varname> and <varname>After=</varname> on all mount units required to access the specified 61 paths. This is equivalent to having them listed explicitly in 62 <varname>RequiresMountsFor=</varname>.</para></listitem> 63 64 <listitem><para>Similarly, units with <varname>PrivateTmp=</varname> enabled automatically get mount 65 unit dependencies for all mounts required to access <filename>/tmp/</filename> and 66 <filename>/var/tmp/</filename>. They will also gain an automatic <varname>After=</varname> dependency 67 on 68 <citerefentry><refentrytitle>systemd-tmpfiles-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. 69 </para></listitem> 70 71 <listitem><para>Units whose standard output or error output is connected to <option>journal</option> or 72 <option>kmsg</option> (or their combinations with console output, see below) automatically acquire 73 dependencies of type <varname>After=</varname> on 74 <filename>systemd-journald.socket</filename>.</para></listitem> 75 76 <listitem><para>Units using <varname>LogNamespace=</varname> will automatically gain ordering and 77 requirement dependencies on the two socket units associated with 78 <filename>systemd-journald@.service</filename> instances.</para></listitem> 79 </itemizedlist> 80 </refsect1> 81 82 <!-- We don't have any default dependency here. --> 83 84 <refsect1> 85 <title>Paths</title> 86 87 <para>The following settings may be used to change a service's view of the filesystem. Please note that the paths 88 must be absolute and must not contain a <literal>..</literal> path component.</para> 89 90 <variablelist class='unit-directives'> 91 92 <varlistentry> 93 <term><varname>ExecSearchPath=</varname></term> 94 95 <listitem><para>Takes a colon separated list of absolute paths relative to which the executable 96 used by the <varname>Exec*=</varname> (e.g. <varname>ExecStart=</varname>, 97 <varname>ExecStop=</varname>, etc.) properties can be found. <varname>ExecSearchPath=</varname> 98 overrides <varname>$PATH</varname> if <varname>$PATH</varname> is not supplied by the user through 99 <varname>Environment=</varname>, <varname>EnvironmentFile=</varname> or 100 <varname>PassEnvironment=</varname>. Assigning an empty string removes previous assignments 101 and setting <varname>ExecSearchPath=</varname> to a value multiple times will append 102 to the previous setting. 103 </para></listitem> 104 </varlistentry> 105 106 <varlistentry> 107 <term><varname>WorkingDirectory=</varname></term> 108 109 <listitem><para>Takes a directory path relative to the service's root directory specified by 110 <varname>RootDirectory=</varname>, or the special value <literal>~</literal>. Sets the working directory for 111 executed processes. If set to <literal>~</literal>, the home directory of the user specified in 112 <varname>User=</varname> is used. If not set, defaults to the root directory when systemd is running as a 113 system instance and the respective user's home directory if run as user. If the setting is prefixed with the 114 <literal>-</literal> character, a missing working directory is not considered fatal. If 115 <varname>RootDirectory=</varname>/<varname>RootImage=</varname> is not set, then 116 <varname>WorkingDirectory=</varname> is relative to the root of the system running the service manager. Note 117 that setting this parameter might result in additional dependencies to be added to the unit (see 118 above).</para></listitem> 119 </varlistentry> 120 121 <varlistentry> 122 <term><varname>RootDirectory=</varname></term> 123 124 <listitem><para>Takes a directory path relative to the host's root directory (i.e. the root of the system 125 running the service manager). Sets the root directory for executed processes, with the <citerefentry 126 project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system 127 call. If this is used, it must be ensured that the process binary and all its auxiliary files are available in 128 the <function>chroot()</function> jail. Note that setting this parameter might result in additional 129 dependencies to be added to the unit (see above).</para> 130 131 <para>The <varname>MountAPIVFS=</varname> and <varname>PrivateUsers=</varname> settings are particularly useful 132 in conjunction with <varname>RootDirectory=</varname>. For details, see below.</para> 133 134 <para>If <varname>RootDirectory=</varname>/<varname>RootImage=</varname> are used together with 135 <varname>NotifyAccess=</varname> the notification socket is automatically mounted from the host into 136 the root environment, to ensure the notification interface can work correctly.</para> 137 138 <para>Note that services using <varname>RootDirectory=</varname>/<varname>RootImage=</varname> will 139 not be able to log via the syslog or journal protocols to the host logging infrastructure, unless the 140 relevant sockets are mounted from the host, specifically:</para> 141 142 <example> 143 <title>Mounting logging sockets into root environment</title> 144 145 <programlisting>BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout</programlisting> 146 </example> 147 148 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 149 </varlistentry> 150 151 <varlistentry> 152 <term><varname>RootImage=</varname></term> 153 154 <listitem><para>Takes a path to a block device node or regular file as argument. This call is similar 155 to <varname>RootDirectory=</varname> however mounts a file system hierarchy from a block device node 156 or loopback file instead of a directory. The device node or file system image file needs to contain a 157 file system without a partition table, or a file system within an MBR/MS-DOS or GPT partition table 158 with only a single Linux-compatible partition, or a set of file systems within a GPT partition table 159 that follows the <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions 160 Specification</ulink>.</para> 161 162 <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or 163 <literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is 164 set, then this setting adds <filename>/dev/loop-control</filename> with <constant>rw</constant> mode, 165 <literal>block-loop</literal> and <literal>block-blkext</literal> with <constant>rwm</constant> mode 166 to <varname>DeviceAllow=</varname>. See 167 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> 168 for the details about <varname>DevicePolicy=</varname> or <varname>DeviceAllow=</varname>. Also, see 169 <varname>PrivateDevices=</varname> below, as it may change the setting of 170 <varname>DevicePolicy=</varname>.</para> 171 172 <para>Units making use of <varname>RootImage=</varname> automatically gain an 173 <varname>After=</varname> dependency on <filename>systemd-udevd.service</filename>.</para> 174 175 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 176 </varlistentry> 177 178 <varlistentry> 179 <term><varname>RootImageOptions=</varname></term> 180 181 <listitem><para>Takes a comma-separated list of mount options that will be used on disk images specified by 182 <varname>RootImage=</varname>. Optionally a partition name can be prefixed, followed by colon, in 183 case the image has multiple partitions, otherwise partition name <literal>root</literal> is implied. 184 Options for multiple partitions can be specified in a single line with space separators. Assigning an empty 185 string removes previous assignments. Duplicated options are ignored. For a list of valid mount options, please 186 refer to 187 <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>. 188 </para> 189 190 <para>Valid partition names follow the <ulink 191 url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink>: 192 <constant>root</constant>, <constant>usr</constant>, <constant>home</constant>, <constant>srv</constant>, 193 <constant>esp</constant>, <constant>xbootldr</constant>, <constant>tmp</constant>, 194 <constant>var</constant>.</para> 195 196 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 197 </varlistentry> 198 199 <varlistentry> 200 <term><varname>RootHash=</varname></term> 201 202 <listitem><para>Takes a data integrity (dm-verity) root hash specified in hexadecimal, or the path to a file 203 containing a root hash in ASCII hexadecimal format. This option enables data integrity checks using dm-verity, 204 if the used image contains the appropriate integrity data (see above) or if <varname>RootVerity=</varname> is used. 205 The specified hash must match the root hash of integrity data, and is usually at least 256 bits (and hence 64 206 formatted hexadecimal characters) long (in case of SHA256 for example). If this option is not specified, but 207 the image file carries the <literal>user.verity.roothash</literal> extended file attribute (see <citerefentry 208 project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>), then the root 209 hash is read from it, also as formatted hexadecimal characters. If the extended file attribute is not found (or 210 is not supported by the underlying file system), but a file with the <filename>.roothash</filename> suffix is 211 found next to the image file, bearing otherwise the same name (except if the image has the 212 <filename>.raw</filename> suffix, in which case the root hash file must not have it in its name), the root hash 213 is read from it and automatically used, also as formatted hexadecimal characters.</para> 214 215 <para>If the disk image contains a separate <filename>/usr/</filename> partition it may also be 216 Verity protected, in which case the root hash may configured via an extended attribute 217 <literal>user.verity.usrhash</literal> or a <filename>.usrhash</filename> file adjacent to the disk 218 image. There's currently no option to configure the root hash for the <filename>/usr/</filename> file 219 system via the unit file directly.</para> 220 221 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 222 </varlistentry> 223 224 <varlistentry> 225 <term><varname>RootHashSignature=</varname></term> 226 227 <listitem><para>Takes a PKCS7 signature of the <varname>RootHash=</varname> option as a path to a 228 DER-encoded signature file, or as an ASCII base64 string encoding of a DER-encoded signature prefixed 229 by <literal>base64:</literal>. The dm-verity volume will only be opened if the signature of the root 230 hash is valid and signed by a public key present in the kernel keyring. If this option is not 231 specified, but a file with the <filename>.roothash.p7s</filename> suffix is found next to the image 232 file, bearing otherwise the same name (except if the image has the <filename>.raw</filename> suffix, 233 in which case the signature file must not have it in its name), the signature is read from it and 234 automatically used.</para> 235 236 <para>If the disk image contains a separate <filename>/usr/</filename> partition it may also be 237 Verity protected, in which case the signature for the root hash may configured via a 238 <filename>.usrhash.p7s</filename> file adjacent to the disk image. There's currently no option to 239 configure the root hash signature for the <filename>/usr/</filename> via the unit file 240 directly.</para> 241 242 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 243 </varlistentry> 244 245 <varlistentry> 246 <term><varname>RootVerity=</varname></term> 247 248 <listitem><para>Takes the path to a data integrity (dm-verity) file. This option enables data integrity checks 249 using dm-verity, if <varname>RootImage=</varname> is used and a root-hash is passed and if the used image itself 250 does not contains the integrity data. The integrity data must be matched by the root hash. If this option is not 251 specified, but a file with the <filename>.verity</filename> suffix is found next to the image file, bearing otherwise 252 the same name (except if the image has the <filename>.raw</filename> suffix, in which case the verity data file must 253 not have it in its name), the verity data is read from it and automatically used.</para> 254 255 <para>This option is supported only for disk images that contain a single file system, without an 256 enveloping partition table. Images that contain a GPT partition table should instead include both 257 root file system and matching Verity data in the same image, implementing the <ulink 258 url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink>.</para> 259 260 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 261 </varlistentry> 262 263 <varlistentry> 264 <term><varname>MountAPIVFS=</varname></term> 265 266 <listitem><para>Takes a boolean argument. If on, a private mount namespace for the unit's processes is created 267 and the API file systems <filename>/proc/</filename>, <filename>/sys/</filename>, <filename>/dev/</filename> and 268 <filename>/run/</filename> (as an empty <literal>tmpfs</literal>) are mounted inside of it, unless they are 269 already mounted. Note that this option has no effect unless used in conjunction with 270 <varname>RootDirectory=</varname>/<varname>RootImage=</varname> as these four mounts are 271 generally mounted in the host anyway, and unless the root directory is changed, the private mount namespace 272 will be a 1:1 copy of the host's, and include these four mounts. Note that the <filename>/dev/</filename> file 273 system of the host is bind mounted if this option is used without <varname>PrivateDevices=</varname>. To run 274 the service with a private, minimal version of <filename>/dev/</filename>, combine this option with 275 <varname>PrivateDevices=</varname>.</para> 276 277 <para>In order to allow propagating mounts at runtime in a safe manner, <filename>/run/systemd/propagate</filename> 278 on the host will be used to set up new mounts, and <filename>/run/host/incoming/</filename> in the private namespace 279 will be used as an intermediate step to store them before being moved to the final mount point.</para></listitem> 280 </varlistentry> 281 282 <varlistentry> 283 <term><varname>ProtectProc=</varname></term> 284 285 <listitem><para>Takes one of <literal>noaccess</literal>, <literal>invisible</literal>, 286 <literal>ptraceable</literal> or <literal>default</literal> (which it defaults to). When set, this 287 controls the <literal>hidepid=</literal> mount option of the <literal>procfs</literal> instance for 288 the unit that controls which directories with process metainformation 289 (<filename>/proc/<replaceable>PID</replaceable></filename>) are visible and accessible: when set to 290 <literal>noaccess</literal> the ability to access most of other users' process metadata in 291 <filename>/proc/</filename> is taken away for processes of the service. When set to 292 <literal>invisible</literal> processes owned by other users are hidden from 293 <filename>/proc/</filename>. If <literal>ptraceable</literal> all processes that cannot be 294 <function>ptrace()</function>'ed by a process are hidden to it. If <literal>default</literal> no 295 restrictions on <filename>/proc/</filename> access or visibility are made. For further details see 296 <ulink url="https://www.kernel.org/doc/html/latest/filesystems/proc.html#mount-options">The /proc 297 Filesystem</ulink>. It is generally recommended to run most system services with this option set to 298 <literal>invisible</literal>. This option is implemented via file system namespacing, and thus cannot 299 be used with services that shall be able to install mount points in the host file system 300 hierarchy. Note that the root user is unaffected by this option, so to be effective it has to be used 301 together with <varname>User=</varname> or <varname>DynamicUser=yes</varname>, and also without the 302 <literal>CAP_SYS_PTRACE</literal> capability, which also allows a process to bypass this feature. It 303 cannot be used for services that need to access metainformation about other users' processes. This 304 option implies <varname>MountAPIVFS=</varname>.</para> 305 306 <para>If the kernel doesn't support per-mount point <option>hidepid=</option> mount options this 307 setting remains without effect, and the unit's processes will be able to access and see other process 308 as if the option was not used.</para> 309 310 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 311 </varlistentry> 312 313 <varlistentry> 314 <term><varname>ProcSubset=</varname></term> 315 316 <listitem><para>Takes one of <literal>all</literal> (the default) and <literal>pid</literal>. If 317 <literal>pid</literal>, all files and directories not directly associated with process management and 318 introspection are made invisible in the <filename>/proc/</filename> file system configured for the 319 unit's processes. This controls the <literal>subset=</literal> mount option of the 320 <literal>procfs</literal> instance for the unit. For further details see <ulink 321 url="https://www.kernel.org/doc/html/latest/filesystems/proc.html#mount-options">The /proc 322 Filesystem</ulink>. Note that Linux exposes various kernel APIs via <filename>/proc/</filename>, 323 which are made unavailable with this setting. Since these APIs are used frequently this option is 324 useful only in a few, specific cases, and is not suitable for most non-trivial programs.</para> 325 326 <para>Much like <varname>ProtectProc=</varname> above, this is implemented via file system mount 327 namespacing, and hence the same restrictions apply: it is only available to system services, it 328 disables mount propagation to the host mount table, and it implies 329 <varname>MountAPIVFS=</varname>. Also, like <varname>ProtectProc=</varname> this setting is gracefully 330 disabled if the used kernel does not support the <literal>subset=</literal> mount option of 331 <literal>procfs</literal>.</para></listitem> 332 </varlistentry> 333 334 <varlistentry> 335 <term><varname>BindPaths=</varname></term> 336 <term><varname>BindReadOnlyPaths=</varname></term> 337 338 <listitem><para>Configures unit-specific bind mounts. A bind mount makes a particular file or directory 339 available at an additional place in the unit's view of the file system. Any bind mounts created with this 340 option are specific to the unit, and are not visible in the host's mount table. This option expects a 341 whitespace separated list of bind mount definitions. Each definition consists of a colon-separated triple of 342 source path, destination path and option string, where the latter two are optional. If only a source path is 343 specified the source and destination is taken to be the same. The option string may be either 344 <literal>rbind</literal> or <literal>norbind</literal> for configuring a recursive or non-recursive bind 345 mount. If the destination path is omitted, the option string must be omitted too. 346 Each bind mount definition may be prefixed with <literal>-</literal>, in which case it will be ignored 347 when its source path does not exist.</para> 348 349 <para><varname>BindPaths=</varname> creates regular writable bind mounts (unless the source file system mount 350 is already marked read-only), while <varname>BindReadOnlyPaths=</varname> creates read-only bind mounts. These 351 settings may be used more than once, each usage appends to the unit's list of bind mounts. If the empty string 352 is assigned to either of these two options the entire list of bind mounts defined prior to this is reset. Note 353 that in this case both read-only and regular bind mounts are reset, regardless which of the two settings is 354 used.</para> 355 356 <para>This option is particularly useful when <varname>RootDirectory=</varname>/<varname>RootImage=</varname> 357 is used. In this case the source path refers to a path on the host file system, while the destination path 358 refers to a path below the root directory of the unit.</para> 359 360 <para>Note that the destination directory must exist or systemd must be able to create it. Thus, it 361 is not possible to use those options for mount points nested underneath paths specified in 362 <varname>InaccessiblePaths=</varname>, or under <filename>/home/</filename> and other protected 363 directories if <varname>ProtectHome=yes</varname> is 364 specified. <varname>TemporaryFileSystem=</varname> with <literal>:ro</literal> or 365 <varname>ProtectHome=tmpfs</varname> should be used instead.</para></listitem> 366 </varlistentry> 367 368 <varlistentry> 369 <term><varname>MountImages=</varname></term> 370 371 <listitem><para>This setting is similar to <varname>RootImage=</varname> in that it mounts a file 372 system hierarchy from a block device node or loopback file, but the destination directory can be 373 specified as well as mount options. This option expects a whitespace separated list of mount 374 definitions. Each definition consists of a colon-separated tuple of source path and destination 375 definitions, optionally followed by another colon and a list of mount options.</para> 376 377 <para>Mount options may be defined as a single comma-separated list of options, in which case they 378 will be implicitly applied to the root partition on the image, or a series of colon-separated tuples 379 of partition name and mount options. Valid partition names and mount options are the same as for 380 <varname>RootImageOptions=</varname> setting described above.</para> 381 382 <para>Each mount definition may be prefixed with <literal>-</literal>, in which case it will be 383 ignored when its source path does not exist. The source argument is a path to a block device node or 384 regular file. If source or destination contain a <literal>:</literal>, it needs to be escaped as 385 <literal>\:</literal>. The device node or file system image file needs to follow the same rules as 386 specified for <varname>RootImage=</varname>. Any mounts created with this option are specific to the 387 unit, and are not visible in the host's mount table.</para> 388 389 <para>These settings may be used more than once, each usage appends to the unit's list of mount 390 paths. If the empty string is assigned, the entire list of mount paths defined prior to this is 391 reset.</para> 392 393 <para>Note that the destination directory must exist or systemd must be able to create it. Thus, it 394 is not possible to use those options for mount points nested underneath paths specified in 395 <varname>InaccessiblePaths=</varname>, or under <filename>/home/</filename> and other protected 396 directories if <varname>ProtectHome=yes</varname> is specified.</para> 397 398 <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or 399 <literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is 400 set, then this setting adds <filename>/dev/loop-control</filename> with <constant>rw</constant> mode, 401 <literal>block-loop</literal> and <literal>block-blkext</literal> with <constant>rwm</constant> mode 402 to <varname>DeviceAllow=</varname>. See 403 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> 404 for the details about <varname>DevicePolicy=</varname> or <varname>DeviceAllow=</varname>. Also, see 405 <varname>PrivateDevices=</varname> below, as it may change the setting of 406 <varname>DevicePolicy=</varname>.</para> 407 408 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 409 </varlistentry> 410 411 <varlistentry> 412 <term><varname>ExtensionImages=</varname></term> 413 414 <listitem><para>This setting is similar to <varname>MountImages=</varname> in that it mounts a file 415 system hierarchy from a block device node or loopback file, but instead of providing a destination 416 path, an overlay will be set up. This option expects a whitespace separated list of mount 417 definitions. Each definition consists of a source path, optionally followed by a colon and a list of 418 mount options.</para> 419 420 <para>A read-only OverlayFS will be set up on top of <filename>/usr/</filename> and 421 <filename>/opt/</filename> hierarchies. The order in which the images are listed will determine the 422 order in which the overlay is laid down: images specified first to last will result in overlayfs 423 layers bottom to top.</para> 424 425 <para>Mount options may be defined as a single comma-separated list of options, in which case they 426 will be implicitly applied to the root partition on the image, or a series of colon-separated tuples 427 of partition name and mount options. Valid partition names and mount options are the same as for 428 <varname>RootImageOptions=</varname> setting described above.</para> 429 430 <para>Each mount definition may be prefixed with <literal>-</literal>, in which case it will be 431 ignored when its source path does not exist. The source argument is a path to a block device node or 432 regular file. If the source path contains a <literal>:</literal>, it needs to be escaped as 433 <literal>\:</literal>. The device node or file system image file needs to follow the same rules as 434 specified for <varname>RootImage=</varname>. Any mounts created with this option are specific to the 435 unit, and are not visible in the host's mount table.</para> 436 437 <para>These settings may be used more than once, each usage appends to the unit's list of image 438 paths. If the empty string is assigned, the entire list of mount paths defined prior to this is 439 reset.</para> 440 441 <para>Each image must carry a <filename>/usr/lib/extension-release.d/extension-release.IMAGE</filename> 442 file, with the appropriate metadata which matches <varname>RootImage=</varname>/<varname>RootDirectory=</varname> 443 or the host. See: 444 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> 445 446 <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or 447 <literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is 448 set, then this setting adds <filename>/dev/loop-control</filename> with <constant>rw</constant> mode, 449 <literal>block-loop</literal> and <literal>block-blkext</literal> with <constant>rwm</constant> mode 450 to <varname>DeviceAllow=</varname>. See 451 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> 452 for the details about <varname>DevicePolicy=</varname> or <varname>DeviceAllow=</varname>. Also, see 453 <varname>PrivateDevices=</varname> below, as it may change the setting of 454 <varname>DevicePolicy=</varname>.</para> 455 456 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 457 </varlistentry> 458 459 <varlistentry> 460 <term><varname>ExtensionDirectories=</varname></term> 461 462 <listitem><para>This setting is similar to <varname>BindReadOnlyPaths=</varname> in that it mounts a file 463 system hierarchy from a directory, but instead of providing a destination path, an overlay will be set 464 up. This option expects a whitespace separated list of source directories.</para> 465 466 <para>A read-only OverlayFS will be set up on top of <filename>/usr/</filename> and 467 <filename>/opt/</filename> hierarchies. The order in which the directories are listed will determine 468 the order in which the overlay is laid down: directories specified first to last will result in overlayfs 469 layers bottom to top.</para> 470 471 <para>Each directory listed in <varname>ExtensionDirectories=</varname> may be prefixed with <literal>-</literal>, 472 in which case it will be ignored when its source path does not exist. Any mounts created with this option are 473 specific to the unit, and are not visible in the host's mount table.</para> 474 475 <para>These settings may be used more than once, each usage appends to the unit's list of directories 476 paths. If the empty string is assigned, the entire list of mount paths defined prior to this is 477 reset.</para> 478 479 <para>Each directory must contain a <filename>/usr/lib/extension-release.d/extension-release.IMAGE</filename> 480 file, with the appropriate metadata which matches <varname>RootImage=</varname>/<varname>RootDirectory=</varname> 481 or the host. See: 482 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> 483 484 <para>Note that usage from user units requires overlayfs support in unprivileged user namespaces, 485 which was first introduced in kernel v5.11.</para> 486 487 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 488 </varlistentry> 489 </variablelist> 490 </refsect1> 491 492 <refsect1> 493 <title>User/Group Identity</title> 494 495 <xi:include href="system-only.xml" xpointer="plural"/> 496 497 <variablelist class='unit-directives'> 498 499 <varlistentry> 500 <term><varname>User=</varname></term> 501 <term><varname>Group=</varname></term> 502 503 <listitem><para>Set the UNIX user or group that the processes are executed as, respectively. Takes a single 504 user or group name, or a numeric ID as argument. For system services (services run by the system service 505 manager, i.e. managed by PID 1) and for user services of the root user (services managed by root's instance of 506 <command>systemd --user</command>), the default is <literal>root</literal>, but <varname>User=</varname> may be 507 used to specify a different user. For user services of any other user, switching user identity is not 508 permitted, hence the only valid setting is the same user the user's service manager is running as. If no group 509 is set, the default group of the user is used. This setting does not affect commands whose command line is 510 prefixed with <literal>+</literal>.</para> 511 512 <para>Note that this enforces only weak restrictions on the user/group name syntax, but will generate 513 warnings in many cases where user/group names do not adhere to the following rules: the specified 514 name should consist only of the characters a-z, A-Z, 0-9, <literal>_</literal> and 515 <literal>-</literal>, except for the first character which must be one of a-z, A-Z and 516 <literal>_</literal> (i.e. digits and <literal>-</literal> are not permitted as first character). The 517 user/group name must have at least one character, and at most 31. These restrictions are made in 518 order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux 519 systems. For further details on the names accepted and the names warned about see <ulink 520 url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink>.</para> 521 522 <para>When used in conjunction with <varname>DynamicUser=</varname> the user/group name specified is 523 dynamically allocated at the time the service is started, and released at the time the service is 524 stopped — unless it is already allocated statically (see below). If <varname>DynamicUser=</varname> 525 is not used the specified user and group must have been created statically in the user database no 526 later than the moment the service is started, for example using the 527 <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> 528 facility, which is applied at boot or package install time. If the user does not exist by then 529 program invocation will fail.</para> 530 531 <para>If the <varname>User=</varname> setting is used the supplementary group list is initialized 532 from the specified user's default group list, as defined in the system's user and group 533 database. Additional groups may be configured through the <varname>SupplementaryGroups=</varname> 534 setting (see below).</para></listitem> 535 </varlistentry> 536 537 <varlistentry> 538 <term><varname>DynamicUser=</varname></term> 539 540 <listitem><para>Takes a boolean parameter. If set, a UNIX user and group pair is allocated 541 dynamically when the unit is started, and released as soon as it is stopped. The user and group will 542 not be added to <filename>/etc/passwd</filename> or <filename>/etc/group</filename>, but are managed 543 transiently during runtime. The 544 <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> glibc 545 NSS module provides integration of these dynamic users/groups into the system's user and group 546 databases. The user and group name to use may be configured via <varname>User=</varname> and 547 <varname>Group=</varname> (see above). If these options are not used and dynamic user/group 548 allocation is enabled for a unit, the name of the dynamic user/group is implicitly derived from the 549 unit name. If the unit name without the type suffix qualifies as valid user name it is used directly, 550 otherwise a name incorporating a hash of it is used. If a statically allocated user or group of the 551 configured name already exists, it is used and no dynamic user/group is allocated. Note that if 552 <varname>User=</varname> is specified and the static group with the name exists, then it is required 553 that the static user with the name already exists. Similarly, if <varname>Group=</varname> is 554 specified and the static user with the name exists, then it is required that the static group with 555 the name already exists. Dynamic users/groups are allocated from the UID/GID range 61184…65519. It is 556 recommended to avoid this range for regular system or login users. At any point in time each UID/GID 557 from this range is only assigned to zero or one dynamically allocated users/groups in use. However, 558 UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running as 559 part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by 560 these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus 561 gain access to these files or directories. If <varname>DynamicUser=</varname> is enabled, 562 <varname>RemoveIPC=</varname> and <varname>PrivateTmp=</varname> are implied (and cannot be turned 563 off). This ensures that the lifetime of IPC objects and temporary files created by the executed 564 processes is bound to the runtime of the service, and hence the lifetime of the dynamic 565 user/group. Since <filename>/tmp/</filename> and <filename>/var/tmp/</filename> are usually the only 566 world-writable directories on a system this ensures that a unit making use of dynamic user/group 567 allocation cannot leave files around after unit termination. Furthermore 568 <varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname> are implicitly enabled 569 (and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID 570 files or directories. Moreover <varname>ProtectSystem=strict</varname> and 571 <varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to 572 arbitrary file system locations. In order to allow the service to write to certain directories, they 573 have to be allow-listed using <varname>ReadWritePaths=</varname>, but care must be taken so that 574 UID/GID recycling doesn't create security issues involving files created by the service. Use 575 <varname>RuntimeDirectory=</varname> (see below) in order to assign a writable runtime directory to a 576 service, owned by the dynamic user/group and removed automatically when the unit is terminated. Use 577 <varname>StateDirectory=</varname>, <varname>CacheDirectory=</varname> and 578 <varname>LogsDirectory=</varname> in order to assign a set of writable directories for specific 579 purposes to the service in a way that they are protected from vulnerabilities due to UID reuse (see 580 below). If this option is enabled, care should be taken that the unit's processes do not get access 581 to directories outside of these explicitly configured and managed ones. Specifically, do not use 582 <varname>BindPaths=</varname> and be careful with <constant>AF_UNIX</constant> file descriptor 583 passing for directory file descriptors, as this would permit processes to create files or directories 584 owned by the dynamic user/group that are not subject to the lifecycle and access guarantees of the 585 service. Defaults to off.</para></listitem> 586 </varlistentry> 587 588 <varlistentry> 589 <term><varname>SupplementaryGroups=</varname></term> 590 591 <listitem><para>Sets the supplementary Unix groups the processes are executed as. This takes a space-separated 592 list of group names or IDs. This option may be specified more than once, in which case all listed groups are 593 set as supplementary groups. When the empty string is assigned, the list of supplementary groups is reset, and 594 all assignments prior to this one will have no effect. In any way, this option does not override, but extends 595 the list of supplementary groups configured in the system group database for the user. This does not affect 596 commands prefixed with <literal>+</literal>.</para></listitem> 597 </varlistentry> 598 599 <varlistentry> 600 <term><varname>PAMName=</varname></term> 601 602 <listitem><para>Sets the PAM service name to set up a session as. If set, the executed process will be 603 registered as a PAM session under the specified service name. This is only useful in conjunction with the 604 <varname>User=</varname> setting, and is otherwise ignored. If not set, no PAM session will be opened for the 605 executed processes. See <citerefentry 606 project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> for 607 details.</para> 608 609 <para>Note that for each unit making use of this option a PAM session handler process will be maintained as 610 part of the unit and stays around as long as the unit is active, to ensure that appropriate actions can be 611 taken when the unit and hence the PAM session terminates. This process is named <literal>(sd-pam)</literal> and 612 is an immediate child process of the unit's main process.</para> 613 614 <para>Note that when this option is used for a unit it is very likely (depending on PAM configuration) that the 615 main unit process will be migrated to its own session scope unit when it is activated. This process will hence 616 be associated with two units: the unit it was originally started from (and for which 617 <varname>PAMName=</varname> was configured), and the session scope unit. Any child processes of that process 618 will however be associated with the session scope unit only. This has implications when used in combination 619 with <varname>NotifyAccess=</varname><option>all</option>, as these child processes will not be able to affect 620 changes in the original unit through notification messages. These messages will be considered belonging to the 621 session scope unit and not the original unit. It is hence not recommended to use <varname>PAMName=</varname> in 622 combination with <varname>NotifyAccess=</varname><option>all</option>.</para> 623 </listitem> 624 </varlistentry> 625 626 </variablelist> 627 </refsect1> 628 629 <refsect1> 630 <title>Capabilities</title> 631 632 <xi:include href="system-or-user-ns.xml" xpointer="plural"/> 633 634 <variablelist class='unit-directives'> 635 636 <varlistentry> 637 <term><varname>CapabilityBoundingSet=</varname></term> 638 639 <listitem><para>Controls which capabilities to include in the capability bounding set for the 640 executed process. See <citerefentry 641 project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> 642 for details. Takes a whitespace-separated list of capability names, 643 e.g. <constant>CAP_SYS_ADMIN</constant>, <constant>CAP_DAC_OVERRIDE</constant>, 644 <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be included in the bounding set, all 645 others are removed. If the list of capabilities is prefixed with <literal>~</literal>, all but the 646 listed capabilities will be included, the effect of the assignment inverted. Note that this option 647 also affects the respective capabilities in the effective, permitted and inheritable capability 648 sets. If this option is not used, the capability bounding set is not modified on process execution, 649 hence no limits on the capabilities of the process are enforced. This option may appear more than 650 once, in which case the bounding sets are merged by <constant>OR</constant>, or by 651 <constant>AND</constant> if the lines are prefixed with <literal>~</literal> (see below). If the 652 empty string is assigned to this option, the bounding set is reset to the empty capability set, and 653 all prior settings have no effect. If set to <literal>~</literal> (without any further argument), 654 the bounding set is reset to the full set of available capabilities, also undoing any previous 655 settings. This does not affect commands prefixed with <literal>+</literal>.</para> 656 657 <para>Use 658 <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s 659 <command>capability</command> command to retrieve a list of capabilities defined on the local 660 system.</para> 661 662 <para>Example: if a unit has the following, 663 <programlisting>CapabilityBoundingSet=CAP_A CAP_B 664CapabilityBoundingSet=CAP_B CAP_C</programlisting> 665 then <constant index='false'>CAP_A</constant>, <constant index='false'>CAP_B</constant>, and 666 <constant index='false'>CAP_C</constant> are set. If the second line is prefixed with 667 <literal>~</literal>, e.g., 668 <programlisting>CapabilityBoundingSet=CAP_A CAP_B 669CapabilityBoundingSet=~CAP_B CAP_C</programlisting> 670 then, only <constant index='false'>CAP_A</constant> is set.</para></listitem> 671 </varlistentry> 672 673 <varlistentry> 674 <term><varname>AmbientCapabilities=</varname></term> 675 676 <listitem><para>Controls which capabilities to include in the ambient capability set for the executed 677 process. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, 678 <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. This option may appear more than 679 once in which case the ambient capability sets are merged (see the above examples in 680 <varname>CapabilityBoundingSet=</varname>). If the list of capabilities is prefixed with <literal>~</literal>, 681 all but the listed capabilities will be included, the effect of the assignment inverted. If the empty string is 682 assigned to this option, the ambient capability set is reset to the empty capability set, and all prior 683 settings have no effect. If set to <literal>~</literal> (without any further argument), the ambient capability 684 set is reset to the full set of available capabilities, also undoing any previous settings. Note that adding 685 capabilities to ambient capability set adds them to the process's inherited capability set. </para><para> 686 Ambient capability sets are useful if you want to execute a process as a non-privileged user but still want to 687 give it some capabilities. Note that in this case option <constant>keep-caps</constant> is automatically added 688 to <varname>SecureBits=</varname> to retain the capabilities over the user 689 change. <varname>AmbientCapabilities=</varname> does not affect commands prefixed with 690 <literal>+</literal>.</para></listitem> 691 </varlistentry> 692 693 </variablelist> 694 </refsect1> 695 696 <refsect1> 697 <title>Security</title> 698 699 <variablelist class='unit-directives'> 700 701 <varlistentry> 702 <term><varname>NoNewPrivileges=</varname></term> 703 704 <listitem><para>Takes a boolean argument. If true, ensures that the service process and all its 705 children can never gain new privileges through <function>execve()</function> (e.g. via setuid or 706 setgid bits, or filesystem capabilities). This is the simplest and most effective way to ensure that 707 a process and its children can never elevate privileges again. Defaults to false, but certain 708 settings override this and ignore the value of this setting. This is the case when 709 <varname>DynamicUser=</varname>, 710 <varname>LockPersonality=</varname>, 711 <varname>MemoryDenyWriteExecute=</varname>, 712 <varname>PrivateDevices=</varname>, 713 <varname>ProtectClock=</varname>, 714 <varname>ProtectHostname=</varname>, 715 <varname>ProtectKernelLogs=</varname>, 716 <varname>ProtectKernelModules=</varname>, 717 <varname>ProtectKernelTunables=</varname>, 718 <varname>RestrictAddressFamilies=</varname>, 719 <varname>RestrictNamespaces=</varname>, 720 <varname>RestrictRealtime=</varname>, 721 <varname>RestrictSUIDSGID=</varname>, 722 <varname>SystemCallArchitectures=</varname>, 723 <varname>SystemCallFilter=</varname>, or 724 <varname>SystemCallLog=</varname> are specified. Note that even if this setting is overridden 725 by them, <command>systemctl show</command> shows the original value of this setting. In case the 726 service will be run in a new mount namespace anyway and SELinux is disabled, all file systems 727 are mounted with <constant>MS_NOSUID</constant> flag. Also see 728 <ulink url="https://www.kernel.org/doc/html/latest/userspace-api/no_new_privs.html">No New 729 Privileges Flag</ulink>.</para></listitem> 730 </varlistentry> 731 732 <varlistentry> 733 <term><varname>SecureBits=</varname></term> 734 735 <listitem><para>Controls the secure bits set for the executed process. Takes a space-separated combination of 736 options from the following list: <option>keep-caps</option>, <option>keep-caps-locked</option>, 737 <option>no-setuid-fixup</option>, <option>no-setuid-fixup-locked</option>, <option>noroot</option>, and 738 <option>noroot-locked</option>. This option may appear more than once, in which case the secure bits are 739 ORed. If the empty string is assigned to this option, the bits are reset to 0. This does not affect commands 740 prefixed with <literal>+</literal>. See <citerefentry 741 project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 742 details.</para></listitem> 743 </varlistentry> 744 745 </variablelist> 746 </refsect1> 747 748 <refsect1> 749 <title>Mandatory Access Control</title> 750 751 <xi:include href="system-only.xml" xpointer="plural"/> 752 753 <variablelist class='unit-directives'> 754 755 <varlistentry> 756 <term><varname>SELinuxContext=</varname></term> 757 758 <listitem><para>Set the SELinux security context of the executed process. If set, this will override the 759 automated domain transition. However, the policy still needs to authorize the transition. This directive is 760 ignored if SELinux is disabled. If prefixed by <literal>-</literal>, failing to set the SELinux 761 security context will be ignored, but it's still possible that the subsequent 762 <function>execve()</function> may fail if the policy doesn't allow the transition for the 763 non-overridden context. This does not affect commands prefixed with <literal>+</literal>. See 764 <citerefentry 765 project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> 766 for details.</para></listitem> 767 </varlistentry> 768 769 <varlistentry> 770 <term><varname>AppArmorProfile=</varname></term> 771 772 <listitem><para>Takes a profile name as argument. The process executed by the unit will switch to 773 this profile when started. Profiles must already be loaded in the kernel, or the unit will fail. If 774 prefixed by <literal>-</literal>, all errors will be ignored. This setting has no effect if AppArmor 775 is not enabled. This setting does not affect commands prefixed with <literal>+</literal>.</para> 776 </listitem> 777 </varlistentry> 778 779 <varlistentry> 780 <term><varname>SmackProcessLabel=</varname></term> 781 782 <listitem><para>Takes a <option>SMACK64</option> security label as argument. The process executed by the unit 783 will be started under this label and SMACK will decide whether the process is allowed to run or not, based on 784 it. The process will continue to run under the label specified here unless the executable has its own 785 <option>SMACK64EXEC</option> label, in which case the process will transition to run under that label. When not 786 specified, the label that systemd is running under is used. This directive is ignored if SMACK is 787 disabled.</para> 788 789 <para>The value may be prefixed by <literal>-</literal>, in which case all errors will be ignored. An empty 790 value may be specified to unset previous assignments. This does not affect commands prefixed with 791 <literal>+</literal>.</para></listitem> 792 </varlistentry> 793 794 </variablelist> 795 </refsect1> 796 797 <refsect1> 798 <title>Process Properties</title> 799 800 <variablelist class='unit-directives'> 801 802 <varlistentry> 803 <term><varname>LimitCPU=</varname></term> 804 <term><varname>LimitFSIZE=</varname></term> 805 <term><varname>LimitDATA=</varname></term> 806 <term><varname>LimitSTACK=</varname></term> 807 <term><varname>LimitCORE=</varname></term> 808 <term><varname>LimitRSS=</varname></term> 809 <term><varname>LimitNOFILE=</varname></term> 810 <term><varname>LimitAS=</varname></term> 811 <term><varname>LimitNPROC=</varname></term> 812 <term><varname>LimitMEMLOCK=</varname></term> 813 <term><varname>LimitLOCKS=</varname></term> 814 <term><varname>LimitSIGPENDING=</varname></term> 815 <term><varname>LimitMSGQUEUE=</varname></term> 816 <term><varname>LimitNICE=</varname></term> 817 <term><varname>LimitRTPRIO=</varname></term> 818 <term><varname>LimitRTTIME=</varname></term> 819 820 <listitem><para>Set soft and hard limits on various resources for executed processes. See 821 <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 822 details on the resource limit concept. Resource limits may be specified in two formats: either as 823 single value to set a specific soft and hard limit to the same value, or as colon-separated pair 824 <option>soft:hard</option> to set both limits individually (e.g. <literal>LimitAS=4G:16G</literal>). 825 Use the string <option>infinity</option> to configure no limit on a specific resource. The 826 multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits 827 measured in bytes (e.g. <literal>LimitAS=16G</literal>). For the limits referring to time values, the 828 usual time units ms, s, min, h and so on may be used (see 829 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 830 details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of 831 seconds is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is 832 implied. Also, note that the effective granularity of the limits might influence their 833 enforcement. For example, time limits specified for <varname>LimitCPU=</varname> will be rounded up 834 implicitly to multiples of 1s. For <varname>LimitNICE=</varname> the value may be specified in two 835 syntaxes: if prefixed with <literal>+</literal> or <literal>-</literal>, the value is understood as 836 regular Linux nice value in the range -20…19. If not prefixed like this the value is understood as 837 raw resource limit parameter in the range 0…40 (with 0 being equivalent to 1).</para> 838 839 <para>Note that most process resource limits configured with these options are per-process, and 840 processes may fork in order to acquire a new set of resources that are accounted independently of the 841 original process, and may thus escape limits set. Also note that <varname>LimitRSS=</varname> is not 842 implemented on Linux, and setting it has no effect. Often it is advisable to prefer the resource 843 controls listed in 844 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> 845 over these per-process limits, as they apply to services as a whole, may be altered dynamically at 846 runtime, and are generally more expressive. For example, <varname>MemoryMax=</varname> is a more 847 powerful (and working) replacement for <varname>LimitRSS=</varname>.</para> 848 849 <para>Note that <varname>LimitNPROC=</varname> will limit the number of processes from one (real) UID and 850 not the number of processes started (forked) by the service. Therefore the limit is cumulative for all 851 processes running under the same UID. Please also note that the <varname>LimitNPROC=</varname> will not be 852 enforced if the service is running as root (and not dropping privileges). Due to these limitations, 853 <varname>TasksMax=</varname> (see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle> 854 <manvolnum>5</manvolnum></citerefentry>) is typically a better choice than <varname>LimitNPROC=</varname>. 855 </para> 856 857 <para>Resource limits not configured explicitly for a unit default to the value configured in the various 858 <varname>DefaultLimitCPU=</varname>, <varname>DefaultLimitFSIZE=</varname>, … options available in 859 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and – 860 if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user 861 services, see below).</para> 862 863 <para>For system units these resource limits may be chosen freely. When these settings are configured 864 in a user service (i.e. a service run by the per-user instance of the service manager) they cannot be 865 used to raise the limits above those set for the user manager itself when it was first invoked, as 866 the user's service manager generally lacks the privileges to do so. In user context these 867 configuration options are hence only useful to lower the limits passed in or to raise the soft limit 868 to the maximum of the hard limit as configured for the user. To raise the user's limits further, the 869 available configuration mechanisms differ between operating systems, but typically require 870 privileges. In most cases it is possible to configure higher per-user resource limits via PAM or by 871 setting limits on the system service encapsulating the user's service manager, i.e. the user's 872 instance of <filename>user@.service</filename>. After making such changes, make sure to restart the 873 user's service manager.</para> 874 875 <table> 876 <title>Resource limit directives, their equivalent <command>ulimit</command> shell commands and the unit used</title> 877 878 <tgroup cols='3'> 879 <colspec colname='directive' /> 880 <colspec colname='equivalent' /> 881 <colspec colname='unit' /> 882 <thead> 883 <row> 884 <entry>Directive</entry> 885 <entry><command>ulimit</command> equivalent</entry> 886 <entry>Unit</entry> 887 </row> 888 </thead> 889 <tbody> 890 <row> 891 <entry>LimitCPU=</entry> 892 <entry>ulimit -t</entry> 893 <entry>Seconds</entry> 894 </row> 895 <row> 896 <entry>LimitFSIZE=</entry> 897 <entry>ulimit -f</entry> 898 <entry>Bytes</entry> 899 </row> 900 <row> 901 <entry>LimitDATA=</entry> 902 <entry>ulimit -d</entry> 903 <entry>Bytes</entry> 904 </row> 905 <row> 906 <entry>LimitSTACK=</entry> 907 <entry>ulimit -s</entry> 908 <entry>Bytes</entry> 909 </row> 910 <row> 911 <entry>LimitCORE=</entry> 912 <entry>ulimit -c</entry> 913 <entry>Bytes</entry> 914 </row> 915 <row> 916 <entry>LimitRSS=</entry> 917 <entry>ulimit -m</entry> 918 <entry>Bytes</entry> 919 </row> 920 <row> 921 <entry>LimitNOFILE=</entry> 922 <entry>ulimit -n</entry> 923 <entry>Number of File Descriptors</entry> 924 </row> 925 <row> 926 <entry>LimitAS=</entry> 927 <entry>ulimit -v</entry> 928 <entry>Bytes</entry> 929 </row> 930 <row> 931 <entry>LimitNPROC=</entry> 932 <entry>ulimit -u</entry> 933 <entry>Number of Processes</entry> 934 </row> 935 <row> 936 <entry>LimitMEMLOCK=</entry> 937 <entry>ulimit -l</entry> 938 <entry>Bytes</entry> 939 </row> 940 <row> 941 <entry>LimitLOCKS=</entry> 942 <entry>ulimit -x</entry> 943 <entry>Number of Locks</entry> 944 </row> 945 <row> 946 <entry>LimitSIGPENDING=</entry> 947 <entry>ulimit -i</entry> 948 <entry>Number of Queued Signals</entry> 949 </row> 950 <row> 951 <entry>LimitMSGQUEUE=</entry> 952 <entry>ulimit -q</entry> 953 <entry>Bytes</entry> 954 </row> 955 <row> 956 <entry>LimitNICE=</entry> 957 <entry>ulimit -e</entry> 958 <entry>Nice Level</entry> 959 </row> 960 <row> 961 <entry>LimitRTPRIO=</entry> 962 <entry>ulimit -r</entry> 963 <entry>Realtime Priority</entry> 964 </row> 965 <row> 966 <entry>LimitRTTIME=</entry> 967 <entry>No equivalent</entry> 968 <entry>Microseconds</entry> 969 </row> 970 </tbody> 971 </tgroup> 972 </table></listitem> 973 </varlistentry> 974 975 <varlistentry> 976 <term><varname>UMask=</varname></term> 977 978 <listitem><para>Controls the file mode creation mask. Takes an access mode in octal notation. See 979 <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 980 details. Defaults to 0022 for system units. For user units the default value is inherited from the 981 per-user service manager (whose default is in turn inherited from the system service manager, and 982 thus typically also is 0022 — unless overridden by a PAM module). In order to change the per-user mask 983 for all user services, consider setting the <varname>UMask=</varname> setting of the user's 984 <filename>user@.service</filename> system service instance. The per-user umask may also be set via 985 the <varname>umask</varname> field of a user's <ulink url="https://systemd.io/USER_RECORD">JSON User 986 Record</ulink> (for users managed by 987 <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 988 this field may be controlled via <command>homectl --umask=</command>). It may also be set via a PAM 989 module, such as <citerefentry 990 project='man-pages'><refentrytitle>pam_umask</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem> 991 </varlistentry> 992 993 <varlistentry> 994 <term><varname>CoredumpFilter=</varname></term> 995 996 <listitem><para>Controls which types of memory mappings will be saved if the process dumps core 997 (using the <filename>/proc/<replaceable>pid</replaceable>/coredump_filter</filename> file). Takes a 998 whitespace-separated combination of mapping type names or numbers (with the default base 16). Mapping 999 type names are <constant>private-anonymous</constant>, <constant>shared-anonymous</constant>, 1000 <constant>private-file-backed</constant>, <constant>shared-file-backed</constant>, 1001 <constant>elf-headers</constant>, <constant>private-huge</constant>, 1002 <constant>shared-huge</constant>, <constant>private-dax</constant>, <constant>shared-dax</constant>, 1003 and the special values <constant>all</constant> (all types) and <constant>default</constant> (the 1004 kernel default of <literal><constant>private-anonymous</constant> 1005 <constant>shared-anonymous</constant> <constant>elf-headers</constant> 1006 <constant>private-huge</constant></literal>). See 1007 <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> 1008 for the meaning of the mapping types. When specified multiple times, all specified masks are 1009 ORed. When not set, or if the empty value is assigned, the inherited value is not changed.</para> 1010 1011 <example> 1012 <title>Add DAX pages to the dump filter</title> 1013 1014 <programlisting>CoredumpFilter=default private-dax shared-dax</programlisting> 1015 </example> 1016 </listitem> 1017 </varlistentry> 1018 1019 <varlistentry> 1020 <term><varname>KeyringMode=</varname></term> 1021 1022 <listitem><para>Controls how the kernel session keyring is set up for the service (see <citerefentry 1023 project='man-pages'><refentrytitle>session-keyring</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 1024 details on the session keyring). Takes one of <option>inherit</option>, <option>private</option>, 1025 <option>shared</option>. If set to <option>inherit</option> no special keyring setup is done, and the kernel's 1026 default behaviour is applied. If <option>private</option> is used a new session keyring is allocated when a 1027 service process is invoked, and it is not linked up with any user keyring. This is the recommended setting for 1028 system services, as this ensures that multiple services running under the same system user ID (in particular 1029 the root user) do not share their key material among each other. If <option>shared</option> is used a new 1030 session keyring is allocated as for <option>private</option>, but the user keyring of the user configured with 1031 <varname>User=</varname> is linked into it, so that keys assigned to the user may be requested by the unit's 1032 processes. In this modes multiple units running processes under the same user ID may share key material. Unless 1033 <option>inherit</option> is selected the unique invocation ID for the unit (see below) is added as a protected 1034 key by the name <literal>invocation_id</literal> to the newly created session keyring. Defaults to 1035 <option>private</option> for services of the system service manager and to <option>inherit</option> for 1036 non-service units and for services of the user service manager.</para></listitem> 1037 </varlistentry> 1038 1039 <varlistentry> 1040 <term><varname>OOMScoreAdjust=</varname></term> 1041 1042 <listitem><para>Sets the adjustment value for the Linux kernel's Out-Of-Memory (OOM) killer score for 1043 executed processes. Takes an integer between -1000 (to disable OOM killing of processes of this unit) 1044 and 1000 (to make killing of processes of this unit under memory pressure very likely). See <ulink 1045 url="https://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink> for details. If 1046 not specified defaults to the OOM score adjustment level of the service manager itself, which is 1047 normally at 0.</para> 1048 1049 <para>Use the <varname>OOMPolicy=</varname> setting of service units to configure how the service 1050 manager shall react to the kernel OOM killer or <command>systemd-oomd</command> terminating a process of the service. See 1051 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> 1052 for details.</para></listitem> 1053 </varlistentry> 1054 1055 <varlistentry> 1056 <term><varname>TimerSlackNSec=</varname></term> 1057 <listitem><para>Sets the timer slack in nanoseconds for the executed processes. The timer slack controls the 1058 accuracy of wake-ups triggered by timers. See 1059 <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for more 1060 information. Note that in contrast to most other time span definitions this parameter takes an integer value in 1061 nano-seconds if no unit is specified. The usual time units are understood too.</para></listitem> 1062 </varlistentry> 1063 1064 <varlistentry> 1065 <term><varname>Personality=</varname></term> 1066 1067 <listitem><para>Controls which kernel architecture <citerefentry 1068 project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> shall report, 1069 when invoked by unit processes. Takes one of the architecture identifiers <constant>x86</constant>, 1070 <constant>x86-64</constant>, <constant>ppc</constant>, <constant>ppc-le</constant>, <constant>ppc64</constant>, 1071 <constant>ppc64-le</constant>, <constant>s390</constant> or <constant>s390x</constant>. Which personality 1072 architectures are supported depends on the system architecture. Usually the 64bit versions of the various 1073 system architectures support their immediate 32bit personality architecture counterpart, but no others. For 1074 example, <constant>x86-64</constant> systems support the <constant>x86-64</constant> and 1075 <constant>x86</constant> personalities but no others. The personality feature is useful when running 32-bit 1076 services on a 64-bit host system. If not specified, the personality is left unmodified and thus reflects the 1077 personality of the host system's kernel.</para></listitem> 1078 </varlistentry> 1079 1080 <varlistentry> 1081 <term><varname>IgnoreSIGPIPE=</varname></term> 1082 1083 <listitem><para>Takes a boolean argument. If true, causes <constant>SIGPIPE</constant> to be ignored in the 1084 executed process. Defaults to true because <constant>SIGPIPE</constant> generally is useful only in shell 1085 pipelines.</para></listitem> 1086 </varlistentry> 1087 1088 </variablelist> 1089 </refsect1> 1090 1091 <refsect1> 1092 <title>Scheduling</title> 1093 1094 <variablelist class='unit-directives'> 1095 1096 <varlistentry> 1097 <term><varname>Nice=</varname></term> 1098 1099 <listitem><para>Sets the default nice level (scheduling priority) for executed processes. Takes an 1100 integer between -20 (highest priority) and 19 (lowest priority). In case of resource contention, 1101 smaller values mean more resources will be made available to the unit's processes, larger values mean 1102 less resources will be made available. See 1103 <citerefentry><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 1104 details.</para></listitem> 1105 </varlistentry> 1106 1107 <varlistentry> 1108 <term><varname>CPUSchedulingPolicy=</varname></term> 1109 1110 <listitem><para>Sets the CPU scheduling policy for executed processes. Takes one of <option>other</option>, 1111 <option>batch</option>, <option>idle</option>, <option>fifo</option> or <option>rr</option>. See 1112 <citerefentry project='man-pages'><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 1113 details.</para></listitem> 1114 </varlistentry> 1115 1116 <varlistentry> 1117 <term><varname>CPUSchedulingPriority=</varname></term> 1118 1119 <listitem><para>Sets the CPU scheduling priority for executed processes. The available priority range 1120 depends on the selected CPU scheduling policy (see above). For real-time scheduling policies an 1121 integer between 1 (lowest priority) and 99 (highest priority) can be used. In case of CPU resource 1122 contention, smaller values mean less CPU time is made available to the service, larger values mean 1123 more. See <citerefentry 1124 project='man-pages'><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> 1125 for details. </para></listitem> 1126 </varlistentry> 1127 1128 <varlistentry> 1129 <term><varname>CPUSchedulingResetOnFork=</varname></term> 1130 1131 <listitem><para>Takes a boolean argument. If true, elevated CPU scheduling priorities and policies 1132 will be reset when the executed processes call 1133 <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>, 1134 and can hence not leak into child processes. See 1135 <citerefentry project='man-pages'><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> 1136 for details. Defaults to false.</para></listitem> 1137 </varlistentry> 1138 1139 <varlistentry> 1140 <term><varname>CPUAffinity=</varname></term> 1141 1142 <listitem><para>Controls the CPU affinity of the executed processes. Takes a list of CPU indices or ranges 1143 separated by either whitespace or commas. Alternatively, takes a special "numa" value in which case systemd 1144 automatically derives allowed CPU range based on the value of <varname>NUMAMask=</varname> option. CPU ranges 1145 are specified by the lower and upper CPU indices separated by a dash. This option may be specified more than 1146 once, in which case the specified CPU affinity masks are merged. If the empty string is assigned, the mask 1147 is reset, all assignments prior to this will have no effect. See 1148 <citerefentry project='man-pages'><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 1149 details.</para></listitem> 1150 </varlistentry> 1151 1152 <varlistentry> 1153 <term><varname>NUMAPolicy=</varname></term> 1154 1155 <listitem><para>Controls the NUMA memory policy of the executed processes. Takes a policy type, one of: 1156 <option>default</option>, <option>preferred</option>, <option>bind</option>, <option>interleave</option> and 1157 <option>local</option>. A list of NUMA nodes that should be associated with the policy must be specified 1158 in <varname>NUMAMask=</varname>. For more details on each policy please see, 1159 <citerefentry><refentrytitle>set_mempolicy</refentrytitle><manvolnum>2</manvolnum></citerefentry>. For overall 1160 overview of NUMA support in Linux see, 1161 <citerefentry project='man-pages'><refentrytitle>numa</refentrytitle><manvolnum>7</manvolnum></citerefentry>. 1162 </para></listitem> 1163 </varlistentry> 1164 1165 <varlistentry> 1166 <term><varname>NUMAMask=</varname></term> 1167 1168 <listitem><para>Controls the NUMA node list which will be applied alongside with selected NUMA policy. 1169 Takes a list of NUMA nodes and has the same syntax as a list of CPUs for <varname>CPUAffinity=</varname> 1170 option or special "all" value which will include all available NUMA nodes in the mask. Note that the list 1171 of NUMA nodes is not required for <option>default</option> and <option>local</option> 1172 policies and for <option>preferred</option> policy we expect a single NUMA node.</para></listitem> 1173 </varlistentry> 1174 1175 <varlistentry> 1176 <term><varname>IOSchedulingClass=</varname></term> 1177 1178 <listitem><para>Sets the I/O scheduling class for executed processes. Takes one of the strings 1179 <option>realtime</option>, <option>best-effort</option> or <option>idle</option>. The kernel's 1180 default scheduling class is <option>best-effort</option> at a priority of 4. If the empty string is 1181 assigned to this option, all prior assignments to both <varname>IOSchedulingClass=</varname> and 1182 <varname>IOSchedulingPriority=</varname> have no effect. See 1183 <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 1184 details.</para></listitem> 1185 </varlistentry> 1186 1187 <varlistentry> 1188 <term><varname>IOSchedulingPriority=</varname></term> 1189 1190 <listitem><para>Sets the I/O scheduling priority for executed processes. Takes an integer between 0 1191 (highest priority) and 7 (lowest priority). In case of I/O contention, smaller values mean more I/O 1192 bandwidth is made available to the unit's processes, larger values mean less bandwidth. The available 1193 priorities depend on the selected I/O scheduling class (see above). If the empty string is assigned 1194 to this option, all prior assignments to both <varname>IOSchedulingClass=</varname> and 1195 <varname>IOSchedulingPriority=</varname> have no effect. For the kernel's default scheduling class 1196 (<option>best-effort</option>) this defaults to 4. See 1197 <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 1198 details.</para></listitem> 1199 </varlistentry> 1200 1201 </variablelist> 1202 </refsect1> 1203 1204 <refsect1> 1205 <title>Sandboxing</title> 1206 1207 <para>The following sandboxing options are an effective way to limit the exposure of the system towards the unit's 1208 processes. It is recommended to turn on as many of these options for each unit as is possible without negatively 1209 affecting the process' ability to operate. Note that many of these sandboxing features are gracefully turned off on 1210 systems where the underlying security mechanism is not available. For example, <varname>ProtectSystem=</varname> 1211 has no effect if the kernel is built without file system namespacing or if the service manager runs in a container 1212 manager that makes file system namespacing unavailable to its payload. Similar, 1213 <varname>RestrictRealtime=</varname> has no effect on systems that lack support for SECCOMP system call filtering, 1214 or in containers where support for this is turned off.</para> 1215 1216 <para>Also note that some sandboxing functionality is generally not available in user services (i.e. services run 1217 by the per-user service manager). Specifically, the various settings requiring file system namespacing support 1218 (such as <varname>ProtectSystem=</varname>) are not available, as the underlying kernel functionality is only 1219 accessible to privileged processes. However, most namespacing settings, that will not work on their own in user 1220 services, will work when used in conjunction with <varname>PrivateUsers=</varname><option>true</option>.</para> 1221 1222 <variablelist class='unit-directives'> 1223 1224 <varlistentry> 1225 <term><varname>ProtectSystem=</varname></term> 1226 1227 <listitem><para>Takes a boolean argument or the special values <literal>full</literal> or 1228 <literal>strict</literal>. If true, mounts the <filename>/usr/</filename> and the boot loader 1229 directories (<filename>/boot</filename> and <filename>/efi</filename>) read-only for processes 1230 invoked by this unit. If set to <literal>full</literal>, the <filename>/etc/</filename> directory is 1231 mounted read-only, too. If set to <literal>strict</literal> the entire file system hierarchy is 1232 mounted read-only, except for the API file system subtrees <filename>/dev/</filename>, 1233 <filename>/proc/</filename> and <filename>/sys/</filename> (protect these directories using 1234 <varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>, 1235 <varname>ProtectControlGroups=</varname>). This setting ensures that any modification of the vendor-supplied 1236 operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is 1237 recommended to enable this setting for all long-running services, unless they are involved with system updates 1238 or need to modify the operating system in other ways. If this option is used, 1239 <varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. This 1240 setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot ensure protection in all 1241 cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>, see below. Defaults to 1242 off.</para></listitem> 1243 </varlistentry> 1244 1245 <varlistentry> 1246 <term><varname>ProtectHome=</varname></term> 1247 1248 <listitem><para>Takes a boolean argument or the special values <literal>read-only</literal> or 1249 <literal>tmpfs</literal>. If true, the directories <filename>/home/</filename>, 1250 <filename>/root</filename>, and <filename>/run/user</filename> are made inaccessible and empty for 1251 processes invoked by this unit. If set to <literal>read-only</literal>, the three directories are 1252 made read-only instead. If set to <literal>tmpfs</literal>, temporary file systems are mounted on the 1253 three directories in read-only mode. The value <literal>tmpfs</literal> is useful to hide home 1254 directories not relevant to the processes invoked by the unit, while still allowing necessary 1255 directories to be made visible when listed in <varname>BindPaths=</varname> or 1256 <varname>BindReadOnlyPaths=</varname>.</para> 1257 1258 <para>Setting this to <literal>yes</literal> is mostly equivalent to set the three directories in 1259 <varname>InaccessiblePaths=</varname>. Similarly, <literal>read-only</literal> is mostly equivalent to 1260 <varname>ReadOnlyPaths=</varname>, and <literal>tmpfs</literal> is mostly equivalent to 1261 <varname>TemporaryFileSystem=</varname> with <literal>:ro</literal>.</para> 1262 1263 <para>It is recommended to enable this setting for all long-running services (in particular 1264 network-facing ones), to ensure they cannot get access to private user data, unless the services 1265 actually require access to the user's private data. This setting is implied if 1266 <varname>DynamicUser=</varname> is set. This setting cannot ensure protection in all cases. In 1267 general it has the same limitations as <varname>ReadOnlyPaths=</varname>, see below.</para> 1268 1269 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1270 </varlistentry> 1271 1272 <varlistentry> 1273 <term><varname>RuntimeDirectory=</varname></term> 1274 <term><varname>StateDirectory=</varname></term> 1275 <term><varname>CacheDirectory=</varname></term> 1276 <term><varname>LogsDirectory=</varname></term> 1277 <term><varname>ConfigurationDirectory=</varname></term> 1278 1279 <listitem><para>These options take a whitespace-separated list of directory names. The specified 1280 directory names must be relative, and may not include <literal>..</literal>. If set, when the unit is 1281 started, one or more directories by the specified names will be created (including their parents) 1282 below the locations defined in the following table. Also, the corresponding environment variable will 1283 be defined with the full paths of the directories. If multiple directories are set, then in the 1284 environment variable the paths are concatenated with colon (<literal>:</literal>).</para> 1285 <table> 1286 <title>Automatic directory creation and environment variables</title> 1287 <tgroup cols='4'> 1288 <thead> 1289 <row> 1290 <entry>Directory</entry> 1291 <entry>Below path for system units</entry> 1292 <entry>Below path for user units</entry> 1293 <entry>Environment variable set</entry> 1294 </row> 1295 </thead> 1296 <tbody> 1297 <row> 1298 <entry><varname>RuntimeDirectory=</varname></entry> 1299 <entry><filename>/run/</filename></entry> 1300 <entry><varname>$XDG_RUNTIME_DIR</varname></entry> 1301 <entry><varname>$RUNTIME_DIRECTORY</varname></entry> 1302 </row> 1303 <row> 1304 <entry><varname>StateDirectory=</varname></entry> 1305 <entry><filename>/var/lib/</filename></entry> 1306 <entry><varname>$XDG_CONFIG_HOME</varname></entry> 1307 <entry><varname>$STATE_DIRECTORY</varname></entry> 1308 </row> 1309 <row> 1310 <entry><varname>CacheDirectory=</varname></entry> 1311 <entry><filename>/var/cache/</filename></entry> 1312 <entry><varname>$XDG_CACHE_HOME</varname></entry> 1313 <entry><varname>$CACHE_DIRECTORY</varname></entry> 1314 </row> 1315 <row> 1316 <entry><varname>LogsDirectory=</varname></entry> 1317 <entry><filename>/var/log/</filename></entry> 1318 <entry><varname>$XDG_CONFIG_HOME</varname><filename>/log/</filename></entry> 1319 <entry><varname>$LOGS_DIRECTORY</varname></entry> 1320 </row> 1321 <row> 1322 <entry><varname>ConfigurationDirectory=</varname></entry> 1323 <entry><filename>/etc/</filename></entry> 1324 <entry><varname>$XDG_CONFIG_HOME</varname></entry> 1325 <entry><varname>$CONFIGURATION_DIRECTORY</varname></entry> 1326 </row> 1327 </tbody> 1328 </tgroup> 1329 </table> 1330 1331 <para>In case of <varname>RuntimeDirectory=</varname> the innermost subdirectories are removed when 1332 the unit is stopped. It is possible to preserve the specified directories in this case if 1333 <varname>RuntimeDirectoryPreserve=</varname> is configured to <option>restart</option> or 1334 <option>yes</option> (see below). The directories specified with <varname>StateDirectory=</varname>, 1335 <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, 1336 <varname>ConfigurationDirectory=</varname> are not removed when the unit is stopped.</para> 1337 1338 <para>Except in case of <varname>ConfigurationDirectory=</varname>, the innermost specified directories will be 1339 owned by the user and group specified in <varname>User=</varname> and <varname>Group=</varname>. If the 1340 specified directories already exist and their owning user or group do not match the configured ones, all files 1341 and directories below the specified directories as well as the directories themselves will have their file 1342 ownership recursively changed to match what is configured. As an optimization, if the specified directories are 1343 already owned by the right user and group, files and directories below of them are left as-is, even if they do 1344 not match what is requested. The innermost specified directories will have their access mode adjusted to the 1345 what is specified in <varname>RuntimeDirectoryMode=</varname>, <varname>StateDirectoryMode=</varname>, 1346 <varname>CacheDirectoryMode=</varname>, <varname>LogsDirectoryMode=</varname> and 1347 <varname>ConfigurationDirectoryMode=</varname>.</para> 1348 1349 <para>These options imply <varname>BindPaths=</varname> for the specified paths. When combined with 1350 <varname>RootDirectory=</varname> or <varname>RootImage=</varname> these paths always reside on the host and 1351 are mounted from there into the unit's file system namespace.</para> 1352 1353 <para>If <varname>DynamicUser=</varname> is used, the logic for <varname>CacheDirectory=</varname>, 1354 <varname>LogsDirectory=</varname> and <varname>StateDirectory=</varname> is slightly altered: the directories are created below 1355 <filename>/var/cache/private</filename>, <filename>/var/log/private</filename> and <filename>/var/lib/private</filename>, 1356 respectively, which are host directories made inaccessible to 1357 unprivileged users, which ensures that access to these directories cannot be gained through dynamic 1358 user ID recycling. Symbolic links are created to hide this difference in behaviour. Both from 1359 perspective of the host and from inside the unit, the relevant directories hence always appear 1360 directly below <filename>/var/cache</filename>, <filename>/var/log</filename> and 1361 <filename>/var/lib</filename>.</para> 1362 1363 <para>Use <varname>RuntimeDirectory=</varname> to manage one or more runtime directories for the unit and bind 1364 their lifetime to the daemon runtime. This is particularly useful for unprivileged daemons that cannot create 1365 runtime directories in <filename>/run/</filename> due to lack of privileges, and to make sure the runtime 1366 directory is cleaned up automatically after use. For runtime directories that require more complex or different 1367 configuration or lifetime guarantees, please consider using 1368 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> 1369 1370 <para><varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>, <varname>CacheDirectory=</varname> 1371 and <varname>LogsDirectory=</varname> optionally support a second parameter, separated by <literal>:</literal>. 1372 The second parameter will be interpreted as a destination path that will be created as a symlink to the directory. 1373 The symlinks will be created after any <varname>BindPaths=</varname> or <varname>TemporaryFileSystem=</varname> 1374 options have been set up, to make ephemeral symlinking possible. The same source can have multiple symlinks, by 1375 using the same first parameter, but a different second parameter.</para></listitem> 1376 1377 <para>The directories defined by these options are always created under the standard paths used by systemd 1378 (<filename>/var/</filename>, <filename>/run/</filename>, <filename>/etc/</filename>, …). If the service needs 1379 directories in a different location, a different mechanism has to be used to create them.</para> 1380 1381 <para><citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> provides 1382 functionality that overlaps with these options. Using these options is recommended, because the lifetime of 1383 the directories is tied directly to the lifetime of the unit, and it is not necessary to ensure that the 1384 <filename>tmpfiles.d</filename> configuration is executed before the unit is started.</para> 1385 1386 <para>To remove any of the directories created by these settings, use the <command>systemctl clean 1387 …</command> command on the relevant units, see 1388 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for 1389 details.</para> 1390 1391 <para>Example: if a system service unit has the following, 1392 <programlisting>RuntimeDirectory=foo/bar baz</programlisting> 1393 the service manager creates <filename index='false'>/run/foo</filename> (if it does not exist), 1394 1395 <filename index='false'>/run/foo/bar</filename>, and <filename index='false'>/run/baz</filename>. The 1396 directories <filename index='false'>/run/foo/bar</filename> and 1397 <filename index='false'>/run/baz</filename> except <filename index='false'>/run/foo</filename> are 1398 owned by the user and group specified in <varname>User=</varname> and <varname>Group=</varname>, and removed 1399 when the service is stopped.</para> 1400 1401 <para>Example: if a system service unit has the following, 1402 <programlisting>RuntimeDirectory=foo/bar 1403StateDirectory=aaa/bbb ccc</programlisting> 1404 then the environment variable <literal>RUNTIME_DIRECTORY</literal> is set with <literal>/run/foo/bar</literal>, and 1405 <literal>STATE_DIRECTORY</literal> is set with <literal>/var/lib/aaa/bbb:/var/lib/ccc</literal>.</para> 1406 1407 <para>Example: if a system service unit has the following, 1408 <programlisting>RuntimeDirectory=foo:bar foo:baz</programlisting> 1409 the service manager creates <filename index='false'>/run/foo</filename> (if it does not exist), and 1410 <filename index='false'>/run/bar</filename> plus <filename index='false'>/run/baz</filename> as symlinks to 1411 <filename index='false'>/run/foo</filename>.</para> 1412 </varlistentry> 1413 1414 <varlistentry> 1415 <term><varname>RuntimeDirectoryMode=</varname></term> 1416 <term><varname>StateDirectoryMode=</varname></term> 1417 <term><varname>CacheDirectoryMode=</varname></term> 1418 <term><varname>LogsDirectoryMode=</varname></term> 1419 <term><varname>ConfigurationDirectoryMode=</varname></term> 1420 1421 <listitem><para>Specifies the access mode of the directories specified in <varname>RuntimeDirectory=</varname>, 1422 <varname>StateDirectory=</varname>, <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, or 1423 <varname>ConfigurationDirectory=</varname>, respectively, as an octal number. Defaults to 1424 <constant>0755</constant>. See "Permissions" in <citerefentry 1425 project='man-pages'><refentrytitle>path_resolution</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a 1426 discussion of the meaning of permission bits.</para></listitem> 1427 </varlistentry> 1428 1429 <varlistentry> 1430 <term><varname>RuntimeDirectoryPreserve=</varname></term> 1431 1432 <listitem><para>Takes a boolean argument or <option>restart</option>. If set to <option>no</option> (the 1433 default), the directories specified in <varname>RuntimeDirectory=</varname> are always removed when the service 1434 stops. If set to <option>restart</option> the directories are preserved when the service is both automatically 1435 and manually restarted. Here, the automatic restart means the operation specified in 1436 <varname>Restart=</varname>, and manual restart means the one triggered by <command>systemctl restart 1437 foo.service</command>. If set to <option>yes</option>, then the directories are not removed when the service is 1438 stopped. Note that since the runtime directory <filename>/run/</filename> is a mount point of 1439 <literal>tmpfs</literal>, then for system services the directories specified in 1440 <varname>RuntimeDirectory=</varname> are removed when the system is rebooted.</para></listitem> 1441 </varlistentry> 1442 1443 <varlistentry> 1444 <term><varname>TimeoutCleanSec=</varname></term> 1445 <listitem><para>Configures a timeout on the clean-up operation requested through <command>systemctl 1446 clean …</command>, see 1447 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for 1448 details. Takes the usual time values and defaults to <constant>infinity</constant>, i.e. by default 1449 no timeout is applied. If a timeout is configured the clean operation will be aborted forcibly when 1450 the timeout is reached, potentially leaving resources on disk.</para></listitem> 1451 </varlistentry> 1452 1453 <varlistentry> 1454 <term><varname>ReadWritePaths=</varname></term> 1455 <term><varname>ReadOnlyPaths=</varname></term> 1456 <term><varname>InaccessiblePaths=</varname></term> 1457 <term><varname>ExecPaths=</varname></term> 1458 <term><varname>NoExecPaths=</varname></term> 1459 1460 <listitem><para>Sets up a new file system namespace for executed processes. These options may be used 1461 to limit access a process has to the file system. Each setting takes a space-separated list of paths 1462 relative to the host's root directory (i.e. the system running the service manager). Note that if 1463 paths contain symlinks, they are resolved relative to the root directory set with 1464 <varname>RootDirectory=</varname>/<varname>RootImage=</varname>.</para> 1465 1466 <para>Paths listed in <varname>ReadWritePaths=</varname> are accessible from within the namespace 1467 with the same access modes as from outside of it. Paths listed in <varname>ReadOnlyPaths=</varname> 1468 are accessible for reading only, writing will be refused even if the usual file access controls would 1469 permit this. Nest <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in 1470 order to provide writable subdirectories within read-only directories. Use 1471 <varname>ReadWritePaths=</varname> in order to allow-list specific paths for write access if 1472 <varname>ProtectSystem=strict</varname> is used.</para> 1473 1474 <para>Paths listed in <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside 1475 the namespace along with everything below them in the file system hierarchy. This may be more restrictive than 1476 desired, because it is not possible to nest <varname>ReadWritePaths=</varname>, <varname>ReadOnlyPaths=</varname>, 1477 <varname>BindPaths=</varname>, or <varname>BindReadOnlyPaths=</varname> inside it. For a more flexible option, 1478 see <varname>TemporaryFileSystem=</varname>.</para> 1479 1480 <para>Content in paths listed in <varname>NoExecPaths=</varname> are not executable even if the usual 1481 file access controls would permit this. Nest <varname>ExecPaths=</varname> inside of 1482 <varname>NoExecPaths=</varname> in order to provide executable content within non-executable 1483 directories.</para> 1484 1485 <para>Non-directory paths may be specified as well. These options may be specified more than once, 1486 in which case all paths listed will have limited access from within the namespace. If the empty string is 1487 assigned to this option, the specific list is reset, and all prior assignments have no effect.</para> 1488 1489 <para>Paths in <varname>ReadWritePaths=</varname>, <varname>ReadOnlyPaths=</varname>, 1490 <varname>InaccessiblePaths=</varname>, <varname>ExecPaths=</varname> and 1491 <varname>NoExecPaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be 1492 ignored when they do not exist. If prefixed with <literal>+</literal> the paths are taken relative to the root 1493 directory of the unit, as configured with <varname>RootDirectory=</varname>/<varname>RootImage=</varname>, 1494 instead of relative to the root directory of the host (see above). When combining <literal>-</literal> and 1495 <literal>+</literal> on the same path make sure to specify <literal>-</literal> first, and <literal>+</literal> 1496 second.</para> 1497 1498 <para>Note that these settings will disconnect propagation of mounts from the unit's processes to the 1499 host. This means that this setting may not be used for services which shall be able to install mount points in 1500 the main mount namespace. For <varname>ReadWritePaths=</varname> and <varname>ReadOnlyPaths=</varname> 1501 propagation in the other direction is not affected, i.e. mounts created on the host generally appear in the 1502 unit processes' namespace, and mounts removed on the host also disappear there too. In particular, note that 1503 mount propagation from host to unit will result in unmodified mounts to be created in the unit's namespace, 1504 i.e. writable mounts appearing on the host will be writable in the unit's namespace too, even when propagated 1505 below a path marked with <varname>ReadOnlyPaths=</varname>! Restricting access with these options hence does 1506 not extend to submounts of a directory that are created later on. This means the lock-down offered by that 1507 setting is not complete, and does not offer full protection. </para> 1508 1509 <para>Note that the effect of these settings may be undone by privileged processes. In order to set up an 1510 effective sandboxed environment for a unit it is thus recommended to combine these settings with either 1511 <varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or 1512 <varname>SystemCallFilter=~@mount</varname>.</para> 1513 1514 <para>Simple allow-list example using these directives: 1515 <programlisting>[Service] 1516ReadOnlyPaths=/ 1517ReadWritePaths=/var /run 1518InaccessiblePaths=-/lost+found 1519NoExecPaths=/ 1520ExecPaths=/usr/sbin/my_daemon /usr/lib /usr/lib64 1521</programlisting></para> 1522 1523 <xi:include href="system-or-user-ns.xml" xpointer="plural"/></listitem> 1524 </varlistentry> 1525 1526 <varlistentry> 1527 <term><varname>TemporaryFileSystem=</varname></term> 1528 1529 <listitem><para>Takes a space-separated list of mount points for temporary file systems (tmpfs). If set, a new file 1530 system namespace is set up for executed processes, and a temporary file system is mounted on each mount point. 1531 This option may be specified more than once, in which case temporary file systems are mounted on all listed mount 1532 points. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. 1533 Each mount point may optionally be suffixed with a colon (<literal>:</literal>) and mount options such as 1534 <literal>size=10%</literal> or <literal>ro</literal>. By default, each temporary file system is mounted 1535 with <literal>nodev,strictatime,mode=0755</literal>. These can be disabled by explicitly specifying the corresponding 1536 mount options, e.g., <literal>dev</literal> or <literal>nostrictatime</literal>.</para> 1537 1538 <para>This is useful to hide files or directories not relevant to the processes invoked by the unit, while necessary 1539 files or directories can be still accessed by combining with <varname>BindPaths=</varname> or 1540 <varname>BindReadOnlyPaths=</varname>:</para> 1541 1542 <para>Example: if a unit has the following, 1543 <programlisting>TemporaryFileSystem=/var:ro 1544BindReadOnlyPaths=/var/lib/systemd</programlisting> 1545 then the invoked processes by the unit cannot see any files or directories under <filename>/var/</filename> except for 1546 <filename>/var/lib/systemd</filename> or its contents.</para> 1547 1548 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1549 </varlistentry> 1550 1551 <varlistentry> 1552 <term><varname>PrivateTmp=</varname></term> 1553 1554 <listitem><para>Takes a boolean argument. If true, sets up a new file system namespace for the 1555 executed processes and mounts private <filename>/tmp/</filename> and <filename>/var/tmp/</filename> 1556 directories inside it that are not shared by processes outside of the namespace. This is useful to 1557 secure access to temporary files of the process, but makes sharing between processes via 1558 <filename>/tmp/</filename> or <filename>/var/tmp/</filename> impossible. If true, all temporary files 1559 created by a service in these directories will be removed after the service is stopped. Defaults to 1560 false. It is possible to run two or more units within the same private <filename>/tmp/</filename> and 1561 <filename>/var/tmp/</filename> namespace by using the <varname>JoinsNamespaceOf=</varname> directive, 1562 see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> 1563 for details. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting the 1564 same restrictions regarding mount propagation and privileges apply as for 1565 <varname>ReadOnlyPaths=</varname> and related calls, see above. Enabling this setting has the side 1566 effect of adding <varname>Requires=</varname> and <varname>After=</varname> dependencies on all mount 1567 units necessary to access <filename>/tmp/</filename> and <filename>/var/tmp/</filename>. Moreover an 1568 implicitly <varname>After=</varname> ordering on 1569 <citerefentry><refentrytitle>systemd-tmpfiles-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 1570 is added.</para> 1571 1572 <para>Note that the implementation of this setting might be impossible (for example if mount namespaces are not 1573 available), and the unit should be written in a way that does not solely rely on this setting for 1574 security.</para> 1575 1576 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1577 </varlistentry> 1578 1579 <varlistentry> 1580 <term><varname>PrivateDevices=</varname></term> 1581 1582 <listitem><para>Takes a boolean argument. If true, sets up a new <filename>/dev/</filename> mount for 1583 the executed processes and only adds API pseudo devices such as <filename>/dev/null</filename>, 1584 <filename>/dev/zero</filename> or <filename>/dev/random</filename> (as well as the pseudo TTY 1585 subsystem) to it, but no physical devices such as <filename>/dev/sda</filename>, system memory 1586 <filename>/dev/mem</filename>, system ports <filename>/dev/port</filename> and others. This is useful 1587 to turn off physical device access by the executed process. Defaults to false.</para> 1588 1589 <para>Enabling this option will install a system call filter to block low-level I/O system calls that 1590 are grouped in the <varname>@raw-io</varname> set, remove <constant>CAP_MKNOD</constant> and 1591 <constant>CAP_SYS_RAWIO</constant> from the capability bounding set for the unit, and set 1592 <varname>DevicePolicy=closed</varname> (see 1593 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> 1594 for details). Note that using this setting will disconnect propagation of mounts from the service to 1595 the host (propagation in the opposite direction continues to work). This means that this setting may 1596 not be used for services which shall be able to install mount points in the main mount namespace. The 1597 new <filename>/dev/</filename> will be mounted read-only and 'noexec'. The latter may break old 1598 programs which try to set up executable memory by using 1599 <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> of 1600 <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. For this setting the 1601 same restrictions regarding mount propagation and privileges apply as for 1602 <varname>ReadOnlyPaths=</varname> and related calls, see above. If turned on and if running in user 1603 mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting 1604 <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.</para> 1605 1606 <para>Note that the implementation of this setting might be impossible (for example if mount 1607 namespaces are not available), and the unit should be written in a way that does not solely rely on 1608 this setting for security.</para> 1609 1610 <xi:include href="system-or-user-ns.xml" xpointer="singular"/> 1611 1612 <para>When access to some but not all devices must be possible, the <varname>DeviceAllow=</varname> 1613 setting might be used instead. See 1614 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 1615 </para></listitem> 1616 </varlistentry> 1617 1618 <varlistentry> 1619 <term><varname>PrivateNetwork=</varname></term> 1620 1621 <listitem><para>Takes a boolean argument. If true, sets up a new network namespace for the executed processes 1622 and configures only the loopback network device <literal>lo</literal> inside it. No other network devices will 1623 be available to the executed process. This is useful to turn off network access by the executed process. 1624 Defaults to false. It is possible to run two or more units within the same private network namespace by using 1625 the <varname>JoinsNamespaceOf=</varname> directive, see 1626 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 1627 details. Note that this option will disconnect all socket families from the host, including 1628 <constant>AF_NETLINK</constant> and <constant>AF_UNIX</constant>. Effectively, for 1629 <constant>AF_NETLINK</constant> this means that device configuration events received from 1630 <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> are 1631 not delivered to the unit's processes. And for <constant>AF_UNIX</constant> this has the effect that 1632 <constant>AF_UNIX</constant> sockets in the abstract socket namespace of the host will become unavailable to 1633 the unit's processes (however, those located in the file system will continue to be accessible).</para> 1634 1635 <para>Note that the implementation of this setting might be impossible (for example if network namespaces are 1636 not available), and the unit should be written in a way that does not solely rely on this setting for 1637 security.</para> 1638 1639 <para>When this option is used on a socket unit any sockets bound on behalf of this unit will be 1640 bound within a private network namespace. This may be combined with 1641 <varname>JoinsNamespaceOf=</varname> to listen on sockets inside of network namespaces of other 1642 services.</para> 1643 1644 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1645 </varlistentry> 1646 1647 <varlistentry> 1648 <term><varname>NetworkNamespacePath=</varname></term> 1649 1650 <listitem><para>Takes an absolute file system path refererring to a Linux network namespace 1651 pseudo-file (i.e. a file like <filename>/proc/$PID/ns/net</filename> or a bind mount or symlink to 1652 one). When set the invoked processes are added to the network namespace referenced by that path. The 1653 path has to point to a valid namespace file at the moment the processes are forked off. If this 1654 option is used <varname>PrivateNetwork=</varname> has no effect. If this option is used together with 1655 <varname>JoinsNamespaceOf=</varname> then it only has an effect if this unit is started before any of 1656 the listed units that have <varname>PrivateNetwork=</varname> or 1657 <varname>NetworkNamespacePath=</varname> configured, as otherwise the network namespace of those 1658 units is reused.</para> 1659 1660 <para>When this option is used on a socket unit any sockets bound on behalf of this unit will be 1661 bound within the specified network namespace.</para> 1662 1663 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1664 </varlistentry> 1665 1666 <varlistentry> 1667 <term><varname>PrivateIPC=</varname></term> 1668 1669 <listitem><para>Takes a boolean argument. If true, sets up a new IPC namespace for the executed processes. 1670 Each IPC namespace has its own set of System V IPC identifiers and its own POSIX message queue file system. 1671 This is useful to avoid name clash of IPC identifiers. Defaults to false. It is possible to run two or 1672 more units within the same private IPC namespace by using the <varname>JoinsNamespaceOf=</varname> directive, 1673 see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 1674 details.</para> 1675 1676 <para>Note that IPC namespacing does not have an effect on 1677 <constant>AF_UNIX</constant> sockets, which are the most common 1678 form of IPC used on Linux. Instead, <constant>AF_UNIX</constant> 1679 sockets in the file system are subject to mount namespacing, and 1680 those in the abstract namespace are subject to network namespacing. 1681 IPC namespacing only has an effect on SysV IPC (which is mostly 1682 legacy) as well as POSIX message queues (for which 1683 <constant>AF_UNIX</constant>/<constant>SOCK_SEQPACKET</constant> 1684 sockets are typically a better replacement). IPC namespacing also 1685 has no effect on POSIX shared memory (which is subject to mount 1686 namespacing) either. See 1687 <citerefentry project='man-pages'><refentrytitle>ipc_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 1688 the details.</para> 1689 1690 <para>Note that the implementation of this setting might be impossible (for example if IPC namespaces are 1691 not available), and the unit should be written in a way that does not solely rely on this setting for 1692 security.</para> 1693 1694 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1695 </varlistentry> 1696 1697 <varlistentry> 1698 <term><varname>IPCNamespacePath=</varname></term> 1699 1700 <listitem><para>Takes an absolute file system path refererring to a Linux IPC namespace 1701 pseudo-file (i.e. a file like <filename>/proc/$PID/ns/ipc</filename> or a bind mount or symlink to 1702 one). When set the invoked processes are added to the network namespace referenced by that path. The 1703 path has to point to a valid namespace file at the moment the processes are forked off. If this 1704 option is used <varname>PrivateIPC=</varname> has no effect. If this option is used together with 1705 <varname>JoinsNamespaceOf=</varname> then it only has an effect if this unit is started before any of 1706 the listed units that have <varname>PrivateIPC=</varname> or 1707 <varname>IPCNamespacePath=</varname> configured, as otherwise the network namespace of those 1708 units is reused.</para> 1709 1710 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1711 </varlistentry> 1712 1713 <varlistentry> 1714 <term><varname>PrivateUsers=</varname></term> 1715 1716 <listitem><para>Takes a boolean argument. If true, sets up a new user namespace for the executed processes and 1717 configures a minimal user and group mapping, that maps the <literal>root</literal> user and group as well as 1718 the unit's own user and group to themselves and everything else to the <literal>nobody</literal> user and 1719 group. This is useful to securely detach the user and group databases used by the unit from the rest of the 1720 system, and thus to create an effective sandbox environment. All files, directories, processes, IPC objects and 1721 other resources owned by users/groups not equaling <literal>root</literal> or the unit's own will stay visible 1722 from within the unit but appear owned by the <literal>nobody</literal> user and group. If this mode is enabled, 1723 all unit processes are run without privileges in the host user namespace (regardless if the unit's own 1724 user/group is <literal>root</literal> or not). Specifically this means that the process will have zero process 1725 capabilities on the host's user namespace, but full capabilities within the service's user namespace. Settings 1726 such as <varname>CapabilityBoundingSet=</varname> will affect only the latter, and there's no way to acquire 1727 additional capabilities in the host's user namespace. Defaults to off.</para> 1728 1729 <para>When this setting is set up by a per-user instance of the service manager, the mapping of the 1730 <literal>root</literal> user and group to itself is omitted (unless the user manager is root). 1731 Additionally, in the per-user instance manager case, the 1732 user namespace will be set up before most other namespaces. This means that combining 1733 <varname>PrivateUsers=</varname><option>true</option> with other namespaces will enable use of features not 1734 normally supported by the per-user instances of the service manager.</para> 1735 1736 <para>This setting is particularly useful in conjunction with 1737 <varname>RootDirectory=</varname>/<varname>RootImage=</varname>, as the need to synchronize the user and group 1738 databases in the root directory and on the host is reduced, as the only users and groups who need to be matched 1739 are <literal>root</literal>, <literal>nobody</literal> and the unit's own user and group.</para> 1740 1741 <para>Note that the implementation of this setting might be impossible (for example if user namespaces are not 1742 available), and the unit should be written in a way that does not solely rely on this setting for 1743 security.</para></listitem> 1744 </varlistentry> 1745 1746 <varlistentry> 1747 <term><varname>ProtectHostname=</varname></term> 1748 1749 <listitem><para>Takes a boolean argument. When set, sets up a new UTS namespace for the executed 1750 processes. In addition, changing hostname or domainname is prevented. Defaults to off.</para> 1751 1752 <para>Note that the implementation of this setting might be impossible (for example if UTS namespaces 1753 are not available), and the unit should be written in a way that does not solely rely on this setting 1754 for security.</para> 1755 1756 <para>Note that when this option is enabled for a service hostname changes no longer propagate from 1757 the system into the service, it is hence not suitable for services that need to take notice of system 1758 hostname changes dynamically.</para> 1759 1760 <para>If this setting is on, but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant> 1761 capability (e.g. services for which <varname>User=</varname> is set), 1762 <varname>NoNewPrivileges=yes</varname> is implied.</para> 1763 1764 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1765 </varlistentry> 1766 1767 <varlistentry> 1768 <term><varname>ProtectClock=</varname></term> 1769 1770 <listitem><para>Takes a boolean argument. If set, writes to the hardware clock or system clock will be denied. 1771 It is recommended to turn this on for most services that do not need modify the clock. Defaults to off. Enabling 1772 this option removes <constant>CAP_SYS_TIME</constant> and <constant>CAP_WAKE_ALARM</constant> from the 1773 capability bounding set for this unit, installs a system call filter to block calls that can set the 1774 clock, and <varname>DeviceAllow=char-rtc r</varname> is implied. This ensures <filename>/dev/rtc0</filename>, 1775 <filename>/dev/rtc1</filename>, etc. are made read-only to the service. See 1776 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> 1777 for the details about <varname>DeviceAllow=</varname>. If this setting is on, but the unit 1778 doesn't have the <constant>CAP_SYS_ADMIN</constant> capability (e.g. services for which 1779 <varname>User=</varname> is set), <varname>NoNewPrivileges=yes</varname> is implied.</para> 1780 1781 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1782 </varlistentry> 1783 1784 <varlistentry> 1785 <term><varname>ProtectKernelTunables=</varname></term> 1786 1787 <listitem><para>Takes a boolean argument. If true, kernel variables accessible through 1788 <filename>/proc/sys/</filename>, <filename>/sys/</filename>, <filename>/proc/sysrq-trigger</filename>, 1789 <filename>/proc/latency_stats</filename>, <filename>/proc/acpi</filename>, 1790 <filename>/proc/timer_stats</filename>, <filename>/proc/fs</filename> and <filename>/proc/irq</filename> will 1791 be made read-only to all processes of the unit. Usually, tunable kernel variables should be initialized only at 1792 boot-time, for example with the 1793 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> mechanism. Few 1794 services need to write to these at runtime; it is hence recommended to turn this on for most services. For this 1795 setting the same restrictions regarding mount propagation and privileges apply as for 1796 <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off. If this 1797 setting is on, but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant> capability 1798 (e.g. services for which <varname>User=</varname> is set), 1799 <varname>NoNewPrivileges=yes</varname> is implied. Note that this option does not prevent 1800 indirect changes to kernel tunables effected by IPC calls to other processes. However, 1801 <varname>InaccessiblePaths=</varname> may be used to make relevant IPC file system objects 1802 inaccessible. If <varname>ProtectKernelTunables=</varname> is set, 1803 <varname>MountAPIVFS=yes</varname> is implied.</para> 1804 1805 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1806 </varlistentry> 1807 1808 <varlistentry> 1809 <term><varname>ProtectKernelModules=</varname></term> 1810 1811 <listitem><para>Takes a boolean argument. If true, explicit module loading will be denied. This allows 1812 module load and unload operations to be turned off on modular kernels. It is recommended to turn this on for most services 1813 that do not need special file systems or extra kernel modules to work. Defaults to off. Enabling this option 1814 removes <constant>CAP_SYS_MODULE</constant> from the capability bounding set for the unit, and installs a 1815 system call filter to block module system calls, also <filename>/usr/lib/modules</filename> is made 1816 inaccessible. For this setting the same restrictions regarding mount propagation and privileges apply as for 1817 <varname>ReadOnlyPaths=</varname> and related calls, see above. Note that limited automatic module loading due 1818 to user configuration or kernel mapping tables might still happen as side effect of requested user operations, 1819 both privileged and unprivileged. To disable module auto-load feature please see 1820 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> 1821 <constant>kernel.modules_disabled</constant> mechanism and 1822 <filename>/proc/sys/kernel/modules_disabled</filename> documentation. If this setting is on, 1823 but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant> capability (e.g. services for 1824 which <varname>User=</varname> is set), <varname>NoNewPrivileges=yes</varname> is implied.</para> 1825 1826 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1827 </varlistentry> 1828 1829 <varlistentry> 1830 <term><varname>ProtectKernelLogs=</varname></term> 1831 1832 <listitem><para>Takes a boolean argument. If true, access to the kernel log ring buffer will be denied. It is 1833 recommended to turn this on for most services that do not need to read from or write to the kernel log ring 1834 buffer. Enabling this option removes <constant>CAP_SYSLOG</constant> from the capability bounding set for this 1835 unit, and installs a system call filter to block the 1836 <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> 1837 system call (not to be confused with the libc API 1838 <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> 1839 for userspace logging). The kernel exposes its log buffer to userspace via <filename>/dev/kmsg</filename> and 1840 <filename>/proc/kmsg</filename>. If enabled, these are made inaccessible to all the processes in the unit. 1841 If this setting is on, but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant> 1842 capability (e.g. services for which <varname>User=</varname> is set), 1843 <varname>NoNewPrivileges=yes</varname> is implied.</para> 1844 1845 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 1846 </varlistentry> 1847 1848 <varlistentry> 1849 <term><varname>ProtectControlGroups=</varname></term> 1850 1851 <listitem><para>Takes a boolean argument. If true, the Linux Control Groups (<citerefentry 1852 project='man-pages'><refentrytitle>cgroups</refentrytitle><manvolnum>7</manvolnum></citerefentry>) hierarchies 1853 accessible through <filename>/sys/fs/cgroup/</filename> will be made read-only to all processes of the 1854 unit. Except for container managers no services should require write access to the control groups hierarchies; 1855 it is hence recommended to turn this on for most services. For this setting the same restrictions regarding 1856 mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see 1857 above. Defaults to off. If <varname>ProtectControlGroups=</varname> is set, <varname>MountAPIVFS=yes</varname> 1858 is implied.</para> 1859 1860 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 1861 </varlistentry> 1862 1863 <varlistentry> 1864 <term><varname>RestrictAddressFamilies=</varname></term> 1865 1866 <listitem><para>Restricts the set of socket address families accessible to the processes of this 1867 unit. Takes <literal>none</literal>, or a space-separated list of address family names to 1868 allow-list, such as <constant>AF_UNIX</constant>, <constant>AF_INET</constant> or 1869 <constant>AF_INET6</constant>. When <literal>none</literal> is specified, then all address 1870 families will be denied. When prefixed with <literal>~</literal> the listed address 1871 families will be applied as deny list, otherwise as allow list. Note that this restricts access 1872 to the 1873 <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> 1874 system call only. Sockets passed into the process by other means (for example, by using socket 1875 activation with socket units, see 1876 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>) 1877 are unaffected. Also, sockets created with <function>socketpair()</function> (which creates connected 1878 AF_UNIX sockets only) are unaffected. Note that this option has no effect on 32-bit x86, s390, s390x, 1879 mips, mips-le, ppc, ppc-le, ppc64, ppc64-le and is ignored (but works correctly on other ABIs, 1880 including x86-64). Note that on systems supporting multiple ABIs (such as x86/x86-64) it is 1881 recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the 1882 restrictions of this option. Specifically, it is recommended to combine this option with 1883 <varname>SystemCallArchitectures=native</varname> or similar. If running in user mode, or in system 1884 mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting 1885 <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied. By default, no 1886 restrictions apply, all address families are accessible to processes. If assigned the empty string, 1887 any previous address family restriction changes are undone. This setting does not affect commands 1888 prefixed with <literal>+</literal>.</para> 1889 1890 <para>Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive 1891 network protocols, such as <constant>AF_PACKET</constant>. Note that in most cases, the local 1892 <constant>AF_UNIX</constant> address family should be included in the configured allow list as it is frequently 1893 used for local communication, including for 1894 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> 1895 logging.</para></listitem> 1896 </varlistentry> 1897 1898 <varlistentry> 1899 <term><varname>RestrictFileSystems=</varname></term> 1900 1901 <listitem><para>Restricts the set of filesystems processes of this unit can open files on. Takes a space-separated 1902 list of filesystem names. Any filesystem listed is made accessible to the unit's processes, access to filesystem 1903 types not listed is prohibited (allow-listing). If the first character of the list is <literal>~</literal>, the 1904 effect is inverted: access to the filesystems listed is prohibited (deny-listing). If the empty string is assigned, 1905 access to filesystems is not restricted.</para> 1906 1907 <para>If you specify both types of this option (i.e. allow-listing and deny-listing), the first encountered will take 1908 precedence and will dictate the default action (allow access to the filesystem or deny it). Then the next occurrences 1909 of this option will add or delete the listed filesystems from the set of the restricted filesystems, depending on its 1910 type and the default action.</para> 1911 1912 <para>Example: if a unit has the following, 1913 <programlisting>RestrictFileSystems=ext4 tmpfs 1914RestrictFileSystems=ext2 ext4</programlisting> 1915 then access to <constant>ext4</constant>, <constant>tmpfs</constant>, and <constant>ext2</constant> is allowed 1916 and access to other filesystems is denied.</para> 1917 1918 <para>Example: if a unit has the following, 1919 <programlisting>RestrictFileSystems=ext4 tmpfs 1920RestrictFileSystems=~ext4</programlisting> 1921 then only access <constant>tmpfs</constant> is allowed.</para> 1922 1923 <para>Example: if a unit has the following, 1924 <programlisting>RestrictFileSystems=~ext4 tmpfs 1925RestrictFileSystems=ext4</programlisting> 1926 then only access to <constant>tmpfs</constant> is denied.</para> 1927 1928 <para>As the number of possible filesystems is large, predefined sets of filesystems are provided. A set 1929 starts with <literal>@</literal> character, followed by name of the set.</para> 1930 1931 <table> 1932 <title>Currently predefined filesystem sets</title> 1933 1934 <tgroup cols='2'> 1935 <colspec colname='set' /> 1936 <colspec colname='description' /> 1937 <thead> 1938 <row> 1939 <entry>Set</entry> 1940 <entry>Description</entry> 1941 </row> 1942 </thead> 1943 <tbody> 1944 <row> 1945 <entry>@basic-api</entry> 1946 <entry>Basic filesystem API.</entry> 1947 </row> 1948 <row> 1949 <entry>@auxiliary-api</entry> 1950 <entry>Auxiliary filesystem API.</entry> 1951 </row> 1952 <row> 1953 <entry>@common-block</entry> 1954 <entry>Common block device filesystems.</entry> 1955 </row> 1956 <row> 1957 <entry>@historical-block</entry> 1958 <entry>Historical block device filesystems.</entry> 1959 </row> 1960 <row> 1961 <entry>@network</entry> 1962 <entry>Well-known network filesystems.</entry> 1963 </row> 1964 <row> 1965 <entry>@privileged-api</entry> 1966 <entry>Privileged filesystem API.</entry> 1967 </row> 1968 <row> 1969 <entry>@temporary</entry> 1970 <entry>Temporary filesystems: tmpfs, ramfs.</entry> 1971 </row> 1972 <row> 1973 <entry>@known</entry> 1974 <entry>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.</entry> 1975 </row> 1976 </tbody> 1977 </tgroup> 1978 </table> 1979 1980 <para>Use 1981 <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s 1982 <command>filesystems</command> command to retrieve a list of filesystems defined on the local 1983 system.</para> 1984 1985 <para>Note that this setting might not be supported on some systems (for example if the LSM eBPF hook is 1986 not enabled in the underlying kernel or if not using the unified control group hierarchy). In that case this setting 1987 has no effect.</para></listitem> 1988 </varlistentry> 1989 1990 <varlistentry> 1991 <term><varname>RestrictNamespaces=</varname></term> 1992 1993 <listitem><para>Restricts access to Linux namespace functionality for the processes of this unit. For details 1994 about Linux namespaces, see <citerefentry 1995 project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Either 1996 takes a boolean argument, or a space-separated list of namespace type identifiers. If false (the default), no 1997 restrictions on namespace creation and switching are made. If true, access to any kind of namespacing is 1998 prohibited. Otherwise, a space-separated list of namespace type identifiers must be specified, consisting of 1999 any combination of: <constant>cgroup</constant>, <constant>ipc</constant>, <constant>net</constant>, 2000 <constant>mnt</constant>, <constant>pid</constant>, <constant>user</constant> and <constant>uts</constant>. Any 2001 namespace type listed is made accessible to the unit's processes, access to namespace types not listed is 2002 prohibited (allow-listing). By prepending the list with a single tilde character (<literal>~</literal>) the 2003 effect may be inverted: only the listed namespace types will be made inaccessible, all unlisted ones are 2004 permitted (deny-listing). If the empty string is assigned, the default namespace restrictions are applied, 2005 which is equivalent to false. This option may appear more than once, in which case the namespace types are 2006 merged by <constant>OR</constant>, or by <constant>AND</constant> if the lines are prefixed with 2007 <literal>~</literal> (see examples below). Internally, this setting limits access to the 2008 <citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>2</manvolnum></citerefentry>, 2009 <citerefentry><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry> and 2010 <citerefentry><refentrytitle>setns</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls, taking 2011 the specified flags parameters into account. Note that — if this option is used — in addition to restricting 2012 creation and switching of the specified types of namespaces (or all of them, if true) access to the 2013 <function>setns()</function> system call with a zero flags parameter is prohibited. This setting is only 2014 supported on x86, x86-64, mips, mips-le, mips64, mips64-le, mips64-n32, mips64-le-n32, ppc64, ppc64-le, s390 2015 and s390x, and enforces no restrictions on other architectures. If running in user mode, or in system mode, but 2016 without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>), 2017 <varname>NoNewPrivileges=yes</varname> is implied.</para> 2018 2019 <para>Example: if a unit has the following, 2020 <programlisting>RestrictNamespaces=cgroup ipc 2021RestrictNamespaces=cgroup net</programlisting> 2022 then <constant>cgroup</constant>, <constant>ipc</constant>, and <constant>net</constant> are set. 2023 If the second line is prefixed with <literal>~</literal>, e.g., 2024 <programlisting>RestrictNamespaces=cgroup ipc 2025RestrictNamespaces=~cgroup net</programlisting> 2026 then, only <constant>ipc</constant> is set.</para></listitem> 2027 </varlistentry> 2028 2029 <varlistentry> 2030 <term><varname>LockPersonality=</varname></term> 2031 2032 <listitem><para>Takes a boolean argument. If set, locks down the <citerefentry 2033 project='man-pages'><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry> system 2034 call so that the kernel execution domain may not be changed from the default or the personality selected with 2035 <varname>Personality=</varname> directive. This may be useful to improve security, because odd personality 2036 emulations may be poorly tested and source of vulnerabilities. If running in user mode, or in system mode, but 2037 without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>), 2038 <varname>NoNewPrivileges=yes</varname> is implied.</para></listitem> 2039 </varlistentry> 2040 2041 <varlistentry> 2042 <term><varname>MemoryDenyWriteExecute=</varname></term> 2043 2044 <listitem><para>Takes a boolean argument. If set, attempts to create memory mappings that are writable and 2045 executable at the same time, or to change existing memory mappings to become executable, or mapping shared 2046 memory segments as executable are prohibited. Specifically, a system call filter is added that rejects 2047 <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls with both 2048 <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set, 2049 <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> or 2050 <citerefentry><refentrytitle>pkey_mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls 2051 with <constant>PROT_EXEC</constant> set and 2052 <citerefentry><refentrytitle>shmat</refentrytitle><manvolnum>2</manvolnum></citerefentry> system calls with 2053 <constant>SHM_EXEC</constant> set. Note that this option is incompatible with programs and libraries that 2054 generate program code dynamically at runtime, including JIT execution engines, executable stacks, and code 2055 "trampoline" feature of various C compilers. This option improves service security, as it makes harder for 2056 software exploits to change running code dynamically. However, the protection can be circumvented, if 2057 the service can write to a filesystem, which is not mounted with <constant>noexec</constant> (such as 2058 <filename>/dev/shm</filename>), or it can use <function>memfd_create()</function>. This can be 2059 prevented by making such file systems inaccessible to the service 2060 (e.g. <varname>InaccessiblePaths=/dev/shm</varname>) and installing further system call filters 2061 (<varname>SystemCallFilter=~memfd_create</varname>). Note that this feature is fully available on 2062 x86-64, and partially on x86. Specifically, the <function>shmat()</function> protection is not 2063 available on x86. Note that on systems supporting multiple ABIs (such as x86/x86-64) it is 2064 recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the 2065 restrictions of this option. Specifically, it is recommended to combine this option with 2066 <varname>SystemCallArchitectures=native</varname> or similar. If running in user mode, or in system 2067 mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting 2068 <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.</para></listitem> 2069 </varlistentry> 2070 2071 <varlistentry> 2072 <term><varname>RestrictRealtime=</varname></term> 2073 2074 <listitem><para>Takes a boolean argument. If set, any attempts to enable realtime scheduling in a process of 2075 the unit are refused. This restricts access to realtime task scheduling policies such as 2076 <constant>SCHED_FIFO</constant>, <constant>SCHED_RR</constant> or <constant>SCHED_DEADLINE</constant>. See 2077 <citerefentry project='man-pages'><refentrytitle>sched</refentrytitle><manvolnum>7</manvolnum></citerefentry> 2078 for details about these scheduling policies. If running in user mode, or in system mode, but without the 2079 <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>), 2080 <varname>NoNewPrivileges=yes</varname> is implied. Realtime scheduling policies may be used to monopolize CPU 2081 time for longer periods of time, and may hence be used to lock up or otherwise trigger Denial-of-Service 2082 situations on the system. It is hence recommended to restrict access to realtime scheduling to the few programs 2083 that actually require them. Defaults to off.</para></listitem> 2084 </varlistentry> 2085 2086 <varlistentry> 2087 <term><varname>RestrictSUIDSGID=</varname></term> 2088 2089 <listitem><para>Takes a boolean argument. If set, any attempts to set the set-user-ID (SUID) or 2090 set-group-ID (SGID) bits on files or directories will be denied (for details on these bits see 2091 <citerefentry 2092 project='man-pages'><refentrytitle>inode</refentrytitle><manvolnum>7</manvolnum></citerefentry>). If 2093 running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> 2094 capability (e.g. setting <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is 2095 implied. As the SUID/SGID bits are mechanisms to elevate privileges, and allows users to acquire the 2096 identity of other users, it is recommended to restrict creation of SUID/SGID files to the few 2097 programs that actually require them. Note that this restricts marking of any type of file system 2098 object with these bits, including both regular files and directories (where the SGID is a different 2099 meaning than for files, see documentation). This option is implied if <varname>DynamicUser=</varname> 2100 is enabled. Defaults to off.</para></listitem> 2101 </varlistentry> 2102 2103 <varlistentry> 2104 <term><varname>RemoveIPC=</varname></term> 2105 2106 <listitem><para>Takes a boolean parameter. If set, all System V and POSIX IPC objects owned by the user and 2107 group the processes of this unit are run as are removed when the unit is stopped. This setting only has an 2108 effect if at least one of <varname>User=</varname>, <varname>Group=</varname> and 2109 <varname>DynamicUser=</varname> are used. It has no effect on IPC objects owned by the root user. Specifically, 2110 this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If 2111 multiple units use the same user or group the IPC objects are removed when the last of these units is 2112 stopped. This setting is implied if <varname>DynamicUser=</varname> is set.</para> 2113 2114 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 2115 </varlistentry> 2116 2117 <varlistentry> 2118 <term><varname>PrivateMounts=</varname></term> 2119 2120 <listitem><para>Takes a boolean parameter. If set, the processes of this unit will be run in their own private 2121 file system (mount) namespace with all mount propagation from the processes towards the host's main file system 2122 namespace turned off. This means any file system mount points established or removed by the unit's processes 2123 will be private to them and not be visible to the host. However, file system mount points established or 2124 removed on the host will be propagated to the unit's processes. See <citerefentry 2125 project='man-pages'><refentrytitle>mount_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 2126 details on file system namespaces. Defaults to off.</para> 2127 2128 <para>When turned on, this executes three operations for each invoked process: a new 2129 <constant>CLONE_NEWNS</constant> namespace is created, after which all existing mounts are remounted to 2130 <constant>MS_SLAVE</constant> to disable propagation from the unit's processes to the host (but leaving 2131 propagation in the opposite direction in effect). Finally, the mounts are remounted again to the propagation 2132 mode configured with <varname>MountFlags=</varname>, see below.</para> 2133 2134 <para>File system namespaces are set up individually for each process forked off by the service manager. Mounts 2135 established in the namespace of the process created by <varname>ExecStartPre=</varname> will hence be cleaned 2136 up automatically as soon as that process exits and will not be available to subsequent processes forked off for 2137 <varname>ExecStart=</varname> (and similar applies to the various other commands configured for 2138 units). Similarly, <varname>JoinsNamespaceOf=</varname> does not permit sharing kernel mount namespaces between 2139 units, it only enables sharing of the <filename>/tmp/</filename> and <filename>/var/tmp/</filename> 2140 directories.</para> 2141 2142 <para>Other file system namespace unit settings — <varname>PrivateMounts=</varname>, 2143 <varname>PrivateTmp=</varname>, <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, 2144 <varname>ProtectHome=</varname>, <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname>, 2145 <varname>ReadWritePaths=</varname>, … — also enable file system namespacing in a fashion equivalent to this 2146 option. Hence it is primarily useful to explicitly request this behaviour if none of the other settings are 2147 used.</para> 2148 2149 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 2150 </varlistentry> 2151 2152 <varlistentry> 2153 <term><varname>MountFlags=</varname></term> 2154 2155 <listitem><para>Takes a mount propagation setting: <option>shared</option>, <option>slave</option> or 2156 <option>private</option>, which controls whether file system mount points in the file system namespaces set up 2157 for this unit's processes will receive or propagate mounts and unmounts from other file system namespaces. See 2158 <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> 2159 for details on mount propagation, and the three propagation flags in particular.</para> 2160 2161 <para>This setting only controls the <emphasis>final</emphasis> propagation setting in effect on all mount 2162 points of the file system namespace created for each process of this unit. Other file system namespacing unit 2163 settings (see the discussion in <varname>PrivateMounts=</varname> above) will implicitly disable mount and 2164 unmount propagation from the unit's processes towards the host by changing the propagation setting of all mount 2165 points in the unit's file system namespace to <option>slave</option> first. Setting this option to 2166 <option>shared</option> does not reestablish propagation in that case.</para> 2167 2168 <para>If not set – but file system namespaces are enabled through another file system namespace unit setting – 2169 <option>shared</option> mount propagation is used, but — as mentioned — as <option>slave</option> is applied 2170 first, propagation from the unit's processes to the host is still turned off.</para> 2171 2172 <para>It is not recommended to use <option>private</option> mount propagation for units, as this means 2173 temporary mounts (such as removable media) of the host will stay mounted and thus indefinitely busy in forked 2174 off processes, as unmount propagation events won't be received by the file system namespace of the unit.</para> 2175 2176 <para>Usually, it is best to leave this setting unmodified, and use higher level file system namespacing 2177 options instead, in particular <varname>PrivateMounts=</varname>, see above.</para> 2178 2179 <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem> 2180 </varlistentry> 2181 2182 </variablelist> 2183 </refsect1> 2184 2185 <refsect1> 2186 <title>System Call Filtering</title> 2187 <variablelist class='unit-directives'> 2188 2189 <varlistentry> 2190 <term><varname>SystemCallFilter=</varname></term> 2191 2192 <listitem><para>Takes a space-separated list of system call names. If this setting is used, all 2193 system calls executed by the unit processes except for the listed ones will result in immediate 2194 process termination with the <constant>SIGSYS</constant> signal (allow-listing). (See 2195 <varname>SystemCallErrorNumber=</varname> below for changing the default action). If the first 2196 character of the list is <literal>~</literal>, the effect is inverted: only the listed system calls 2197 will result in immediate process termination (deny-listing). Deny-listed system calls and system call 2198 groups may optionally be suffixed with a colon (<literal>:</literal>) and <literal>errno</literal> 2199 error number (between 0 and 4095) or errno name such as <constant>EPERM</constant>, 2200 <constant>EACCES</constant> or <constant>EUCLEAN</constant> (see <citerefentry 2201 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> for a 2202 full list). This value will be returned when a deny-listed system call is triggered, instead of 2203 terminating the processes immediately. Special setting <literal>kill</literal> can be used to 2204 explicitly specify killing. This value takes precedence over the one given in 2205 <varname>SystemCallErrorNumber=</varname>, see below. If running in user mode, or in system mode, 2206 but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting 2207 <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied. This feature 2208 makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful 2209 for enforcing a minimal sandboxing environment. Note that the <function>execve()</function>, 2210 <function>exit()</function>, <function>exit_group()</function>, <function>getrlimit()</function>, 2211 <function>rt_sigreturn()</function>, <function>sigreturn()</function> system calls and the system calls 2212 for querying time and sleeping are implicitly allow-listed and do not need to be listed 2213 explicitly. This option may be specified more than once, in which case the filter masks are 2214 merged. If the empty string is assigned, the filter is reset, all prior assignments will have no 2215 effect. This does not affect commands prefixed with <literal>+</literal>.</para> 2216 2217 <para>Note that on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off 2218 alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this 2219 option. Specifically, it is recommended to combine this option with 2220 <varname>SystemCallArchitectures=native</varname> or similar.</para> 2221 2222 <para>Note that strict system call filters may impact execution and error handling code paths of the service 2223 invocation. Specifically, access to the <function>execve()</function> system call is required for the execution 2224 of the service binary — if it is blocked service invocation will necessarily fail. Also, if execution of the 2225 service binary fails for some reason (for example: missing service executable), the error handling logic might 2226 require access to an additional set of system calls in order to process and log this failure correctly. It 2227 might be necessary to temporarily disable system call filters in order to simplify debugging of such 2228 failures.</para> 2229 2230 <para>If you specify both types of this option (i.e. allow-listing and deny-listing), the first 2231 encountered will take precedence and will dictate the default action (termination or approval of a 2232 system call). Then the next occurrences of this option will add or delete the listed system calls 2233 from the set of the filtered system calls, depending of its type and the default action. (For 2234 example, if you have started with an allow list rule for <function>read()</function> and 2235 <function>write()</function>, and right after it add a deny list rule for <function>write()</function>, 2236 then <function>write()</function> will be removed from the set.)</para> 2237 2238 <para>As the number of possible system calls is large, predefined sets of system calls are provided. A set 2239 starts with <literal>@</literal> character, followed by name of the set. 2240 2241 <table> 2242 <title>Currently predefined system call sets</title> 2243 2244 <tgroup cols='2'> 2245 <colspec colname='set' /> 2246 <colspec colname='description' /> 2247 <thead> 2248 <row> 2249 <entry>Set</entry> 2250 <entry>Description</entry> 2251 </row> 2252 </thead> 2253 <tbody> 2254 <row> 2255 <entry>@aio</entry> 2256 <entry>Asynchronous I/O (<citerefentry project='man-pages'><refentrytitle>io_setup</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>io_submit</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> 2257 </row> 2258 <row> 2259 <entry>@basic-io</entry> 2260 <entry>System calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing (<citerefentry project='man-pages'><refentrytitle>read</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>write</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> 2261 </row> 2262 <row> 2263 <entry>@chown</entry> 2264 <entry>Changing file ownership (<citerefentry project='man-pages'><refentrytitle>chown</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>fchownat</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> 2265 </row> 2266 <row> 2267 <entry>@clock</entry> 2268 <entry>System calls for changing the system clock (<citerefentry project='man-pages'><refentrytitle>adjtimex</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>settimeofday</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> 2269 </row> 2270 <row> 2271 <entry>@cpu-emulation</entry> 2272 <entry>System calls for CPU emulation functionality (<citerefentry project='man-pages'><refentrytitle>vm86</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> 2273 </row> 2274 <row> 2275 <entry>@debug</entry> 2276 <entry>Debugging, performance monitoring and tracing functionality (<citerefentry project='man-pages'><refentrytitle>ptrace</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>perf_event_open</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> 2277 </row> 2278 <row> 2279 <entry>@file-system</entry> 2280 <entry>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</entry> 2281 </row> 2282 <row> 2283 <entry>@io-event</entry> 2284 <entry>Event loop system calls (<citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>select</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>eventfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> 2285 </row> 2286 <row> 2287 <entry>@ipc</entry> 2288 <entry>Pipes, SysV IPC, POSIX Message Queues and other IPC (<citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>svipc</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> 2289 </row> 2290 <row> 2291 <entry>@keyring</entry> 2292 <entry>Kernel keyring access (<citerefentry project='man-pages'><refentrytitle>keyctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> 2293 </row> 2294 <row> 2295 <entry>@memlock</entry> 2296 <entry>Locking of memory in RAM (<citerefentry project='man-pages'><refentrytitle>mlock</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>mlockall</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> 2297 </row> 2298 <row> 2299 <entry>@module</entry> 2300 <entry>Loading and unloading of kernel modules (<citerefentry project='man-pages'><refentrytitle>init_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>delete_module</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> 2301 </row> 2302 <row> 2303 <entry>@mount</entry> 2304 <entry>Mounting and unmounting of file systems (<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> 2305 </row> 2306 <row> 2307 <entry>@network-io</entry> 2308 <entry>Socket I/O (including local AF_UNIX): <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry></entry> 2309 </row> 2310 <row> 2311 <entry>@obsolete</entry> 2312 <entry>Unusual, obsolete or unimplemented (<citerefentry project='man-pages'><refentrytitle>create_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>gtty</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> 2313 </row> 2314 <row> 2315 <entry>@privileged</entry> 2316 <entry>All system calls which need super-user capabilities (<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> 2317 </row> 2318 <row> 2319 <entry>@process</entry> 2320 <entry>Process control, execution, namespacing operations (<citerefentry project='man-pages'><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …)</entry> 2321 </row> 2322 <row> 2323 <entry>@raw-io</entry> 2324 <entry>Raw I/O port access (<citerefentry project='man-pages'><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>iopl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <function>pciconfig_read()</function>, …)</entry> 2325 </row> 2326 <row> 2327 <entry>@reboot</entry> 2328 <entry>System calls for rebooting and reboot preparation (<citerefentry project='man-pages'><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <function>kexec()</function>, …)</entry> 2329 </row> 2330 <row> 2331 <entry>@resources</entry> 2332 <entry>System calls for changing resource limits, memory and scheduling parameters (<citerefentry project='man-pages'><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> 2333 </row> 2334 <row> 2335 <entry>@setuid</entry> 2336 <entry>System calls for changing user ID and group ID credentials, (<citerefentry project='man-pages'><refentrytitle>setuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setgid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setresuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> 2337 </row> 2338 <row> 2339 <entry>@signal</entry> 2340 <entry>System calls for manipulating and handling process signals (<citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> 2341 </row> 2342 <row> 2343 <entry>@swap</entry> 2344 <entry>System calls for enabling/disabling swap devices (<citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>swapoff</refentrytitle><manvolnum>2</manvolnum></citerefentry>)</entry> 2345 </row> 2346 <row> 2347 <entry>@sync</entry> 2348 <entry>Synchronizing files and memory to disk (<citerefentry project='man-pages'><refentrytitle>fsync</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>msync</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> 2349 </row> 2350 <row> 2351 <entry>@system-service</entry> 2352 <entry>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: <literal>@clock</literal>, <literal>@mount</literal>, <literal>@swap</literal>, <literal>@reboot</literal>.</entry> 2353 </row> 2354 <row> 2355 <entry>@timer</entry> 2356 <entry>System calls for scheduling operations by time (<citerefentry project='man-pages'><refentrytitle>alarm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>timer_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> 2357 </row> 2358 <row> 2359 <entry>@known</entry> 2360 <entry>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.</entry> 2361 </row> 2362 </tbody> 2363 </tgroup> 2364 </table> 2365 2366 Note, that as new system calls are added to the kernel, additional system calls might be added to the groups 2367 above. Contents of the sets may also change between systemd versions. In addition, the list of system calls 2368 depends on the kernel version and architecture for which systemd was compiled. Use 2369 <command>systemd-analyze syscall-filter</command> to list the actual list of system calls in each 2370 filter.</para> 2371 2372 <para>Generally, allow-listing system calls (rather than deny-listing) is the safer mode of 2373 operation. It is recommended to enforce system call allow lists for all long-running system 2374 services. Specifically, the following lines are a relatively safe basic choice for the majority of 2375 system services:</para> 2376 2377 <programlisting>[Service] 2378SystemCallFilter=@system-service 2379SystemCallErrorNumber=EPERM</programlisting> 2380 2381 <para>Note that various kernel system calls are defined redundantly: there are multiple system calls 2382 for executing the same operation. For example, the <function>pidfd_send_signal()</function> system 2383 call may be used to execute operations similar to what can be done with the older 2384 <function>kill()</function> system call, hence blocking the latter without the former only provides 2385 weak protection. Since new system calls are added regularly to the kernel as development progresses, 2386 keeping system call deny lists comprehensive requires constant work. It is thus recommended to use 2387 allow-listing instead, which offers the benefit that new system calls are by default implicitly 2388 blocked until the allow list is updated.</para> 2389 2390 <para>Also note that a number of system calls are required to be accessible for the dynamic linker to 2391 work. The dynamic linker is required for running most regular programs (specifically: all dynamic ELF 2392 binaries, which is how most distributions build packaged programs). This means that blocking these 2393 system calls (which include <function>open()</function>, <function>openat()</function> or 2394 <function>mmap()</function>) will make most programs typically shipped with generic distributions 2395 unusable.</para> 2396 2397 <para>It is recommended to combine the file system namespacing related options with 2398 <varname>SystemCallFilter=~@mount</varname>, in order to prohibit the unit's processes to undo the 2399 mappings. Specifically these are the options <varname>PrivateTmp=</varname>, 2400 <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>, 2401 <varname>ProtectKernelTunables=</varname>, <varname>ProtectControlGroups=</varname>, 2402 <varname>ProtectKernelLogs=</varname>, <varname>ProtectClock=</varname>, <varname>ReadOnlyPaths=</varname>, 2403 <varname>InaccessiblePaths=</varname> and <varname>ReadWritePaths=</varname>.</para></listitem> 2404 </varlistentry> 2405 2406 <varlistentry> 2407 <term><varname>SystemCallErrorNumber=</varname></term> 2408 2409 <listitem><para>Takes an <literal>errno</literal> error number (between 1 and 4095) or errno name 2410 such as <constant>EPERM</constant>, <constant>EACCES</constant> or <constant>EUCLEAN</constant>, to 2411 return when the system call filter configured with <varname>SystemCallFilter=</varname> is triggered, 2412 instead of terminating the process immediately. See <citerefentry 2413 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> for a 2414 full list of error codes. When this setting is not used, or when the empty string or the special 2415 setting <literal>kill</literal> is assigned, the process will be terminated immediately when the 2416 filter is triggered.</para></listitem> 2417 </varlistentry> 2418 2419 <varlistentry> 2420 <term><varname>SystemCallArchitectures=</varname></term> 2421 2422 <listitem><para>Takes a space-separated list of architecture identifiers to include in the system call 2423 filter. The known architecture identifiers are the same as for <varname>ConditionArchitecture=</varname> 2424 described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 2425 as well as <constant>x32</constant>, <constant>mips64-n32</constant>, <constant>mips64-le-n32</constant>, and 2426 the special identifier <constant>native</constant>. The special identifier <constant>native</constant> 2427 implicitly maps to the native architecture of the system (or more precisely: to the architecture the system 2428 manager is compiled for). If running in user mode, or in system mode, but without the 2429 <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>), 2430 <varname>NoNewPrivileges=yes</varname> is implied. By default, this option is set to the empty list, i.e. no 2431 filtering is applied.</para> 2432 2433 <para>If this setting is used, processes of this unit will only be permitted to call native system calls, and 2434 system calls of the specified architectures. For the purposes of this option, the x32 architecture is treated 2435 as including x86-64 system calls. However, this setting still fulfills its purpose, as explained below, on 2436 x32.</para> 2437 2438 <para>System call filtering is not equally effective on all architectures. For example, on x86 2439 filtering of network socket-related calls is not possible, due to ABI limitations — a limitation that x86-64 2440 does not have, however. On systems supporting multiple ABIs at the same time — such as x86/x86-64 — it is hence 2441 recommended to limit the set of permitted system call architectures so that secondary ABIs may not be used to 2442 circumvent the restrictions applied to the native ABI of the system. In particular, setting 2443 <varname>SystemCallArchitectures=native</varname> is a good choice for disabling non-native ABIs.</para> 2444 2445 <para>System call architectures may also be restricted system-wide via the 2446 <varname>SystemCallArchitectures=</varname> option in the global configuration. See 2447 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 2448 details.</para></listitem> 2449 </varlistentry> 2450 2451 <varlistentry> 2452 <term><varname>SystemCallLog=</varname></term> 2453 2454 <listitem><para>Takes a space-separated list of system call names. If this setting is used, all 2455 system calls executed by the unit processes for the listed ones will be logged. If the first 2456 character of the list is <literal>~</literal>, the effect is inverted: all system calls except the 2457 listed system calls will be logged. If running in user mode, or in system mode, but without the 2458 <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>), 2459 <varname>NoNewPrivileges=yes</varname> is implied. This feature makes use of the Secure Computing 2460 Mode 2 interfaces of the kernel ('seccomp filtering') and is useful for auditing or setting up a 2461 minimal sandboxing environment. This option may be specified more than once, in which case the filter 2462 masks are merged. If the empty string is assigned, the filter is reset, all prior assignments will 2463 have no effect. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> 2464 </varlistentry> 2465 2466 </variablelist> 2467 </refsect1> 2468 2469 <refsect1> 2470 <title>Environment</title> 2471 2472 <variablelist class='unit-directives'> 2473 2474 <varlistentry> 2475 <term><varname>Environment=</varname></term> 2476 2477 <listitem><para>Sets environment variables for executed processes. Each line is unquoted using the 2478 rules described in "Quoting" section in 2479 <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> 2480 and becomes a list of variable assignments. If you need to assign a value containing spaces or the 2481 equals sign to a variable, put quotes around the whole assignment. Variable expansion is not 2482 performed inside the strings and the <literal>$</literal> character has no special meaning. Specifier 2483 expansion is performed, see the "Specifiers" section in 2484 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 2485 </para> 2486 2487 <para>This option may be specified more than once, in which case all listed variables will be set. If 2488 the same variable is listed twice, the later setting will override the earlier setting. If the empty 2489 string is assigned to this option, the list of environment variables is reset, all prior assignments 2490 have no effect.</para> 2491 2492 <para>The names of the variables can contain ASCII letters, digits, and the underscore character. 2493 Variable names cannot be empty or start with a digit. In variable values, most characters are 2494 allowed, but non-printable characters are currently rejected.</para> 2495 2496 <para>Example: 2497 <programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"</programlisting> 2498 gives three variables <literal>VAR1</literal>, 2499 <literal>VAR2</literal>, <literal>VAR3</literal> 2500 with the values <literal>word1 word2</literal>, 2501 <literal>word3</literal>, <literal>$word 5 6</literal>. 2502 </para> 2503 2504 <para>See <citerefentry 2505 project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 2506 details about environment variables.</para> 2507 2508 <para>Note that environment variables are not suitable for passing secrets (such as passwords, key 2509 material, …) to service processes. Environment variables set for a unit are exposed to unprivileged 2510 clients via D-Bus IPC, and generally not understood as being data that requires protection. Moreover, 2511 environment variables are propagated down the process tree, including across security boundaries 2512 (such as setuid/setgid executables), and hence might leak to processes that should not have access to 2513 the secret data. Use <varname>LoadCredential=</varname>, <varname>LoadCredentialEncrypted=</varname> 2514 or <varname>SetCredentialEncrypted=</varname> (see below) to pass data to unit processes 2515 securely.</para></listitem> 2516 </varlistentry> 2517 2518 <varlistentry> 2519 <term><varname>EnvironmentFile=</varname></term> 2520 2521 <listitem><para>Similar to <varname>Environment=</varname> but reads the environment variables from a text file. 2522 The text file should contain newline-separated variable assignments. Empty lines, lines without an 2523 <literal>=</literal> separator, or lines starting with <literal>;</literal> or <literal>#</literal> will be 2524 ignored, which may be used for commenting. The file must be UTF-8 encoded. Valid characters are <ulink 2525 url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink> other than <ulink 2526 url="https://www.unicode.org/glossary/#noncharacter">noncharacters</ulink>, U+0000 NUL, and U+FEFF <ulink 2527 url="https://www.unicode.org/glossary/#byte_order_mark">byte order mark</ulink>. Control codes other than NUL 2528 are allowed.</para> 2529 2530 <para>In the file, an unquoted value after the <literal>=</literal> is parsed with the same backslash-escape 2531 rules as <ulink 2532 url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">unquoted 2533 text</ulink> in a POSIX shell, but unlike in a shell, interior whitespace is preserved and quotes after the 2534 first non-whitespace character are preserved. Leading and trailing whitespace (space, tab, carriage return) is 2535 discarded, but interior whitespace within the line is preserved verbatim. A line ending with a backslash will be 2536 continued to the following one, with the newline itself discarded. A backslash 2537 <literal>\</literal> followed by any character other than newline will preserve the following character, so that 2538 <literal>\\</literal> will become the value <literal>\</literal>.</para> 2539 2540 <para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span multiple lines 2541 and contain any character verbatim other than single quote, like <ulink 2542 url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">single-quoted 2543 text</ulink> in a POSIX shell. No backslash-escape sequences are recognized. Leading and trailing whitespace 2544 outside of the single quotes is discarded.</para> 2545 2546 <para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span multiple lines, 2547 and the same escape sequences are recognized as in <ulink 2548 url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">double-quoted 2549 text</ulink> of a POSIX shell. Backslash (<literal>\</literal>) followed by any of <literal>"\`$</literal> will 2550 preserve that character. A backslash followed by newline is a line continuation, and the newline itself is 2551 discarded. A backslash followed by any other character is ignored; both the backslash and the following 2552 character are preserved verbatim. Leading and trailing whitespace outside of the double quotes is 2553 discarded.</para> 2554 2555 <para>The argument passed should be an absolute filename or wildcard expression, optionally prefixed with 2556 <literal>-</literal>, which indicates that if the file does not exist, it will not be read and no error or 2557 warning message is logged. This option may be specified more than once in which case all specified files are 2558 read. If the empty string is assigned to this option, the list of file to read is reset, all prior assignments 2559 have no effect.</para> 2560 2561 <para>The files listed with this directive will be read shortly before the process is executed (more 2562 specifically, after all processes from a previous unit state terminated. This means you can generate these 2563 files in one unit state, and read it with this option in the next. The files are read from the file 2564 system of the service manager, before any file system changes like bind mounts take place).</para> 2565 2566 <para>Settings from these files override settings made with <varname>Environment=</varname>. If the same 2567 variable is set twice from these files, the files will be read in the order they are specified and the later 2568 setting will override the earlier setting.</para></listitem> 2569 </varlistentry> 2570 2571 <varlistentry> 2572 <term><varname>PassEnvironment=</varname></term> 2573 2574 <listitem><para>Pass environment variables set for the system service manager to executed processes. Takes a 2575 space-separated list of variable names. This option may be specified more than once, in which case all listed 2576 variables will be passed. If the empty string is assigned to this option, the list of environment variables to 2577 pass is reset, all prior assignments have no effect. Variables specified that are not set for the system 2578 manager will not be passed and will be silently ignored. Note that this option is only relevant for the system 2579 service manager, as system services by default do not automatically inherit any environment variables set for 2580 the service manager itself. However, in case of the user service manager all environment variables are passed 2581 to the executed processes anyway, hence this option is without effect for the user service manager.</para> 2582 2583 <para>Variables set for invoked processes due to this setting are subject to being overridden by those 2584 configured with <varname>Environment=</varname> or <varname>EnvironmentFile=</varname>.</para> 2585 2586 <para>Example: 2587 <programlisting>PassEnvironment=VAR1 VAR2 VAR3</programlisting> 2588 passes three variables <literal>VAR1</literal>, 2589 <literal>VAR2</literal>, <literal>VAR3</literal> 2590 with the values set for those variables in PID1.</para> 2591 2592 <para> 2593 See <citerefentry 2594 project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details 2595 about environment variables.</para></listitem> 2596 </varlistentry> 2597 2598 <varlistentry> 2599 <term><varname>UnsetEnvironment=</varname></term> 2600 2601 <listitem><para>Explicitly unset environment variable assignments that would normally be passed from the 2602 service manager to invoked processes of this unit. Takes a space-separated list of variable names or variable 2603 assignments. This option may be specified more than once, in which case all listed variables/assignments will 2604 be unset. If the empty string is assigned to this option, the list of environment variables/assignments to 2605 unset is reset. If a variable assignment is specified (that is: a variable name, followed by 2606 <literal>=</literal>, followed by its value), then any environment variable matching this precise assignment is 2607 removed. If a variable name is specified (that is a variable name without any following <literal>=</literal> or 2608 value), then any assignment matching the variable name, regardless of its value is removed. Note that the 2609 effect of <varname>UnsetEnvironment=</varname> is applied as final step when the environment list passed to 2610 executed processes is compiled. That means it may undo assignments from any configuration source, including 2611 assignments made through <varname>Environment=</varname> or <varname>EnvironmentFile=</varname>, inherited from 2612 the system manager's global set of environment variables, inherited via <varname>PassEnvironment=</varname>, 2613 set by the service manager itself (such as <varname>$NOTIFY_SOCKET</varname> and such), or set by a PAM module 2614 (in case <varname>PAMName=</varname> is used).</para> 2615 2616 <para>See "Environment Variables in Spawned Processes" below for a description of how those 2617 settings combine to form the inherited environment. See <citerefentry 2618 project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for general 2619 information about environment variables.</para></listitem> 2620 </varlistentry> 2621 2622 </variablelist> 2623 </refsect1> 2624 2625 <refsect1> 2626 <title>Logging and Standard Input/Output</title> 2627 2628 <variablelist class='unit-directives'> 2629 <varlistentry> 2630 2631 <term><varname>StandardInput=</varname></term> 2632 2633 <listitem><para>Controls where file descriptor 0 (STDIN) of the executed processes is connected to. Takes one 2634 of <option>null</option>, <option>tty</option>, <option>tty-force</option>, <option>tty-fail</option>, 2635 <option>data</option>, <option>file:<replaceable>path</replaceable></option>, <option>socket</option> or 2636 <option>fd:<replaceable>name</replaceable></option>.</para> 2637 2638 <para>If <option>null</option> is selected, standard input will be connected to <filename>/dev/null</filename>, 2639 i.e. all read attempts by the process will result in immediate EOF.</para> 2640 2641 <para>If <option>tty</option> is selected, standard input is connected to a TTY (as configured by 2642 <varname>TTYPath=</varname>, see below) and the executed process becomes the controlling process of the 2643 terminal. If the terminal is already being controlled by another process, the executed process waits until the 2644 current controlling process releases the terminal.</para> 2645 2646 <para><option>tty-force</option> is similar to <option>tty</option>, but the executed process is forcefully and 2647 immediately made the controlling process of the terminal, potentially removing previous controlling processes 2648 from the terminal.</para> 2649 2650 <para><option>tty-fail</option> is similar to <option>tty</option>, but if the terminal already has a 2651 controlling process start-up of the executed process fails.</para> 2652 2653 <para>The <option>data</option> option may be used to configure arbitrary textual or binary data to pass via 2654 standard input to the executed process. The data to pass is configured via 2655 <varname>StandardInputText=</varname>/<varname>StandardInputData=</varname> (see below). Note that the actual 2656 file descriptor type passed (memory file, regular file, UNIX pipe, …) might depend on the kernel and available 2657 privileges. In any case, the file descriptor is read-only, and when read returns the specified data followed by 2658 EOF.</para> 2659 2660 <para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file 2661 system object to standard input. An absolute path following the <literal>:</literal> character is expected, 2662 which may refer to a regular file, a FIFO or special file. If an <constant>AF_UNIX</constant> socket in the 2663 file system is specified, a stream socket is connected to it. The latter is useful for connecting standard 2664 input of processes to arbitrary system services.</para> 2665 2666 <para>The <option>socket</option> option is valid in socket-activated services only, and requires the relevant 2667 socket unit file (see 2668 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details) 2669 to have <varname>Accept=yes</varname> set, or to specify a single socket only. If this option is set, standard 2670 input will be connected to the socket the service was activated from, which is primarily useful for 2671 compatibility with daemons designed for use with the traditional <citerefentry 2672 project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> socket activation 2673 daemon.</para> 2674 2675 <para>The <option>fd:<replaceable>name</replaceable></option> option connects standard input to a specific, 2676 named file descriptor provided by a socket unit. The name may be specified as part of this option, following a 2677 <literal>:</literal> character (e.g. <literal>fd:foobar</literal>). If no name is specified, the name 2678 <literal>stdin</literal> is implied (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdin</literal>). 2679 At least one socket unit defining the specified name must be provided via the <varname>Sockets=</varname> 2680 option, and the file descriptor name may differ from the name of its containing socket unit. If multiple 2681 matches are found, the first one will be used. See <varname>FileDescriptorName=</varname> in 2682 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more 2683 details about named file descriptors and their ordering.</para> 2684 2685 <para>This setting defaults to <option>null</option>, unless 2686 <varname>StandardInputText=</varname>/<varname>StandardInputData=</varname> are set, in which case it 2687 defaults to <option>data</option>.</para></listitem> 2688 </varlistentry> 2689 2690 <varlistentry> 2691 <term><varname>StandardOutput=</varname></term> 2692 2693 <listitem><para>Controls where file descriptor 1 (stdout) of the executed processes is connected 2694 to. Takes one of <option>inherit</option>, <option>null</option>, <option>tty</option>, 2695 <option>journal</option>, <option>kmsg</option>, <option>journal+console</option>, 2696 <option>kmsg+console</option>, <option>file:<replaceable>path</replaceable></option>, 2697 <option>append:<replaceable>path</replaceable></option>, <option>truncate:<replaceable>path</replaceable></option>, 2698 <option>socket</option> or <option>fd:<replaceable>name</replaceable></option>.</para> 2699 2700 <para><option>inherit</option> duplicates the file descriptor of standard input for standard output.</para> 2701 2702 <para><option>null</option> connects standard output to <filename>/dev/null</filename>, i.e. everything written 2703 to it will be lost.</para> 2704 2705 <para><option>tty</option> connects standard output to a tty (as configured via <varname>TTYPath=</varname>, 2706 see below). If the TTY is used for output only, the executed process will not become the controlling process of 2707 the terminal, and will not fail or wait for other processes to release the terminal.</para> 2708 2709 <para><option>journal</option> connects standard output with the journal, which is accessible via 2710 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Note 2711 that everything that is written to kmsg (see below) is implicitly stored in the journal as well, the 2712 specific option listed below is hence a superset of this one. (Also note that any external, 2713 additional syslog daemons receive their log data from the journal, too, hence this is the option to 2714 use when logging shall be processed with such a daemon.)</para> 2715 2716 <para><option>kmsg</option> connects standard output with the kernel log buffer which is accessible via 2717 <citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 2718 in addition to the journal. The journal daemon might be configured to send all logs to kmsg anyway, in which 2719 case this option is no different from <option>journal</option>.</para> 2720 2721 <para><option>journal+console</option> and <option>kmsg+console</option> work in a similar way as the 2722 two options above but copy the output to the system console as well.</para> 2723 2724 <para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file 2725 system object to standard output. The semantics are similar to the same option of 2726 <varname>StandardInput=</varname>, see above. If <replaceable>path</replaceable> refers to a regular file 2727 on the filesystem, it is opened (created if it doesn't exist yet) for writing at the beginning of the file, 2728 but without truncating it. 2729 If standard input and output are directed to the same file path, it is opened only once — for reading as well 2730 as writing — and duplicated. This is particularly useful when the specified path refers to an 2731 <constant>AF_UNIX</constant> socket in the file system, as in that case only a 2732 single stream connection is created for both input and output.</para> 2733 2734 <para><option>append:<replaceable>path</replaceable></option> is similar to 2735 <option>file:<replaceable>path</replaceable></option> above, but it opens the file in append mode. 2736 </para> 2737 2738 <para><option>truncate:<replaceable>path</replaceable></option> is similar to 2739 <option>file:<replaceable>path</replaceable></option> above, but it truncates the file when opening 2740 it. For units with multiple command lines, e.g. <varname>Type=oneshot</varname> services with 2741 multiple <varname>ExecStart=</varname>, or services with <varname>ExecCondition=</varname>, 2742 <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname>, the output file is reopened 2743 and therefore re-truncated for each command line. If the output file is truncated while another 2744 process still has the file open, e.g. by an <varname>ExecReload=</varname> running concurrently with 2745 an <varname>ExecStart=</varname>, and the other process continues writing to the file without 2746 adjusting its offset, then the space between the file pointers of the two processes may be filled 2747 with <constant>NUL</constant> bytes, producing a sparse file. Thus, 2748 <option>truncate:<replaceable>path</replaceable></option> is typically only useful for units where 2749 only one process runs at a time, such as services with a single <varname>ExecStart=</varname> and no 2750 <varname>ExecStartPost=</varname>, <varname>ExecReload=</varname>, <varname>ExecStop=</varname> or 2751 similar.</para> 2752 2753 <para><option>socket</option> connects standard output to a socket acquired via socket activation. The 2754 semantics are similar to the same option of <varname>StandardInput=</varname>, see above.</para> 2755 2756 <para>The <option>fd:<replaceable>name</replaceable></option> option connects standard output to a 2757 specific, named file descriptor provided by a socket unit. A name may be specified as part of this 2758 option, following a <literal>:</literal> character 2759 (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>). If no name is specified, the name 2760 <literal>stdout</literal> is implied (i.e. <literal>fd</literal> is equivalent to 2761 <literal>fd:stdout</literal>). At least one socket unit defining the specified name must be provided 2762 via the <varname>Sockets=</varname> option, and the file descriptor name may differ from the name of 2763 its containing socket unit. If multiple matches are found, the first one will be used. See 2764 <varname>FileDescriptorName=</varname> in 2765 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> 2766 for more details about named descriptors and their ordering.</para> 2767 2768 <para>If the standard output (or error output, see below) of a unit is connected to the journal or 2769 the kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> 2770 on <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section 2771 above). Also note that in this case stdout (or stderr, see below) will be an 2772 <constant>AF_UNIX</constant> stream socket, and not a pipe or FIFO that can be re-opened. This means 2773 when executing shell scripts the construct <command>echo "hello" > /dev/stderr</command> for 2774 writing text to stderr will not work. To mitigate this use the construct <command>echo "hello" 2775 >&2</command> instead, which is mostly equivalent and avoids this pitfall.</para> 2776 2777 <para>This setting defaults to the value set with <varname>DefaultStandardOutput=</varname> in 2778 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which 2779 defaults to <option>journal</option>. Note that setting this parameter might result in additional dependencies 2780 to be added to the unit (see above).</para></listitem> 2781 </varlistentry> 2782 2783 <varlistentry> 2784 <term><varname>StandardError=</varname></term> 2785 2786 <listitem><para>Controls where file descriptor 2 (stderr) of the executed processes is connected to. The 2787 available options are identical to those of <varname>StandardOutput=</varname>, with some exceptions: if set to 2788 <option>inherit</option> the file descriptor used for standard output is duplicated for standard error, while 2789 <option>fd:<replaceable>name</replaceable></option> will use a default file descriptor name of 2790 <literal>stderr</literal>.</para> 2791 2792 <para>This setting defaults to the value set with <varname>DefaultStandardError=</varname> in 2793 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which 2794 defaults to <option>inherit</option>. Note that setting this parameter might result in additional dependencies 2795 to be added to the unit (see above).</para></listitem> 2796 </varlistentry> 2797 2798 <varlistentry> 2799 <term><varname>StandardInputText=</varname></term> 2800 <term><varname>StandardInputData=</varname></term> 2801 2802 <listitem><para>Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to 2803 the executed processes. These settings have no effect unless <varname>StandardInput=</varname> is set 2804 to <option>data</option> (which is the default if <varname>StandardInput=</varname> is not set 2805 otherwise, but <varname>StandardInputText=</varname>/<varname>StandardInputData=</varname> is). Use 2806 this option to embed process input data directly in the unit file.</para> 2807 2808 <para><varname>StandardInputText=</varname> accepts arbitrary textual data. C-style escapes for special 2809 characters as well as the usual <literal>%</literal>-specifiers are resolved. Each time this setting is used 2810 the specified text is appended to the per-unit data buffer, followed by a newline character (thus every use 2811 appends a new line to the end of the buffer). Note that leading and trailing whitespace of lines configured 2812 with this option is removed. If an empty line is specified the buffer is cleared (hence, in order to insert an 2813 empty line, add an additional <literal>\n</literal> to the end or beginning of a line).</para> 2814 2815 <para><varname>StandardInputData=</varname> accepts arbitrary binary data, encoded in <ulink 2816 url="https://tools.ietf.org/html/rfc2045#section-6.8">Base64</ulink>. No escape sequences or specifiers are 2817 resolved. Any whitespace in the encoded version is ignored during decoding.</para> 2818 2819 <para>Note that <varname>StandardInputText=</varname> and <varname>StandardInputData=</varname> operate on the 2820 same data buffer, and may be mixed in order to configure both binary and textual data for the same input 2821 stream. The textual or binary data is joined strictly in the order the settings appear in the unit 2822 file. Assigning an empty string to either will reset the data buffer.</para> 2823 2824 <para>Please keep in mind that in order to maintain readability long unit file settings may be split into 2825 multiple lines, by suffixing each line (except for the last) with a <literal>\</literal> character (see 2826 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 2827 details). This is particularly useful for large data configured with these two options. Example:</para> 2828 2829 <programlisting>… 2830StandardInput=data 2831StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZXMgYW5kIHNvIGRv \ 2832 IEkKQSBmdWxsIGNvbW1pdG1lbnQncyB3aGF0IEnigLJtIHRoaW5raW5nIG9mCllvdSB3b3VsZG4n \ 2833 dCBnZXQgdGhpcyBmcm9tIGFueSBvdGhlciBndXkKSSBqdXN0IHdhbm5hIHRlbGwgeW91IGhvdyBJ \ 2834 J20gZmVlbGluZwpHb3R0YSBtYWtlIHlvdSB1bmRlcnN0YW5kCgpOZXZlciBnb25uYSBnaXZlIHlv \ 2835 dSB1cApOZXZlciBnb25uYSBsZXQgeW91IGRvd24KTmV2ZXIgZ29ubmEgcnVuIGFyb3VuZCBhbmQg \ 2836 ZGVzZXJ0IHlvdQpOZXZlciBnb25uYSBtYWtlIHlvdSBjcnkKTmV2ZXIgZ29ubmEgc2F5IGdvb2Ri \ 2837 eWUKTmV2ZXIgZ29ubmEgdGVsbCBhIGxpZSBhbmQgaHVydCB5b3UK 2838…</programlisting></listitem> 2839 </varlistentry> 2840 2841 <varlistentry> 2842 <term><varname>LogLevelMax=</varname></term> 2843 2844 <listitem><para>Configures filtering by log level of log messages generated by this unit. Takes a 2845 <command>syslog</command> log level, one of <option>emerg</option> (lowest log level, only highest priority 2846 messages), <option>alert</option>, <option>crit</option>, <option>err</option>, <option>warning</option>, 2847 <option>notice</option>, <option>info</option>, <option>debug</option> (highest log level, also lowest priority 2848 messages). See <citerefentry 2849 project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for 2850 details. By default no filtering is applied (i.e. the default maximum log level is <option>debug</option>). Use 2851 this option to configure the logging system to drop log messages of a specific service above the specified 2852 level. For example, set <varname>LogLevelMax=</varname><option>info</option> in order to turn off debug logging 2853 of a particularly chatty unit. Note that the configured level is applied to any log messages written by any 2854 of the processes belonging to this unit, as well as any log messages written by the system manager process 2855 (PID 1) in reference to this unit, sent via any supported logging protocol. The filtering is applied 2856 early in the logging pipeline, before any kind of further processing is done. Moreover, messages which pass 2857 through this filter successfully might still be dropped by filters applied at a later stage in the logging 2858 subsystem. For example, <varname>MaxLevelStore=</varname> configured in 2859 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> might 2860 prohibit messages of higher log levels to be stored on disk, even though the per-unit 2861 <varname>LogLevelMax=</varname> permitted it to be processed.</para></listitem> 2862 </varlistentry> 2863 2864 <varlistentry> 2865 <term><varname>LogExtraFields=</varname></term> 2866 2867 <listitem><para>Configures additional log metadata fields to include in all log records generated by 2868 processes associated with this unit. This setting takes one or more journal field assignments in the 2869 format <literal>FIELD=VALUE</literal> separated by whitespace. See 2870 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> 2871 for details on the journal field concept. Even though the underlying journal implementation permits 2872 binary field values, this setting accepts only valid UTF-8 values. To include space characters in a 2873 journal field value, enclose the assignment in double quotes ("). <!-- " fake closing quote for emacs--> 2874 The usual specifiers are expanded in all assignments (see below). Note that this setting is not only 2875 useful for attaching additional metadata to log records of a unit, but given that all fields and 2876 values are indexed may also be used to implement cross-unit log record matching. Assign an empty 2877 string to reset the list.</para></listitem> 2878 </varlistentry> 2879 2880 <varlistentry> 2881 <term><varname>LogRateLimitIntervalSec=</varname></term> 2882 <term><varname>LogRateLimitBurst=</varname></term> 2883 2884 <listitem><para>Configures the rate limiting that is applied to messages generated by this unit. If, in the 2885 time interval defined by <varname>LogRateLimitIntervalSec=</varname>, more messages than specified in 2886 <varname>LogRateLimitBurst=</varname> are logged by a service, all further messages within the interval are 2887 dropped until the interval is over. A message about the number of dropped messages is generated. The time 2888 specification for <varname>LogRateLimitIntervalSec=</varname> may be specified in the following units: "s", 2889 "min", "h", "ms", "us" (see 2890 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details). 2891 The default settings are set by <varname>RateLimitIntervalSec=</varname> and <varname>RateLimitBurst=</varname> 2892 configured in <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 2893 </para></listitem> 2894 </varlistentry> 2895 2896 <varlistentry> 2897 <term><varname>LogNamespace=</varname></term> 2898 2899 <listitem><para>Run the unit's processes in the specified journal namespace. Expects a short 2900 user-defined string identifying the namespace. If not used the processes of the service are run in 2901 the default journal namespace, i.e. their log stream is collected and processed by 2902 <filename>systemd-journald.service</filename>. If this option is used any log data generated by 2903 processes of this unit (regardless if via the <function>syslog()</function>, journal native logging 2904 or stdout/stderr logging) is collected and processed by an instance of the 2905 <filename>systemd-journald@.service</filename> template unit, which manages the specified 2906 namespace. The log data is stored in a data store independent from the default log namespace's data 2907 store. See 2908 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 2909 for details about journal namespaces.</para> 2910 2911 <para>Internally, journal namespaces are implemented through Linux mount namespacing and 2912 over-mounting the directory that contains the relevant <constant>AF_UNIX</constant> sockets used for 2913 logging in the unit's mount namespace. Since mount namespaces are used this setting disconnects 2914 propagation of mounts from the unit's processes to the host, similar to how 2915 <varname>ReadOnlyPaths=</varname> and similar settings (see above) work. Journal namespaces may hence 2916 not be used for services that need to establish mount points on the host.</para> 2917 2918 <para>When this option is used the unit will automatically gain ordering and requirement dependencies 2919 on the two socket units associated with the <filename>systemd-journald@.service</filename> instance 2920 so that they are automatically established prior to the unit starting up. Note that when this option 2921 is used log output of this service does not appear in the regular 2922 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> 2923 output, unless the <option>--namespace=</option> option is used.</para> 2924 2925 <xi:include href="system-only.xml" xpointer="singular"/></listitem> 2926 </varlistentry> 2927 2928 <varlistentry> 2929 <term><varname>SyslogIdentifier=</varname></term> 2930 2931 <listitem><para>Sets the process name ("<command>syslog</command> tag") to prefix log lines sent to 2932 the logging system or the kernel log buffer with. If not set, defaults to the process name of the 2933 executed process. This option is only useful when <varname>StandardOutput=</varname> or 2934 <varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to 2935 the same settings in combination with <option>+console</option>) and only applies to log messages 2936 written to stdout or stderr.</para></listitem> 2937 </varlistentry> 2938 2939 <varlistentry> 2940 <term><varname>SyslogFacility=</varname></term> 2941 2942 <listitem><para>Sets the <command>syslog</command> facility identifier to use when logging. One of 2943 <option>kern</option>, <option>user</option>, <option>mail</option>, <option>daemon</option>, 2944 <option>auth</option>, <option>syslog</option>, <option>lpr</option>, <option>news</option>, 2945 <option>uucp</option>, <option>cron</option>, <option>authpriv</option>, <option>ftp</option>, 2946 <option>local0</option>, <option>local1</option>, <option>local2</option>, <option>local3</option>, 2947 <option>local4</option>, <option>local5</option>, <option>local6</option> or 2948 <option>local7</option>. See <citerefentry 2949 project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for 2950 details. This option is only useful when <varname>StandardOutput=</varname> or 2951 <varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to 2952 the same settings in combination with <option>+console</option>), and only applies to log messages 2953 written to stdout or stderr. Defaults to <option>daemon</option>.</para></listitem> 2954 </varlistentry> 2955 2956 <varlistentry> 2957 <term><varname>SyslogLevel=</varname></term> 2958 2959 <listitem><para>The default <command>syslog</command> log level to use when logging to the logging system or 2960 the kernel log buffer. One of <option>emerg</option>, <option>alert</option>, <option>crit</option>, 2961 <option>err</option>, <option>warning</option>, <option>notice</option>, <option>info</option>, 2962 <option>debug</option>. See <citerefentry 2963 project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for 2964 details. This option is only useful when <varname>StandardOutput=</varname> or 2965 <varname>StandardError=</varname> are set to <option>journal</option> or 2966 <option>kmsg</option> (or to the same settings in combination with <option>+console</option>), and only applies 2967 to log messages written to stdout or stderr. Note that individual lines output by executed processes may be 2968 prefixed with a different log level which can be used to override the default log level specified here. The 2969 interpretation of these prefixes may be disabled with <varname>SyslogLevelPrefix=</varname>, see below. For 2970 details, see <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 2971 Defaults to <option>info</option>.</para></listitem> 2972 </varlistentry> 2973 2974 <varlistentry> 2975 <term><varname>SyslogLevelPrefix=</varname></term> 2976 2977 <listitem><para>Takes a boolean argument. If true and <varname>StandardOutput=</varname> or 2978 <varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to 2979 the same settings in combination with <option>+console</option>), log lines written by the executed 2980 process that are prefixed with a log level will be processed with this log level set but the prefix 2981 removed. If set to false, the interpretation of these prefixes is disabled and the logged lines are 2982 passed on as-is. This only applies to log messages written to stdout or stderr. For details about 2983 this prefixing see 2984 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 2985 Defaults to true.</para></listitem> 2986 </varlistentry> 2987 2988 <varlistentry> 2989 <term><varname>TTYPath=</varname></term> 2990 2991 <listitem><para>Sets the terminal device node to use if standard input, output, or error are connected to a TTY 2992 (see above). Defaults to <filename>/dev/console</filename>.</para></listitem> 2993 </varlistentry> 2994 2995 <varlistentry> 2996 <term><varname>TTYReset=</varname></term> 2997 2998 <listitem><para>Reset the terminal device specified with <varname>TTYPath=</varname> before and after 2999 execution. Defaults to <literal>no</literal>.</para></listitem> 3000 </varlistentry> 3001 3002 <varlistentry> 3003 <term><varname>TTYVHangup=</varname></term> 3004 3005 <listitem><para>Disconnect all clients which have opened the terminal device specified with 3006 <varname>TTYPath=</varname> before and after execution. Defaults to <literal>no</literal>.</para></listitem> 3007 </varlistentry> 3008 3009 <varlistentry> 3010 <term><varname>TTYRows=</varname></term> 3011 <term><varname>TTYColumns=</varname></term> 3012 3013 <listitem><para>Configure the size of the TTY specified with <varname>TTYPath=</varname>. If unset or 3014 set to the empty string, the kernel default is used.</para></listitem> 3015 </varlistentry> 3016 3017 <varlistentry> 3018 <term><varname>TTYVTDisallocate=</varname></term> 3019 3020 <listitem><para>If the terminal device specified with <varname>TTYPath=</varname> is a virtual console 3021 terminal, try to deallocate the TTY before and after execution. This ensures that the screen and scrollback 3022 buffer is cleared. Defaults to <literal>no</literal>.</para></listitem> 3023 </varlistentry> 3024 </variablelist> 3025 </refsect1> 3026 3027 <refsect1> 3028 <title>Credentials</title> 3029 3030 <variablelist class='unit-directives'> 3031 3032 <varlistentry> 3033 <term><varname>LoadCredential=</varname><replaceable>ID</replaceable><optional>:<replaceable>PATH</replaceable></optional></term> 3034 <term><varname>LoadCredentialEncrypted=</varname><replaceable>ID</replaceable><optional>:<replaceable>PATH</replaceable></optional></term> 3035 3036 <listitem><para>Pass a credential to the unit. Credentials are limited-size binary or textual objects 3037 that may be passed to unit processes. They are primarily used for passing cryptographic keys (both 3038 public and private) or certificates, user account information or identity information from host to 3039 services. The data is accessible from the unit's processes via the file system, at a read-only 3040 location that (if possible and permitted) is backed by non-swappable memory. The data is only 3041 accessible to the user associated with the unit, via the 3042 <varname>User=</varname>/<varname>DynamicUser=</varname> settings (as well as the superuser). When 3043 available, the location of credentials is exported as the <varname>$CREDENTIALS_DIRECTORY</varname> 3044 environment variable to the unit's processes.</para> 3045 3046 <para>The <varname>LoadCredential=</varname> setting takes a textual ID to use as name for a 3047 credential plus a file system path, separated by a colon. The ID must be a short ASCII string 3048 suitable as filename in the filesystem, and may be chosen freely by the user. If the specified path 3049 is absolute it is opened as regular file and the credential data is read from it. If the absolute 3050 path refers to an <constant>AF_UNIX</constant> stream socket in the file system a connection is made 3051 to it (only once at unit start-up) and the credential data read from the connection, providing an 3052 easy IPC integration point for dynamically transferring credentials from other services.</para> 3053 3054 <para>If the specified path is not absolute and itself qualifies as valid credential identifier it is 3055 attempted to find a credential that the service manager itself received under the specified name — 3056 which may be used to propagate credentials from an invoking environment (e.g. a container manager 3057 that invoked the service manager) into a service. If no matching system credential is found, the 3058 directories <filename>/etc/credstore/</filename>, <filename>/run/credstore/</filename> and 3059 <filename>/usr/lib/credstore/</filename> are searched for files under the credential's name — which 3060 hence are recommended locations for credential data on disk. If 3061 <varname>LoadCredentialEncrypted=</varname> is used <filename>/run/credstore.encrypted/</filename>, 3062 <filename>/etc/credstore.encrypted/</filename>, and 3063 <filename>/usr/lib/credstore.encrypted/</filename> are searched as well.</para> 3064 3065 <para>If the file system path is omitted it is chosen identical to the credential name, i.e. this is 3066 a terse way to declare credentials to inherit from the service manager into a service. This option 3067 may be used multiple times, each time defining an additional credential to pass to the unit.</para> 3068 3069 <para>If an absolute path referring to a directory is specified, every file in that directory 3070 (recursively) will be loaded as a separate credential. The ID for each credential will be the 3071 provided ID suffixed with <literal>_$FILENAME</literal> (e.g., <literal>Key_file1</literal>). When 3072 loading from a directory, symlinks will be ignored.</para> 3073 3074 <para>The contents of the file/socket may be arbitrary binary or textual data, including newline 3075 characters and <constant>NUL</constant> bytes.</para> 3076 3077 <para>The <varname>LoadCredentialEncrypted=</varname> setting is identical to 3078 <varname>LoadCredential=</varname>, except that the credential data is decrypted and authenticated 3079 before being passed on to the executed processes. Specifically, the referenced path should refer to a 3080 file or socket with an encrypted credential, as implemented by 3081 <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This 3082 credential is loaded, decrypted, authenticated and then passed to the application in plaintext form, 3083 in the same way a regular credential specified via <varname>LoadCredential=</varname> would be. A 3084 credential configured this way may be symmetrically encrypted/authenticated with a secret key derived 3085 from the system's TPM2 security chip, or with a secret key stored in 3086 <filename>/var/lib/systemd/credentials.secret</filename>, or with both. Using encrypted and 3087 authenticated credentials improves security as credentials are not stored in plaintext and only 3088 authenticated and decrypted into plaintext the moment a service requiring them is started. Moreover, 3089 credentials may be bound to the local hardware and installations, so that they cannot easily be 3090 analyzed offline, or be generated externally.</para> 3091 3092 <para>The credential files/IPC sockets must be accessible to the service manager, but don't have to 3093 be directly accessible to the unit's processes: the credential data is read and copied into separate, 3094 read-only copies for the unit that are accessible to appropriately privileged processes. This is 3095 particularly useful in combination with <varname>DynamicUser=</varname> as this way privileged data 3096 can be made available to processes running under a dynamic UID (i.e. not a previously known one) 3097 without having to open up access to all users.</para> 3098 3099 <para>In order to reference the path a credential may be read from within a 3100 <varname>ExecStart=</varname> command line use <literal>${CREDENTIALS_DIRECTORY}/mycred</literal>, 3101 e.g. <literal>ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred</literal>. In order to reference the path 3102 a credential may be read from within a <varname>Environment=</varname> line use 3103 <literal>%d/mycred</literal>, e.g. <literal>Environment=MYCREDPATH=%d/mycred</literal>.</para> 3104 3105 <para>Currently, an accumulated credential size limit of 1 MB per unit is enforced.</para> 3106 3107 <para>The service manager itself may receive system credentials that can be propagated to services 3108 from a hosting container manager or VM hypervisor. See the <ulink 3109 url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink> documentation for details 3110 about the former. For the latter, use the <command>qemu</command> <literal>fw_cfg</literal> node 3111 <literal>opt/io.systemd.credentials/</literal>. Example qemu switch: <literal>-fw_cfg 3112 name=opt/io.systemd.credentials/mycred,string=supersecret</literal>. They may also be specified on 3113 the kernel command line using the <literal>systemd.set_credential=</literal> switch (see 3114 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) 3115 and from the UEFI firmware environment via 3116 <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> 3117 3118 <para>If referencing an <constant>AF_UNIX</constant> stream socket to connect to, the connection will 3119 originate from an abstract namespace socket, that includes information about the unit and the 3120 credential ID in its socket name. Use <citerefentry 3121 project='man-pages'><refentrytitle>getpeername</refentrytitle><manvolnum>2</manvolnum></citerefentry> 3122 to query this information. The returned socket name is formatted as <constant>NUL</constant> 3123 <replaceable>RANDOM</replaceable> <literal>/unit/</literal> <replaceable>UNIT</replaceable> 3124 <literal>/</literal> <replaceable>ID</replaceable>, i.e. a <constant>NUL</constant> byte (as required 3125 for abstract namespace socket names), followed by a random string (consisting of alphadecimal 3126 characters), followed by the literal string <literal>/unit/</literal>, followed by the requesting 3127 unit name, followed by the literal character <literal>/</literal>, followed by the textual credential 3128 ID requested. Example: <literal>\0adf9d86b6eda275e/unit/foobar.service/credx</literal> in case the 3129 credential <literal>credx</literal> is requested for a unit <literal>foobar.service</literal>. This 3130 functionality is useful for using a single listening socket to serve credentials to multiple 3131 consumers.</para> 3132 3133 <para>For further information see <ulink url="https://systemd.io/CREDENTIALS">System and Service 3134 Credentials</ulink> documentation.</para></listitem> 3135 </varlistentry> 3136 3137 <varlistentry> 3138 <term><varname>SetCredential=</varname><replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></term> 3139 <term><varname>SetCredentialEncrypted=</varname><replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></term> 3140 3141 <listitem><para>The <varname>SetCredential=</varname> setting is similar to 3142 <varname>LoadCredential=</varname> but accepts a literal value to use as data for the credential, 3143 instead of a file system path to read the data from. Do not use this option for data that is supposed 3144 to be secret, as it is accessible to unprivileged processes via IPC. It's only safe to use this for 3145 user IDs, public key material and similar non-sensitive data. For everything else use 3146 <varname>LoadCredential=</varname>. In order to embed binary data into the credential data use 3147 C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to embed 3148 a <constant>NUL</constant> byte).</para> 3149 3150 <para>The <varname>SetCredentialEncrypted=</varname> setting is identical to 3151 <varname>SetCredential=</varname> but expects an encrypted credential in literal form as value. This 3152 allows embedding confidential credentials securely directly in unit files. Use 3153 <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry>' 3154 <option>-p</option> switch to generate suitable <varname>SetCredentialEncrypted=</varname> lines 3155 directly from plaintext credentials. For further details see 3156 <varname>LoadCredentialEncrypted=</varname> above.</para> 3157 3158 <para>If a credential of the same ID is listed in both <varname>LoadCredential=</varname> and 3159 <varname>SetCredential=</varname>, the latter will act as default if the former cannot be 3160 retrieved. In this case not being able to retrieve the credential from the path specified in 3161 <varname>LoadCredential=</varname> is not considered fatal.</para></listitem> 3162 </varlistentry> 3163 </variablelist> 3164 </refsect1> 3165 3166 <refsect1> 3167 <title>System V Compatibility</title> 3168 <variablelist class='unit-directives'> 3169 3170 <varlistentry> 3171 <term><varname>UtmpIdentifier=</varname></term> 3172 3173 <listitem><para>Takes a four character identifier string for an <citerefentry 3174 project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> and wtmp entry 3175 for this service. This should only be set for services such as <command>getty</command> implementations (such 3176 as <citerefentry 3177 project='die-net'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>) where utmp/wtmp 3178 entries must be created and cleared before and after execution, or for services that shall be executed as if 3179 they were run by a <command>getty</command> process (see below). If the configured string is longer than four 3180 characters, it is truncated and the terminal four characters are used. This setting interprets %I style string 3181 replacements. This setting is unset by default, i.e. no utmp/wtmp entries are created or cleaned up for this 3182 service.</para></listitem> 3183 </varlistentry> 3184 3185 <varlistentry> 3186 <term><varname>UtmpMode=</varname></term> 3187 3188 <listitem><para>Takes one of <literal>init</literal>, <literal>login</literal> or <literal>user</literal>. If 3189 <varname>UtmpIdentifier=</varname> is set, controls which type of <citerefentry 3190 project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>/wtmp entries 3191 for this service are generated. This setting has no effect unless <varname>UtmpIdentifier=</varname> is set 3192 too. If <literal>init</literal> is set, only an <constant>INIT_PROCESS</constant> entry is generated and the 3193 invoked process must implement a <command>getty</command>-compatible utmp/wtmp logic. If 3194 <literal>login</literal> is set, first an <constant>INIT_PROCESS</constant> entry, followed by a 3195 <constant>LOGIN_PROCESS</constant> entry is generated. In this case, the invoked process must implement a 3196 <citerefentry 3197 project='die-net'><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible 3198 utmp/wtmp logic. If <literal>user</literal> is set, first an <constant>INIT_PROCESS</constant> entry, then a 3199 <constant>LOGIN_PROCESS</constant> entry and finally a <constant>USER_PROCESS</constant> entry is 3200 generated. In this case, the invoked process may be any process that is suitable to be run as session 3201 leader. Defaults to <literal>init</literal>.</para></listitem> 3202 </varlistentry> 3203 3204 </variablelist> 3205 </refsect1> 3206 3207 <refsect1> 3208 <title>Environment Variables in Spawned Processes</title> 3209 3210 <para>Processes started by the service manager are executed with an environment variable block assembled from 3211 multiple sources. Processes started by the system service manager generally do not inherit environment variables 3212 set for the service manager itself (but this may be altered via <varname>PassEnvironment=</varname>), but processes 3213 started by the user service manager instances generally do inherit all environment variables set for the service 3214 manager itself.</para> 3215 3216 <para>For each invoked process the list of environment variables set is compiled from the following sources:</para> 3217 3218 <itemizedlist> 3219 <listitem><para>Variables globally configured for the service manager, using the 3220 <varname>DefaultEnvironment=</varname> setting in 3221 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 3222 the kernel command line option <varname>systemd.setenv=</varname> understood by 3223 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, or via 3224 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> 3225 <command>set-environment</command> verb.</para></listitem> 3226 3227 <listitem><para>Variables defined by the service manager itself (see the list below).</para></listitem> 3228 3229 <listitem><para>Variables set in the service manager's own environment variable block (subject to 3230 <varname>PassEnvironment=</varname> for the system service manager).</para></listitem> 3231 3232 <listitem><para>Variables set via <varname>Environment=</varname> in the unit file.</para></listitem> 3233 3234 <listitem><para>Variables read from files specified via <varname>EnvironmentFile=</varname> in the unit 3235 file.</para></listitem> 3236 3237 <listitem><para>Variables set by any PAM modules in case <varname>PAMName=</varname> is in effect, 3238 cf. <citerefentry 3239 project='man-pages'><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry>. 3240 </para></listitem> 3241 </itemizedlist> 3242 3243 <para>If the same environment variable is set by multiple of these sources, the later source — according 3244 to the order of the list above — wins. Note that as the final step all variables listed in 3245 <varname>UnsetEnvironment=</varname> are removed from the compiled environment variable list, immediately 3246 before it is passed to the executed process.</para> 3247 3248 <para>The general philosophy is to expose a small curated list of environment variables to processes. 3249 Services started by the system manager (PID 1) will be started, without additional service-specific 3250 configuration, with just a few environment variables. The user manager inherits environment variables as 3251 any other system service, but in addition may receive additional environment variables from PAM, and, 3252 typically, additional imported variables when the user starts a graphical session. It is recommended to 3253 keep the environment blocks in both the system and user managers lean. Importing all variables 3254 inherited by the graphical session or by one of the user shells is strongly discouraged.</para> 3255 3256 <para>Hint: <command>systemd-run -P env</command> and <command>systemd-run --user -P env</command> print 3257 the effective system and user service environment blocks.</para> 3258 3259 <refsect2> 3260 <title>Environment Variables Set or Propagated by the Service Manager</title> 3261 3262 <para>The following environment variables are propagated by the service manager or generated internally 3263 for each invoked process:</para> 3264 3265 <variablelist class='environment-variables'> 3266 <varlistentry> 3267 <term><varname>$PATH</varname></term> 3268 3269 <listitem><para>Colon-separated list of directories to use when launching 3270 executables. <command>systemd</command> uses a fixed value of 3271 <literal><filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename></literal> 3272 in the system manager. When compiled for systems with "unmerged <filename>/usr/</filename>" 3273 (<filename>/bin</filename> is not a symlink to <filename>/usr/bin</filename>), 3274 <literal>:<filename>/sbin</filename>:<filename>/bin</filename></literal> is appended. In case of 3275 the user manager, a different path may be configured by the distribution. It is recommended to 3276 not rely on the order of entries, and have only one program with a given name in 3277 <varname>$PATH</varname>.</para></listitem> 3278 </varlistentry> 3279 3280 <varlistentry> 3281 <term><varname>$LANG</varname></term> 3282 3283 <listitem><para>Locale. Can be set in <citerefentry 3284 project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> 3285 or on the kernel command line (see 3286 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and 3287 <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>). 3288 </para></listitem> 3289 </varlistentry> 3290 3291 <varlistentry> 3292 <term><varname>$USER</varname></term> 3293 <term><varname>$LOGNAME</varname></term> 3294 <term><varname>$HOME</varname></term> 3295 <term><varname>$SHELL</varname></term> 3296 3297 <listitem><para>User name (twice), home directory, and the 3298 login shell. The variables are set for the units that have 3299 <varname>User=</varname> set, which includes user 3300 <command>systemd</command> instances. See 3301 <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 3302 </para></listitem> 3303 </varlistentry> 3304 3305 <varlistentry> 3306 <term><varname>$INVOCATION_ID</varname></term> 3307 3308 <listitem><para>Contains a randomized, unique 128bit ID identifying each runtime cycle of the unit, formatted 3309 as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into 3310 an activating or active state, and may be used to identify this specific runtime cycle, in particular in data 3311 stored offline, such as the journal. The same ID is passed to all processes run as part of the 3312 unit.</para></listitem> 3313 </varlistentry> 3314 3315 <varlistentry> 3316 <term><varname>$XDG_RUNTIME_DIR</varname></term> 3317 3318 <listitem><para>The directory to use for runtime objects (such as IPC objects) and volatile state. Set for all 3319 services run by the user <command>systemd</command> instance, as well as any system services that use 3320 <varname>PAMName=</varname> with a PAM stack that includes <command>pam_systemd</command>. See below and 3321 <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more 3322 information.</para></listitem> 3323 </varlistentry> 3324 3325 <varlistentry> 3326 <term><varname>$RUNTIME_DIRECTORY</varname></term> 3327 <term><varname>$STATE_DIRECTORY</varname></term> 3328 <term><varname>$CACHE_DIRECTORY</varname></term> 3329 <term><varname>$LOGS_DIRECTORY</varname></term> 3330 <term><varname>$CONFIGURATION_DIRECTORY</varname></term> 3331 3332 <listitem><para>Absolute paths to the directories defined with 3333 <varname>RuntimeDirectory=</varname>, <varname>StateDirectory=</varname>, 3334 <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and 3335 <varname>ConfigurationDirectory=</varname> when those settings are used.</para> 3336 </listitem> 3337 </varlistentry> 3338 3339 <varlistentry> 3340 <term><varname>$CREDENTIALS_DIRECTORY</varname></term> 3341 3342 <listitem><para>An absolute path to the per-unit directory with credentials configured via 3343 <varname>LoadCredential=</varname>/<varname>SetCredential=</varname>. The directory is marked 3344 read-only and is placed in unswappable memory (if supported and permitted), and is only accessible to 3345 the UID associated with the unit via <varname>User=</varname> or <varname>DynamicUser=</varname> (and 3346 the superuser).</para></listitem> 3347 </varlistentry> 3348 3349 <varlistentry> 3350 <term><varname>$MAINPID</varname></term> 3351 3352 <listitem><para>The PID of the unit's main process if it is 3353 known. This is only set for control processes as invoked by 3354 <varname>ExecReload=</varname> and similar. </para></listitem> 3355 </varlistentry> 3356 3357 <varlistentry> 3358 <term><varname>$MANAGERPID</varname></term> 3359 3360 <listitem><para>The PID of the user <command>systemd</command> 3361 instance, set for processes spawned by it. </para></listitem> 3362 </varlistentry> 3363 3364 <varlistentry> 3365 <term><varname>$LISTEN_FDS</varname></term> 3366 <term><varname>$LISTEN_PID</varname></term> 3367 <term><varname>$LISTEN_FDNAMES</varname></term> 3368 3369 <listitem><para>Information about file descriptors passed to a 3370 service for socket activation. See 3371 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 3372 </para></listitem> 3373 </varlistentry> 3374 3375 <varlistentry> 3376 <term><varname>$NOTIFY_SOCKET</varname></term> 3377 3378 <listitem><para>The socket 3379 <function>sd_notify()</function> talks to. See 3380 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 3381 </para></listitem> 3382 </varlistentry> 3383 3384 <varlistentry> 3385 <term><varname>$WATCHDOG_PID</varname></term> 3386 <term><varname>$WATCHDOG_USEC</varname></term> 3387 3388 <listitem><para>Information about watchdog keep-alive notifications. See 3389 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 3390 </para></listitem> 3391 </varlistentry> 3392 3393 <varlistentry> 3394 <term><varname>$SYSTEMD_EXEC_PID</varname></term> 3395 3396 <listitem><para>The PID of the unit process (e.g. process invoked by 3397 <varname>ExecStart=</varname>). The child process can use this information to determine 3398 whether the process is directly invoked by the service manager or indirectly as a child of 3399 another process by comparing this value with the current PID (as similar to the scheme used in 3400 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> 3401 with <varname>$LISTEN_PID</varname> and <varname>$LISTEN_FDS</varname>).</para></listitem> 3402 </varlistentry> 3403 3404 <varlistentry> 3405 <term><varname>$TERM</varname></term> 3406 3407 <listitem><para>Terminal type, set only for units connected to 3408 a terminal (<varname>StandardInput=tty</varname>, 3409 <varname>StandardOutput=tty</varname>, or 3410 <varname>StandardError=tty</varname>). See 3411 <citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 3412 </para></listitem> 3413 </varlistentry> 3414 3415 <varlistentry> 3416 <term><varname>$LOG_NAMESPACE</varname></term> 3417 3418 <listitem><para>Contains the name of the selected logging namespace when the 3419 <varname>LogNamespace=</varname> service setting is used.</para></listitem> 3420 </varlistentry> 3421 3422 <varlistentry> 3423 <term><varname>$JOURNAL_STREAM</varname></term> 3424 3425 <listitem><para>If the standard output or standard error output of the executed processes are connected to the 3426 journal (for example, by setting <varname>StandardError=journal</varname>) <varname>$JOURNAL_STREAM</varname> 3427 contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a 3428 colon (<literal>:</literal>). This permits invoked processes to safely detect whether their standard output or 3429 standard error output are connected to the journal. The device and inode numbers of the file descriptors should 3430 be compared with the values set in the environment variable to determine whether the process output is still 3431 connected to the journal. Note that it is generally not sufficient to only check whether 3432 <varname>$JOURNAL_STREAM</varname> is set at all as services might invoke external processes replacing their 3433 standard output or standard error output, without unsetting the environment variable.</para> 3434 3435 <para>If both standard output and standard error of the executed processes are connected to the journal via a 3436 stream socket, this environment variable will contain information about the standard error stream, as that's 3437 usually the preferred destination for log data. (Note that typically the same stream is used for both standard 3438 output and standard error, hence very likely the environment variable contains device and inode information 3439 matching both stream file descriptors.)</para> 3440 3441 <para>This environment variable is primarily useful to allow services to optionally upgrade their used log 3442 protocol to the native journal protocol (using 3443 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and other 3444 functions) if their standard output or standard error output is connected to the journal anyway, thus enabling 3445 delivery of structured metadata along with logged messages.</para></listitem> 3446 </varlistentry> 3447 3448 <varlistentry> 3449 <term><varname>$SERVICE_RESULT</varname></term> 3450 3451 <listitem><para>Only used for the service unit type. This environment variable is passed to all 3452 <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service 3453 "result". Currently, the following values are defined:</para> 3454 3455 <table> 3456 <title>Defined <varname>$SERVICE_RESULT</varname> values</title> 3457 <tgroup cols='2'> 3458 <colspec colname='result'/> 3459 <colspec colname='meaning'/> 3460 <thead> 3461 <row> 3462 <entry>Value</entry> 3463 <entry>Meaning</entry> 3464 </row> 3465 </thead> 3466 3467 <tbody> 3468 <row> 3469 <entry><literal>success</literal></entry> 3470 <entry>The service ran successfully and exited cleanly.</entry> 3471 </row> 3472 <row> 3473 <entry><literal>protocol</literal></entry> 3474 <entry>A protocol violation occurred: the service did not take the steps required by its unit configuration (specifically what is configured in its <varname>Type=</varname> setting).</entry> 3475 </row> 3476 <row> 3477 <entry><literal>timeout</literal></entry> 3478 <entry>One of the steps timed out.</entry> 3479 </row> 3480 <row> 3481 <entry><literal>exit-code</literal></entry> 3482 <entry>Service process exited with a non-zero exit code; see <varname>$EXIT_CODE</varname> below for the actual exit code returned.</entry> 3483 </row> 3484 <row> 3485 <entry><literal>signal</literal></entry> 3486 <entry>A service process was terminated abnormally by a signal, without dumping core. See <varname>$EXIT_CODE</varname> below for the actual signal causing the termination.</entry> 3487 </row> 3488 <row> 3489 <entry><literal>core-dump</literal></entry> 3490 <entry>A service process terminated abnormally with a signal and dumped core. See <varname>$EXIT_CODE</varname> below for the signal causing the termination.</entry> 3491 </row> 3492 <row> 3493 <entry><literal>watchdog</literal></entry> 3494 <entry>Watchdog keep-alive ping was enabled for the service, but the deadline was missed.</entry> 3495 </row> 3496 <row> 3497 <entry><literal>start-limit-hit</literal></entry> 3498 <entry>A start limit was defined for the unit and it was hit, causing the unit to fail to start. See <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> for details.</entry> 3499 </row> 3500 <row> 3501 <entry><literal>resources</literal></entry> 3502 <entry>A catch-all condition in case a system operation failed.</entry> 3503 </row> 3504 </tbody> 3505 </tgroup> 3506 </table> 3507 3508 <para>This environment variable is useful to monitor failure or successful termination of a service. Even 3509 though this variable is available in both <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>, it 3510 is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services 3511 that managed to start up correctly, and the latter covers both services that failed during their start-up and 3512 those which failed during their runtime.</para></listitem> 3513 </varlistentry> 3514 3515 <varlistentry> 3516 <term><varname>$EXIT_CODE</varname></term> 3517 <term><varname>$EXIT_STATUS</varname></term> 3518 3519 <listitem><para>Only defined for the service unit type. These environment variables are passed to all 3520 <varname>ExecStop=</varname>, <varname>ExecStopPost=</varname> processes and contain exit status/code 3521 information of the main process of the service. For the precise definition of the exit code and status, see 3522 <citerefentry><refentrytitle>wait</refentrytitle><manvolnum>2</manvolnum></citerefentry>. <varname>$EXIT_CODE</varname> 3523 is one of <literal>exited</literal>, <literal>killed</literal>, 3524 <literal>dumped</literal>. <varname>$EXIT_STATUS</varname> contains the numeric exit code formatted as string 3525 if <varname>$EXIT_CODE</varname> is <literal>exited</literal>, and the signal name in all other cases. Note 3526 that these environment variables are only set if the service manager succeeded to start and identify the main 3527 process of the service.</para> 3528 3529 <table> 3530 <title>Summary of possible service result variable values</title> 3531 <tgroup cols='3'> 3532 <colspec colname='result' /> 3533 <colspec colname='code' /> 3534 <colspec colname='status' /> 3535 <thead> 3536 <row> 3537 <entry><varname>$SERVICE_RESULT</varname></entry> 3538 <entry><varname>$EXIT_CODE</varname></entry> 3539 <entry><varname>$EXIT_STATUS</varname></entry> 3540 </row> 3541 </thead> 3542 3543 <tbody> 3544 <row> 3545 <entry morerows="1" valign="top"><literal>success</literal></entry> 3546 <entry valign="top"><literal>killed</literal></entry> 3547 <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>TERM</literal>, <literal>PIPE</literal></entry> 3548 </row> 3549 <row> 3550 <entry valign="top"><literal>exited</literal></entry> 3551 <entry><literal>0</literal></entry> 3552 </row> 3553 <row> 3554 <entry morerows="1" valign="top"><literal>protocol</literal></entry> 3555 <entry valign="top">not set</entry> 3556 <entry>not set</entry> 3557 </row> 3558 <row> 3559 <entry><literal>exited</literal></entry> 3560 <entry><literal>0</literal></entry> 3561 </row> 3562 <row> 3563 <entry morerows="1" valign="top"><literal>timeout</literal></entry> 3564 <entry valign="top"><literal>killed</literal></entry> 3565 <entry><literal>TERM</literal>, <literal>KILL</literal></entry> 3566 </row> 3567 <row> 3568 <entry valign="top"><literal>exited</literal></entry> 3569 <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal 3570 >3</literal>, …, <literal>255</literal></entry> 3571 </row> 3572 <row> 3573 <entry valign="top"><literal>exit-code</literal></entry> 3574 <entry valign="top"><literal>exited</literal></entry> 3575 <entry><literal>1</literal>, <literal>2</literal>, <literal 3576 >3</literal>, …, <literal>255</literal></entry> 3577 </row> 3578 <row> 3579 <entry valign="top"><literal>signal</literal></entry> 3580 <entry valign="top"><literal>killed</literal></entry> 3581 <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>KILL</literal>, …</entry> 3582 </row> 3583 <row> 3584 <entry valign="top"><literal>core-dump</literal></entry> 3585 <entry valign="top"><literal>dumped</literal></entry> 3586 <entry><literal>ABRT</literal>, <literal>SEGV</literal>, <literal>QUIT</literal>, …</entry> 3587 </row> 3588 <row> 3589 <entry morerows="2" valign="top"><literal>watchdog</literal></entry> 3590 <entry><literal>dumped</literal></entry> 3591 <entry><literal>ABRT</literal></entry> 3592 </row> 3593 <row> 3594 <entry><literal>killed</literal></entry> 3595 <entry><literal>TERM</literal>, <literal>KILL</literal></entry> 3596 </row> 3597 <row> 3598 <entry><literal>exited</literal></entry> 3599 <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal 3600 >3</literal>, …, <literal>255</literal></entry> 3601 </row> 3602 <row> 3603 <entry valign="top"><literal>exec-condition</literal></entry> 3604 <entry><literal>exited</literal></entry> 3605 <entry><literal>1</literal>, <literal>2</literal>, <literal>3</literal>, <literal 3606 >4</literal>, …, <literal>254</literal></entry> 3607 </row> 3608 <row> 3609 <entry valign="top"><literal>oom-kill</literal></entry> 3610 <entry valign="top"><literal>killed</literal></entry> 3611 <entry><literal>TERM</literal>, <literal>KILL</literal></entry> 3612 </row> 3613 <row> 3614 <entry><literal>start-limit-hit</literal></entry> 3615 <entry>not set</entry> 3616 <entry>not set</entry> 3617 </row> 3618 <row> 3619 <entry><literal>resources</literal></entry> 3620 <entry>any of the above</entry> 3621 <entry>any of the above</entry> 3622 </row> 3623 <row> 3624 <entry namest="results" nameend="status">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 <literal>timeout</literal> and <literal>watchdog</literal> rows above only the signals that systemd sends have been included. Moreover, using <varname>SuccessExitStatus=</varname> additional exit statuses may be declared to indicate clean termination, which is not reflected by this table.</entry> 3625 </row> 3626 </tbody> 3627 </tgroup> 3628 </table></listitem> 3629 </varlistentry> 3630 3631 <varlistentry> 3632 <term><varname>$MONITOR_SERVICE_RESULT</varname></term> 3633 <term><varname>$MONITOR_EXIT_CODE</varname></term> 3634 <term><varname>$MONITOR_EXIT_STATUS</varname></term> 3635 <term><varname>$MONITOR_INVOCATION_ID</varname></term> 3636 <term><varname>$MONITOR_UNIT</varname></term> 3637 3638 <listitem><para>Only defined for the service unit type. Those environment variable are passed to 3639 all <varname>ExecStart=</varname> and <varname>ExecStartPre=</varname> processes which run in 3640 services triggered by <varname>OnFailure=</varname> or <varname>OnSuccess=</varname> dependencies. 3641 </para> 3642 3643 <para>Variables <varname>$MONITOR_SERVICE_RESULT</varname>, <varname>$MONITOR_EXIT_CODE</varname> 3644 and <varname>$MONITOR_EXIT_STATUS</varname> take the same values as for 3645 <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes. Variables 3646 <varname>$MONITOR_INVOCATION_ID</varname> and <varname>$MONITOR_UNIT</varname> are set to the 3647 invocaton id and unit name of the service which triggered the dependency.</para> 3648 3649 <para>Note that when multiple services trigger the same unit, those variables will be 3650 <emphasis>not</emphasis> be passed. Consider using a template handler unit for that case instead: 3651 <literal>OnFailure=<replaceable>handler</replaceable>@%n.service</literal> for non-templated units, 3652 or <literal>OnFailure=<replaceable>handler</replaceable>@%p-%i.service</literal> for templated 3653 units.</para></listitem> 3654 </varlistentry> 3655 3656 <varlistentry> 3657 <term><varname>$PIDFILE</varname></term> 3658 3659 <listitem><para>The path to the configured PID file, in case the process is forked off on behalf of 3660 a service that uses the <varname>PIDFile=</varname> setting, see 3661 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> 3662 for details. Service code may use this environment variable to automatically generate a PID file at 3663 the location configured in the unit file. This field is set to an absolute path in the file 3664 system.</para></listitem> 3665 </varlistentry> 3666 3667 </variablelist> 3668 3669 <para>For system services, when <varname>PAMName=</varname> is enabled and <command>pam_systemd</command> is part 3670 of the selected PAM stack, additional environment variables defined by systemd may be set for 3671 services. Specifically, these are <varname>$XDG_SEAT</varname>, <varname>$XDG_VTNR</varname>, see 3672 <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details.</para> 3673 </refsect2> 3674 3675 </refsect1> 3676 3677 <refsect1> 3678 <title>Process Exit Codes</title> 3679 3680 <para>When invoking a unit process the service manager possibly fails to apply the execution parameters configured 3681 with the settings above. In that case the already created service process will exit with a non-zero exit code 3682 before the configured command line is executed. (Or in other words, the child process possibly exits with these 3683 error codes, after having been created by the <citerefentry 3684 project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, but 3685 before the matching <citerefentry 3686 project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call is 3687 called.) Specifically, exit codes defined by the C library, by the LSB specification and by the systemd service 3688 manager itself are used.</para> 3689 3690 <para>The following basic service exit codes are defined by the C library.</para> 3691 3692 <table> 3693 <title>Basic C library exit codes</title> 3694 <tgroup cols='3'> 3695 <thead> 3696 <row> 3697 <entry>Exit Code</entry> 3698 <entry>Symbolic Name</entry> 3699 <entry>Description</entry> 3700 </row> 3701 </thead> 3702 <tbody> 3703 <row> 3704 <entry>0</entry> 3705 <entry><constant>EXIT_SUCCESS</constant></entry> 3706 <entry>Generic success code.</entry> 3707 </row> 3708 <row> 3709 <entry>1</entry> 3710 <entry><constant>EXIT_FAILURE</constant></entry> 3711 <entry>Generic failure or unspecified error.</entry> 3712 </row> 3713 </tbody> 3714 </tgroup> 3715 </table> 3716 3717 <para>The following service exit codes are defined by the <ulink 3718 url="https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB specification</ulink>. 3719 </para> 3720 3721 <table> 3722 <title>LSB service exit codes</title> 3723 <tgroup cols='3'> 3724 <thead> 3725 <row> 3726 <entry>Exit Code</entry> 3727 <entry>Symbolic Name</entry> 3728 <entry>Description</entry> 3729 </row> 3730 </thead> 3731 <tbody> 3732 <row> 3733 <entry>2</entry> 3734 <entry><constant>EXIT_INVALIDARGUMENT</constant></entry> 3735 <entry>Invalid or excess arguments.</entry> 3736 </row> 3737 <row> 3738 <entry>3</entry> 3739 <entry><constant>EXIT_NOTIMPLEMENTED</constant></entry> 3740 <entry>Unimplemented feature.</entry> 3741 </row> 3742 <row> 3743 <entry>4</entry> 3744 <entry><constant>EXIT_NOPERMISSION</constant></entry> 3745 <entry>The user has insufficient privileges.</entry> 3746 </row> 3747 <row> 3748 <entry>5</entry> 3749 <entry><constant>EXIT_NOTINSTALLED</constant></entry> 3750 <entry>The program is not installed.</entry> 3751 </row> 3752 <row> 3753 <entry>6</entry> 3754 <entry><constant>EXIT_NOTCONFIGURED</constant></entry> 3755 <entry>The program is not configured.</entry> 3756 </row> 3757 <row> 3758 <entry>7</entry> 3759 <entry><constant>EXIT_NOTRUNNING</constant></entry> 3760 <entry>The program is not running.</entry> 3761 </row> 3762 </tbody> 3763 </tgroup> 3764 </table> 3765 3766 <para> 3767 The LSB specification suggests that error codes 200 and above are reserved for implementations. Some of them are 3768 used by the service manager to indicate problems during process invocation: 3769 </para> 3770 <table> 3771 <title>systemd-specific exit codes</title> 3772 <tgroup cols='3'> 3773 <thead> 3774 <row> 3775 <entry>Exit Code</entry> 3776 <entry>Symbolic Name</entry> 3777 <entry>Description</entry> 3778 </row> 3779 </thead> 3780 <tbody> 3781 <row> 3782 <entry>200</entry> 3783 <entry><constant>EXIT_CHDIR</constant></entry> 3784 <entry>Changing to the requested working directory failed. See <varname>WorkingDirectory=</varname> above.</entry> 3785 </row> 3786 <row> 3787 <entry>201</entry> 3788 <entry><constant>EXIT_NICE</constant></entry> 3789 <entry>Failed to set up process scheduling priority (nice level). See <varname>Nice=</varname> above.</entry> 3790 </row> 3791 <row> 3792 <entry>202</entry> 3793 <entry><constant>EXIT_FDS</constant></entry> 3794 <entry>Failed to close unwanted file descriptors, or to adjust passed file descriptors.</entry> 3795 </row> 3796 <row> 3797 <entry>203</entry> 3798 <entry><constant>EXIT_EXEC</constant></entry> 3799 <entry>The actual process execution failed (specifically, the <citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call). Most likely this is caused by a missing or non-accessible executable file.</entry> 3800 </row> 3801 <row> 3802 <entry>204</entry> 3803 <entry><constant>EXIT_MEMORY</constant></entry> 3804 <entry>Failed to perform an action due to memory shortage.</entry> 3805 </row> 3806 <row> 3807 <entry>205</entry> 3808 <entry><constant>EXIT_LIMITS</constant></entry> 3809 <entry>Failed to adjust resource limits. See <varname>LimitCPU=</varname> and related settings above.</entry> 3810 </row> 3811 <row> 3812 <entry>206</entry> 3813 <entry><constant>EXIT_OOM_ADJUST</constant></entry> 3814 <entry>Failed to adjust the OOM setting. See <varname>OOMScoreAdjust=</varname> above.</entry> 3815 </row> 3816 <row> 3817 <entry>207</entry> 3818 <entry><constant>EXIT_SIGNAL_MASK</constant></entry> 3819 <entry>Failed to set process signal mask.</entry> 3820 </row> 3821 <row> 3822 <entry>208</entry> 3823 <entry><constant>EXIT_STDIN</constant></entry> 3824 <entry>Failed to set up standard input. See <varname>StandardInput=</varname> above.</entry> 3825 </row> 3826 <row> 3827 <entry>209</entry> 3828 <entry><constant>EXIT_STDOUT</constant></entry> 3829 <entry>Failed to set up standard output. See <varname>StandardOutput=</varname> above.</entry> 3830 </row> 3831 <row> 3832 <entry>210</entry> 3833 <entry><constant>EXIT_CHROOT</constant></entry> 3834 <entry>Failed to change root directory (<citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>). See <varname>RootDirectory=</varname>/<varname>RootImage=</varname> above.</entry> 3835 </row> 3836 <row> 3837 <entry>211</entry> 3838 <entry><constant>EXIT_IOPRIO</constant></entry> 3839 <entry>Failed to set up IO scheduling priority. See <varname>IOSchedulingClass=</varname>/<varname>IOSchedulingPriority=</varname> above.</entry> 3840 </row> 3841 <row> 3842 <entry>212</entry> 3843 <entry><constant>EXIT_TIMERSLACK</constant></entry> 3844 <entry>Failed to set up timer slack. See <varname>TimerSlackNSec=</varname> above.</entry> 3845 </row> 3846 <row> 3847 <entry>213</entry> 3848 <entry><constant>EXIT_SECUREBITS</constant></entry> 3849 <entry>Failed to set process secure bits. See <varname>SecureBits=</varname> above.</entry> 3850 </row> 3851 <row> 3852 <entry>214</entry> 3853 <entry><constant>EXIT_SETSCHEDULER</constant></entry> 3854 <entry>Failed to set up CPU scheduling. See <varname>CPUSchedulingPolicy=</varname>/<varname>CPUSchedulingPriority=</varname> above.</entry> 3855 </row> 3856 <row> 3857 <entry>215</entry> 3858 <entry><constant>EXIT_CPUAFFINITY</constant></entry> 3859 <entry>Failed to set up CPU affinity. See <varname>CPUAffinity=</varname> above.</entry> 3860 </row> 3861 <row> 3862 <entry>216</entry> 3863 <entry><constant>EXIT_GROUP</constant></entry> 3864 <entry>Failed to determine or change group credentials. See <varname>Group=</varname>/<varname>SupplementaryGroups=</varname> above.</entry> 3865 </row> 3866 <row> 3867 <entry>217</entry> 3868 <entry><constant>EXIT_USER</constant></entry> 3869 <entry>Failed to determine or change user credentials, or to set up user namespacing. See <varname>User=</varname>/<varname>PrivateUsers=</varname> above.</entry> 3870 </row> 3871 <row> 3872 <entry>218</entry> 3873 <entry><constant>EXIT_CAPABILITIES</constant></entry> 3874 <entry>Failed to drop capabilities, or apply ambient capabilities. See <varname>CapabilityBoundingSet=</varname>/<varname>AmbientCapabilities=</varname> above.</entry> 3875 </row> 3876 <row> 3877 <entry>219</entry> 3878 <entry><constant>EXIT_CGROUP</constant></entry> 3879 <entry>Setting up the service control group failed.</entry> 3880 </row> 3881 <row> 3882 <entry>220</entry> 3883 <entry><constant>EXIT_SETSID</constant></entry> 3884 <entry>Failed to create new process session.</entry> 3885 </row> 3886 <row> 3887 <entry>221</entry> 3888 <entry><constant>EXIT_CONFIRM</constant></entry> 3889 <entry>Execution has been cancelled by the user. See the <varname>systemd.confirm_spawn=</varname> kernel command line setting on <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details.</entry> 3890 </row> 3891 <row> 3892 <entry>222</entry> 3893 <entry><constant>EXIT_STDERR</constant></entry> 3894 <entry>Failed to set up standard error output. See <varname>StandardError=</varname> above.</entry> 3895 </row> 3896 <row> 3897 <entry>224</entry> 3898 <entry><constant>EXIT_PAM</constant></entry> 3899 <entry>Failed to set up PAM session. See <varname>PAMName=</varname> above.</entry> 3900 </row> 3901 <row> 3902 <entry>225</entry> 3903 <entry><constant>EXIT_NETWORK</constant></entry> 3904 <entry>Failed to set up network namespacing. See <varname>PrivateNetwork=</varname> above.</entry> 3905 </row> 3906 <row> 3907 <entry>226</entry> 3908 <entry><constant>EXIT_NAMESPACE</constant></entry> 3909 <entry>Failed to set up mount, UTS, or IPC namespacing. See <varname>ReadOnlyPaths=</varname>, <varname>ProtectHostname=</varname>, <varname>PrivateIPC=</varname>, and related settings above.</entry> 3910 </row> 3911 <row> 3912 <entry>227</entry> 3913 <entry><constant>EXIT_NO_NEW_PRIVILEGES</constant></entry> 3914 <entry>Failed to disable new privileges. See <varname>NoNewPrivileges=yes</varname> above.</entry> 3915 </row> 3916 <row> 3917 <entry>228</entry> 3918 <entry><constant>EXIT_SECCOMP</constant></entry> 3919 <entry>Failed to apply system call filters. See <varname>SystemCallFilter=</varname> and related settings above.</entry> 3920 </row> 3921 <row> 3922 <entry>229</entry> 3923 <entry><constant>EXIT_SELINUX_CONTEXT</constant></entry> 3924 <entry>Determining or changing SELinux context failed. See <varname>SELinuxContext=</varname> above.</entry> 3925 </row> 3926 <row> 3927 <entry>230</entry> 3928 <entry><constant>EXIT_PERSONALITY</constant></entry> 3929 <entry>Failed to set up an execution domain (personality). See <varname>Personality=</varname> above.</entry> 3930 </row> 3931 <row> 3932 <entry>231</entry> 3933 <entry><constant>EXIT_APPARMOR_PROFILE</constant></entry> 3934 <entry>Failed to prepare changing AppArmor profile. See <varname>AppArmorProfile=</varname> above.</entry> 3935 </row> 3936 <row> 3937 <entry>232</entry> 3938 <entry><constant>EXIT_ADDRESS_FAMILIES</constant></entry> 3939 <entry>Failed to restrict address families. See <varname>RestrictAddressFamilies=</varname> above.</entry> 3940 </row> 3941 <row> 3942 <entry>233</entry> 3943 <entry><constant>EXIT_RUNTIME_DIRECTORY</constant></entry> 3944 <entry>Setting up runtime directory failed. See <varname>RuntimeDirectory=</varname> and related settings above.</entry> 3945 </row> 3946 <row> 3947 <entry>235</entry> 3948 <entry><constant>EXIT_CHOWN</constant></entry> 3949 <entry>Failed to adjust socket ownership. Used for socket units only.</entry> 3950 </row> 3951 <row> 3952 <entry>236</entry> 3953 <entry><constant>EXIT_SMACK_PROCESS_LABEL</constant></entry> 3954 <entry>Failed to set SMACK label. See <varname>SmackProcessLabel=</varname> above.</entry> 3955 </row> 3956 <row> 3957 <entry>237</entry> 3958 <entry><constant>EXIT_KEYRING</constant></entry> 3959 <entry>Failed to set up kernel keyring.</entry> 3960 </row> 3961 <row> 3962 <entry>238</entry> 3963 <entry><constant>EXIT_STATE_DIRECTORY</constant></entry> 3964 <entry>Failed to set up unit's state directory. See <varname>StateDirectory=</varname> above.</entry> 3965 </row> 3966 <row> 3967 <entry>239</entry> 3968 <entry><constant>EXIT_CACHE_DIRECTORY</constant></entry> 3969 <entry>Failed to set up unit's cache directory. See <varname>CacheDirectory=</varname> above.</entry> 3970 </row> 3971 <row> 3972 <entry>240</entry> 3973 <entry><constant>EXIT_LOGS_DIRECTORY</constant></entry> 3974 <entry>Failed to set up unit's logging directory. See <varname>LogsDirectory=</varname> above.</entry> 3975 </row> 3976 <row> 3977 <entry>241</entry> 3978 <entry><constant>EXIT_CONFIGURATION_DIRECTORY</constant></entry> 3979 <entry>Failed to set up unit's configuration directory. See <varname>ConfigurationDirectory=</varname> above.</entry> 3980 </row> 3981 <row> 3982 <entry>242</entry> 3983 <entry><constant>EXIT_NUMA_POLICY</constant></entry> 3984 <entry>Failed to set up unit's NUMA memory policy. See <varname>NUMAPolicy=</varname> and <varname>NUMAMask=</varname> above.</entry> 3985 </row> 3986 <row> 3987 <entry>243</entry> 3988 <entry><constant>EXIT_CREDENTIALS</constant></entry> 3989 <entry>Failed to set up unit's credentials. See <varname>LoadCredential=</varname> and <varname>SetCredential=</varname> above.</entry> 3990 </row> 3991 <row> 3992 <entry>245</entry> 3993 <entry><constant>EXIT_BPF</constant></entry> 3994 <entry>Failed to apply BPF restrictions. See <varname>RestrictFileSystems=</varname> above.</entry> 3995 </row> 3996 </tbody> 3997 </tgroup> 3998 </table> 3999 4000 <para>Finally, the BSD operating systems define a set of exit codes, typically defined on Linux systems too:</para> 4001 4002 <table> 4003 <title>BSD exit codes</title> 4004 <tgroup cols='3'> 4005 <thead> 4006 <row> 4007 <entry>Exit Code</entry> 4008 <entry>Symbolic Name</entry> 4009 <entry>Description</entry> 4010 </row> 4011 </thead> 4012 <tbody> 4013 <row> 4014 <entry>64</entry> 4015 <entry><constant>EX_USAGE</constant></entry> 4016 <entry>Command line usage error</entry> 4017 </row> 4018 <row> 4019 <entry>65</entry> 4020 <entry><constant>EX_DATAERR</constant></entry> 4021 <entry>Data format error</entry> 4022 </row> 4023 <row> 4024 <entry>66</entry> 4025 <entry><constant>EX_NOINPUT</constant></entry> 4026 <entry>Cannot open input</entry> 4027 </row> 4028 <row> 4029 <entry>67</entry> 4030 <entry><constant>EX_NOUSER</constant></entry> 4031 <entry>Addressee unknown</entry> 4032 </row> 4033 <row> 4034 <entry>68</entry> 4035 <entry><constant>EX_NOHOST</constant></entry> 4036 <entry>Host name unknown</entry> 4037 </row> 4038 <row> 4039 <entry>69</entry> 4040 <entry><constant>EX_UNAVAILABLE</constant></entry> 4041 <entry>Service unavailable</entry> 4042 </row> 4043 <row> 4044 <entry>70</entry> 4045 <entry><constant>EX_SOFTWARE</constant></entry> 4046 <entry>internal software error</entry> 4047 </row> 4048 <row> 4049 <entry>71</entry> 4050 <entry><constant>EX_OSERR</constant></entry> 4051 <entry>System error (e.g., can't fork)</entry> 4052 </row> 4053 <row> 4054 <entry>72</entry> 4055 <entry><constant>EX_OSFILE</constant></entry> 4056 <entry>Critical OS file missing</entry> 4057 </row> 4058 <row> 4059 <entry>73</entry> 4060 <entry><constant>EX_CANTCREAT</constant></entry> 4061 <entry>Can't create (user) output file</entry> 4062 </row> 4063 <row> 4064 <entry>74</entry> 4065 <entry><constant>EX_IOERR</constant></entry> 4066 <entry>Input/output error</entry> 4067 </row> 4068 <row> 4069 <entry>75</entry> 4070 <entry><constant>EX_TEMPFAIL</constant></entry> 4071 <entry>Temporary failure; user is invited to retry</entry> 4072 </row> 4073 <row> 4074 <entry>76</entry> 4075 <entry><constant>EX_PROTOCOL</constant></entry> 4076 <entry>Remote error in protocol</entry> 4077 </row> 4078 <row> 4079 <entry>77</entry> 4080 <entry><constant>EX_NOPERM</constant></entry> 4081 <entry>Permission denied</entry> 4082 </row> 4083 <row> 4084 <entry>78</entry> 4085 <entry><constant>EX_CONFIG</constant></entry> 4086 <entry>Configuration error</entry> 4087 </row> 4088 </tbody> 4089 </tgroup> 4090 </table> 4091 </refsect1> 4092 4093 <refsect1> 4094 <title>Examples</title> 4095 4096 <example> 4097 <title><varname>$MONITOR_<replaceable>*</replaceable></varname> usage</title> 4098 4099 <para>A service <filename index="false">myfailer.service</filename> which can trigger an 4100 <varname>OnFailure=</varname> dependency.</para> 4101 4102 <programlisting> 4103[Unit] 4104Description=Service which can trigger an OnFailure= dependency 4105OnFailure=myhandler.service 4106 4107[Service] 4108ExecStart=/bin/myprogram 4109 </programlisting> 4110 4111 <para>A service <filename index="false">mysuccess.service</filename> which can trigger an 4112 <varname>OnSuccess=</varname> dependency.</para> 4113 4114 <programlisting> 4115[Unit] 4116Description=Service which can trigger an OnSuccess= dependency 4117OnSuccess=myhandler.service 4118 4119[Service] 4120ExecStart=/bin/mysecondprogram 4121 </programlisting> 4122 4123 <para>A service <filename index="false">myhandler.service</filename> which can be triggered 4124 by any of the above services.</para> 4125 4126 <programlisting> 4127[Unit] 4128Description=Acts on service failing or succeeding 4129 4130[Service] 4131ExecStart=/bin/bash -c "echo $MONITOR_SERVICE_RESULT $MONITOR_EXIT_CODE $MONITOR_EXIT_STATUS $MONITOR_INVOCATION_ID $MONITOR_UNIT" 4132 </programlisting> 4133 4134 <para>If <filename index="false">myfailer.service</filename> were to run and exit in failure, 4135 then <filename index="false">myhandler.service</filename> would be triggered and the 4136 monitor variables would be set as follows:</para> 4137 4138 <programlisting> 4139MONITOR_SERVICE_RESULT=exit-code 4140MONITOR_EXIT_CODE=exited 4141MONITOR_EXIT_STATUS=1 4142MONITOR_INVOCATION_ID=cc8fdc149b2b4ca698d4f259f4054236 4143MONITOR_UNIT=myfailer.service 4144 </programlisting> 4145 4146 <para>If <filename index="false">mysuccess.service</filename> were to run and exit in success, 4147 then <filename index="false">myhandler.service</filename> would be triggered and the 4148 monitor variables would be set as follows:</para> 4149 4150 <programlisting> 4151MONITOR_SERVICE_RESULT=success 4152MONITOR_EXIT_CODE=exited 4153MONITOR_EXIT_STATUS=0 4154MONITOR_INVOCATION_ID=6ab9af147b8c4a3ebe36e7a5f8611697 4155MONITOR_UNIT=mysuccess.service 4156 </programlisting> 4157 4158 </example> 4159 4160 </refsect1> 4161 4162 <refsect1> 4163 <title>See Also</title> 4164 <para> 4165 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 4166 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 4167 <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 4168 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 4169 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4170 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4171 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4172 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4173 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4174 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4175 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4176 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4177 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, 4178 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, 4179 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 4180 <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 4181 <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry> 4182 </para> 4183 </refsect1> 4184 4185</refentry> 4186