man/systemd.resource-control.xml

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