diff options
Diffstat (limited to 'man/systemd.resource-control.xml')
| -rw-r--r-- | man/systemd.resource-control.xml | 243 |
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> |