man/systemd.resource-control.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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 hierarchial 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
 119         <listitem>
 120           <para>Assign the specified CPU time share weight to the
 121           processes executed. Takes an integer value. This controls
 122           the <literal>cpu.shares</literal> control group attribute,
 123           which defaults to 1024. For details about this control group
 124           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 a
 127           slice relative to their CPU time share weight.</para>
 128
 129           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 130         </listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><varname>CPUQuota=</varname></term>
 135
 136         <listitem>
 137           <para>Assign the specified CPU time quota to the processes
 138           executed. Takes a percentage value (suffixed with "%") or an
 139           absolute time (suffixed by one of the common time units, us,
 140           ms, s, ...). The percentage specifies how much CPU time the
 141           unit shall get at maximum, relative to the total CPU time
 142           available on one CPU. Use values &gt; 100% for alloting CPU
 143           time on more than one CPU. If an absolute time is specified
 144           the processes of this unit will get this much absolute time
 145           within each quota period, at maximum. This controls the
 146           <literal>cpu.cfs_quota_us</literal> control group
 147           attribute. For details about this control group attribute,
 148           see <ulink
 149           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
 150
 151           <para>Example: <varname>CPUShares=20%</varname> ensures that
 152           the executed processes will never get more than 20% CPU time
 153           on one CPU.</para>
 154
 155           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term><varname>CPUQuotaPeriodSec=</varname></term>
 161
 162         <listitem>
 163           <para>Specify the CPU quota period to use. Defaults to
 164           100ms. This controls the <literal>cpu.cfs_period_us</literal>
 165           control group attribute. For details about this control
 166           group attribute, see <ulink
 167           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
 168
 169           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 170         </listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><varname>MemoryAccounting=</varname></term>
 175
 176         <listitem>
 177           <para>Turn on process and kernel memory accounting for this
 178           unit. Takes a boolean argument. Note that turning on memory
 179           accounting for one unit might also implicitly turn it on for
 180           all its parent slices. The system default for this setting
 181           maybe controlled with
 182           <varname>DefaultMemoryAccounting=</varname> in
 183           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 184         </listitem>
 185       </varlistentry>
 186
 187       <varlistentry>
 188         <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
 189
 190         <listitem>
 191           <para>Specify the limit on maximum memory usage of the
 192           executed processes. The limit specifies how much process and
 193           kernel memory can be used by tasks in this unit. Takes a
 194           memory size in bytes. If the value is suffixed with K, M, G
 195           or T, the specified memory size is parsed as Kilobytes,
 196           Megabytes, Gigabytes, or Terabytes (with the base 1024),
 197           respectively. This controls the
 198           <literal>memory.limit_in_bytes</literal> control group
 199           attribute. For details about this control group attribute,
 200           see <ulink
 201           url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
 202
 203           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 204         </listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><varname>BlockIOAccounting=</varname></term>
 209
 210         <listitem>
 211           <para>Turn on Block IO accounting for this unit. Takes a
 212           boolean argument. Note that turning on block IO accounting
 213           for one unit might also implicitly turn it on for all units
 214           contained in the same slice and all for its parent slices
 215           and the units contained therein. The system default for this
 216           setting maybe controlled with
 217           <varname>DefaultBlockIOAccounting=</varname> in
 218           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 219         </listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
 224
 225         <listitem><para>Set the default
 226         overall block IO weight for the
 227         executed processes. Takes a single
 228         weight value (between 10 and 1000) to
 229         set the default block IO weight. This
 230         controls the
 231         <literal>blkio.weight</literal>
 232         control group attribute, which
 233         defaults to 1000. For details about
 234         this control group attribute, see
 235         <ulink
 236             url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
 237
 238         <para>Implies
 239         <literal>BlockIOAccounting=true</literal>.</para>
 240         </listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 245
 246         <listitem>
 247           <para>Set the per-device overall block IO weight for the
 248           executed processes. Takes a space-separated pair of a file
 249           path and a weight value to specify the device specific
 250           weight value, between 10 and 1000. (Example: "/dev/sda
 251           500"). The file path may be specified as path to a block
 252           device node or as any other file, in which case the backing
 253           block device of the file system of the file is
 254           determined. This controls the
 255           <literal>blkio.weight_device</literal> control group
 256           attribute, which defaults to 1000. Use this option multiple
 257           times to set weights for multiple devices. For details about
 258           this control group attribute, see <ulink
 259           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
 260
 261           <para>Implies
 262           <literal>BlockIOAccounting=true</literal>.</para>
 263         </listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 268         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 269
 270         <listitem>
 271           <para>Set the per-device overall block IO bandwidth limit
 272           for the executed processes. Takes a space-separated pair of
 273           a file path and a bandwidth value (in bytes per second) to
 274           specify the device specific bandwidth. The file path may be
 275           a path to a block device node, or as any other file in which
 276           case the backing block device of the file system of the file
 277           is used. If the bandwidth is suffixed with K, M, G, or T,
 278           the specified bandwidth is parsed as Kilobytes, Megabytes,
 279           Gigabytes, or Terabytes, respectively, to the base of
 280           1000. (Example:
 281           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
 282           controls the <literal>blkio.read_bps_device</literal> and
 283           <literal>blkio.write_bps_device</literal> control group
 284           attributes. Use this option multiple times to set bandwidth
 285           limits for multiple devices. For details about these control
 286           group attributes, see <ulink
 287           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 288           </para>
 289
 290           <para>Implies
 291           <literal>BlockIOAccounting=true</literal>.</para>
 292         </listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><varname>DeviceAllow=</varname></term>
 297
 298         <listitem>
 299           <para>Control access to specific device nodes by the
 300           executed processes. Takes two space-separated strings: a
 301           device node specifier followed by a combination of
 302           <constant>r</constant>, <constant>w</constant>,
 303           <constant>m</constant> to control
 304           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
 305           or creation of the specific device node(s) by the unit
 306           (<emphasis>m</emphasis>knod), respectively. This controls
 307           the <literal>devices.allow</literal> and
 308           <literal>devices.deny</literal> control group
 309           attributes. For details about these control group
 310           attributes, see <ulink
 311           url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
 312
 313           <para>The device node specifier is either a path to a device
 314           node in the file system, starting with
 315           <filename>/dev/</filename>, or a string starting with either
 316           <literal>char-</literal> or <literal>block-</literal>
 317           followed by a device group name, as listed in
 318           <filename>/proc/devices</filename>. The latter is useful to
 319           whitelist all current and future devices belonging to a
 320           specific device group at once. The device group is matched
 321           according to file name globbing rules, you may hence use the
 322           <literal>*</literal> and <literal>?</literal>
 323           wildcards. Examples: <filename>/dev/sda5</filename> is a
 324           path to a device node, referring to an ATA or SCSI block
 325           device. <literal>char-pts</literal> and
 326           <literal>char-alsa</literal> are specifiers for all pseudo
 327           TTYs and all ALSA sound devices,
 328           respectively. <literal>char-cpu/*</literal> is a specifier
 329           matching all CPU related device groups.</para>
 330         </listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
 335
 336         <listitem>
 337           <para>
 338             Control the policy for allowing device access:
 339           </para>
 340           <variablelist>
 341             <varlistentry>
 342               <term><option>strict</option></term>
 343               <listitem>
 344                 <para>means to only allow types of access that are
 345                 explicitly specified.</para>
 346               </listitem>
 347             </varlistentry>
 348
 349             <varlistentry>
 350               <term><option>closed</option></term>
 351               <listitem>
 352                 <para>in addition, allows access to standard pseudo
 353                 devices including
 354                 <filename>/dev/null</filename>,
 355                 <filename>/dev/zero</filename>,
 356                 <filename>/dev/full</filename>,
 357                 <filename>/dev/random</filename>, and
 358                 <filename>/dev/urandom</filename>.
 359                 </para>
 360               </listitem>
 361             </varlistentry>
 362
 363             <varlistentry>
 364               <term><option>auto</option></term>
 365               <listitem>
 366                 <para>
 367                   in addition, allows access to all devices if no
 368                   explicit <varname>DeviceAllow=</varname> is present.
 369                   This is the default.
 370                 </para>
 371               </listitem>
 372             </varlistentry>
 373           </variablelist>
 374         </listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><varname>Slice=</varname></term>
 379
 380         <listitem>
 381           <para>The name of the slice unit to place the unit
 382           in. Defaults to <filename>system.slice</filename> for all
 383           non-instantiated units of all unit types (except for slice
 384           units themselves see below). Instance units are by default
 385           placed in a subslice of <filename>system.slice</filename>
 386           that is named after the template name.</para>
 387
 388           <para>This option may be used to arrange systemd units in a
 389           hierarchy of slices each of which might have resource
 390           settings applied.</para>
 391
 392           <para>For units of type slice, the only accepted value for
 393           this setting is the parent slice. Since the name of a slice
 394           unit implies the parent slice, it is hence redundant to ever
 395           set this parameter directly for slice units.</para>
 396         </listitem>
 397       </varlistentry>
 398
 399     </variablelist>
 400   </refsect1>
 401
 402   <refsect1>
 403     <title>See Also</title>
 404     <para>
 405       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 406       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 407       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 408       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 409       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 410       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 411       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 412       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 413       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 414       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 415       The documentation for control groups and specific controllers in the Linux kernel:
 416       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
 417       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
 418       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
 419       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 420     </para>
 421   </refsect1>
 422 </refentry>