man/systemd.resource-control.xml

   1 <?xml version='1.0'?>
   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   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd.resource-control">
  10   <refentryinfo>
  11     <title>systemd.resource-control</title>
  12     <productname>systemd</productname>
  13   </refentryinfo>
  14
  15   <refmeta>
  16     <refentrytitle>systemd.resource-control</refentrytitle>
  17     <manvolnum>5</manvolnum>
  18   </refmeta>
  19
  20   <refnamediv>
  21     <refname>systemd.resource-control</refname>
  22     <refpurpose>Resource control unit settings</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para>
  27       <filename><replaceable>slice</replaceable>.slice</filename>,
  28       <filename><replaceable>scope</replaceable>.scope</filename>,
  29       <filename><replaceable>service</replaceable>.service</filename>,
  30       <filename><replaceable>socket</replaceable>.socket</filename>,
  31       <filename><replaceable>mount</replaceable>.mount</filename>,
  32       <filename><replaceable>swap</replaceable>.swap</filename>
  33     </para>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para>Unit configuration files for services, slices, scopes, sockets, mount points, and swap devices share a subset
  40     of configuration options for resource control of spawned processes. Internally, this relies on the Linux Control
  41     Groups (cgroups) kernel concept for organizing processes in a hierarchical tree of named groups for the purpose of
  42     resource management.</para>
  43
  44     <para>This man page lists the configuration options shared by
  45     those six unit types. See
  46     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  47     for the common options of all unit configuration files, and
  48     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  49     <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  50     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  51     <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  52     <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  53     and
  54     <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  55     for more information on the specific unit configuration files. The
  56     resource control configuration options are configured in the
  57     [Slice], [Scope], [Service], [Socket], [Mount], or [Swap]
  58     sections, depending on the unit type.</para>
  59
  60     <para>In addition, options which control resources available to programs
  61     <emphasis>executed</emphasis> by systemd are listed in
  62     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  63     Those options complement options listed here.</para>
  64
  65     <para>See the <ulink
  66     url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New
  67     Control Group Interfaces</ulink> for an introduction on how to make
  68     use of resource control APIs from programs.</para>
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>Implicit Dependencies</title>
  73
  74     <para>The following dependencies are implicitly added:</para>
  75
  76     <itemizedlist>
  77       <listitem><para>Units with the <varname>Slice=</varname> setting set automatically acquire
  78       <varname>Requires=</varname> and <varname>After=</varname> dependencies on the specified
  79       slice unit.</para></listitem>
  80     </itemizedlist>
  81   </refsect1>
  82
  83   <!-- We don't have any default dependency here. -->
  84
  85   <refsect1>
  86     <title>Unified and Legacy Control Group Hierarchies</title>
  87
  88     <para>The unified control group hierarchy is the new version of kernel control group interface, see <ulink
  89     url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. Depending on the resource type,
  90     there are differences in resource control capabilities.  Also, because of interface changes, some resource types
  91     have separate set of options on the unified hierarchy.</para>
  92
  93     <para>
  94       <variablelist>
  95
  96         <varlistentry>
  97           <term><option>CPU</option></term>
  98           <listitem>
  99             <para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace
 100             <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para>
 101
 102             <para>The <literal>cpuacct</literal> controller does not exist separately on the unified hierarchy.</para>
 103           </listitem>
 104         </varlistentry>
 105
 106         <varlistentry>
 107           <term><option>Memory</option></term>
 108           <listitem>
 109             <para><varname>MemoryMax=</varname> replaces <varname>MemoryLimit=</varname>. <varname>MemoryLow=</varname>
 110             and <varname>MemoryHigh=</varname> are effective only on unified hierarchy.</para>
 111           </listitem>
 112         </varlistentry>
 113
 114         <varlistentry>
 115           <term><option>IO</option></term>
 116           <listitem>
 117             <para><varname>IO</varname> prefixed settings are a superset of and replace <varname>BlockIO</varname>
 118             prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para>
 119           </listitem>
 120         </varlistentry>
 121
 122       </variablelist>
 123     </para>
 124
 125     <para>To ease the transition, there is best-effort translation between the two versions of settings. For each
 126     controller, if any of the settings for the unified hierarchy are present, all settings for the legacy hierarchy are
 127     ignored. If the resulting settings are for the other type of hierarchy, the configurations are translated before
 128     application.</para>
 129
 130     <para>Legacy control group hierarchy (see <ulink
 131     url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>), also called cgroup-v1,
 132     doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group
 133     hierarchy, resource control is disabled for systemd user instance, see
 134     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 135     </para>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Options</title>
 140
 141     <para>Units of the types listed above can have settings
 142     for resource control configuration:</para>
 143
 144     <variablelist class='unit-directives'>
 145
 146       <varlistentry>
 147         <term><varname>CPUAccounting=</varname></term>
 148
 149         <listitem>
 150           <para>Turn on CPU usage accounting for this unit. Takes a
 151           boolean argument. Note that turning on CPU accounting for
 152           one unit will also implicitly turn it on for all units
 153           contained in the same slice and for all its parent slices
 154           and the units contained therein. The system default for this
 155           setting may be controlled with
 156           <varname>DefaultCPUAccounting=</varname> in
 157           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 158         </listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><varname>CPUWeight=<replaceable>weight</replaceable></varname></term>
 163         <term><varname>StartupCPUWeight=<replaceable>weight</replaceable></varname></term>
 164
 165         <listitem>
 166           <para>Assign the specified CPU time weight to the processes executed, if the unified control group hierarchy
 167           is used on the system. These options take an integer value and control the <literal>cpu.weight</literal>
 168           control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control
 169           group attribute, see <ulink
 170           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink
 171           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
 172           The available CPU time is split up among all units within one slice relative to their CPU time weight.</para>
 173
 174           <para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system,
 175           <varname>CPUWeight=</varname> applies to normal runtime of the system, and if the former is not set also to
 176           the startup phase. Using <varname>StartupCPUWeight=</varname> allows prioritizing specific services at
 177           boot-up differently than during normal runtime.</para>
 178
 179           <para>These settings replace <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>.</para>
 180         </listitem>
 181       </varlistentry>
 182
 183       <varlistentry>
 184         <term><varname>CPUQuota=</varname></term>
 185
 186         <listitem>
 187           <para>Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with
 188           "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time
 189           available on one CPU. Use values &gt; 100% for allotting CPU time on more than one CPU. This controls the
 190           <literal>cpu.max</literal> attribute on the unified control group hierarchy and
 191           <literal>cpu.cfs_quota_us</literal> on legacy. For details about these control group attributes, see <ulink
 192           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink
 193           url="https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt">sched-bwc.txt</ulink>.</para>
 194
 195           <para>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than
 196           20% CPU time on one CPU.</para>
 197
 198         </listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><varname>MemoryAccounting=</varname></term>
 203
 204         <listitem>
 205           <para>Turn on process and kernel memory accounting for this
 206           unit. Takes a boolean argument. Note that turning on memory
 207           accounting for one unit will also implicitly turn it on for
 208           all units contained in the same slice and for all its parent
 209           slices and the units contained therein. The system default
 210           for this setting may be controlled with
 211           <varname>DefaultMemoryAccounting=</varname> in
 212           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><varname>MemoryMin=<replaceable>bytes</replaceable></varname></term>
 218
 219         <listitem>
 220           <para>Specify the memory usage protection of the executed processes in this unit. If the memory usages of
 221           this unit and all its ancestors are below their minimum boundaries, this unit's memory won't be reclaimed.</para>
 222
 223           <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
 224           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
 225           percentage value may be specified, which is taken relative to the installed physical memory on the
 226           system. This controls the <literal>memory.min</literal> control group attribute. For details about this
 227           control group attribute, see <ulink
 228           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 229
 230           <para>This setting is supported only if the unified control group hierarchy is used and disables
 231           <varname>MemoryLimit=</varname>.</para>
 232         </listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term><varname>MemoryLow=<replaceable>bytes</replaceable></varname></term>
 237
 238         <listitem>
 239           <para>Specify the best-effort memory usage protection of the executed processes in this unit. If the memory
 240           usages of this unit and all its ancestors are below their low boundaries, this unit's memory won't be
 241           reclaimed as long as memory can be reclaimed from unprotected units.</para>
 242
 243           <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
 244           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
 245           percentage value may be specified, which is taken relative to the installed physical memory on the
 246           system. This controls the <literal>memory.low</literal> control group attribute. For details about this
 247           control group attribute, see <ulink
 248           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 249
 250           <para>This setting is supported only if the unified control group hierarchy is used and disables
 251           <varname>MemoryLimit=</varname>.</para>
 252         </listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><varname>MemoryHigh=<replaceable>bytes</replaceable></varname></term>
 257
 258         <listitem>
 259           <para>Specify the high limit on memory usage of the executed processes in this unit. Memory usage may go
 260           above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away
 261           aggressively in such cases. This is the main mechanism to control memory usage of a unit.</para>
 262
 263           <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
 264           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
 265           percentage value may be specified, which is taken relative to the installed physical memory on the
 266           system. If assigned the
 267           special value <literal>infinity</literal>, no memory limit is applied. This controls the
 268           <literal>memory.high</literal> control group attribute. For details about this control group attribute, see
 269           <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 270
 271           <para>This setting is supported only if the unified control group hierarchy is used and disables
 272           <varname>MemoryLimit=</varname>.</para>
 273         </listitem>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term><varname>MemoryMax=<replaceable>bytes</replaceable></varname></term>
 278
 279         <listitem>
 280           <para>Specify the absolute limit on memory usage of the executed processes in this unit. If memory usage
 281           cannot be contained under the limit, out-of-memory killer is invoked inside the unit. It is recommended to
 282           use <varname>MemoryHigh=</varname> as the main control mechanism and use <varname>MemoryMax=</varname> as the
 283           last line of defense.</para>
 284
 285           <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is
 286           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a
 287           percentage value may be specified, which is taken relative to the installed physical memory on the system. If
 288           assigned the special value <literal>infinity</literal>, no memory limit is applied. This controls the
 289           <literal>memory.max</literal> control group attribute. For details about this control group attribute, see
 290           <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 291
 292           <para>This setting replaces <varname>MemoryLimit=</varname>.</para>
 293         </listitem>
 294       </varlistentry>
 295
 296       <varlistentry>
 297         <term><varname>MemorySwapMax=<replaceable>bytes</replaceable></varname></term>
 298
 299         <listitem>
 300           <para>Specify the absolute limit on swap usage of the executed processes in this unit.</para>
 301
 302           <para>Takes a swap size in bytes. If the value is suffixed with K, M, G or T, the specified swap size is
 303           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the
 304           special value <literal>infinity</literal>, no swap limit is applied. This controls the
 305           <literal>memory.swap.max</literal> control group attribute. For details about this control group attribute,
 306           see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 307
 308           <para>This setting is supported only if the unified control group hierarchy is used and disables
 309           <varname>MemoryLimit=</varname>.</para>
 310         </listitem>
 311       </varlistentry>
 312
 313       <varlistentry>
 314         <term><varname>TasksAccounting=</varname></term>
 315
 316         <listitem>
 317           <para>Turn on task accounting for this unit. Takes a
 318           boolean argument. If enabled, the system manager will keep
 319           track of the number of tasks in the unit. The number of
 320           tasks accounted this way includes both kernel threads and
 321           userspace processes, with each thread counting
 322           individually. Note that turning on tasks accounting for one
 323           unit will also implicitly turn it on for all units contained
 324           in the same slice and for all its parent slices and the
 325           units contained therein. The system default for this setting
 326           may be controlled with
 327           <varname>DefaultTasksAccounting=</varname> in
 328           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 329         </listitem>
 330       </varlistentry>
 331
 332       <varlistentry>
 333         <term><varname>TasksMax=<replaceable>N</replaceable></varname></term>
 334
 335         <listitem>
 336           <para>Specify the maximum number of tasks that may be created in the unit. This ensures that the number of
 337           tasks accounted for the unit (see above) stays below a specific limit. This either takes an absolute number
 338           of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the
 339           system.  If assigned the special value <literal>infinity</literal>, no tasks limit is applied. This controls
 340           the <literal>pids.max</literal> control group attribute. For details about this control group attribute, see
 341           <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para>
 342
 343           <para>The
 344           system default for this setting may be controlled with
 345           <varname>DefaultTasksMax=</varname> in
 346           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 347         </listitem>
 348       </varlistentry>
 349
 350       <varlistentry>
 351         <term><varname>IOAccounting=</varname></term>
 352
 353         <listitem>
 354           <para>Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the
 355           system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly
 356           turn it on for all units contained in the same slice and all for its parent slices and the units contained
 357           therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname>
 358           in
 359           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 360
 361           <para>This setting replaces <varname>BlockIOAccounting=</varname> and disables settings prefixed with
 362           <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 363         </listitem>
 364       </varlistentry>
 365
 366       <varlistentry>
 367         <term><varname>IOWeight=<replaceable>weight</replaceable></varname></term>
 368         <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term>
 369
 370         <listitem>
 371           <para>Set the default overall block I/O weight for the executed processes, if the unified control group
 372           hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block
 373           I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to
 374           100. For details about this control group attribute, see <ulink
 375           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.  The available I/O
 376           bandwidth is split up among all units within one slice relative to their block I/O weight.</para>
 377
 378           <para>While <varname>StartupIOWeight=</varname> only applies
 379           to the startup phase of the system,
 380           <varname>IOWeight=</varname> applies to the later runtime of
 381           the system, and if the former is not set also to the startup
 382           phase. This allows prioritizing specific services at boot-up
 383           differently than during runtime.</para>
 384
 385           <para>These settings replace <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname>
 386           and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 387         </listitem>
 388       </varlistentry>
 389
 390       <varlistentry>
 391         <term><varname>IODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 392
 393         <listitem>
 394           <para>Set the per-device overall block I/O weight for the executed processes, if the unified control group
 395           hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify
 396           the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). The file path may be
 397           specified as path to a block device node or as any other file, in which case the backing block device of the
 398           file system of the file is determined. This controls the <literal>io.weight</literal> control group
 399           attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For
 400           details about this control group attribute, see <ulink
 401           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 402
 403           <para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with
 404           <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 405         </listitem>
 406       </varlistentry>
 407
 408       <varlistentry>
 409         <term><varname>IOReadBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 410         <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 411
 412         <listitem>
 413           <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified
 414           control group hierarchy is used on the system. This limit is not work-conserving and the executed processes
 415           are not allowed to use more even if the device has idle capacity.  Takes a space-separated pair of a file
 416           path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may
 417           be a path to a block device node, or as any other file in which case the backing block device of the file
 418           system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is
 419           parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example:
 420           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control
 421           group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details
 422           about this control group attribute, see <ulink
 423           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.
 424           </para>
 425
 426           <para>These settings replace <varname>BlockIOReadBandwidth=</varname> and
 427           <varname>BlockIOWriteBandwidth=</varname> and disable settings prefixed with <varname>BlockIO</varname> or
 428           <varname>StartupBlockIO</varname>.</para>
 429         </listitem>
 430       </varlistentry>
 431
 432       <varlistentry>
 433         <term><varname>IOReadIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term>
 434         <term><varname>IOWriteIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term>
 435
 436         <listitem>
 437           <para>Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the
 438           unified control group hierarchy is used on the system. This limit is not work-conserving and the executed
 439           processes are not allowed to use more even if the device has idle capacity.  Takes a space-separated pair of
 440           a file path and an IOPS value to specify the device specific IOPS. The file path may be a path to a block
 441           device node, or as any other file in which case the backing block device of the file system of the file is
 442           used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS,
 443           GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example:
 444           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control
 445           group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about
 446           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>These settings are supported only if the unified control group hierarchy is used and disable settings
 451           prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
 452         </listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><varname>IPAccounting=</varname></term>
 457
 458         <listitem>
 459           <para>Takes a boolean argument. If true, turns on IPv4 and IPv6 network traffic accounting for packets sent
 460           or received by the unit. When this option is turned on, all IPv4 and IPv6 sockets created by any process of
 461           the unit are accounted for.</para>
 462
 463           <para>When this option is used in socket units, it applies to all IPv4 and IPv6 sockets
 464           associated with it (including both listening and connection sockets where this applies). Note that for
 465           socket-activated services, this configuration setting and the accounting data of the service unit and the
 466           socket unit are kept separate, and displayed separately. No propagation of the setting and the collected
 467           statistics is done, in either direction. Moreover, any traffic sent or received on any of the socket unit's
 468           sockets is accounted to the socket unit — and never to the service unit it might have activated, even if the
 469           socket is used by it.</para>
 470
 471           <para>The system default for this setting may be controlled with <varname>DefaultIPAccounting=</varname> in
 472           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 473         </listitem>
 474       </varlistentry>
 475
 476       <varlistentry>
 477         <term><varname>IPAddressAllow=<replaceable>ADDRESS[/PREFIXLENGTH]…</replaceable></varname></term>
 478         <term><varname>IPAddressDeny=<replaceable>ADDRESS[/PREFIXLENGTH]…</replaceable></varname></term>
 479
 480         <listitem>
 481           <para>Turn on address range network traffic filtering for packets sent and received over AF_INET and AF_INET6
 482           sockets.  Both directives take a space separated list of IPv4 or IPv6 addresses, each optionally suffixed
 483           with an address prefix length (separated by a <literal>/</literal> character). If the latter is omitted, the
 484           address is considered a host address, i.e. the prefix covers the whole address (32 for IPv4, 128 for IPv6).
 485           </para>
 486
 487           <para>The access lists configured with this option are applied to all sockets created by processes of this
 488           unit (or in the case of socket units, associated with it). The lists are implicitly combined with any lists
 489           configured for any of the parent slice units this unit might be a member of. By default all access lists are
 490           empty. When configured the lists are enforced as follows:</para>
 491
 492           <itemizedlist>
 493             <listitem><para>Access will be granted in case its destination/source address matches any entry in the
 494             <varname>IPAddressAllow=</varname> setting.</para></listitem>
 495
 496             <listitem><para>Otherwise, access will be denied in case its destination/source address matches any entry
 497             in the <varname>IPAddressDeny=</varname> setting.</para></listitem>
 498
 499             <listitem><para>Otherwise, access will be granted.</para></listitem>
 500           </itemizedlist>
 501
 502           <para>In order to implement a whitelisting IP firewall, it is recommended to use a
 503           <varname>IPAddressDeny=</varname><constant>any</constant> setting on an upper-level slice unit (such as the
 504           root slice <filename>-.slice</filename> or the slice containing all system services
 505           <filename>system.slice</filename> – see
 506           <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 507           details on these slice units), plus individual per-service <varname>IPAddressAllow=</varname> lines
 508           permitting network access to relevant services, and only them.</para>
 509
 510           <para>Note that for socket-activated services, the IP access list configured on the socket unit applies to
 511           all sockets associated with it directly, but not to any sockets created by the ultimately activated services
 512           for it. Conversely, the IP access list configured for the service is not applied to any sockets passed into
 513           the service via socket activation. Thus, it is usually a good idea, to replicate the IP access lists on both
 514           the socket and the service unit, however it often makes sense to maintain one list more open and the other
 515           one more restricted, depending on the usecase.</para>
 516
 517           <para>If these settings are used multiple times in the same unit the specified lists are combined. If an
 518           empty string is assigned to these settings the specific access list is reset and all previous settings undone.</para>
 519
 520           <para>In place of explicit IPv4 or IPv6 address and prefix length specifications a small set of symbolic
 521           names may be used. The following names are defined:</para>
 522
 523           <table>
 524             <title>Special address/network names</title>
 525
 526             <tgroup cols='3'>
 527               <colspec colname='name'/>
 528               <colspec colname='definition'/>
 529               <colspec colname='meaning'/>
 530
 531               <thead>
 532                 <row>
 533                   <entry>Symbolic Name</entry>
 534                   <entry>Definition</entry>
 535                   <entry>Meaning</entry>
 536                 </row>
 537               </thead>
 538
 539             <tbody>
 540               <row>
 541                 <entry><constant>any</constant></entry>
 542                 <entry>0.0.0.0/0 ::/0</entry>
 543                 <entry>Any host</entry>
 544               </row>
 545
 546               <row>
 547                 <entry><constant>localhost</constant></entry>
 548                 <entry>127.0.0.0/8 ::1/128</entry>
 549                 <entry>All addresses on the local loopback</entry>
 550               </row>
 551
 552               <row>
 553                 <entry><constant>link-local</constant></entry>
 554                 <entry>169.254.0.0/16 fe80::/64</entry>
 555                 <entry>All link-local IP addresses</entry>
 556               </row>
 557
 558               <row>
 559                 <entry><constant>multicast</constant></entry>
 560                 <entry>224.0.0.0/4 ff00::/8</entry>
 561                 <entry>All IP multicasting addresses</entry>
 562               </row>
 563             </tbody>
 564             </tgroup>
 565           </table>
 566
 567           <para>Note that these settings might not be supported on some systems (for example if eBPF control group
 568           support is not enabled in the underlying kernel or container manager). These settings will have no effect in
 569           that case. If compatibility with such systems is desired it is hence recommended to not exclusively rely on
 570           them for IP security.</para>
 571         </listitem>
 572       </varlistentry>
 573
 574       <varlistentry>
 575         <term><varname>DeviceAllow=</varname></term>
 576
 577         <listitem>
 578           <para>Control access to specific device nodes by the
 579           executed processes. Takes two space-separated strings: a
 580           device node specifier followed by a combination of
 581           <constant>r</constant>, <constant>w</constant>,
 582           <constant>m</constant> to control
 583           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
 584           or creation of the specific device node(s) by the unit
 585           (<emphasis>m</emphasis>knod), respectively. This controls
 586           the <literal>devices.allow</literal> and
 587           <literal>devices.deny</literal> control group
 588           attributes. For details about these control group
 589           attributes, see <ulink
 590           url="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>.</para>
 591
 592           <para>The device node specifier is either a path to a device
 593           node in the file system, starting with
 594           <filename>/dev/</filename>, or a string starting with either
 595           <literal>char-</literal> or <literal>block-</literal>
 596           followed by a device group name, as listed in
 597           <filename>/proc/devices</filename>. The latter is useful to
 598           whitelist all current and future devices belonging to a
 599           specific device group at once. The device group is matched
 600           according to filename globbing rules, you may hence use the
 601           <literal>*</literal> and <literal>?</literal>
 602           wildcards. Examples: <filename>/dev/sda5</filename> is a
 603           path to a device node, referring to an ATA or SCSI block
 604           device. <literal>char-pts</literal> and
 605           <literal>char-alsa</literal> are specifiers for all pseudo
 606           TTYs and all ALSA sound devices,
 607           respectively. <literal>char-cpu/*</literal> is a specifier
 608           matching all CPU related device groups.</para>
 609         </listitem>
 610       </varlistentry>
 611
 612       <varlistentry>
 613         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
 614
 615         <listitem>
 616           <para>
 617             Control the policy for allowing device access:
 618           </para>
 619           <variablelist>
 620             <varlistentry>
 621               <term><option>strict</option></term>
 622               <listitem>
 623                 <para>means to only allow types of access that are
 624                 explicitly specified.</para>
 625               </listitem>
 626             </varlistentry>
 627
 628             <varlistentry>
 629               <term><option>closed</option></term>
 630               <listitem>
 631                 <para>in addition, allows access to standard pseudo
 632                 devices including
 633                 <filename>/dev/null</filename>,
 634                 <filename>/dev/zero</filename>,
 635                 <filename>/dev/full</filename>,
 636                 <filename>/dev/random</filename>, and
 637                 <filename>/dev/urandom</filename>.
 638                 </para>
 639               </listitem>
 640             </varlistentry>
 641
 642             <varlistentry>
 643               <term><option>auto</option></term>
 644               <listitem>
 645                 <para>
 646                   in addition, allows access to all devices if no
 647                   explicit <varname>DeviceAllow=</varname> is present.
 648                   This is the default.
 649                 </para>
 650               </listitem>
 651             </varlistentry>
 652           </variablelist>
 653         </listitem>
 654       </varlistentry>
 655
 656       <varlistentry>
 657         <term><varname>Slice=</varname></term>
 658
 659         <listitem>
 660           <para>The name of the slice unit to place the unit
 661           in. Defaults to <filename>system.slice</filename> for all
 662           non-instantiated units of all unit types (except for slice
 663           units themselves see below). Instance units are by default
 664           placed in a subslice of <filename>system.slice</filename>
 665           that is named after the template name.</para>
 666
 667           <para>This option may be used to arrange systemd units in a
 668           hierarchy of slices each of which might have resource
 669           settings applied.</para>
 670
 671           <para>For units of type slice, the only accepted value for
 672           this setting is the parent slice. Since the name of a slice
 673           unit implies the parent slice, it is hence redundant to ever
 674           set this parameter directly for slice units.</para>
 675
 676           <para>Special care should be taken when relying on the default slice assignment in templated service units
 677           that have <varname>DefaultDependencies=no</varname> set, see
 678           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, section
 679           "Default Dependencies" for details.</para>
 680
 681         </listitem>
 682       </varlistentry>
 683
 684       <varlistentry>
 685         <term><varname>Delegate=</varname></term>
 686
 687         <listitem>
 688           <para>Turns on delegation of further resource control partitioning to processes of the unit. Units where this
 689           is enabled may create and manage their own private subhierarchy of control groups below the control group of
 690           the unit itself. For unprivileged services (i.e. those using the <varname>User=</varname> setting) the unit's
 691           control group will be made accessible to the relevant user. When enabled the service manager will refrain
 692           from manipulating control groups or moving processes below the unit's control group, so that a clear concept
 693           of ownership is established: the control group tree above the unit's control group (i.e. towards the root
 694           control group) is owned and managed by the service manager of the host, while the control group tree below
 695           the unit's control group is owned and managed by the unit itself. Takes either a boolean argument or a list
 696           of control group controller names. If true, delegation is turned on, and all supported controllers are
 697           enabled for the unit, making them available to the unit's processes for management. If false, delegation is
 698           turned off entirely (and no additional controllers are enabled). If set to a list of controllers, delegation
 699           is turned on, and the specified controllers are enabled for the unit. Note that additional controllers than
 700           the ones specified might be made available as well, depending on configuration of the containing slice unit
 701           or other units contained in it. Note that assigning the empty string will enable delegation, but reset the
 702           list of controllers, all assignments prior to this will have no effect.  Defaults to false.</para>
 703
 704           <para>Note that controller delegation to less privileged code is only safe on the unified control group
 705           hierarchy. Accordingly, access to the specified controllers will not be granted to unprivileged services on
 706           the legacy hierarchy, even when requested.</para>
 707
 708           <para>The following controller names may be specified: <option>cpu</option>, <option>cpuacct</option>,
 709           <option>io</option>, <option>blkio</option>, <option>memory</option>, <option>devices</option>,
 710           <option>pids</option>. Not all of these controllers are available on all kernels however, and some are
 711           specific to the unified hierarchy while others are specific to the legacy hierarchy. Also note that the
 712           kernel might support further controllers, which aren't covered here yet as delegation is either not supported
 713           at all for them or not defined cleanly.</para>
 714         </listitem>
 715       </varlistentry>
 716
 717     </variablelist>
 718   </refsect1>
 719
 720   <refsect1>
 721     <title>Deprecated Options</title>
 722
 723     <para>The following options are deprecated. Use the indicated superseding options instead:</para>
 724
 725     <variablelist class='unit-directives'>
 726
 727       <varlistentry>
 728         <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
 729         <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>
 730
 731         <listitem>
 732           <para>Assign the specified CPU time share weight to the processes executed. These options take an integer
 733           value and control the <literal>cpu.shares</literal> control group attribute. The allowed range is 2 to
 734           262144. Defaults to 1024. For details about this control group attribute, see <ulink
 735           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
 736           The available CPU time is split up among all units within one slice relative to their CPU time share
 737           weight.</para>
 738
 739           <para>While <varname>StartupCPUShares=</varname> only applies to the startup phase of the system,
 740           <varname>CPUShares=</varname> applies to normal runtime of the system, and if the former is not set also to
 741           the startup phase. Using <varname>StartupCPUShares=</varname> allows prioritizing specific services at
 742           boot-up differently than during normal runtime.</para>
 743
 744           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 745
 746           <para>These settings are deprecated. Use <varname>CPUWeight=</varname> and
 747           <varname>StartupCPUWeight=</varname> instead.</para>
 748         </listitem>
 749       </varlistentry>
 750
 751       <varlistentry>
 752         <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
 753
 754         <listitem>
 755           <para>Specify the limit on maximum memory usage of the executed processes. The limit specifies how much
 756           process and kernel memory can be used by tasks in this unit. Takes a memory size in bytes. If the value is
 757           suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or
 758           Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is
 759           taken relative to the installed physical memory on the system. If assigned the special value
 760           <literal>infinity</literal>, no memory limit is applied. This controls the
 761           <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group
 762           attribute, see <ulink
 763           url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para>
 764
 765           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 766
 767           <para>This setting is deprecated. Use <varname>MemoryMax=</varname> instead.</para>
 768         </listitem>
 769       </varlistentry>
 770
 771       <varlistentry>
 772         <term><varname>BlockIOAccounting=</varname></term>
 773
 774         <listitem>
 775           <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the
 776           system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly
 777           turn it on for all units contained in the same slice and all for its parent slices and the units contained
 778           therein. The system default for this setting may be controlled with
 779           <varname>DefaultBlockIOAccounting=</varname> in
 780           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 781
 782           <para>This setting is deprecated. Use <varname>IOAccounting=</varname> instead.</para>
 783         </listitem>
 784       </varlistentry>
 785
 786       <varlistentry>
 787         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
 788         <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
 789
 790         <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control
 791         group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default
 792         block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to
 793         500. For details about this control group attribute, see <ulink
 794         url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
 795         The available I/O bandwidth is split up among all units within one slice relative to their block I/O
 796         weight.</para>
 797
 798         <para>While <varname>StartupBlockIOWeight=</varname> only
 799         applies to the startup phase of the system,
 800         <varname>BlockIOWeight=</varname> applies to the later runtime
 801         of the system, and if the former is not set also to the
 802         startup phase. This allows prioritizing specific services at
 803         boot-up differently than during runtime.</para>
 804
 805         <para>Implies
 806         <literal>BlockIOAccounting=true</literal>.</para>
 807
 808         <para>These settings are deprecated. Use <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname>
 809         instead.</para>
 810
 811       </listitem>
 812       </varlistentry>
 813
 814       <varlistentry>
 815         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 816
 817         <listitem>
 818           <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group
 819           hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify
 820           the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be
 821           specified as path to a block device node or as any other file, in which case the backing block device of the
 822           file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group
 823           attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For
 824           details about this control group attribute, see <ulink
 825           url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
 826
 827           <para>Implies
 828           <literal>BlockIOAccounting=true</literal>.</para>
 829
 830           <para>This setting is deprecated. Use <varname>IODeviceWeight=</varname> instead.</para>
 831         </listitem>
 832       </varlistentry>
 833
 834       <varlistentry>
 835         <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 836         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 837
 838         <listitem>
 839           <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control
 840           group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in
 841           bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device
 842           node, or as any other file in which case the backing block device of the file system of the file is used. If
 843           the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes,
 844           Gigabytes, or Terabytes, respectively, to the base of 1000. (Example:
 845           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the
 846           <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal>
 847           control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For
 848           details about these control group attributes, see <ulink
 849           url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
 850           </para>
 851
 852           <para>Implies
 853           <literal>BlockIOAccounting=true</literal>.</para>
 854
 855           <para>These settings are deprecated. Use <varname>IOReadBandwidthMax=</varname> and
 856           <varname>IOWriteBandwidthMax=</varname> instead.</para>
 857         </listitem>
 858       </varlistentry>
 859
 860     </variablelist>
 861   </refsect1>
 862
 863   <refsect1>
 864     <title>See Also</title>
 865     <para>
 866       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 867       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 868       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 869       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 870       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 871       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 872       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 873       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 874       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 875       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 876       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 877       The documentation for control groups and specific controllers in the Linux kernel:
 878       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>,
 879       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt">cpuacct.txt</ulink>,
 880       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>,
 881       <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
 882       <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt">sched-bwc.txt</ulink>.
 883     </para>
 884   </refsect1>
 885 </refentry>