<!-- We don't have any default dependency here. -->
- <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://docs.kernel.org/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>CPU</term>
- <listitem>
- <para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace
- <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para>
-
- <para>The <literal>cpuacct</literal> controller does not exist separately on the unified hierarchy.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>IO</term>
- <listitem>
- <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>
-
- </variablelist>
- </para>
-
- <para>To ease the transition, there is best-effort translation between the two versions of settings. For each
- controller, if any of the settings for the unified hierarchy are present, all settings for the legacy hierarchy are
- ignored. If the resulting settings are for the other type of hierarchy, the configurations are translated before
- application.</para>
-
- <para>Legacy control group hierarchy (see <ulink
- url="https://docs.kernel.org/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>
<title>Options</title>
<varname>CPUWeight=</varname> applies to normal runtime of the system, and if the former is not set also to
the startup and shutdown phases. Using <varname>StartupCPUWeight=</varname> allows prioritizing specific services at
boot-up and shutdown differently than during normal runtime.</para>
-
- <para>These settings replace <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>.</para>
</listitem>
</varlistentry>
For details about this control group attribute, see <ulink
url="https://docs.kernel.org/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> or
<literal>memory.low</literal> value by specifying <varname>DefaultMemoryMin=</varname> or
<varname>DefaultMemoryLow=</varname>, which has the same semantics as
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://docs.kernel.org/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>
</listitem>
</varlistentry>
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://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files">Memory Interface Files</ulink>.</para>
-
- <para>This setting replaces <varname>MemoryLimit=</varname>.</para>
</listitem>
</varlistentry>
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://docs.kernel.org/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>
</listitem>
</varlistentry>
<term><varname>TasksMax=<replaceable>N</replaceable></varname></term>
<listitem>
- <para>Specify the maximum number of tasks that may be created in the unit. This ensures that the number of
- tasks accounted for the unit (see above) stays below a specific limit. This either takes an absolute number
- 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://docs.kernel.org/admin-guide/cgroup-v1/pids.html">Process Number Controller</ulink>.
- </para>
+ <para>Specify the maximum number of tasks that may be created in the unit. This ensures that the
+ number of tasks accounted for the unit (see above) stays below a specific limit. This either takes
+ an absolute number 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, the
+ <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#pid">pids controller
+ </ulink>.</para>
<para>The system default for this setting may be controlled with
<varname>DefaultTasksMax=</varname> in
therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname>
in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
-
- <para>This setting replaces <varname>BlockIOAccounting=</varname> and disables settings prefixed with
- <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
</listitem>
</varlistentry>
the system, and if the former is not set also to the startup
and shutdown phases. This allows prioritizing specific services at boot-up
and shutdown differently than during runtime.</para>
-
- <para>These settings replace <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname>
- and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
</listitem>
</varlistentry>
For details about this control group attribute, see <ulink
url="https://docs.kernel.org/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
url="https://docs.kernel.org/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>
url="https://docs.kernel.org/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>
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://docs.kernel.org/admin-guide/cgroup-v1/devices.html">Device Whitelist Controller</ulink>.
- In the unified cgroup hierarchy this functionality is implemented using eBPF filtering.</para>
+ (<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
</variablelist>
</refsect1>
- <refsect1>
- <title>Deprecated Options</title>
-
- <para>The following options are deprecated. Use the indicated superseding options instead:</para>
-
- <variablelist class='unit-directives'>
-
- <varlistentry>
- <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
- <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>
-
- <listitem>
- <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://docs.kernel.org/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>
-
- <para>While <varname>StartupCPUShares=</varname> applies to the startup and shutdown phases of the system,
- <varname>CPUShares=</varname> applies to normal runtime of the system, and if the former is not set also to
- the startup and shutdown phases. Using <varname>StartupCPUShares=</varname> allows prioritizing specific services at
- boot-up and shutdown differently than during normal runtime.</para>
-
- <para>Implies <literal>CPUAccounting=yes</literal>.</para>
-
- <para>These settings are deprecated. Use <varname>CPUWeight=</varname> and
- <varname>StartupCPUWeight=</varname> instead.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
-
- <listitem>
- <para>Specify the limit on maximum memory usage of the executed processes. The limit specifies how much
- process and kernel memory can be used by tasks in this unit. 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. If assigned the special value
- <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://docs.kernel.org/admin-guide/cgroup-v1/memory.html">Memory Resource Controller</ulink>.</para>
-
- <para>Implies <literal>MemoryAccounting=yes</literal>.</para>
-
- <para>This setting is deprecated. Use <varname>MemoryMax=</varname> instead.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>BlockIOAccounting=</varname></term>
-
- <listitem>
- <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the
- system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly
- turn it on for all units contained in the same slice and all for its parent slices and the units contained
- therein. The system default for this setting may be controlled with
- <varname>DefaultBlockIOAccounting=</varname> in
- <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
-
- <para>This setting is deprecated. Use <varname>IOAccounting=</varname> instead.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
- <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
-
- <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control
- 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://docs.kernel.org/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>
-
- <para>While <varname>StartupBlockIOWeight=</varname> only
- applies to the startup and shutdown phases of the system,
- <varname>BlockIOWeight=</varname> applies to the later runtime
- of the system, and if the former is not set also to the
- startup and shutdown phases. This allows prioritizing specific services at
- boot-up and shutdown differently than during runtime.</para>
-
- <para>Implies
- <literal>BlockIOAccounting=yes</literal>.</para>
-
- <para>These settings are deprecated. Use <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname>
- instead.</para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
-
- <listitem>
- <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group
- hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify
- the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be
- specified as path to a block device node or as any other file, in which case the backing block device of the
- 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://docs.kernel.org/admin-guide/cgroup-v1/blkio-controller.html">Block IO Controller</ulink>.</para>
-
- <para>Implies
- <literal>BlockIOAccounting=yes</literal>.</para>
-
- <para>This setting is deprecated. Use <varname>IODeviceWeight=</varname> instead.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
- <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
-
- <listitem>
- <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control
- group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in
- bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device
- node, or as any other file in which case the backing block device of the file system of the file is used. If
- the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes,
- Gigabytes, or Terabytes, respectively, to the base of 1000. (Example:
- "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the
- <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://docs.kernel.org/admin-guide/cgroup-v1/blkio-controller.html">Block IO Controller</ulink>.
- </para>
-
- <para>Implies
- <literal>BlockIOAccounting=yes</literal>.</para>
-
- <para>These settings are deprecated. Use <varname>IOReadBandwidthMax=</varname> and
- <varname>IOWriteBandwidthMax=</varname> instead.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </refsect1>
-
<refsect1>
<title>See Also</title>
<para>
memory its accounting data is flushed out too. However, this data is generally not lost, as a journal log record
is generated declaring the consumed resources whenever a unit shuts down.</para>
- <para>Processes systemd spawns are placed in individual Linux
- control groups named after the unit which they belong to in the
- private systemd hierarchy. (see <ulink
- url="https://docs.kernel.org/admin-guide/cgroup-v1/index.html">Control Groups version 1</ulink>
- for more information about control groups, or short "cgroups").
- systemd uses this to effectively keep track of processes. Control
- group information is maintained in the kernel, and is accessible
- via the file system hierarchy (beneath
- <filename>/sys/fs/cgroup/systemd/</filename>), or in tools such as
- <citerefentry project='man-pages'><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- or
- <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- (<command>ps xawf -eo pid,user,cgroup,args</command> is
- particularly useful to list all processes and the systemd units
- they belong to.).</para>
+ <para>Processes systemd spawns are placed in individual Linux control groups named after the unit which
+ they belong to in the private systemd hierarchy. (see <ulink
+ url="https://docs.kernel.org/admin-guide/cgroup-v2.html">Control Groups v2</ulink> for more information
+ about control groups, or short "cgroups"). systemd uses this to effectively keep track of
+ processes. Control group information is maintained in the kernel, and is accessible via the file system
+ hierarchy (beneath <filename>/sys/fs/cgroup/</filename>), or in tools such as <citerefentry
+ project='man-pages'><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
+ <citerefentry
+ project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> (<command>ps
+ xawf -eo pid,user,cgroup,args</command> is particularly useful to list all processes and the systemd
+ units they belong to.).</para>
<para>systemd is compatible with the SysV init system to a large
degree: SysV init scripts are supported and simply read as an
for every boot.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>systemd.unified_cgroup_hierarchy</varname></term>
-
- <listitem><para>When specified without an argument or with a true argument,
- enables the usage of
- <ulink url="https://docs.kernel.org/admin-guide/cgroup-v2.html">unified cgroup hierarchy</ulink>
- (a.k.a. cgroups-v2). When specified with a false argument, fall back to
- hybrid or full legacy cgroup hierarchy.</para>
-
- <para>If this option is not specified, the default behaviour is determined
- during compilation (the <option>-Ddefault-hierarchy=</option> meson
- option). If the kernel does not support unified cgroup hierarchy, the legacy
- hierarchy will be used even if this option is specified.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>systemd.legacy_systemd_cgroup_controller</varname></term>
-
- <listitem><para>Takes effect if the full unified cgroup hierarchy is not used
- (see previous option). When specified without an argument or with a true
- argument, disables the use of "hybrid" cgroup hierarchy (i.e. a cgroups-v2
- tree used for systemd, and
- <ulink url="https://docs.kernel.org/admin-guide/cgroup-v1/index.html">legacy
- cgroup hierarchy</ulink>, a.k.a. cgroups-v1, for other controllers), and
- forces a full "legacy" mode. When specified with a false argument, enables
- the use of "hybrid" hierarchy.</para>
-
- <para>If this option is not specified, the default behaviour is determined
- during compilation (the <option>-Ddefault-hierarchy=</option> meson
- option). If the kernel does not support unified cgroup hierarchy, the legacy
- hierarchy will be used even if this option is specified.</para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>systemd.set_credential=</varname></term>
projects / thirdparty / systemd.git / commitdiff
