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