man/systemd.resource-control.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2013 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd.resource-control">
  25   <refentryinfo>
  26     <title>systemd.resource-control</title>
  27     <productname>systemd</productname>
  28
  29     <authorgroup>
  30       <author>
  31         <contrib>Developer</contrib>
  32         <firstname>Lennart</firstname>
  33         <surname>Poettering</surname>
  34         <email>lennart@poettering.net</email>
  35       </author>
  36     </authorgroup>
  37   </refentryinfo>
  38
  39   <refmeta>
  40     <refentrytitle>systemd.resource-control</refentrytitle>
  41     <manvolnum>5</manvolnum>
  42   </refmeta>
  43
  44   <refnamediv>
  45     <refname>systemd.resource-control</refname>
  46     <refpurpose>Resource control unit settings</refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <para>
  51       <filename><replaceable>slice</replaceable>.slice</filename>,
  52       <filename><replaceable>scope</replaceable>.scope</filename>,
  53       <filename><replaceable>service</replaceable>.service</filename>,
  54       <filename><replaceable>socket</replaceable>.socket</filename>,
  55       <filename><replaceable>mount</replaceable>.mount</filename>,
  56       <filename><replaceable>swap</replaceable>.swap</filename>
  57     </para>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  63     <para>Unit configuration files for services, slices, scopes, sockets, mount points, and swap devices share a subset
  64     of configuration options for resource control of spawned processes. Internally, this relies on the Linux Control
  65     Groups (cgroups) kernel concept for organizing processes in a hierarchical tree of named groups for the purpose of
  66     resource management.</para>
  67
  68     <para>This man page lists the configuration options shared by
  69     those six unit types. See
  70     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  71     for the common options of all unit configuration files, and
  72     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  73     <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  74     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  75     <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  76     <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  77     and
  78     <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  79     for more information on the specific unit configuration files. The
  80     resource control configuration options are configured in the
  81     [Slice], [Scope], [Service], [Socket], [Mount], or [Swap]
  82     sections, depending on the unit type.</para>
  83
  84     <para>In addition, options which control resources available to programs
  85     <emphasis>executed</emphasis> by systemd are listed in
  86     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  87     Those options complement options listed here.</para>
  88
  89     <para>See the <ulink
  90     url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New
  91     Control Group Interfaces</ulink> for an introduction on how to make
  92     use of resource control APIs from programs.</para>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Implicit Dependencies</title>
  97
  98     <para>The following dependencies are implicitly added:</para>
  99
 100     <itemizedlist>
 101       <listitem><para>Units with the <varname>Slice=</varname> setting set automatically acquire
 102       <varname>Requires=</varname> and <varname>After=</varname> dependencies on the specified
 103       slice unit.</para></listitem>
 104     </itemizedlist>
 105   </refsect1>
 106
 107   <!-- We don't have any default dependency here. -->
 108
 109   <refsect1>
 110     <title>Unified and Legacy Control Group Hierarchies</title>
 111
 112     <para>The unified control group hierarchy is the new version of kernel control group interface, see <ulink
 113     url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. Depending on the resource type,
 114     there are differences in resource control capabilities.  Also, because of interface changes, some resource types
 115     have separate set of options on the unified hierarchy.</para>
 116
 117     <para>
 118       <variablelist>
 119
 120         <varlistentry>
 121           <term><option>CPU</option></term>
 122           <listitem>
 123             <para>Due to the lack of consensus in the kernel community, the CPU controller support on the unified
 124             control group hierarchy requires out-of-tree kernel patches. See <ulink
 125             url="https://git.kernel.org/cgit/linux/kernel/git/tj/cgroup.git/tree/Documentation/cgroup-v2-cpu.txt?h=cgroup-v2-cpu">cgroup-v2-cpu.txt</ulink>.</para>
 126
 127             <para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace
 128             <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para>
 129
 130             <para>The <literal>cpuacct</literal> controller does not exist separately on the unified hierarchy.</para>
 131           </listitem>
 132         </varlistentry>
 133
 134         <varlistentry>
 135           <term><option>Memory</option></term>
 136           <listitem>
 137             <para><varname>MemoryMax=</varname> replaces <varname>MemoryLimit=</varname>. <varname>MemoryLow=</varname>
 138             and <varname>MemoryHigh=</varname> are effective only on unified hierarchy.</para>
 139           </listitem>
 140         </varlistentry>
 141
 142         <varlistentry>
 143           <term><option>IO</option></term>
 144           <listitem>
 145             <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname>
 146             prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para>
 147           </listitem>
 148         </varlistentry>
 149
 150       </variablelist>
 151     </para>
 152
 153     <para>To ease the transition, there is best-effort translation between the two versions of settings. For each
 154     controller, if any of the settings for the unified hierarchy are present, all settings for the legacy hierarchy are
 155     ignored. If the resulting settings are for the other type of hierarchy, the configurations are translated before
 156     application.</para>
 157
 158     <para>Legacy control group hierarchy (see <ulink
 159     url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>), also called cgroup-v1,
 160     doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group
 161     hierarchy, resource control is disabled for systemd user instance, see
 162     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 163     </para>
 164   </refsect1>
 165
 166   <refsect1>
 167     <title>Options</title>
 168
 169     <para>Units of the types listed above can have settings
 170     for resource control configuration:</para>
 171
 172     <variablelist class='unit-directives'>
 173
 174       <varlistentry>
 175         <term><varname>CPUAccounting=</varname></term>
 176
 177         <listitem>
 178           <para>Turn on CPU usage accounting for this unit. Takes a
 179           boolean argument. Note that turning on CPU accounting for
 180           one unit will also implicitly turn it on for all units
 181           contained in the same slice and for all its parent slices
 182           and the units contained therein. The system default for this
 183           setting may be controlled with
 184           <varname>DefaultCPUAccounting=</varname> in
 185           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 186         </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><varname>CPUWeight=<replaceable>weight</replaceable></varname></term>
 191         <term><varname>StartupCPUWeight=<replaceable>weight</replaceable></varname></term>
 192
 193         <listitem>
 194           <para>Assign the specified CPU time weight to the processes executed, if the unified control group hierarchy
 195           is used on the system. These options take an integer value and control the <literal>cpu.weight</literal>
 196           control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control
 197           group attribute, see <ulink
 198           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink
 199           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
 200           The available CPU time is split up among all units within one slice relative to their CPU time weight.</para>
 201
 202           <para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system,
 203           <varname>CPUWeight=</varname> applies to normal runtime of the system, and if the former is not set also to
 204           the startup phase. Using <varname>StartupCPUWeight=</varname> allows prioritizing specific services at
 205           boot-up differently than during normal runtime.</para>
 206
 207           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 208
 209           <para>These settings replace <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>.</para>
 210         </listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><varname>CPUQuota=</varname></term>
 215
 216         <listitem>
 217           <para>Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with
 218           "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time
 219           available on one CPU. Use values &gt; 100% for allotting CPU time on more than one CPU. This controls the
 220           <literal>cpu.max</literal> attribute on the unified control group hierarchy and
 221           <literal>cpu.cfs_quota_us</literal> on legacy. For details about these control group attributes, see <ulink
 222           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink
 223           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
 224
 225           <para>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than
 226           20% CPU time on one CPU.</para>
 227
 228           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 229         </listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term><varname>MemoryAccounting=</varname></term>
 234
 235         <listitem>
 236           <para>Turn on process and kernel memory accounting for this
 237           unit. Takes a boolean argument. Note that turning on memory
 238           accounting for one unit will also implicitly turn it on for
 239           all units contained in the same slice and for all its parent
 240           slices and the units contained therein. The system default
 241           for this setting may be controlled with
 242           <varname>DefaultMemoryAccounting=</varname> in
 243           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><varname>MemoryLow=<replaceable>bytes</replaceable></varname></term>
 249
 250         <listitem>
 251           <para>Specify the best-effort memory usage protection of the executed processes in this unit. If the memory
 252           usages of this unit and all its ancestors are below their low boundaries, this unit's memory won't be
 253           reclaimed as long as memory can be reclaimed from unprotected units.</para>
 254
 255           <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
 256           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
 257           percentage value may be specified, which is taken relative to the installed physical memory on the
 258           system. This controls the <literal>memory.low</literal> control group attribute. For details about this
 259           control group attribute, see <ulink
 260           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 261
 262           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 263
 264           <para>This setting is supported only if the unified control group hierarchy is used and disables
 265           <varname>MemoryLimit=</varname>.</para>
 266         </listitem>
 267       </varlistentry>
 268
 269       <varlistentry>
 270         <term><varname>MemoryHigh=<replaceable>bytes</replaceable></varname></term>
 271
 272         <listitem>
 273           <para>Specify the high limit on memory usage of the executed processes in this unit. Memory usage may go
 274           above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away
 275           aggressively in such cases. This is the main mechanism to control memory usage of a unit.</para>
 276
 277           <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
 278           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
 279           percentage value may be specified, which is taken relative to the installed physical memory on the
 280           system. If assigned the
 281           special value <literal>infinity</literal>, no memory limit is applied. This controls the
 282           <literal>memory.high</literal> control group attribute. For details about this control group attribute, see
 283           <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 284
 285           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 286
 287           <para>This setting is supported only if the unified control group hierarchy is used and disables
 288           <varname>MemoryLimit=</varname>.</para>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><varname>MemoryMax=<replaceable>bytes</replaceable></varname></term>
 294
 295         <listitem>
 296           <para>Specify the absolute limit on memory usage of the executed processes in this unit. If memory usage
 297           cannot be contained under the limit, out-of-memory killer is invoked inside the unit. It is recommended to
 298           use <varname>MemoryHigh=</varname> as the main control mechanism and use <varname>MemoryMax=</varname> as the
 299           last line of defense.</para>
 300
 301           <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
 302           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
 303           percentage value may be specified, which is taken relative to the installed physical memory on the system. If
 304           assigned the special value <literal>infinity</literal>, no memory limit is applied. This controls the
 305           <literal>memory.max</literal> control group attribute. For details about this control group attribute, see
 306           <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 307
 308           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 309
 310           <para>This setting replaces <varname>MemoryLimit=</varname>.</para>
 311         </listitem>
 312       </varlistentry>
 313
 314       <varlistentry>
 315         <term><varname>MemorySwapMax=<replaceable>bytes</replaceable></varname></term>
 316
 317         <listitem>
 318           <para>Specify the absolute limit on swap usage of the executed processes in this unit.</para>
 319
 320           <para>Takes a swap size in bytes. If the value is suffixed with K, M, G or T, the specified swap size is
 321           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the
 322           special value <literal>infinity</literal>, no swap limit is applied. This controls the
 323           <literal>memory.swap.max</literal> control group attribute. For details about this control group attribute,
 324           see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 325
 326           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 327
 328           <para>This setting is supported only if the unified control group hierarchy is used and disables
 329           <varname>MemoryLimit=</varname>.</para>
 330         </listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><varname>TasksAccounting=</varname></term>
 335
 336         <listitem>
 337           <para>Turn on task accounting for this unit. Takes a
 338           boolean argument. If enabled, the system manager will keep
 339           track of the number of tasks in the unit. The number of
 340           tasks accounted this way includes both kernel threads and
 341           userspace processes, with each thread counting
 342           individually. Note that turning on tasks accounting for one
 343           unit will also implicitly turn it on for all units contained
 344           in the same slice and for all its parent slices and the
 345           units contained therein. The system default for this setting
 346           may be controlled with
 347           <varname>DefaultTasksAccounting=</varname> in
 348           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 349         </listitem>
 350       </varlistentry>
 351
 352       <varlistentry>
 353         <term><varname>TasksMax=<replaceable>N</replaceable></varname></term>
 354
 355         <listitem>
 356           <para>Specify the maximum number of tasks that may be created in the unit. This ensures that the number of
 357           tasks accounted for the unit (see above) stays below a specific limit. This either takes an absolute number
 358           of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the
 359           system.  If assigned the special value <literal>infinity</literal>, no tasks limit is applied. This controls
 360           the <literal>pids.max</literal> control group attribute. For details about this control group attribute, see
 361           <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para>
 362
 363           <para>Implies <literal>TasksAccounting=true</literal>. The
 364           system default for this setting may be controlled with
 365           <varname>DefaultTasksMax=</varname> in
 366           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 367         </listitem>
 368       </varlistentry>
 369
 370       <varlistentry>
 371         <term><varname>IOAccounting=</varname></term>
 372
 373         <listitem>
 374           <para>Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the
 375           system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly
 376           turn it on for all units contained in the same slice and all for its parent slices and the units contained
 377           therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname>
 378           in
 379           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 380
 381           <para>This setting replaces <varname>BlockIOAccounting=</varname> and disables settings prefixed with
 382           <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 383         </listitem>
 384       </varlistentry>
 385
 386       <varlistentry>
 387         <term><varname>IOWeight=<replaceable>weight</replaceable></varname></term>
 388         <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term>
 389
 390         <listitem>
 391           <para>Set the default overall block I/O weight for the executed processes, if the unified control group
 392           hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block
 393           I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to
 394           100. For details about this control group attribute, see <ulink
 395           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.  The available I/O
 396           bandwidth is split up among all units within one slice relative to their block I/O weight.</para>
 397
 398           <para>While <varname>StartupIOWeight=</varname> only applies
 399           to the startup phase of the system,
 400           <varname>IOWeight=</varname> applies to the later runtime of
 401           the system, and if the former is not set also to the startup
 402           phase. This allows prioritizing specific services at boot-up
 403           differently than during runtime.</para>
 404
 405           <para>Implies <literal>IOAccounting=true</literal>.</para>
 406
 407           <para>These settings replace <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname>
 408           and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 409         </listitem>
 410       </varlistentry>
 411
 412       <varlistentry>
 413         <term><varname>IODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 414
 415         <listitem>
 416           <para>Set the per-device overall block I/O weight for the executed processes, if the unified control group
 417           hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify
 418           the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). The file path may be
 419           specified as path to a block device node or as any other file, in which case the backing block device of the
 420           file system of the file is determined. This controls the <literal>io.weight</literal> control group
 421           attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For
 422           details about this control group attribute, see <ulink
 423           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 424
 425           <para>Implies <literal>IOAccounting=true</literal>.</para>
 426
 427           <para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with
 428           <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 429         </listitem>
 430       </varlistentry>
 431
 432       <varlistentry>
 433         <term><varname>IOReadBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 434         <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 435
 436         <listitem>
 437           <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified
 438           control group hierarchy is used on the system. This limit is not work-conserving and the executed processes
 439           are not allowed to use more even if the device has idle capacity.  Takes a space-separated pair of a file
 440           path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may
 441           be a path to a block device node, or as any other file in which case the backing block device of the file
 442           system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is
 443           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example:
 444           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control
 445           group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details
 446           about this control group attribute, see <ulink
 447           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.
 448           </para>
 449
 450           <para>Implies <literal>IOAccounting=true</literal>.</para>
 451
 452           <para>These settings replace <varname>BlockIOReadBandwidth=</varname> and
 453           <varname>BlockIOWriteBandwidth=</varname> and disable settings prefixed with <varname>BlockIO</varname> or
 454           <varname>StartupBlockIO</varname>.</para>
 455         </listitem>
 456       </varlistentry>
 457
 458       <varlistentry>
 459         <term><varname>IOReadIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term>
 460         <term><varname>IOWriteIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term>
 461
 462         <listitem>
 463           <para>Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the
 464           unified control group hierarchy is used on the system. This limit is not work-conserving and the executed
 465           processes are not allowed to use more even if the device has idle capacity.  Takes a space-separated pair of
 466           a file path and an IOPS value to specify the device specific IOPS. The file path may be a path to a block
 467           device node, or as any other file in which case the backing block device of the file system of the file is
 468           used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS,
 469           GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example:
 470           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control
 471           group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about
 472           this control group attribute, see <ulink
 473           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.
 474           </para>
 475
 476           <para>Implies <literal>IOAccounting=true</literal>.</para>
 477
 478           <para>These settings are supported only if the unified control group hierarchy is used and disable settings
 479           prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 480         </listitem>
 481       </varlistentry>
 482
 483       <varlistentry>
 484         <term><varname>DeviceAllow=</varname></term>
 485
 486         <listitem>
 487           <para>Control access to specific device nodes by the
 488           executed processes. Takes two space-separated strings: a
 489           device node specifier followed by a combination of
 490           <constant>r</constant>, <constant>w</constant>,
 491           <constant>m</constant> to control
 492           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
 493           or creation of the specific device node(s) by the unit
 494           (<emphasis>m</emphasis>knod), respectively. This controls
 495           the <literal>devices.allow</literal> and
 496           <literal>devices.deny</literal> control group
 497           attributes. For details about these control group
 498           attributes, see <ulink
 499           url="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>.</para>
 500
 501           <para>The device node specifier is either a path to a device
 502           node in the file system, starting with
 503           <filename>/dev/</filename>, or a string starting with either
 504           <literal>char-</literal> or <literal>block-</literal>
 505           followed by a device group name, as listed in
 506           <filename>/proc/devices</filename>. The latter is useful to
 507           whitelist all current and future devices belonging to a
 508           specific device group at once. The device group is matched
 509           according to filename globbing rules, you may hence use the
 510           <literal>*</literal> and <literal>?</literal>
 511           wildcards. Examples: <filename>/dev/sda5</filename> is a
 512           path to a device node, referring to an ATA or SCSI block
 513           device. <literal>char-pts</literal> and
 514           <literal>char-alsa</literal> are specifiers for all pseudo
 515           TTYs and all ALSA sound devices,
 516           respectively. <literal>char-cpu/*</literal> is a specifier
 517           matching all CPU related device groups.</para>
 518         </listitem>
 519       </varlistentry>
 520
 521       <varlistentry>
 522         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
 523
 524         <listitem>
 525           <para>
 526             Control the policy for allowing device access:
 527           </para>
 528           <variablelist>
 529             <varlistentry>
 530               <term><option>strict</option></term>
 531               <listitem>
 532                 <para>means to only allow types of access that are
 533                 explicitly specified.</para>
 534               </listitem>
 535             </varlistentry>
 536
 537             <varlistentry>
 538               <term><option>closed</option></term>
 539               <listitem>
 540                 <para>in addition, allows access to standard pseudo
 541                 devices including
 542                 <filename>/dev/null</filename>,
 543                 <filename>/dev/zero</filename>,
 544                 <filename>/dev/full</filename>,
 545                 <filename>/dev/random</filename>, and
 546                 <filename>/dev/urandom</filename>.
 547                 </para>
 548               </listitem>
 549             </varlistentry>
 550
 551             <varlistentry>
 552               <term><option>auto</option></term>
 553               <listitem>
 554                 <para>
 555                   in addition, allows access to all devices if no
 556                   explicit <varname>DeviceAllow=</varname> is present.
 557                   This is the default.
 558                 </para>
 559               </listitem>
 560             </varlistentry>
 561           </variablelist>
 562         </listitem>
 563       </varlistentry>
 564
 565       <varlistentry>
 566         <term><varname>Slice=</varname></term>
 567
 568         <listitem>
 569           <para>The name of the slice unit to place the unit
 570           in. Defaults to <filename>system.slice</filename> for all
 571           non-instantiated units of all unit types (except for slice
 572           units themselves see below). Instance units are by default
 573           placed in a subslice of <filename>system.slice</filename>
 574           that is named after the template name.</para>
 575
 576           <para>This option may be used to arrange systemd units in a
 577           hierarchy of slices each of which might have resource
 578           settings applied.</para>
 579
 580           <para>For units of type slice, the only accepted value for
 581           this setting is the parent slice. Since the name of a slice
 582           unit implies the parent slice, it is hence redundant to ever
 583           set this parameter directly for slice units.</para>
 584
 585           <para>Special care should be taken when relying on the default slice assignment in templated service units
 586           that have <varname>DefaultDependencies=no</varname> set, see
 587           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, section
 588           "Default Dependencies" for details.</para>
 589
 590         </listitem>
 591       </varlistentry>
 592
 593       <varlistentry>
 594         <term><varname>Delegate=</varname></term>
 595
 596         <listitem>
 597           <para>Turns on delegation of further resource control
 598           partitioning to processes of the unit. For unprivileged
 599           services (i.e. those using the <varname>User=</varname>
 600           setting), this allows processes to create a subhierarchy
 601           beneath its control group path. For privileged services and
 602           scopes, this ensures the processes will have all control
 603           group controllers enabled.</para>
 604         </listitem>
 605       </varlistentry>
 606
 607     </variablelist>
 608   </refsect1>
 609
 610   <refsect1>
 611     <title>Deprecated Options</title>
 612
 613     <para>The following options are deprecated. Use the indicated superseding options instead:</para>
 614
 615     <variablelist class='unit-directives'>
 616
 617       <varlistentry>
 618         <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
 619         <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>
 620
 621         <listitem>
 622           <para>Assign the specified CPU time share weight to the processes executed. These options take an integer
 623           value and control the <literal>cpu.shares</literal> control group attribute. The allowed range is 2 to
 624           262144. Defaults to 1024. For details about this control group attribute, see <ulink
 625           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
 626           The available CPU time is split up among all units within one slice relative to their CPU time share
 627           weight.</para>
 628
 629           <para>While <varname>StartupCPUShares=</varname> only applies to the startup phase of the system,
 630           <varname>CPUShares=</varname> applies to normal runtime of the system, and if the former is not set also to
 631           the startup phase. Using <varname>StartupCPUShares=</varname> allows prioritizing specific services at
 632           boot-up differently than during normal runtime.</para>
 633
 634           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 635
 636           <para>These settings are deprecated. Use <varname>CPUWeight=</varname> and
 637           <varname>StartupCPUWeight=</varname> instead.</para>
 638         </listitem>
 639       </varlistentry>
 640
 641       <varlistentry>
 642         <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
 643
 644         <listitem>
 645           <para>Specify the limit on maximum memory usage of the executed processes. The limit specifies how much
 646           process and kernel memory can be used by tasks in this unit. Takes a memory size in bytes. If the value is
 647           suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or
 648           Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is
 649           taken relative to the installed physical memory on the system. If assigned the special value
 650           <literal>infinity</literal>, no memory limit is applied. This controls the
 651           <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group
 652           attribute, see <ulink
 653           url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para>
 654
 655           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 656
 657           <para>This setting is deprecated. Use <varname>MemoryMax=</varname> instead.</para>
 658         </listitem>
 659       </varlistentry>
 660
 661       <varlistentry>
 662         <term><varname>BlockIOAccounting=</varname></term>
 663
 664         <listitem>
 665           <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the
 666           system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly
 667           turn it on for all units contained in the same slice and all for its parent slices and the units contained
 668           therein. The system default for this setting may be controlled with
 669           <varname>DefaultBlockIOAccounting=</varname> in
 670           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 671
 672           <para>This setting is deprecated. Use <varname>IOAccounting=</varname> instead.</para>
 673         </listitem>
 674       </varlistentry>
 675
 676       <varlistentry>
 677         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
 678         <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
 679
 680         <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control
 681         group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default
 682         block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to
 683         500. For details about this control group attribute, see <ulink
 684         url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
 685         The available I/O bandwidth is split up among all units within one slice relative to their block I/O
 686         weight.</para>
 687
 688         <para>While <varname>StartupBlockIOWeight=</varname> only
 689         applies to the startup phase of the system,
 690         <varname>BlockIOWeight=</varname> applies to the later runtime
 691         of the system, and if the former is not set also to the
 692         startup phase. This allows prioritizing specific services at
 693         boot-up differently than during runtime.</para>
 694
 695         <para>Implies
 696         <literal>BlockIOAccounting=true</literal>.</para>
 697
 698         <para>These settings are deprecated. Use <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname>
 699         instead.</para>
 700
 701       </listitem>
 702       </varlistentry>
 703
 704       <varlistentry>
 705         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 706
 707         <listitem>
 708           <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group
 709           hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify
 710           the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be
 711           specified as path to a block device node or as any other file, in which case the backing block device of the
 712           file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group
 713           attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For
 714           details about this control group attribute, see <ulink
 715           url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
 716
 717           <para>Implies
 718           <literal>BlockIOAccounting=true</literal>.</para>
 719
 720           <para>This setting is deprecated. Use <varname>IODeviceWeight=</varname> instead.</para>
 721         </listitem>
 722       </varlistentry>
 723
 724       <varlistentry>
 725         <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 726         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 727
 728         <listitem>
 729           <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control
 730           group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in
 731           bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device
 732           node, or as any other file in which case the backing block device of the file system of the file is used. If
 733           the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes,
 734           Gigabytes, or Terabytes, respectively, to the base of 1000. (Example:
 735           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the
 736           <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal>
 737           control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For
 738           details about these control group attributes, see <ulink
 739           url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
 740           </para>
 741
 742           <para>Implies
 743           <literal>BlockIOAccounting=true</literal>.</para>
 744
 745           <para>These settings are deprecated. Use <varname>IOReadBandwidthMax=</varname> and
 746           <varname>IOWriteBandwidthMax=</varname> instead.</para>
 747         </listitem>
 748       </varlistentry>
 749
 750     </variablelist>
 751   </refsect1>
 752
 753   <refsect1>
 754     <title>See Also</title>
 755     <para>
 756       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 757       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 758       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 759       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 760       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 761       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 762       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 763       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 764       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 765       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 766       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 767       The documentation for control groups and specific controllers in the Linux kernel:
 768       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>,
 769       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt">cpuacct.txt</ulink>,
 770       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>,
 771       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
 772     </para>
 773   </refsect1>
 774 </refentry>