HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/systemd.resource-control.xml
Git blob: 4e908f150ecd12ac5646273caecddd2ae106061a
Lines 1001–1891 of 1,891
<para>This option can appear multiple times, in which case the network interface names are merged. If the
empty string is assigned the set is reset, all prior assignments will have not effect.
</para>
<para>If you specify both types of this option (i.e. allow-listing and deny-listing), the first encountered
will take precedence and will dictate the default action (allow vs deny). Then the next occurrences of this
option will add or delete the listed network interface names from the set, depending of its type and the
default action.
</para>
<para>The loopback interface ("lo") is not treated in any special way, you have to configure it explicitly
in the unit file.
</para>
<para>Example 1: allow-list
<programlisting>
RestrictNetworkInterfaces=eth1
RestrictNetworkInterfaces=eth2</programlisting>
Programs in the unit will be only able to use the eth1 and eth2 network
interfaces.
</para>
<para>Example 2: deny-list
<programlisting>
RestrictNetworkInterfaces=~eth1 eth2</programlisting>
Programs in the unit will be able to use any network interface but eth1 and eth2.
</para>
<para>Example 3: mixed
<programlisting>
RestrictNetworkInterfaces=eth1 eth2
RestrictNetworkInterfaces=~eth1</programlisting>
Programs in the unit will be only able to use the eth2 network interface.
</para>
<xi:include href="cgroup-sandboxing.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v250"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BindNetworkInterface=</varname></term>
<listitem>
<para>Takes the name of a network interface. This option causes every socket created by processes of this
unit to be bound to the specified network interface.
</para>
<para>It is specially useful to confine a process to a VRF, when the program does not offer native support
for it. It is equivalent to running the program using <constant>ip vrf exec</constant>.
</para>
<para>In systems using <filename>nss-resolve</filename>, the interface used for DNS resolution can be chosen
by using the <varname>SYSTEMD_NSS_RESOLVE_IFINDEX</varname> environment variable.</para>
<para>The feature is implemented with <constant>cgroup/sock_create</constant> cgroup-bpf hooks.</para>
<para>Example:<programlisting>[Service]
BindNetworkInterface=vrf-mgmt
</programlisting></para>
<xi:include href="cgroup-sandboxing.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v260"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>NFTSet=</varname><replaceable>family</replaceable>:<replaceable>table</replaceable>:<replaceable>set</replaceable></term>
<listitem>
<para>This setting provides a method for integrating dynamic cgroup, user and group IDs into
firewall rules with <ulink url="https://netfilter.org/projects/nftables/index.html">NFT</ulink>
sets. The benefit of using this setting is to be able to use the IDs as selectors in firewall rules
easily and this in turn allows more fine grained filtering. NFT rules for cgroup matching use
numeric cgroup IDs, which change every time a service is restarted, making them hard to use in
systemd environment otherwise. Dynamic and random IDs used by <varname>DynamicUser=</varname> can
be also integrated with this setting.</para>
<para>This option expects a whitespace separated list of NFT set definitions. Each definition
consists of a colon-separated tuple of source type (one of <literal>cgroup</literal>,
<literal>user</literal> or <literal>group</literal>), NFT address family (one of
<literal>arp</literal>, <literal>bridge</literal>, <literal>inet</literal>, <literal>ip</literal>,
<literal>ip6</literal>, or <literal>netdev</literal>), table name and set name. The names of tables
and sets must conform to lexicographic restrictions of NFT table names. The type of the element used in
the NFT filter must match the type implied by the directive (<literal>cgroup</literal>,
<literal>user</literal> or <literal>group</literal>) as shown in the table below. When a control
group or a unit is realized, the corresponding ID will be appended to the NFT sets and it will be
be removed when the control group or unit is removed. <command>systemd</command> only inserts
elements to (or removes from) the sets, so the related NFT rules, tables and sets must be prepared
elsewhere in advance. Failures to manage the sets will be ignored.</para>
<table>
<title>Defined <varname>source type</varname> values</title>
<tgroup cols='3'>
<colspec colname='source type'/>
<colspec colname='description'/>
<colspec colname='NFT type name'/>
<thead>
<row>
<entry>Source type</entry>
<entry>Description</entry>
<entry>Corresponding NFT type name</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>cgroup</literal></entry>
<entry>control group ID</entry>
<entry><literal>cgroupsv2</literal></entry>
</row>
<row>
<entry><literal>user</literal></entry>
<entry>user ID</entry>
<entry><literal>meta skuid</literal></entry>
</row>
<row>
<entry><literal>group</literal></entry>
<entry>group ID</entry>
<entry><literal>meta skgid</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<para>If the firewall rules are reinstalled so that the contents of NFT sets are destroyed, command
<command>systemctl daemon-reload</command> can be used to refill the sets.</para>
<para>Example:
<programlisting>[Service]
NFTSet=cgroup:inet:filter:my_service user:inet:filter:serviceuser
</programlisting>
Corresponding NFT rules:
<programlisting>table inet filter {
set my_service {
type cgroupsv2
}
set serviceuser {
typeof meta skuid
}
chain x {
socket cgroupv2 level 2 @my_service accept
drop
}
chain y {
meta skuid @serviceuser accept
drop
}
}</programlisting>
</para>
<xi:include href="system-only.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
</variablelist>
</refsect2><refsect2><title>BPF Programs</title>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>IPIngressFilterPath=<replaceable>BPF_FS_PROGRAM_PATH</replaceable></varname></term>
<term><varname>IPEgressFilterPath=<replaceable>BPF_FS_PROGRAM_PATH</replaceable></varname></term>
<listitem>
<para>Add custom network traffic filters implemented as BPF programs, applying to all IP packets
sent and received over <constant>AF_INET</constant> and <constant>AF_INET6</constant> sockets.
Takes an absolute path to a pinned BPF program in the BPF virtual filesystem (<filename>/sys/fs/bpf/</filename>).
</para>
<para>The filters configured with this option are applied to all sockets created by processes
of this unit (or in the case of socket units, associated with it). The filters are loaded in addition
to filters any of the parent slice units this unit might be a member of as well as any
<varname>IPAddressAllow=</varname> and <varname>IPAddressDeny=</varname> filters in any of these units.
By default, there are no filters specified.</para>
<para>If these settings are used multiple times in the same unit all the specified programs are attached. If an
empty string is assigned to these settings the program list is reset and all previous specified programs ignored.</para>
<para>If the path <replaceable>BPF_FS_PROGRAM_PATH</replaceable> in <varname>IPIngressFilterPath=</varname> assignment
is already being handled by <varname>BPFProgram=</varname> ingress hook, e.g.
<varname>BPFProgram=</varname><constant>ingress</constant>:<replaceable>BPF_FS_PROGRAM_PATH</replaceable>,
the assignment will be still considered valid and the program will be attached to a cgroup. Same for
<varname>IPEgressFilterPath=</varname> path and <constant>egress</constant> hook.</para>
<para>Note that for socket-activated services, the IP filter programs configured on the socket unit apply to
all sockets associated with it directly, but not to any sockets created by the ultimately activated services
for it. Conversely, the IP filter programs configured for the service are not applied to any sockets passed into
the service via socket activation. Thus, it is usually a good idea, to replicate the IP filter programs on both
the socket and the service unit, however it often makes sense to maintain one configuration more open and the other
one more restricted, depending on the use case.</para>
<para>Note that these settings might not be supported on some systems (for example if eBPF control group
support is not enabled in the underlying kernel or container manager). These settings will have no effect in
that case. If compatibility with such systems is desired it is hence recommended to attach your filter manually
(requires <varname>Delegate=</varname><constant>yes</constant>) instead of using this setting.</para>
<xi:include href="version-info.xml" xpointer="v243"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BPFProgram=<replaceable>type</replaceable>:<replaceable>program-path</replaceable></varname></term>
<listitem>
<para><varname>BPFProgram=</varname> allows attaching custom BPF programs to the cgroup of a
unit. (This generalizes the functionality exposed via <varname>IPEgressFilterPath=</varname> and
<varname>IPIngressFilterPath=</varname> for other hooks.) Cgroup-bpf hooks in the form of BPF
programs loaded to the BPF filesystem are attached with cgroup-bpf attach flags determined by the
unit. For details about attachment types and flags see <ulink
url="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/linux/bpf.h"><filename>bpf.h</filename></ulink>. Also
refer to the general <ulink url="https://docs.kernel.org/bpf/">BPF documentation</ulink>.</para>
<para>The specification of BPF program consists of a pair of BPF program type and program path in
the file system, with <literal>:</literal> as the separator:
<replaceable>type</replaceable>:<replaceable>program-path</replaceable>.</para>
<para>The BPF program type is equivalent to the BPF attach type used in
<citerefentry project='mankier'><refentrytitle>bpftool</refentrytitle><manvolnum>8</manvolnum></citerefentry>
It may be one of
<constant>egress</constant>,
<constant>ingress</constant>,
<constant>sock_create</constant>,
<constant>sock_ops</constant>,
<constant>device</constant>,
<constant>bind4</constant>,
<constant>bind6</constant>,
<constant>connect4</constant>,
<constant>connect6</constant>,
<constant>post_bind4</constant>,
<constant>post_bind6</constant>,
<constant>sendmsg4</constant>,
<constant>sendmsg6</constant>,
<constant>sysctl</constant>,
<constant>recvmsg4</constant>,
<constant>recvmsg6</constant>,
<constant>getsockopt</constant>,
or <constant>setsockopt</constant>.
</para>
<para>The specified program path must be an absolute path referencing a BPF program inode in the
bpffs file system (which generally means it must begin with <filename>/sys/fs/bpf/</filename>). If
a specified program does not exist (i.e. has not been uploaded to the BPF subsystem of the kernel
yet), it will not be installed but unit activation will continue (a warning will be printed to the
logs).</para>
<para>Setting <varname>BPFProgram=</varname> to an empty value makes previous assignments
ineffective.</para>
<para>Multiple assignments of the same program type/path pair have the same effect as a single
assignment: the program will be attached just once.</para>
<para>If BPF <constant>egress</constant> pinned to <replaceable>program-path</replaceable> path is already being
handled by <varname>IPEgressFilterPath=</varname>, <varname>BPFProgram=</varname>
assignment will be considered valid and <varname>BPFProgram=</varname> will be attached to a cgroup.
Similarly for <constant>ingress</constant> hook and <varname>IPIngressFilterPath=</varname> assignment.</para>
<para>BPF programs passed with <varname>BPFProgram=</varname> are attached to the cgroup of a unit
with BPF attach flag <constant>multi</constant>, that allows further attachments of the same
<replaceable>type</replaceable> within cgroup hierarchy topped by the unit cgroup.</para>
<para>Examples:<programlisting>BPFProgram=egress:/sys/fs/bpf/egress-hook
BPFProgram=bind6:/sys/fs/bpf/sock-addr-hook
</programlisting></para>
<xi:include href="version-info.xml" xpointer="v249"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2><refsect2><title>Device Access</title>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>DeviceAllow=</varname></term>
<listitem>
<para>Control access to specific device nodes by the executed processes. Takes two space-separated
strings: a device node specifier followed by a combination of <constant>r</constant>,
<constant>w</constant>, <constant>m</constant> to control <emphasis>r</emphasis>eading,
<emphasis>w</emphasis>riting, or creation of the specific device nodes by the unit
(<emphasis>m</emphasis>knod), respectively. This functionality is implemented using eBPF
filtering.</para>
<para>When access to <emphasis>all</emphasis> physical devices should be disallowed,
<varname>PrivateDevices=</varname> may be used instead. See
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para>The device node specifier is either a path to a device node in the file system, starting with
<filename>/dev/</filename>, or a string starting with either <literal>char-</literal> or
<literal>block-</literal> followed by a device group name, as listed in
<filename>/proc/devices</filename>. The latter is useful to allow-list all current and future
devices belonging to a specific device group at once. The device group is matched according to
filename globbing rules, you may hence use the <literal>*</literal> and <literal>?</literal>
wildcards. (Note that such globbing wildcards are not available for device node path
specifications!) In order to match device nodes by numeric major/minor, use device node paths in
the <filename>/dev/char/</filename> and <filename>/dev/block/</filename> directories. However,
matching devices by major/minor is generally not recommended as assignments are neither stable nor
portable between systems or different kernel versions.</para>
<para>Examples: <filename>/dev/sda5</filename> is a path to a device node, referring to an ATA or
SCSI block device. <literal>char-pts</literal> and <literal>char-alsa</literal> are specifiers for
all pseudo TTYs and all ALSA sound devices, respectively. <literal>char-cpu/*</literal> is a
specifier matching all CPU related device groups.</para>
<para>Note that allow lists defined this way should only reference device groups which are
resolvable at the time the unit is started. Any device groups not resolvable then are not added to
the device allow list. In order to work around this limitation, consider extending service units
with a pair of <command>After=modprobe@xyz.service</command> and
<command>Wants=modprobe@xyz.service</command> lines that load the necessary kernel module
implementing the device group if missing.
Example: <programlisting>…
[Unit]
Wants=modprobe@loop.service
After=modprobe@loop.service
[Service]
DeviceAllow=block-loop
DeviceAllow=/dev/loop-control
…</programlisting></para>
<xi:include href="cgroup-sandboxing.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v208"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DevicePolicy=auto|closed|strict</varname></term>
<listitem>
<para>
Control the policy for allowing device access:
</para>
<variablelist>
<varlistentry>
<term><option>strict</option></term>
<listitem>
<para>means to only allow types of access that are
explicitly specified.</para>
<xi:include href="version-info.xml" xpointer="v208"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>closed</option></term>
<listitem>
<para>in addition, allows access to standard pseudo
devices including
<filename>/dev/null</filename>,
<filename>/dev/zero</filename>,
<filename>/dev/full</filename>,
<filename>/dev/random</filename>, and
<filename>/dev/urandom</filename>.
</para>
<xi:include href="version-info.xml" xpointer="v208"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>auto</option></term>
<listitem>
<para>
in addition, allows access to all devices if no
explicit <varname>DeviceAllow=</varname> is present.
This is the default.
</para>
<xi:include href="version-info.xml" xpointer="v208"/>
</listitem>
</varlistentry>
</variablelist>
<xi:include href="cgroup-sandboxing.xml" xpointer="singular"/>
<xi:include href="version-info.xml" xpointer="v208"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2><refsect2><title>Control Group Management</title>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>Slice=</varname></term>
<listitem>
<para>The name of the slice unit to place the unit
in. Defaults to <filename>system.slice</filename> for all
non-instantiated units of all unit types (except for slice
units themselves see below). Instance units are by default
placed in a subslice of <filename>system.slice</filename>
that is named after the template name.</para>
<para>This option may be used to arrange systemd units in a
hierarchy of slices each of which might have resource
settings applied.</para>
<para>For units of type slice, the only accepted value for
this setting is the parent slice. Since the name of a slice
unit implies the parent slice, it is hence redundant to ever
set this parameter directly for slice units.</para>
<para>Special care should be taken when relying on the default slice assignment in templated service units
that have <varname>DefaultDependencies=no</varname> set, see
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, section
"Default Dependencies" for details.</para>
<xi:include href="version-info.xml" xpointer="v208"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>Delegate=</varname></term>
<listitem>
<para>Turns on delegation of further resource control partitioning to processes of the unit. Units
where this is enabled may create and manage their own private subhierarchy of control groups below
the control group of the unit itself. For unprivileged services (i.e. those using the
<varname>User=</varname> setting) the unit's control group will be made accessible to the relevant
user.</para>
<para>When enabled the service manager will refrain from manipulating control groups or moving
processes below the unit's control group, so that a clear concept of ownership is established: the
control group tree at the level of the unit's control group and above (i.e. towards the root
control group) is owned and managed by the service manager of the host, while the control group
tree below the unit's control group is owned and managed by the unit itself.</para>
<para>Takes either a boolean argument or a (possibly empty) list of control group controller names.
If true, delegation is turned on, and all supported controllers are enabled for the unit, making
them available to the unit's processes for management. If false, delegation is turned off entirely
(and no additional controllers are enabled). If set to a list of controllers, delegation is turned
on, and the specified controllers are enabled for the unit. Assigning the empty string will enable
delegation, but reset the list of controllers, and all assignments prior to this will have no
effect. Note that additional controllers other than the ones specified might be made available as
well, depending on configuration of the containing slice unit or other units contained in it.
Defaults to false.</para>
<para>Note that controller delegation to less privileged code is only safe on the unified control
group hierarchy. Accordingly, access to the specified controllers will not be granted to
unprivileged services on the legacy hierarchy, even when requested.</para>
<xi:include href="supported-controllers.xml" xpointer="controllers-text" />
<para>Not all of these controllers are available on all kernels however, and some are specific to
the unified hierarchy while others are specific to the legacy hierarchy. Also note that the kernel
might support further controllers, which are not covered here yet, as delegation is either not
supported at all for them or not defined cleanly.</para>
<para>Note that because of the hierarchical nature of cgroup hierarchy, any controllers that are
delegated will be enabled for the parent and sibling units of the unit with delegation.</para>
<para>For further details on the delegation model consult <ulink
url="https://systemd.io/CGROUP_DELEGATION">Control Group APIs and Delegation</ulink>.</para>
<xi:include href="version-info.xml" xpointer="v218"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DelegateSubgroup=</varname></term>
<listitem>
<para>Place unit processes in the specified subgroup of the unit's control group. Takes a valid
control group name (not a path!) as parameter, or an empty string to turn this feature
off. Defaults to off. The control group name must be usable as filename and avoid conflicts with
the kernel's control group attribute files (i.e. <filename>cgroup.procs</filename> is not an
acceptable name, since the kernel exposes a native control group attribute file by that name). This
option has no effect unless control group delegation is turned on via <varname>Delegate=</varname>,
see above. Note that this setting only applies to "main" processes of a unit, i.e. for services to
<varname>ExecStart=</varname>, but not for <varname>ExecReload=</varname> and similar. If
delegation is enabled, the latter are always placed inside a subgroup named
<filename>.control</filename>. The specified subgroup is automatically created (and potentially
ownership is passed to the unit's configured user/group) when a process is started in it.</para>
<para>This option is useful to avoid manually moving the invoked process into a subgroup after it
has been started. Since no processes should live in inner nodes of the control group tree it is
almost always necessary to run the main ("supervising") process of a unit that has delegation
turned on in a subgroup.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DisableControllers=</varname></term>
<listitem>
<para>Disables controllers from being enabled for a unit's children. If a controller listed is
already in use in its subtree, the controller will be removed from the subtree. This can be used to
avoid configuration in child units from being able to implicitly or explicitly enable a controller.
Defaults to empty.</para>
<para>Multiple controllers may be specified, separated by spaces. You may also pass
<varname>DisableControllers=</varname> multiple times, in which case each new instance adds another controller
to disable. Passing <varname>DisableControllers=</varname> by itself with no controller name present resets
the disabled controller list.</para>
<para>It may not be possible to disable a controller after units have been started, if the unit or
any child of the unit in question delegates controllers to its children, as any delegated subtree
of the cgroup hierarchy is unmanaged by systemd.</para>
<xi:include href="supported-controllers.xml" xpointer="controllers-text" />
<xi:include href="version-info.xml" xpointer="v240"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2><refsect2><title>Memory Pressure Control</title>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>ManagedOOMSwap=auto|kill</varname></term>
<term><varname>ManagedOOMMemoryPressure=auto|kill</varname></term>
<listitem>
<para>Specifies how
<citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
will act on this unit's cgroups. Defaults to <option>auto</option>.</para>
<para>When set to <option>kill</option>, the unit becomes a candidate for monitoring by
<command>systemd-oomd</command>. If the cgroup passes the limits set by
<citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> or
the unit configuration, <command>systemd-oomd</command> will select a descendant cgroup and send
<constant>SIGKILL</constant> to all of the processes under it. You can find more details on
candidates and kill behavior at
<citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>Setting either of these properties to <option>kill</option> will also result in
<varname>After=</varname> and <varname>Wants=</varname> dependencies on
<filename>systemd-oomd.service</filename> unless <varname>DefaultDependencies=no</varname>.</para>
<para>When set to <option>auto</option>, <command>systemd-oomd</command> will not actively use this
cgroup's data for monitoring and detection. However, if an ancestor cgroup has one of these
properties set to <option>kill</option>, a unit with <option>auto</option> can still be a candidate
for <command>systemd-oomd</command> to terminate.</para>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ManagedOOMMemoryPressureLimit=</varname></term>
<listitem>
<para>Overrides the default memory pressure limit set by
<citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
the cgroup of this unit. Takes a percentage value between 0% and 100%, inclusive. Defaults to 0%,
which means to use the default set by
<citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
This property is ignored unless <varname>ManagedOOMMemoryPressure=</varname><option>kill</option>.
</para>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ManagedOOMMemoryPressureDurationSec=</varname></term>
<listitem>
<para>Overrides the default memory pressure duration set by
<citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
the cgroup of this unit. The specified value supports a time unit such as <literal>ms</literal> or
<literal>μs</literal>, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details on the permitted syntax. Must be set to either empty or a value of at least 1s. Defaults
to empty, which means to use the default set by
<citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
This property is ignored unless <varname>ManagedOOMMemoryPressure=</varname><option>kill</option>.
</para>
<xi:include href="version-info.xml" xpointer="v257"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ManagedOOMPreference=none|avoid|omit</varname></term>
<listitem>
<para>Allows deprioritizing or omitting this unit's cgroup as a candidate when
<command>systemd-oomd</command> needs to act. Requires support for extended attributes (see
<citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
in order to use <option>avoid</option> or <option>omit</option>.</para>
<para>When calculating candidates to relieve swap usage, <command>systemd-oomd</command> will
only respect these extended attributes if the unit's cgroup is owned by root.</para>
<para>When calculating candidates to relieve memory pressure, <command>systemd-oomd</command>
will only respect these extended attributes if the unit's cgroup is owned by root, or if the
unit's cgroup owner, and the owner of the monitored ancestor cgroup are the same. For example,
if <command>systemd-oomd</command> is calculating candidates for <filename>-.slice</filename>,
then extended attributes set on descendants of <filename>/user.slice/user-1000.slice/user@1000.service/</filename>
will be ignored because the descendants are owned by UID 1000, and <filename>-.slice</filename>
is owned by UID 0. But, if calculating candidates for
<filename>/user.slice/user-1000.slice/user@1000.service/</filename>, then extended attributes set
on the descendants would be respected.</para>
<para>If this property is set to <option>avoid</option>, the service manager will convey this to
<command>systemd-oomd</command>, which will only select this cgroup if there are no other viable
candidates.</para>
<para>If this property is set to <option>omit</option>, the service manager will convey this to
<command>systemd-oomd</command>, which will ignore this cgroup as a candidate and will not perform
any actions on it.</para>
<para>It is recommended to use <option>avoid</option> and <option>omit</option> sparingly, as it
can adversely affect <command>systemd-oomd</command>'s kill behavior. Also note that these extended
attributes are not applied recursively to cgroups under this unit's cgroup.</para>
<para>Defaults to <option>none</option> which means <command>systemd-oomd</command> will rank this
unit's cgroup as defined in
<citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and <citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<xi:include href="version-info.xml" xpointer="v248"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>OOMRules=</varname></term>
<listitem>
<para>Takes a space-separated list of OOM ruleset names. The rulesets are defined in
<filename>.oomrule</filename> files placed in
<filename>/etc/systemd/oomd/rules.d/</filename>,
<filename>/run/systemd/oomd/rules.d/</filename>,
<filename>/usr/local/lib/systemd/oomd/rules.d/</filename>, or
<filename>/usr/lib/systemd/oomd/rules.d/</filename>. When set,
<citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
will monitor this unit's cgroup and evaluate the specified rulesets against it.
Each ruleset defines conditions (such as memory pressure or swap usage thresholds) and an action
to take when those conditions are met. See
<citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details on the available ruleset options.</para>
<para>Setting this property will also result in <varname>After=</varname> and
<varname>Wants=</varname> dependencies on <filename>systemd-oomd.service</filename> unless
<varname>DefaultDependencies=no</varname>.</para>
<para>Defaults to an empty list, which means no rulesets are applied. Note that each monitored
cgroup incurs a per-interval walk of its descendant cgroup tree, so monitoring very large numbers of
cgroups via <varname>OOMRules=</varname> may have a measurable performance impact.</para>
<xi:include href="version-info.xml" xpointer="v261"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>MemoryPressureWatch=</varname></term>
<listitem><para>Controls memory pressure monitoring for invoked processes. Takes a boolean or one of
<literal>auto</literal> and <literal>skip</literal>. If <literal>no</literal>, tells the service not
to watch for memory pressure events, by setting the <varname>$MEMORY_PRESSURE_WATCH</varname>
environment variable to the literal string <filename>/dev/null</filename>. If <literal>yes</literal>,
tells the service to watch for memory pressure events. This enables memory accounting for the
service, and ensures the <filename>memory.pressure</filename> cgroup attribute file is accessible for
reading and writing by the service's user. It then sets the <varname>$MEMORY_PRESSURE_WATCH</varname>
environment variable for processes invoked by the unit to the file system path to this file. The
threshold information configured with <varname>MemoryPressureThresholdSec=</varname> is encoded in
the <varname>$MEMORY_PRESSURE_WRITE</varname> environment variable. If the <literal>auto</literal>
value is set the protocol is enabled if memory accounting is anyway enabled for the unit, and
disabled otherwise. If set to <literal>skip</literal> the logic is neither enabled, nor disabled and
the two environment variables are not set.</para>
<para>Note that services are free to use the two environment variables, but it is unproblematic if
they ignore them. Memory pressure handling must be implemented individually in each service, and
usually means different things for different software. For further details on memory pressure
handling see <ulink url="https://systemd.io/PRESSURE">Resource Pressure Handling in
systemd</ulink>.</para>
<para>Services implemented using
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> may use
<citerefentry><refentrytitle>sd_event_add_memory_pressure</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to watch for and handle memory pressure events.</para>
<para>If not explicit set, defaults to the <varname>DefaultMemoryPressureWatch=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>MemoryPressureThresholdSec=</varname></term>
<listitem><para>Sets the memory pressure threshold time for memory pressure monitor as configured via
<varname>MemoryPressureWatch=</varname>. Specifies the maximum allocation latency before a memory
pressure event is signalled to the service, per 2s window. If not specified, defaults to the
<varname>DefaultMemoryPressureThresholdSec=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
(which in turn defaults to 200ms). The specified value expects a time unit such as
<literal>ms</literal> or <literal>μs</literal>, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details on the permitted syntax.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>CPUPressureWatch=</varname></term>
<listitem><para>Controls CPU pressure monitoring for invoked processes. Takes a boolean or one of
<literal>auto</literal> and <literal>skip</literal>. If <literal>no</literal>, tells the service not
to watch for CPU pressure events, by setting the <varname>$CPU_PRESSURE_WATCH</varname>
environment variable to the literal string <filename>/dev/null</filename>. If <literal>yes</literal>,
tells the service to watch for CPU pressure events. This ensures the
<filename>cpu.pressure</filename> cgroup attribute file is accessible for
reading and writing by the service's user. It then sets the <varname>$CPU_PRESSURE_WATCH</varname>
environment variable for processes invoked by the unit to the file system path to this file. The
threshold information configured with <varname>CPUPressureThresholdSec=</varname> is encoded in
the <varname>$CPU_PRESSURE_WRITE</varname> environment variable. If the <literal>auto</literal>
value is set the protocol is enabled if CPU resource controls are configured for the unit (e.g. because
<varname>CPUWeight=</varname> or <varname>CPUQuota=</varname> is set), and
disabled otherwise. If set to <literal>skip</literal> the logic is neither enabled, nor disabled and
the two environment variables are not set.</para>
<para>Note that services are free to use the two environment variables, but it is unproblematic if
they ignore them. CPU pressure handling must be implemented individually in each service, and
usually means different things for different software.</para>
<para>Services implemented using
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> may use
<citerefentry><refentrytitle>sd_event_add_cpu_pressure</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to watch for and handle CPU pressure events.</para>
<para>If not explicitly set, defaults to the <varname>DefaultCPUPressureWatch=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>CPUPressureThresholdSec=</varname></term>
<listitem><para>Sets the CPU pressure threshold time for CPU pressure monitor as configured via
<varname>CPUPressureWatch=</varname>. Specifies the maximum CPU stall time before a CPU
pressure event is signalled to the service, per 2s window. If not specified, defaults to the
<varname>DefaultCPUPressureThresholdSec=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
(which in turn defaults to 200ms). The specified value expects a time unit such as
<literal>ms</literal> or <literal>μs</literal>, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details on the permitted syntax.</para>
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>IOPressureWatch=</varname></term>
<listitem><para>Controls IO pressure monitoring for invoked processes. Takes a boolean or one of
<literal>auto</literal> and <literal>skip</literal>. If <literal>no</literal>, tells the service not
to watch for IO pressure events, by setting the <varname>$IO_PRESSURE_WATCH</varname>
environment variable to the literal string <filename>/dev/null</filename>. If <literal>yes</literal>,
tells the service to watch for IO pressure events. This enables IO accounting for the
service, and ensures the <filename>io.pressure</filename> cgroup attribute file is accessible for
reading and writing by the service's user. It then sets the <varname>$IO_PRESSURE_WATCH</varname>
environment variable for processes invoked by the unit to the file system path to this file. The
threshold information configured with <varname>IOPressureThresholdSec=</varname> is encoded in
the <varname>$IO_PRESSURE_WRITE</varname> environment variable. If the <literal>auto</literal>
value is set the protocol is enabled if IO accounting is anyway enabled for the unit (e.g. because
<varname>IOWeight=</varname> or <varname>IODeviceWeight=</varname> is set), and
disabled otherwise. If set to <literal>skip</literal> the logic is neither enabled, nor disabled and
the two environment variables are not set.</para>
<para>Note that services are free to use the two environment variables, but it is unproblematic if
they ignore them. IO pressure handling must be implemented individually in each service, and
usually means different things for different software.</para>
<para>Services implemented using
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> may use
<citerefentry><refentrytitle>sd_event_add_io_pressure</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to watch for and handle IO pressure events.</para>
<para>If not explicitly set, defaults to the <varname>DefaultIOPressureWatch=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>IOPressureThresholdSec=</varname></term>
<listitem><para>Sets the IO pressure threshold time for IO pressure monitor as configured via
<varname>IOPressureWatch=</varname>. Specifies the maximum IO stall time before an IO
pressure event is signalled to the service, per 2s window. If not specified, defaults to the
<varname>DefaultIOPressureThresholdSec=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
(which in turn defaults to 200ms). The specified value expects a time unit such as
<literal>ms</literal> or <literal>μs</literal>, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details on the permitted syntax.</para>
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
</variablelist>
</refsect2><refsect2><title>Coredump Control</title>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>CoredumpReceive=</varname></term>
<listitem><para>Takes a boolean argument. This setting is used to enable coredump forwarding for containers
that belong to this unit's cgroup. Units with <varname>CoredumpReceive=yes</varname> must also be configured
with <varname>Delegate=yes</varname>. Defaults to false.</para>
<para>When <command>systemd-coredump</command> is handling a coredump for a process from a container,
if the container's leader process is a descendant of a cgroup with <varname>CoredumpReceive=yes</varname>
and <varname>Delegate=yes</varname>, then <command>systemd-coredump</command> will attempt to forward
the coredump to <command>systemd-coredump</command> within the container. See also
<citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>History</title>
<variablelist>
<varlistentry>
<term>systemd 252</term>
<listitem><para>Options for controlling the Legacy Control Group Hierarchy (<ulink
url="https://docs.kernel.org/admin-guide/cgroup-v1/index.html">Control Groups version 1</ulink>)
are now fully deprecated:
<varname>CPUShares=<replaceable>weight</replaceable></varname>,
<varname>StartupCPUShares=<replaceable>weight</replaceable></varname>,
<varname>MemoryLimit=<replaceable>bytes</replaceable></varname>,
<varname>BlockIOAccounting=</varname>,
<varname>BlockIOWeight=<replaceable>weight</replaceable></varname>,
<varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname>,
<varname>BlockIODeviceWeight=<replaceable>device</replaceable>
<replaceable>weight</replaceable></varname>,
<varname>BlockIOReadBandwidth=<replaceable>device</replaceable>
<replaceable>bytes</replaceable></varname>,
<varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname>.
Please switch to the unified cgroup hierarchy.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>systemd 258</term>
<listitem><para><varname>CPUAccounting=</varname> setting is deprecated, because it is always available
on the unified cgroup hierarchy and such setting has no effect.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</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.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member>The documentation for control groups and specific controllers in the Linux kernel:
<ulink url="https://docs.kernel.org/admin-guide/cgroup-v2.html">Control Groups v2</ulink></member>
</simplelist></para>
</refsect1>
</refentry>