summaryrefslogtreecommitdiff
path: root/man/systemd.resource-control.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/systemd.resource-control.xml')
-rw-r--r--man/systemd.resource-control.xml243
1 files changed, 190 insertions, 53 deletions
diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml
index 08cdf06e23..066f2cc19b 100644
--- a/man/systemd.resource-control.xml
+++ b/man/systemd.resource-control.xml
@@ -99,6 +99,31 @@
</refsect1>
<refsect1>
+ <title>Unified and Legacy Control Group Hierarchies</title>
+
+ <para>Unified control group hierarchy is the new version of kernel control group interface. Depending on the
+ resource type, there are differences in resource control capabilities. Also, because of interface changes, some
+ resource types have a separate set of options on the unified hierarchy.</para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><option>IO</option></term>
+ <listitem>
+ <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname>
+ 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. If all
+ settings of a unit for a given resource type are for the other hierarchy type, the settings are translated and
+ applied. If there are any valid settings for the hierarchy in use, all translations are disabled for the resource
+ type. Mixing the two types of settings on a unit can lead to confusing results.</para>
+ </refsect1>
+
+ <refsect1>
<title>Options</title>
<para>Units of the types listed above can have settings
@@ -202,7 +227,7 @@
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/cgroups/memory.txt">memory.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para>
<para>Implies <literal>MemoryAccounting=true</literal>.</para>
</listitem>
@@ -239,7 +264,7 @@
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/cgroups/pids.txt">pids.txt</ulink>.</para>
+ url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para>
<para>Implies <literal>TasksAccounting=true</literal>. The
system default for this setting may be controlled with
@@ -249,17 +274,130 @@
</varlistentry>
<varlistentry>
+ <term><varname>IOAccounting=</varname></term>
+
+ <listitem>
+ <para>Turn on Block I/O accounting for this unit, if the unified 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>DefaultIOAccounting=</varname>
+ in
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <para>This setting is supported only if the unified control group hierarchy is used. Use
+ <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IOWeight=<replaceable>weight</replaceable></varname></term>
+ <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term>
+
+ <listitem>
+ <para>Set the default overall block I/O weight for the executed processes, if the unified control group
+ 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>
+
+ <para>While <varname>StartupIOWeight=</varname> only applies
+ to the startup phase of the system,
+ <varname>IOWeight=</varname> applies to the later runtime of
+ the system, and if the former is not set also to the startup
+ phase. This allows prioritizing specific services at boot-up
+ differently than during runtime.</para>
+
+ <para>Implies <literal>IOAccounting=true</literal>.</para>
+
+ <para>This setting is supported only if the unified control group hierarchy is used. Use
+ <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> on systems using the legacy
+ control group hierarchy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IODeviceWeight=<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 unified 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 1 and 10000. (Example: "/dev/sda 1000"). 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>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>
+
+ <para>Implies <literal>IOAccounting=true</literal>.</para>
+
+ <para>This setting is supported only if the unified control group hierarchy is used. Use
+ <varname>BlockIODeviceWeight=</varname> on systems using the legacy control group hierarchy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IOReadBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
+ <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
+
+ <listitem>
+ <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified
+ control group hierarchy is used on the system. This limit is not work-conserving and the executed processes
+ are not allowed to use more even if the device has idle capacity. 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>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>.
+ </para>
+
+ <para>Implies <literal>IOAccounting=true</literal>.</para>
+
+ <para>This setting is supported only if the unified control group hierarchy is used. Use
+ <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IOReadIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term>
+ <term><varname>IOWriteIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term>
+
+ <listitem>
+ <para>Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the
+ unified control group hierarchy is used on the system. This limit is not work-conserving and the executed
+ processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of
+ a file path and an IOPS value to specify the device specific IOPS. 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 IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS,
+ GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example:
+ "/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>.
+ </para>
+
+ <para>Implies <literal>IOAccounting=true</literal>.</para>
+
+ <para>This setting is supported only if the unified control group hierarchy is used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><varname>BlockIOAccounting=</varname></term>
<listitem>
- <para>Turn on Block I/O accounting for this unit. 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
+ <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 supported only if the legacy control group hierarchy is used. Use
+ <varname>IOAccounting=</varname> on systems using the unified control group hierarchy.</para>
</listitem>
</varlistentry>
@@ -267,15 +405,13 @@
<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. 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/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
- The available I/O bandwidth is split up among all units within
- one slice relative to their block I/O weight.</para>
+ <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://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</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 phase of the system,
@@ -286,29 +422,32 @@
<para>Implies
<literal>BlockIOAccounting=true</literal>.</para>
- </listitem>
+
+ <para>This setting is supported only if the legacy control group hierarchy is used. Use
+ <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> on systems using the unified control group
+ hierarchy.</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. 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://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
+ <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://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
<para>Implies
<literal>BlockIOAccounting=true</literal>.</para>
+
+ <para>This setting is supported only if the legacy control group hierarchy is used. Use
+ <varname>IODeviceWeight=</varname> on systems using the unified control group hierarchy.</para>
</listitem>
</varlistentry>
@@ -317,27 +456,25 @@
<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. 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.read_bps_device</literal> and
- <literal>blkio.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/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
+ <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://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
</para>
<para>Implies
<literal>BlockIOAccounting=true</literal>.</para>
+
+ <para>This setting is supported only if the legacy control group hierarchy is used. Use
+ <varname>IOReadBandwidthMax=</varname> and <varname>IOWriteBandwidthMax=</varname> on systems using the
+ unified control group hierarchy.</para>
</listitem>
</varlistentry>
@@ -357,7 +494,7 @@
<literal>devices.deny</literal> control group
attributes. For details about these control group
attributes, see <ulink
- url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
+ 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
@@ -482,10 +619,10 @@
<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/cgroups/cgroups.txt">cgroups.txt</ulink>,
- <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
- <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
- <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
+ <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>.
</para>
</refsect1>
</refentry>