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