<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd.exec" xmlns:xi="http://www.w3.org/2001/XInclude">
<programlisting>BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout</programlisting>
</example>
+ <xi:include href="vpick.xml" xpointer="directory"/>
+
<xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem>
</varlistentry>
or loopback file instead of a directory. The device node or file system image file needs to contain a
file system without a partition table, or a file system within an MBR/MS-DOS or GPT partition table
with only a single Linux-compatible partition, or a set of file systems within a GPT partition table
- that follows the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
- Specification</ulink>.</para>
+ that follows the
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
+ Discoverable Partitions Specification</ulink>.</para>
<para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or
<literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is
<citerefentry><refentrytitle>systemd-soft-reboot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
in case the service is configured to survive it.</para>
+ <xi:include href="vpick.xml" xpointer="image"/>
+
<xi:include href="system-only.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
- <para>Valid partition names follow the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>:
+ <para>Valid partition names follow the
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
+ Discoverable Partitions Specification</ulink>:
<constant>root</constant>, <constant>usr</constant>, <constant>home</constant>, <constant>srv</constant>,
<constant>esp</constant>, <constant>xbootldr</constant>, <constant>tmp</constant>,
<constant>var</constant>.</para>
<para>To make sure making ephemeral copies can be made efficiently, the root directory or root image
should be located on the same filesystem as <filename>/var/lib/systemd/ephemeral-trees/</filename>.
- When using <varname>RootEphemeral=</varname> with root directories, btrfs should be used as the
- filesystem and the root directory should ideally be a subvolume which <command>systemd</command> can
- snapshot to make the ephemeral copy. For root images, a filesystem with support for reflinks should
- be used to ensure an efficient ephemeral copy.</para>
+ When using <varname>RootEphemeral=</varname> with root directories,
+ <citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs-man5.html'>btrfs</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ should be used as the filesystem and the root directory should ideally be a subvolume which
+ <command>systemd</command> can snapshot to make the ephemeral copy. For root images, a filesystem
+ with support for reflinks should be used to ensure an efficient ephemeral copy.</para>
<xi:include href="system-only.xml" xpointer="singular"/>
<para>This option is supported only for disk images that contain a single file system, without an
enveloping partition table. Images that contain a GPT partition table should instead include both
- root file system and matching Verity data in the same image, implementing the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>.</para>
+ root file system and matching Verity data in the same image, implementing the
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
+ Discoverable Partitions Specification</ulink>.</para>
<xi:include href="system-only.xml" xpointer="singular"/>
<varname>PrivateDevices=</varname> below, as it may change the setting of
<varname>DevicePolicy=</varname>.</para>
+ <xi:include href="vpick.xml" xpointer="image"/>
+
<xi:include href="system-only.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
<para>Note that usage from user units requires overlayfs support in unprivileged user namespaces,
which was first introduced in kernel v5.11.</para>
+ <xi:include href="vpick.xml" xpointer="directory"/>
+
<xi:include href="system-or-user-ns.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
<varlistentry>
<term><varname>SetLoginEnvironment=</varname></term>
- <listitem><para>Takes a boolean parameter that controls whether to set <varname>$HOME</varname>,
- <varname>$LOGNAME</varname>, and <varname>$SHELL</varname> environment variables. If unset, this is
- controlled by whether <varname>User=</varname> is set. If true, they will always be set for system services,
- i.e. even when the default user <literal>root</literal> is used. If false, the mentioned variables are not set
- by systemd, no matter whether <varname>User=</varname> is used or not. This option normally has no effect
- on user services, since these variables are typically inherited from user manager's own environment anyway.</para>
+ <listitem><para>Takes a boolean parameter that controls whether to set the <varname>$HOME</varname>,
+ <varname>$LOGNAME</varname>, and <varname>$SHELL</varname> environment variables. If not set, this
+ defaults to true if <varname>User=</varname>, <varname>DynamicUser=</varname> or
+ <varname>PAMName=</varname> are set, false otherwise. If set to true, the variables will always be
+ set for system services, i.e. even when the default user <literal>root</literal> is used. If set to
+ false, the mentioned variables are not set by the service manager, no matter whether
+ <varname>User=</varname>, <varname>DynamicUser=</varname>, or <varname>PAMName=</varname> are used or
+ not. This option normally has no effect on services of the per-user service manager, since in that
+ case these variables are typically inherited from user manager's own environment anyway.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<listitem><para>Takes a boolean argument. If true, ensures that the service process and all its
children can never gain new privileges through <function>execve()</function> (e.g. via setuid or
setgid bits, or filesystem capabilities). This is the simplest and most effective way to ensure that
- a process and its children can never elevate privileges again. Defaults to false, but certain
- settings override this and ignore the value of this setting. This is the case when
- <varname>DynamicUser=</varname>, <varname>LockPersonality=</varname>,
- <varname>MemoryDenyWriteExecute=</varname>, <varname>PrivateDevices=</varname>,
- <varname>ProtectClock=</varname>, <varname>ProtectHostname=</varname>,
- <varname>ProtectKernelLogs=</varname>, <varname>ProtectKernelModules=</varname>,
- <varname>ProtectKernelTunables=</varname>, <varname>RestrictAddressFamilies=</varname>,
- <varname>RestrictNamespaces=</varname>, <varname>RestrictRealtime=</varname>,
- <varname>RestrictSUIDSGID=</varname>, <varname>SystemCallArchitectures=</varname>,
- <varname>SystemCallFilter=</varname>, or <varname>SystemCallLog=</varname> are specified. Note that
- even if this setting is overridden by them, <command>systemctl show</command> shows the original
- value of this setting. In case the service will be run in a new mount namespace anyway and SELinux is
- disabled, all file systems are mounted with <constant>MS_NOSUID</constant> flag. Also see <ulink
- url="https://docs.kernel.org/userspace-api/no_new_privs.html">No New Privileges
- Flag</ulink>.</para>
+ a process and its children can never elevate privileges again. Defaults to false. In case the service
+ will be run in a new mount namespace anyway and SELinux is disabled, all file systems are mounted with
+ <constant>MS_NOSUID</constant> flag. Also see <ulink
+ url="https://docs.kernel.org/userspace-api/no_new_privs.html">No New Privileges Flag</ulink>.
+ </para>
<para>Note that this setting only has an effect on the unit's processes themselves (or any processes
directly or indirectly forked off them). It has no effect on processes potentially invoked on request
<varlistentry>
<term><varname>IgnoreSIGPIPE=</varname></term>
- <listitem><para>Takes a boolean argument. If true, causes <constant>SIGPIPE</constant> to be ignored in the
- executed process. Defaults to true because <constant>SIGPIPE</constant> generally is useful only in shell
- pipelines.</para></listitem>
+ <listitem><para>Takes a boolean argument. If true, <constant>SIGPIPE</constant> is ignored in the
+ executed process. Defaults to true since <constant>SIGPIPE</constant> is generally only useful in
+ shell pipelines.</para></listitem>
</varlistentry>
</variablelist>
permit this. Nest <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in
order to provide writable subdirectories within read-only directories. Use
<varname>ReadWritePaths=</varname> in order to allow-list specific paths for write access if
- <varname>ProtectSystem=strict</varname> is used.</para>
+ <varname>ProtectSystem=strict</varname> is used. Note that <varname>ReadWritePaths=</varname> cannot
+ be used to gain write access to a file system whose superblock is mounted read-only. On Linux, for
+ each mount point write access is granted only if the mount point itself <emphasis>and</emphasis> the
+ file system superblock backing it are not marked read-only. <varname>ReadWritePaths=</varname> only
+ controls the former, not the latter, hence a read-only file system superblock remains
+ protected.</para>
<para>Paths listed in <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside
the namespace along with everything below them in the file system hierarchy. This may be more restrictive than
<citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> of
<filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. For this setting the
same restrictions regarding mount propagation and privileges apply as for
- <varname>ReadOnlyPaths=</varname> and related calls, see above. If turned on and if running in user
- mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
- <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.</para>
+ <varname>ReadOnlyPaths=</varname> and related calls, see above.</para>
<para>Note that the implementation of this setting might be impossible (for example if mount
namespaces are not available), and the unit should be written in a way that does not solely rely on
<para>Note that this functionality might not be available, for example if KSM is disabled in the
kernel, or the kernel doesn't support controlling KSM at the process level through
- <function>prctl()</function>.</para>
+ <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
the system into the service, it is hence not suitable for services that need to take notice of system
hostname changes dynamically.</para>
- <para>If this setting is on, but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant>
- capability (e.g. services for which <varname>User=</varname> is set),
- <varname>NoNewPrivileges=yes</varname> is implied.</para>
-
<xi:include href="system-or-user-ns.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v242"/></listitem>
Effectively, <filename>/dev/rtc0</filename>, <filename>/dev/rtc1</filename>, etc. are made read-only
to the service. See
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for the details about <varname>DeviceAllow=</varname>. If this setting is on, but the unit doesn't
- have the <constant>CAP_SYS_ADMIN</constant> capability (e.g. services for which
- <varname>User=</varname> is set), <varname>NoNewPrivileges=yes</varname> is implied.</para>
+ for the details about <varname>DeviceAllow=</varname>.</para>
<para>It is recommended to turn this on for most services that do not need modify the clock or check
its state.</para>
<citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> mechanism. Few
services need to write to these at runtime; it is hence recommended to turn this on for most services. For this
setting the same restrictions regarding mount propagation and privileges apply as for
- <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off. If this
- setting is on, but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant> capability
- (e.g. services for which <varname>User=</varname> is set),
- <varname>NoNewPrivileges=yes</varname> is implied. Note that this option does not prevent
- indirect changes to kernel tunables effected by IPC calls to other processes. However,
- <varname>InaccessiblePaths=</varname> may be used to make relevant IPC file system objects
- inaccessible. If <varname>ProtectKernelTunables=</varname> is set,
+ <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off.
+ Note that this option does not prevent indirect changes to kernel tunables effected by IPC calls to
+ other processes. However, <varname>InaccessiblePaths=</varname> may be used to make relevant IPC file system
+ objects inaccessible. If <varname>ProtectKernelTunables=</varname> is set,
<varname>MountAPIVFS=yes</varname> is implied.</para>
<xi:include href="system-or-user-ns.xml" xpointer="singular"/>
both privileged and unprivileged. To disable module auto-load feature please see
<citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<constant>kernel.modules_disabled</constant> mechanism and
- <filename>/proc/sys/kernel/modules_disabled</filename> documentation. If this setting is on,
- but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant> capability (e.g. services for
- which <varname>User=</varname> is set), <varname>NoNewPrivileges=yes</varname> is implied.</para>
+ <filename>/proc/sys/kernel/modules_disabled</filename> documentation.</para>
<xi:include href="system-or-user-ns.xml" xpointer="singular"/>
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for userspace logging). The kernel exposes its log buffer to userspace via <filename>/dev/kmsg</filename> and
<filename>/proc/kmsg</filename>. If enabled, these are made inaccessible to all the processes in the unit.
- If this setting is on, but the unit doesn't have the <constant>CAP_SYS_ADMIN</constant>
- capability (e.g. services for which <varname>User=</varname> is set),
- <varname>NoNewPrivileges=yes</varname> is implied.</para>
+ </para>
<xi:include href="system-or-user-ns.xml" xpointer="singular"/>
including x86-64). Note that on systems supporting multiple ABIs (such as x86/x86-64) it is
recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the
restrictions of this option. Specifically, it is recommended to combine this option with
- <varname>SystemCallArchitectures=native</varname> or similar. If running in user mode, or in system
- mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
- <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied. By default, no
- restrictions apply, all address families are accessible to processes. If assigned the empty string,
- any previous address family restriction changes are undone. This setting does not affect commands
- prefixed with <literal>+</literal>.</para>
+ <varname>SystemCallArchitectures=native</varname> or similar. By default, no restrictions apply, all
+ address families are accessible to processes. If assigned the empty string, any previous address family
+ restriction changes are undone. This setting does not affect commands prefixed with <literal>+</literal>.</para>
<para>Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive
network protocols, such as <constant>AF_PACKET</constant>. Note that in most cases, the local
creation and switching of the specified types of namespaces (or all of them, if true) access to the
<function>setns()</function> system call with a zero flags parameter is prohibited. This setting is only
supported on x86, x86-64, mips, mips-le, mips64, mips64-le, mips64-n32, mips64-le-n32, ppc64, ppc64-le, s390
- and s390x, and enforces no restrictions on other architectures. If running in user mode, or in system mode, but
- without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>),
- <varname>NoNewPrivileges=yes</varname> is implied.</para>
+ and s390x, and enforces no restrictions on other architectures.</para>
<para>Example: if a unit has the following,
<programlisting>RestrictNamespaces=cgroup ipc
project='man-pages'><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry> system
call so that the kernel execution domain may not be changed from the default or the personality selected with
<varname>Personality=</varname> directive. This may be useful to improve security, because odd personality
- emulations may be poorly tested and source of vulnerabilities. If running in user mode, or in system mode, but
- without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>),
- <varname>NoNewPrivileges=yes</varname> is implied.</para>
+ emulations may be poorly tested and source of vulnerabilities.</para>
<xi:include href="version-info.xml" xpointer="v235"/></listitem>
</varlistentry>
available on x86. Note that on systems supporting multiple ABIs (such as x86/x86-64) it is
recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the
restrictions of this option. Specifically, it is recommended to combine this option with
- <varname>SystemCallArchitectures=native</varname> or similar. If running in user mode, or in system
- mode, but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
- <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied.</para>
+ <varname>SystemCallArchitectures=native</varname> or similar.</para>
<xi:include href="version-info.xml" xpointer="v231"/></listitem>
</varlistentry>
the unit are refused. This restricts access to realtime task scheduling policies such as
<constant>SCHED_FIFO</constant>, <constant>SCHED_RR</constant> or <constant>SCHED_DEADLINE</constant>. See
<citerefentry project='man-pages'><refentrytitle>sched</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for details about these scheduling policies. If running in user mode, or in system mode, but without the
- <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>),
- <varname>NoNewPrivileges=yes</varname> is implied. Realtime scheduling policies may be used to monopolize CPU
+ for details about these scheduling policies. Realtime scheduling policies may be used to monopolize CPU
time for longer periods of time, and may hence be used to lock up or otherwise trigger Denial-of-Service
situations on the system. It is hence recommended to restrict access to realtime scheduling to the few programs
that actually require them. Defaults to off.</para>
<listitem><para>Takes a boolean argument. If set, any attempts to set the set-user-ID (SUID) or
set-group-ID (SGID) bits on files or directories will be denied (for details on these bits see
<citerefentry
- project='man-pages'><refentrytitle>inode</refentrytitle><manvolnum>7</manvolnum></citerefentry>). If
- running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant>
- capability (e.g. setting <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is
- implied. As the SUID/SGID bits are mechanisms to elevate privileges, and allow users to acquire the
+ project='man-pages'><refentrytitle>inode</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ As the SUID/SGID bits are mechanisms to elevate privileges, and allow users to acquire the
identity of other users, it is recommended to restrict creation of SUID/SGID files to the few
programs that actually require them. Note that this restricts marking of any type of file system
object with these bits, including both regular files and directories (where the SGID is a different
units, it only enables sharing of the <filename>/tmp/</filename> and <filename>/var/tmp/</filename>
directories.</para>
- <para>Other file system namespace unit settings — <varname>PrivateMounts=</varname>,
- <varname>PrivateTmp=</varname>, <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>,
- <varname>ProtectHome=</varname>, <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname>,
- <varname>ReadWritePaths=</varname>, … — also enable file system namespacing in a fashion equivalent to this
- option. Hence it is primarily useful to explicitly request this behaviour if none of the other settings are
- used.</para>
+ <para>Other file system namespace unit settings — <varname>PrivateTmp=</varname>,
+ <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>,
+ <varname>ProtectHome=</varname>, <varname>ReadOnlyPaths=</varname>,
+ <varname>InaccessiblePaths=</varname>, <varname>ReadWritePaths=</varname>, … — also enable file
+ system namespacing in a fashion equivalent to this option. Hence it is primarily useful to explicitly
+ request this behaviour if none of the other settings are used.</para>
<xi:include href="system-or-user-ns.xml" xpointer="singular"/>
full list). This value will be returned when a deny-listed system call is triggered, instead of
terminating the processes immediately. Special setting <literal>kill</literal> can be used to
explicitly specify killing. This value takes precedence over the one given in
- <varname>SystemCallErrorNumber=</varname>, see below. If running in user mode, or in system mode,
- but without the <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting
- <varname>User=</varname>), <varname>NoNewPrivileges=yes</varname> is implied. This feature
- makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful
- for enforcing a minimal sandboxing environment. Note that the <function>execve()</function>,
- <function>exit()</function>, <function>exit_group()</function>, <function>getrlimit()</function>,
- <function>rt_sigreturn()</function>, <function>sigreturn()</function> system calls and the system calls
- for querying time and sleeping are implicitly allow-listed and do not need to be listed
- explicitly. This option may be specified more than once, in which case the filter masks are
+ <varname>SystemCallErrorNumber=</varname>, see below. This feature makes use of the Secure Computing Mode 2
+ interfaces of the kernel ('seccomp filtering') and is useful for enforcing a minimal sandboxing environment.
+ Note that the <function>execve()</function>, <function>exit()</function>, <function>exit_group()</function>,
+ <function>getrlimit()</function>, <function>rt_sigreturn()</function>, <function>sigreturn()</function>
+ system calls and the system calls for querying time and sleeping are implicitly allow-listed and do not
+ need to be listed explicitly. This option may be specified more than once, in which case the filter masks are
merged. If the empty string is assigned, the filter is reset, all prior assignments will have no
effect. This does not affect commands prefixed with <literal>+</literal>.</para>
as well as <constant>x32</constant>, <constant>mips64-n32</constant>, <constant>mips64-le-n32</constant>, and
the special identifier <constant>native</constant>. The special identifier <constant>native</constant>
implicitly maps to the native architecture of the system (or more precisely: to the architecture the system
- manager is compiled for). If running in user mode, or in system mode, but without the
- <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>),
- <varname>NoNewPrivileges=yes</varname> is implied. By default, this option is set to the empty list, i.e. no
- filtering is applied.</para>
+ manager is compiled for). By default, this option is set to the empty list, i.e. no filtering is applied.</para>
<para>If this setting is used, processes of this unit will only be permitted to call native system calls, and
system calls of the specified architectures. For the purposes of this option, the x32 architecture is treated
<listitem><para>Takes a space-separated list of system call names. If this setting is used, all
system calls executed by the unit processes for the listed ones will be logged. If the first
character of the list is <literal>~</literal>, the effect is inverted: all system calls except the
- listed system calls will be logged. If running in user mode, or in system mode, but without the
- <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=</varname>),
- <varname>NoNewPrivileges=yes</varname> is implied. This feature makes use of the Secure Computing
- Mode 2 interfaces of the kernel ('seccomp filtering') and is useful for auditing or setting up a
- minimal sandboxing environment. This option may be specified more than once, in which case the filter
- masks are merged. If the empty string is assigned, the filter is reset, all prior assignments will
- have no effect. This does not affect commands prefixed with <literal>+</literal>.</para>
+ listed system calls will be logged. This feature makes use of the Secure Computing Mode 2 interfaces
+ of the kernel ('seccomp filtering') and is useful for auditing or setting up a minimal sandboxing
+ environment. This option may be specified more than once, in which case the filter masks are merged.
+ If the empty string is assigned, the filter is reset, all prior assignments will have no effect.
+ This does not affect commands prefixed with <literal>+</literal>.</para>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<listitem><para>Similar to <varname>Environment=</varname>, but reads the environment variables from
a text file. The text file should contain newline-separated variable assignments. Empty lines, lines
without an <literal>=</literal> separator, or lines starting with <literal>;</literal> or
- <literal>#</literal> will be ignored, which may be used for commenting. The file must be UTF-8
- encoded. Valid characters are <ulink
- url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink> other than
- <ulink url="https://www.unicode.org/glossary/#noncharacter">noncharacters</ulink>, U+0000 NUL, and
- U+FEFF <ulink url="https://www.unicode.org/glossary/#byte_order_mark">byte order mark</ulink>.
- Control codes other than NUL are allowed.</para>
+ <literal>#</literal> will be ignored, which may be used for commenting. The file must be encoded with
+ UTF-8. Valid characters are
+ <ulink url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink>
+ other than
+ <ulink url="https://www.unicode.org/glossary/#noncharacter">unicode noncharacters</ulink>,
+ <constant>U+0000</constant> <constant>NUL</constant>, and <constant>U+FEFF</constant>
+ <ulink url="https://www.unicode.org/glossary/#byte_order_mark">unicode byte order mark</ulink>.
+ Control codes other than <constant>NUL</constant> are allowed.</para>
<para>In the file, an unquoted value after the <literal>=</literal> is parsed with the same backslash-escape
rules as <ulink
- url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">unquoted
- text</ulink> in a POSIX shell, but unlike in a shell, interior whitespace is preserved and quotes after the
+ url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">POSIX shell unquoted
+ text</ulink>, but unlike in a shell, interior whitespace is preserved and quotes after the
first non-whitespace character are preserved. Leading and trailing whitespace (space, tab, carriage return) is
discarded, but interior whitespace within the line is preserved verbatim. A line ending with a backslash will be
continued to the following one, with the newline itself discarded. A backslash
<literal>\</literal> followed by any character other than newline will preserve the following character, so that
<literal>\\</literal> will become the value <literal>\</literal>.</para>
- <para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span multiple lines
- and contain any character verbatim other than single quote, like <ulink
- url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">single-quoted
- text</ulink> in a POSIX shell. No backslash-escape sequences are recognized. Leading and trailing whitespace
- outside of the single quotes is discarded.</para>
-
- <para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span multiple lines,
- and the same escape sequences are recognized as in <ulink
- url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">double-quoted
- text</ulink> of a POSIX shell. Backslash (<literal>\</literal>) followed by any of <literal>"\`$</literal> will
- preserve that character. A backslash followed by newline is a line continuation, and the newline itself is
- discarded. A backslash followed by any other character is ignored; both the backslash and the following
- character are preserved verbatim. Leading and trailing whitespace outside of the double quotes is
- discarded.</para>
+ <para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span
+
multiple lines and contain any character verbatim other than single quote, like <ulink
+ url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">POSIX
+ shell single-quoted text</ulink>. No backslash-escape sequences are recognized. Leading and trailing
+ whitespace outside of the single quotes is discarded.</para>
+
+ <para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span
+
multiple lines, and the same escape sequences are recognized as in <ulink
+ url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">POSIX
+ shell double-quoted text</ulink>. Backslash (<literal>\</literal>) followed by any of
+ <literal>"\`$</literal> will preserve that character. A backslash followed by newline is a line
+ continuation, and the newline itself is discarded. A backslash followed by any other character is
+ ignored; both the backslash and the following character are preserved verbatim. Leading and trailing
+ whitespace outside of the double quotes is discarded.</para>
<para>The argument passed should be an absolute filename or wildcard expression, optionally prefixed with
<literal>-</literal>, which indicates that if the file does not exist, it will not be read and no error or
input will be connected to the socket the service was activated from, which is primarily useful for
compatibility with daemons designed for use with the traditional <citerefentry
project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> socket activation
- daemon.</para>
+ daemon (<varname>$LISTEN_FDS</varname> (and related) environment variables are not passed when
+ <option>socket</option> value is configured).</para>
<para>The <option>fd:<replaceable>name</replaceable></option> option connects standard input to a specific,
named file descriptor provided by a socket unit. The name may be specified as part of this option, following a
the kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname>
on <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section
above). Also note that in this case stdout (or stderr, see below) will be an
- <constant>AF_UNIX</constant> stream socket, and not a pipe or FIFO that can be re-opened. This means
+ <constant>AF_UNIX</constant> stream socket, and not a pipe or FIFO that can be reopened. This means
when executing shell scripts the construct <command>echo "hello" > /dev/stderr</command> for
writing text to stderr will not work. To mitigate this use the construct <command>echo "hello"
>&2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
<varname>RateLimitBurst=</varname> configured in
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Note that this only applies to log messages that are processed by the logging subsystem, i.e. by
- <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
This means that if you connect a service's stderr directly to a file via
<varname>StandardOutput=file:…</varname> or a similar setting, the rate limiting will not be applied
to messages written that way (but it will be enforced for messages generated via
<literal>\x7efoobar</literal> would add a pattern matching <literal>~foobar</literal> to the allow list.</para>
<para>Log messages are tested against denied patterns (if any), then against allowed patterns
- (if any). If a log message matches any of the denied patterns, it will be discarded, whatever the
- allowed patterns. Then, remaining log messages are tested against allowed patterns. Messages matching
+ (if any). If a log message matches any of the denied patterns, it is discarded immediately without considering
+ allowed patterns. Remaining log messages are tested against allowed patterns. Messages matching
against none of the allowed pattern are discarded. If no allowed patterns are defined, then all
messages are processed directly after going through denied filters.</para>
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the details about <varname>DevicePolicy=</varname> or <varname>DeviceAllow=</varname>.</para>
+ <para>Note that encrypted credentials targeted for services of the per-user service manager must be
+ encrypted with <command>systemd-creds encrypt --user</command>, and those for the system service
+ manager without the <option>--user</option> switch. Encrypted credentials are always targeted to a
+ specific user or the system as a whole, and it is ensured that per-user service managers cannot
+ decrypt secrets intended for the system or for other users.</para>
+
<para>The credential files/IPC sockets must be accessible to the service manager, but don't have to
be directly accessible to the unit's processes: the credential data is read and copied into separate,
read-only copies for the unit that are accessible to appropriately privileged processes. This is
<varname>FileDescriptorStoreMax=</varname> is set to a non-zero value (see
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details). Applications may check this environment variable before sending file descriptors to
- the service manager via <function>sd_pid_notify_with_fds()</function> (see
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
- details).</para>
+ the service manager via
+ <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ </para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<refsect1>
<title>See Also</title>
- <para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- </para>
+ <para><simplelist type="inline">
+ <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+ <member><citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
+ </simplelist></para>
</refsect1>
</refentry>
projects / thirdparty / systemd.git / blobdiff