<?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
-
-<refentry id="systemd.resource-control">
+<refentry id="systemd.resource-control" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd.resource-control</title>
<productname>systemd</productname>
<refsect1>
<title>Unified and Legacy Control Group Hierarchies</title>
- <para>The unified control group hierarchy is the new version of kernel control group interface, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. Depending on the resource type,
- there are differences in resource control capabilities. Also, because of interface changes, some resource types
- have separate set of options on the unified hierarchy.</para>
+ <para>The unified control group hierarchy is the new version of kernel control group interface, see
+ <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</ulink>.
+ Depending on the resource type, there are differences in resource control capabilities. Also, because of
+ interface changes, some resource types have separate set of options on the unified hierarchy.</para>
<para>
<variablelist>
<varlistentry>
- <term><option>CPU</option></term>
+ <term>CPU</term>
<listitem>
<para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace
<varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para>
</varlistentry>
<varlistentry>
- <term><option>Memory</option></term>
+ <term>Memory</term>
<listitem>
<para><varname>MemoryMax=</varname> replaces <varname>MemoryLimit=</varname>. <varname>MemoryLow=</varname>
and <varname>MemoryHigh=</varname> are effective only on unified hierarchy.</para>
</varlistentry>
<varlistentry>
- <term><option>IO</option></term>
+ <term>IO</term>
<listitem>
- <para><varname>IO</varname> prefixed settings are a superset of and replace <varname>BlockIO</varname>
- prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para>
+ <para><literal>IO</literal>-prefixed settings are a superset of and replace
+ <literal>BlockIO</literal>-prefixed ones. On unified hierarchy, IO resource control also applies
+ to buffered writes.</para>
</listitem>
</varlistentry>
application.</para>
<para>Legacy control group hierarchy (see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>), also called cgroup-v1,
- doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group
- hierarchy, resource control is disabled for systemd user instance, see
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
- </para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/">Control Groups version 1</ulink>),
+ also called cgroup-v1, doesn't allow safe delegation of controllers to unprivileged processes. If the
+ system uses the legacy control group hierarchy, resource control is disabled for the systemd user
+ instance, see
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
is used on the system. These options take an integer value and control the <literal>cpu.weight</literal>
control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control
group attribute, see <ulink
- url="https://www.kernel.org/doc/
Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink
- url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
+ url="https://www.kernel.org/doc/
html/latest/admin-guide/cgroup-v2.html">Control Groups v2</ulink> and <ulink
+ url="https://www.kernel.org/doc/html/latest/scheduler/sched-design-CFS.html">CFS Scheduler</ulink>.
The available CPU time is split up among all units within one slice relative to their CPU time weight.</para>
<para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system,
available on one CPU. Use values > 100% for allotting CPU time on more than one CPU. This controls the
<literal>cpu.max</literal> attribute on the unified control group hierarchy and
<literal>cpu.cfs_quota_us</literal> on legacy. For details about these control group attributes, see <ulink
- url="https://www.kernel.org/doc/
Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink
+ url="https://www.kernel.org/doc/
html/latest/admin-guide/cgroup-v2.html">Control Groups v2</ulink> and <ulink
url="https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt">sched-bwc.txt</ulink>.</para>
<para>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than
<para>This controls the second field of <literal>cpu.max</literal> attribute on the unified control group hierarchy
and <literal>cpu.cfs_period_us</literal> on legacy. For details about these control group attributes, see
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and
- <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
+ <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</ulink> and
+ <ulink url="https://www.kernel.org/doc/html/latest/scheduler/sched-design-CFS.html">CFS Scheduler</ulink>.</para>
<para>Example: <varname>CPUQuotaPeriodSec=10ms</varname> to request that the CPU quota is measured in periods of 10ms.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>AllowedCPUs=</varname></term>
+
+ <listitem>
+ <para>Restrict processes to be executed on specific CPUs. Takes a list of CPU indices or ranges separated by either
+ whitespace or commas. CPU ranges are specified by the lower and upper CPU indices separated by a dash.</para>
+
+ <para>Setting <varname>AllowedCPUs=</varname> doesn't guarantee that all of the CPUs will be used by the processes
+ as it may be limited by parent units. The effective configuration is reported as <varname>EffectiveCPUs=</varname>.</para>
+
+ <para>This setting is supported only with the unified control group hierarchy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>AllowedMemoryNodes=</varname></term>
+
+ <listitem>
+ <para>Restrict processes to be executed on specific memory NUMA nodes. Takes a list of memory NUMA nodes indices
+ or ranges separated by either whitespace or commas. Memory NUMA nodes ranges are specified by the lower and upper
+ CPU indices separated by a dash.</para>
+
+ <para>Setting <varname>AllowedMemoryNodes=</varname> doesn't guarantee that all of the memory NUMA nodes will
+ be used by the processes as it may be limited by parent units. The effective configuration is reported as
+ <varname>EffectiveMemoryNodes=</varname>.</para>
+
+ <para>This setting is supported only with the unified control group hierarchy.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>MemoryAccounting=</varname></term>
<para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
percentage value may be specified, which is taken relative to the installed physical memory on the
- system. This controls the <literal>memory.min</literal> control group attribute. For details about this
+ system. If assigned the special value <literal>infinity</literal>, all available memory is protected, which may be
+ useful in order to always inherit all of the protection afforded by ancestors.
+ This controls the <literal>memory.min</literal> control group attribute. For details about this
control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#memory-interface-files">Memory Interface Files</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para>
+
+ <para>Units may have their children use a default <literal>memory.min</literal> value by specifying
+ <varname>DefaultMemoryMin=</varname>, which has the same semantics as <varname>MemoryMin=</varname>. This setting
+ does not affect <literal>memory.min</literal> in the unit itself.</para>
</listitem>
</varlistentry>
<para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
percentage value may be specified, which is taken relative to the installed physical memory on the
- system. This controls the <literal>memory.low</literal> control group attribute. For details about this
+ system. If assigned the special value <literal>infinity</literal>, all available memory is protected, which may be
+ useful in order to always inherit all of the protection afforded by ancestors.
+ This controls the <literal>memory.low</literal> control group attribute. For details about this
control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#memory-interface-files">Memory Interface Files</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para>
+
+ <para>Units may have their children use a default <literal>memory.low</literal> value by specifying
+ <varname>DefaultMemoryLow=</varname>, which has the same semantics as <varname>MemoryLow=</varname>. This setting
+ does not affect <literal>memory.low</literal> in the unit itself.</para>
</listitem>
</varlistentry>
<term><varname>MemoryHigh=<replaceable>bytes</replaceable></varname></term>
<listitem>
- <para>Specify the high limit on memory usage of the executed processes in this unit. Memory usage may go
+ <para>Specify the throttling limit on memory usage of the executed processes in this unit. Memory usage may go
above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away
aggressively in such cases. This is the main mechanism to control memory usage of a unit.</para>
parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
percentage value may be specified, which is taken relative to the installed physical memory on the
system. If assigned the
- special value <literal>infinity</literal>, no memory limit is applied. This controls the
+ special value <literal>infinity</literal>, no memory throttling is applied. This controls the
<literal>memory.high</literal> control group attribute. For details about this control group attribute, see
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
+ <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#memory-interface-files">Memory Interface Files</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para>
percentage value may be specified, which is taken relative to the installed physical memory on the system. If
assigned the special value <literal>infinity</literal>, no memory limit is applied. This controls the
<literal>memory.max</literal> control group attribute. For details about this control group attribute, see
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
+ <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#memory-interface-files">Memory Interface Files</ulink>.</para>
<para>This setting replaces <varname>MemoryLimit=</varname>.</para>
</listitem>
parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the
special value <literal>infinity</literal>, no swap limit is applied. This controls the
<literal>memory.swap.max</literal> control group attribute. For details about this control group attribute,
- see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
+ see <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#memory-interface-files">Memory Interface Files</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para>
of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the
system. If assigned the special value <literal>infinity</literal>, no tasks limit is applied. This controls
the <literal>pids.max</literal> control group attribute. For details about this control group attribute, see
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para>
+ <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/pids.html">Process Number Controller</ulink>.
+ </para>
- <para>The
- system default for this setting may be controlled with
+ <para>The system default for this setting may be controlled with
<varname>DefaultTasksMax=</varname> in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</listitem>
hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block
I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to
100. For details about this control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. The available I/O
- bandwidth is split up among all units within one slice relative to their block I/O weight.</para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#io-interface-files">IO Interface Files</ulink>.
+ The available I/O bandwidth is split up among all units within one slice relative to their block
+ I/O weight.</para>
<para>While <varname>StartupIOWeight=</varname> only applies
to the startup phase of the system,
device of the file system of the file is determined. This controls the <literal>io.weight</literal> control
group attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices.
For details about this control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#io-interface-files">IO Interface Files</ulink>.</para>
<para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with
<varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
+
+ <para>The specified device node should reference a block device that has an I/O scheduler
+ associated, i.e. should not refer to partition or loopback block devices, but to the originating,
+ physical device. When a path to a regular file or directory is specified it is attempted to
+ discover the correct originating device backing the file system of the specified path. This works
+ correctly only for simpler cases, where the file system is directly placed on a partition or
+ physical block device, or where simple 1:1 encryption using dm-crypt/LUKS is used. This discovery
+ does not cover complex storage and in particular RAID and volume management storage devices.</para>
</listitem>
</varlistentry>
"/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control
group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details
about this control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#io-interface-files">IO Interface Files</ulink>.
</para>
<para>These settings replace <varname>BlockIOReadBandwidth=</varname> and
<varname>BlockIOWriteBandwidth=</varname> and disable settings prefixed with <varname>BlockIO</varname> or
<varname>StartupBlockIO</varname>.</para>
+
+ <para>Similar restrictions on block device discovery as for <varname>IODeviceWeight=</varname> apply, see above.</para>
</listitem>
</varlistentry>
"/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control
group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about
this control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#io-interface-files">IO Interface Files</ulink>.
</para>
<para>These settings are supported only if the unified control group hierarchy is used and disable settings
prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
+
+ <para>Similar restrictions on block device discovery as for <varname>IODeviceWeight=</varname> apply, see above.</para>
</listitem>
</varlistentry>
system of the file is determined. This controls the <literal>io.latency</literal> control group
attribute. Use this option multiple times to set latency target for multiple devices. For details about this
control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#io-interface-files">IO Interface Files</ulink>.</para>
<para>Implies <literal>IOAccounting=yes</literal>.</para>
<para>These settings are supported only if the unified control group hierarchy is used.</para>
+
+ <para>Similar restrictions on block device discovery as for <varname>IODeviceWeight=</varname> apply, see above.</para>
</listitem>
</varlistentry>
<term><varname>IPAddressDeny=<replaceable>ADDRESS[/PREFIXLENGTH]…</replaceable></varname></term>
<listitem>
- <para>Turn on address range network traffic filtering for packets sent and received over AF_INET and AF_INET6
- sockets. Both directives take a space separated list of IPv4 or IPv6 addresses, each optionally suffixed
- with an address prefix length (separated by a <literal>/</literal> character). If the latter is omitted, the
- address is considered a host address, i.e. the prefix covers the whole address (32 for IPv4, 128 for IPv6).
- </para>
-
- <para>The access lists 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 lists are implicitly combined with any lists
- configured for any of the parent slice units this unit might be a member of. By default all access lists are
- empty. When configured the lists are enforced as follows:</para>
+ <para>Turn on network traffic filtering for IP packets sent and received over
+ <constant>AF_INET</constant> and <constant>AF_INET6</constant> sockets. Both directives take a
+ space separated list of IPv4 or IPv6 addresses, each optionally suffixed with an address prefix
+ length in bits after a <literal>/</literal> character. If the suffix is omitted, the address is
+ considered a host address, i.e. the filter covers the whole address (32 bits for IPv4, 128 bits for
+ IPv6).</para>
+
+ <para>The access lists 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 lists are implicitly
+ combined with any lists configured for any of the parent slice units this unit might be a member
+ of. By default both access lists are empty. Both ingress and egress traffic is filtered by these
+ settings. In case of ingress traffic the source IP address is checked against these access lists,
+ in case of egress traffic the destination IP address is checked. The following rules are applied in
+ turn:</para>
<itemizedlist>
- <listitem><para>Access will be granted in case its destination/source address matches any entry in the
- <varname>IPAddressAllow=</varname> setting.</para></listitem>
+ <listitem><para>Access is granted when the checked IP address matches an entry in the
+ <varname>IPAddressAllow=</varname> list.</para></listitem>
- <listitem><para>Otherwise, access will be denied in case its destination/source address matches any entry
- in the <varname>IPAddressDeny=</varname> setting.</para></listitem>
+ <listitem><para>Otherwise, access is denied when the checked IP address matches an entry in the
+ <varname>IPAddressDeny=</varname> list.</para></listitem>
- <listitem><para>Otherwise, access will be granted.</para></listitem>
+ <listitem><para>Otherwise, access is granted.</para></listitem>
</itemizedlist>
- <para>In order to implement a whitelisting IP firewall, it is recommended to use a
- <varname>IPAddressDeny=</varname><constant>any</constant> setting on an upper-level slice unit (such as the
- root slice <filename>-.slice</filename> or the slice containing all system services
+ <para>In order to implement an allow-listing IP firewall, it is recommended to use a
+ <varname>IPAddressDeny=</varname><constant>any</constant> setting on an upper-level slice unit
+ (such as the root slice <filename>-.slice</filename> or the slice containing all system services
<filename>system.slice</filename> – see
- <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details on these slice units), plus individual per-service <varname>IPAddressAllow=</varname> lines
- permitting network access to relevant services, and only them.</para>
-
- <para>Note that for socket-activated services, the IP access list configured on the socket unit applies to
- all sockets associated with it directly, but not to any sockets created by the ultimately activated services
- for it. Conversely, the IP access list configured for the service is not applied to any sockets passed into
- the service via socket activation. Thus, it is usually a good idea, to replicate the IP access lists on both
- the socket and the service unit, however it often makes sense to maintain one list more open and the other
- one more restricted, depending on the usecase.</para>
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details on these slice units), plus individual per-service <varname>IPAddressAllow=</varname>
+ lines permitting network access to relevant services, and only them.</para>
+
+ <para>Note that for socket-activated services, the IP access list configured on the socket unit
+ applies to all sockets associated with it directly, but not to any sockets created by the
+ ultimately activated services for it. Conversely, the IP access list configured for the service is
+ not applied to any sockets passed into the service via socket activation. Thus, it is usually a
+ good idea to replicate the IP access lists on both the socket and the service unit. Nevertheless,
+ it may make sense to maintain one list more open and the other one more restricted, depending on
+ the usecase.</para>
<para>If these settings are used multiple times in the same unit the specified lists are combined. If an
empty string is assigned to these settings the specific access list is reset and all previous settings undone.</para>
</listitem>
</varlistentry>
+ <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>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 usecase.</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 fail the service 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>
+ </listitem>
+ </varlistentry>
+
<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 node(s) by the unit
- (<emphasis>m</emphasis>knod), respectively. This controls
- the <literal>devices.allow</literal> and
- <literal>devices.deny</literal> control group
- attributes. For details about these control group
- attributes, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>.</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
- whitelist 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. 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>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 node(s) by the unit
+ (<emphasis>m</emphasis>knod), respectively. On cgroup-v1 this controls the
+ <literal>devices.allow</literal> control group attribute. For details about this control group
+ attribute, see <ulink
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html">Device Whitelist Controller</ulink>.
+ In the unified cgroup hierarchy this functionality is implemented using eBPF filtering.</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>
+
</listitem>
</varlistentry>
hierarchy. Accordingly, access to the specified controllers will not be granted to unprivileged services on
the legacy hierarchy, even when requested.</para>
- <para>The following controller names may be specified: <option>cpu</option>, <option>cpuacct</option>,
- <option>io</option>, <option>blkio</option>, <option>memory</option>, <option>devices</option>,
- <option>pids</option>. Not all of these controllers are available on all kernels however, and some are
+ <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 aren't covered here yet as delegation is either not supported
at all for them or not defined cleanly.</para>
to disable. Passing <varname>DisableControllers=</varname> by itself with no controller name present resets
the disabled controller list.</para>
- <para>Valid controllers are <option>cpu</option>, <option>cpuacct</option>, <option>io</option>,
- <option>blkio</option>, <option>memory</option>, <option>devices</option>, and <option>pids</option>.</para>
+ <xi:include href="supported-controllers.xml" xpointer="controllers-text" />
</listitem>
</varlistentry>
</variablelist>
<para>Assign the specified CPU time share weight to the processes executed. These options take an integer
value and control the <literal>cpu.shares</literal> control group attribute. The allowed range is 2 to
262144. Defaults to 1024. For details about this control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
+ url="https://www.kernel.org/doc/html/latest/scheduler/sched-design-CFS.html">CFS Scheduler</ulink>.
The available CPU time is split up among all units within one slice relative to their CPU time share
weight.</para>
<literal>infinity</literal>, no memory limit is applied. This controls the
<literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group
attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/memory.html">Memory Resource Controller</ulink>.</para>
<para>Implies <literal>MemoryAccounting=yes</literal>.</para>
group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default
block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to
500. For details about this control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/blkio-controller.html">Block IO Controller</ulink>.
The available I/O bandwidth is split up among all units within one slice relative to their block I/O
weight.</para>
file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group
attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For
details about this control group attribute, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/blkio-controller.html">Block IO Controller</ulink>.</para>
<para>Implies
<literal>BlockIOAccounting=yes</literal>.</para>
<literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal>
control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For
details about these control group attributes, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
+ url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/blkio-controller.html">Block IO Controller</ulink>.
</para>
<para>Implies
<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
The documentation for control groups and specific controllers in the Linux kernel:
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>,
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt">cpuacct.txt</ulink>,
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>,
- <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
- <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt">sched-bwc.txt</ulink>.
+ <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</ulink>.
</para>
</refsect1>
</refentry>
projects / thirdparty / systemd.git / blobdiff