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