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