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,
  64     sockets, mount points, and swap devices share a subset of
  65     configuration options for resource control of spawned
  66     processes. Internally, this relies on the Control Groups
  67     kernel concept for organizing processes in a hierarchical tree of
  68     named groups for the purpose of resource management.</para>
  69
  70     <para>This man page lists the configuration options shared by
  71     those six unit types. See
  72     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  73     for the common options of all unit configuration files, and
  74     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  75     <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  76     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  77     <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  78     <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  79     and
  80     <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  81     for more information on the specific unit configuration files. The
  82     resource control configuration options are configured in the
  83     [Slice], [Scope], [Service], [Socket], [Mount], or [Swap]
  84     sections, depending on the unit type.</para>
  85
  86     <para>See the <ulink
  87     url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New
  88     Control Group Interfaces</ulink> for an introduction on how to make
  89     use of resource control APIs from programs.</para>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Options</title>
  94
  95     <para>Units of the types listed above can have settings
  96     for resource control configuration:</para>
  97
  98     <variablelist class='unit-directives'>
  99
 100       <varlistentry>
 101         <term><varname>CPUAccounting=</varname></term>
 102
 103         <listitem>
 104           <para>Turn on CPU usage accounting for this unit. Takes a
 105           boolean argument. Note that turning on CPU accounting for
 106           one unit might also implicitly turn it on for all units
 107           contained in the same slice and for all its parent slices
 108           and the units contained therein. The system default for this
 109           setting maybe controlled with
 110           <varname>DefaultCPUAccounting=</varname> in
 111           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 112         </listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
 117         <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>
 118
 119         <listitem>
 120           <para>Assign the specified CPU time share weight to the
 121           processes executed. Those options take an integer value and
 122           control the <literal>cpu.shares</literal> control group
 123           attribute, which defaults to 1024. For details about this
 124           control group attribute, see <ulink
 125           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
 126           The available CPU time is split up among all units within
 127           one slice relative to their CPU time share weight.</para>
 128
 129           <para>While <varname>StartupCPUShares=</varname> only
 130           applies to the startup phase of the system,
 131           <varname>CPUShares=</varname> applies to normal runtime of
 132           the system, and if the former is not set also to the startup
 133           phase. Using <varname>StartupCPUShares=</varname> allows
 134           prioritizing specific services at boot-up differently than
 135           during normal runtime.</para>
 136
 137           <para>Those options imply
 138           <literal>CPUAccounting=true</literal>.</para>
 139         </listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><varname>CPUQuota=</varname></term>
 144
 145         <listitem>
 146           <para>Assign the specified CPU time quota to the processes
 147           executed. Takes a percentage value, suffixed with "%". The
 148           percentage specifies how much CPU time the unit shall get at
 149           maximum, relative to the total CPU time available on one
 150           CPU. Use values &gt; 100% for allotting CPU time on more than
 151           one CPU. This controls the
 152           <literal>cpu.cfs_quota_us</literal> control group
 153           attribute. For details about this control group attribute,
 154           see <ulink
 155           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
 156
 157           <para>Example: <varname>CPUQuota=20%</varname> ensures that
 158           the executed processes will never get more than 20% CPU time
 159           on one CPU.</para>
 160
 161           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 162         </listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term><varname>MemoryAccounting=</varname></term>
 167
 168         <listitem>
 169           <para>Turn on process and kernel memory accounting for this
 170           unit. Takes a boolean argument. Note that turning on memory
 171           accounting for one unit might also implicitly turn it on for
 172           all its parent slices. The system default for this setting
 173           maybe controlled with
 174           <varname>DefaultMemoryAccounting=</varname> in
 175           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 176         </listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
 181
 182         <listitem>
 183           <para>Specify the limit on maximum memory usage of the
 184           executed processes. The limit specifies how much process and
 185           kernel memory can be used by tasks in this unit. Takes a
 186           memory size in bytes. If the value is suffixed with K, M, G
 187           or T, the specified memory size is parsed as Kilobytes,
 188           Megabytes, Gigabytes, or Terabytes (with the base 1024),
 189           respectively. This controls the
 190           <literal>memory.limit_in_bytes</literal> control group
 191           attribute. For details about this control group attribute,
 192           see <ulink
 193           url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
 194
 195           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 196         </listitem>
 197       </varlistentry>
 198
 199       <varlistentry>
 200         <term><varname>BlockIOAccounting=</varname></term>
 201
 202         <listitem>
 203           <para>Turn on Block IO accounting for this unit. Takes a
 204           boolean argument. Note that turning on block IO accounting
 205           for one unit might also implicitly turn it on for all units
 206           contained in the same slice and all for its parent slices
 207           and the units contained therein. The system default for this
 208           setting maybe controlled with
 209           <varname>DefaultBlockIOAccounting=</varname> in
 210           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 211         </listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
 216         <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
 217
 218         <listitem><para>Set the default overall block IO weight for
 219         the executed processes. Takes a single weight value (between
 220         10 and 1000) to set the default block IO weight. This controls
 221         the <literal>blkio.weight</literal> control group attribute,
 222         which defaults to 1000. For details about this control group
 223         attribute, see <ulink
 224         url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 225         The available IO bandwidth is split up among all units within
 226         one slice relative to their block IO weight.</para>
 227
 228         <para>While <varname>StartupBlockIOWeight=</varname> only
 229         applies to the startup phase of the system,
 230         <varname>BlockIOWeight=</varname> applies to the later runtime
 231         of the system, and if the former is not set also to the
 232         startup phase. This allows prioritizing specific services at
 233         boot-up differently than during runtime.</para>
 234
 235         <para>Implies
 236         <literal>BlockIOAccounting=true</literal>.</para>
 237         </listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 242
 243         <listitem>
 244           <para>Set the per-device overall block IO weight for the
 245           executed processes. Takes a space-separated pair of a file
 246           path and a weight value to specify the device specific
 247           weight value, between 10 and 1000. (Example: "/dev/sda
 248           500"). The file path may be specified as path to a block
 249           device node or as any other file, in which case the backing
 250           block device of the file system of the file is
 251           determined. This controls the
 252           <literal>blkio.weight_device</literal> control group
 253           attribute, which defaults to 1000. Use this option multiple
 254           times to set weights for multiple devices. For details about
 255           this control group attribute, see <ulink
 256           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
 257
 258           <para>Implies
 259           <literal>BlockIOAccounting=true</literal>.</para>
 260         </listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 265         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 266
 267         <listitem>
 268           <para>Set the per-device overall block IO bandwidth limit
 269           for the executed processes. Takes a space-separated pair of
 270           a file path and a bandwidth value (in bytes per second) to
 271           specify the device specific bandwidth. The file path may be
 272           a path to a block device node, or as any other file in which
 273           case the backing block device of the file system of the file
 274           is used. If the bandwidth is suffixed with K, M, G, or T,
 275           the specified bandwidth is parsed as Kilobytes, Megabytes,
 276           Gigabytes, or Terabytes, respectively, to the base of
 277           1000. (Example:
 278           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
 279           controls the <literal>blkio.read_bps_device</literal> and
 280           <literal>blkio.write_bps_device</literal> control group
 281           attributes. Use this option multiple times to set bandwidth
 282           limits for multiple devices. For details about these control
 283           group attributes, see <ulink
 284           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 285           </para>
 286
 287           <para>Implies
 288           <literal>BlockIOAccounting=true</literal>.</para>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><varname>DeviceAllow=</varname></term>
 294
 295         <listitem>
 296           <para>Control access to specific device nodes by the
 297           executed processes. Takes two space-separated strings: a
 298           device node specifier followed by a combination of
 299           <constant>r</constant>, <constant>w</constant>,
 300           <constant>m</constant> to control
 301           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
 302           or creation of the specific device node(s) by the unit
 303           (<emphasis>m</emphasis>knod), respectively. This controls
 304           the <literal>devices.allow</literal> and
 305           <literal>devices.deny</literal> control group
 306           attributes. For details about these control group
 307           attributes, see <ulink
 308           url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
 309
 310           <para>The device node specifier is either a path to a device
 311           node in the file system, starting with
 312           <filename>/dev/</filename>, or a string starting with either
 313           <literal>char-</literal> or <literal>block-</literal>
 314           followed by a device group name, as listed in
 315           <filename>/proc/devices</filename>. The latter is useful to
 316           whitelist all current and future devices belonging to a
 317           specific device group at once. The device group is matched
 318           according to file name globbing rules, you may hence use the
 319           <literal>*</literal> and <literal>?</literal>
 320           wildcards. Examples: <filename>/dev/sda5</filename> is a
 321           path to a device node, referring to an ATA or SCSI block
 322           device. <literal>char-pts</literal> and
 323           <literal>char-alsa</literal> are specifiers for all pseudo
 324           TTYs and all ALSA sound devices,
 325           respectively. <literal>char-cpu/*</literal> is a specifier
 326           matching all CPU related device groups.</para>
 327         </listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
 332
 333         <listitem>
 334           <para>
 335             Control the policy for allowing device access:
 336           </para>
 337           <variablelist>
 338             <varlistentry>
 339               <term><option>strict</option></term>
 340               <listitem>
 341                 <para>means to only allow types of access that are
 342                 explicitly specified.</para>
 343               </listitem>
 344             </varlistentry>
 345
 346             <varlistentry>
 347               <term><option>closed</option></term>
 348               <listitem>
 349                 <para>in addition, allows access to standard pseudo
 350                 devices including
 351                 <filename>/dev/null</filename>,
 352                 <filename>/dev/zero</filename>,
 353                 <filename>/dev/full</filename>,
 354                 <filename>/dev/random</filename>, and
 355                 <filename>/dev/urandom</filename>.
 356                 </para>
 357               </listitem>
 358             </varlistentry>
 359
 360             <varlistentry>
 361               <term><option>auto</option></term>
 362               <listitem>
 363                 <para>
 364                   in addition, allows access to all devices if no
 365                   explicit <varname>DeviceAllow=</varname> is present.
 366                   This is the default.
 367                 </para>
 368               </listitem>
 369             </varlistentry>
 370           </variablelist>
 371         </listitem>
 372       </varlistentry>
 373
 374       <varlistentry>
 375         <term><varname>Slice=</varname></term>
 376
 377         <listitem>
 378           <para>The name of the slice unit to place the unit
 379           in. Defaults to <filename>system.slice</filename> for all
 380           non-instantiated units of all unit types (except for slice
 381           units themselves see below). Instance units are by default
 382           placed in a subslice of <filename>system.slice</filename>
 383           that is named after the template name.</para>
 384
 385           <para>This option may be used to arrange systemd units in a
 386           hierarchy of slices each of which might have resource
 387           settings applied.</para>
 388
 389           <para>For units of type slice, the only accepted value for
 390           this setting is the parent slice. Since the name of a slice
 391           unit implies the parent slice, it is hence redundant to ever
 392           set this parameter directly for slice units.</para>
 393         </listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><varname>Delegate=</varname></term>
 398
 399         <listitem>
 400           <para>Turns on delegation of further resource control
 401           partitioning to processes of the unit. For unprivileged
 402           services (i.e. those using the <varname>User=</varname>
 403           setting) this allows processes to create a subhierarchy
 404           beneath its control group path. For privileged services and
 405           scopes this ensures the processes will have all control
 406           group controllers enabled.</para>
 407         </listitem>
 408       </varlistentry>
 409
 410     </variablelist>
 411   </refsect1>
 412
 413   <refsect1>
 414     <title>See Also</title>
 415     <para>
 416       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 417       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 418       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 419       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 420       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 421       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 422       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 423       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 424       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 425       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 426       The documentation for control groups and specific controllers in the Linux kernel:
 427       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
 428       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
 429       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
 430       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 431     </para>
 432   </refsect1>
 433 </refentry>