doc: link to html versions of cgroup docs

Also stop linking to some (obsolete) v1 documentation.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2020-01-09 10:37:52 +01:00
parent 8ac7339648
commit bb6d563a50
3 changed files with 40 additions and 44 deletions

View File

@ -21,10 +21,10 @@ comprehensive up-to-date information about all this, particular in light of the
poor implementations of the components interfacing with systemd of current poor implementations of the components interfacing with systemd of current
container managers. container managers.
Before you read on, please make sure you read the low-level [kernel Before you read on, please make sure you read the low-level kernel
documentation about documentation about the
cgroup v2](https://www.kernel.org/doc/Documentation/cgroup-v2.txt). This [unified cgroup hierarchy](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html).
documentation then adds in the higher-level view from systemd. This document then adds in the higher-level view from systemd.
This document augments the existing documentation we already have: This document augments the existing documentation we already have:

View File

@ -82,10 +82,10 @@
<refsect1> <refsect1>
<title>Unified and Legacy Control Group Hierarchies</title> <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 <para>The unified control group hierarchy is the new version of kernel control group interface, see
url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. Depending on the resource type, <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</ulink>.
there are differences in resource control capabilities. Also, because of interface changes, some resource types Depending on the resource type, there are differences in resource control capabilities. Also, because of
have separate set of options on the unified hierarchy.</para> interface changes, some resource types have separate set of options on the unified hierarchy.</para>
<para> <para>
<variablelist> <variablelist>
@ -126,11 +126,11 @@
application.</para> application.</para>
<para>Legacy control group hierarchy (see <ulink <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, url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/">Control Groups version 1</ulink>),
doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group also called cgroup-v1, doesn't allow safe delegation of controllers to unprivileged processes. If the
hierarchy, resource control is disabled for systemd user instance, see system uses the legacy control group hierarchy, resource control is disabled for the systemd user
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. instance, see
</para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -165,8 +165,8 @@
is used on the system. These options take an integer value and control the <literal>cpu.weight</literal> 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 control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control
group attribute, see <ulink 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/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</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/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> 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, <para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system,
@ -187,7 +187,7 @@
available on one CPU. Use values &gt; 100% for allotting CPU time on more than one CPU. This controls the available on one CPU. Use values &gt; 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.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 <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> 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>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than
@ -208,8 +208,8 @@
<para>This controls the second field of <literal>cpu.max</literal> attribute on the unified control group hierarchy <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 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/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</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/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> <para>Example: <varname>CPUQuotaPeriodSec=10ms</varname> to request that the CPU quota is measured in periods of 10ms.</para>
</listitem> </listitem>
@ -274,7 +274,7 @@
useful in order to always inherit all of the protection afforded by ancestors. 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 This controls the <literal>memory.min</literal> control group attribute. For details about this
control group attribute, see <ulink 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">Control Groups v2</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables <para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para> <varname>MemoryLimit=</varname>.</para>
@ -300,7 +300,7 @@
useful in order to always inherit all of the protection afforded by ancestors. 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 This controls the <literal>memory.low</literal> control group attribute. For details about this
control group attribute, see <ulink 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">Control Groups v2</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables <para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para> <varname>MemoryLimit=</varname>.</para>
@ -325,7 +325,7 @@
system. If assigned the system. If assigned the
special value <literal>infinity</literal>, no memory throttling 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 <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">Control Groups v2</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables <para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para> <varname>MemoryLimit=</varname>.</para>
@ -346,7 +346,7 @@
percentage value may be specified, which is taken relative to the installed physical memory on the system. If 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 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 <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">Control Groups v2</ulink>.</para>
<para>This setting replaces <varname>MemoryLimit=</varname>.</para> <para>This setting replaces <varname>MemoryLimit=</varname>.</para>
</listitem> </listitem>
@ -362,7 +362,7 @@
parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the 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 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, <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">Control Groups v2</ulink>.</para>
<para>This setting is supported only if the unified control group hierarchy is used and disables <para>This setting is supported only if the unified control group hierarchy is used and disables
<varname>MemoryLimit=</varname>.</para> <varname>MemoryLimit=</varname>.</para>
@ -397,10 +397,10 @@
of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the 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 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 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 <para>The system default for this setting may be controlled with
system default for this setting may be controlled with
<varname>DefaultTasksMax=</varname> in <varname>DefaultTasksMax=</varname> in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</listitem> </listitem>
@ -431,7 +431,7 @@
hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block 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 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 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 url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</ulink>. The available I/O
bandwidth is split up among all units within one slice relative to their block I/O weight.</para> 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 <para>While <varname>StartupIOWeight=</varname> only applies
@ -457,7 +457,7 @@
device of the file system of the file is determined. This controls the <literal>io.weight</literal> control 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. 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 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">Control Groups v2</ulink>.</para>
<para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with <para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with
<varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
@ -479,7 +479,7 @@
"/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control "/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 group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details
about this control group attribute, see <ulink 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">Control Groups v2</ulink>.
</para> </para>
<para>These settings replace <varname>BlockIOReadBandwidth=</varname> and <para>These settings replace <varname>BlockIOReadBandwidth=</varname> and
@ -503,7 +503,7 @@
"/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control "/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 group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about
this control group attribute, see <ulink 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">Control Groups v2</ulink>.
</para> </para>
<para>These settings are supported only if the unified control group hierarchy is used and disable settings <para>These settings are supported only if the unified control group hierarchy is used and disable settings
@ -522,7 +522,7 @@
system of the file is determined. This controls the <literal>io.latency</literal> control group 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 attribute. Use this option multiple times to set latency target for multiple devices. For details about this
control group attribute, see <ulink 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">Control Groups v2</ulink>.</para>
<para>Implies <literal>IOAccounting=yes</literal>.</para> <para>Implies <literal>IOAccounting=yes</literal>.</para>
@ -697,8 +697,8 @@
(<emphasis>m</emphasis>knod), respectively. On cgroup-v1 this controls the (<emphasis>m</emphasis>knod), respectively. On cgroup-v1 this controls the
<literal>devices.allow</literal> control group attribute. For details about this control group <literal>devices.allow</literal> control group attribute. For details about this control group
attribute, see <ulink attribute, see <ulink
url="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>. On url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html">Device Whitelist Controller</ulink>.
cgroup-v2 this functionality is implemented using eBPF filtering.</para> 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 <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 <filename>/dev/</filename>, or a string starting with either <literal>char-</literal> or
@ -883,7 +883,7 @@ DeviceAllow=/dev/loop-control
<para>Assign the specified CPU time share weight to the processes executed. These options take an integer <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 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 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 The available CPU time is split up among all units within one slice relative to their CPU time share
weight.</para> weight.</para>
@ -911,7 +911,7 @@ DeviceAllow=/dev/loop-control
<literal>infinity</literal>, no memory limit is applied. This controls the <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 <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group
attribute, see <ulink 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> <para>Implies <literal>MemoryAccounting=yes</literal>.</para>
@ -942,7 +942,7 @@ DeviceAllow=/dev/loop-control
group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default 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 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 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 The available I/O bandwidth is split up among all units within one slice relative to their block I/O
weight.</para> weight.</para>
@ -973,7 +973,7 @@ DeviceAllow=/dev/loop-control
file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group 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 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 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 <para>Implies
<literal>BlockIOAccounting=yes</literal>.</para> <literal>BlockIOAccounting=yes</literal>.</para>
@ -997,7 +997,7 @@ DeviceAllow=/dev/loop-control
<literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal> <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 control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For
details about these control group attributes, see <ulink 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>
<para>Implies <para>Implies
@ -1027,11 +1027,7 @@ DeviceAllow=/dev/loop-control
<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</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: 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/html/latest/admin-guide/cgroup-v2.html">Control Groups v2</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>.
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry>

View File

@ -873,7 +873,7 @@
<listitem><para>When specified without an argument or with a true argument, <listitem><para>When specified without an argument or with a true argument,
enables the usage of enables the usage of
<ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">unified cgroup hierarchy</ulink> <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html">unified cgroup hierarchy</ulink>
(a.k.a. cgroups-v2). When specified with a false argument, fall back to (a.k.a. cgroups-v2). When specified with a false argument, fall back to
hybrid or full legacy cgroup hierarchy.</para> hybrid or full legacy cgroup hierarchy.</para>