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