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, to the base of
 230           1000. (Example:
 231           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
 232           controls the <literal>blkio.read_bps_device</literal> and
 233           <literal>blkio.write_bps_device</literal> control group
 234           attributes. Use this option multiple times to set bandwidth
 235           limits for multiple devices. For details about these control
 236           group attributes, see <ulink
 237           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 238           </para>
 239
 240           <para>Implies
 241           <literal>BlockIOAccounting=true</literal>.</para>
 242         </listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><varname>DeviceAllow=</varname></term>
 247
 248         <listitem>
 249           <para>Control access to specific device nodes by the
 250           executed processes. Takes two space-separated strings: a
 251           device node specifier followed by a combination of
 252           <constant>r</constant>, <constant>w</constant>,
 253           <constant>m</constant> to control
 254           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
 255           or creation of the specific device node(s) by the unit
 256           (<emphasis>m</emphasis>knod), respectively. This controls
 257           the <literal>devices.allow</literal> and
 258           <literal>devices.deny</literal> control group
 259           attributes. For details about these control group
 260           attributes, see <ulink
 261           url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
 262
 263           <para>The device node specifier is either a path to a device
 264           node in the file system, starting with
 265           <filename>/dev/</filename>, or a string starting with either
 266           <literal>char-</literal> or <literal>block-</literal>
 267           followed by a device group name, as listed in
 268           <filename>/proc/devices</filename>. The latter is useful to
 269           whitelist all current and future devices belonging to a
 270           specific device group at once. Examples:
 271           <filename>/dev/sda5</filename> is a path to a device node,
 272           referring to an ATA or SCSI block
 273           device. <literal>char-pts</literal> and
 274           <literal>char-alsa</literal> are specifiers for all pseudo
 275           TTYs and all ALSA sound devices, respectively.</para>
 276         </listitem>
 277       </varlistentry>
 278
 279       <varlistentry>
 280         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
 281
 282         <listitem>
 283           <para>
 284             Control the policy for allowing device access:
 285           </para>
 286           <variablelist>
 287             <varlistentry>
 288               <term><option>strict</option></term>
 289               <listitem>
 290                 <para>means to only allow types of access that are
 291                 explicitly specified.</para>
 292               </listitem>
 293             </varlistentry>
 294
 295             <varlistentry>
 296               <term><option>closed</option></term>
 297               <listitem>
 298                 <para>in addition, allows access to standard pseudo
 299                 devices including
 300                 <filename>/dev/null</filename>,
 301                 <filename>/dev/zero</filename>,
 302                 <filename>/dev/full</filename>,
 303                 <filename>/dev/random</filename>, and
 304                 <filename>/dev/urandom</filename>.
 305                 </para>
 306               </listitem>
 307             </varlistentry>
 308
 309             <varlistentry>
 310               <term><option>auto</option></term>
 311               <listitem>
 312                 <para>
 313                   in addition, allows access to all devices if no
 314                   explicit <varname>DeviceAllow=</varname> is present.
 315                   This is the default.
 316                 </para>
 317               </listitem>
 318             </varlistentry>
 319           </variablelist>
 320         </listitem>
 321       </varlistentry>
 322
 323       <varlistentry>
 324         <term><varname>Slice=</varname></term>
 325
 326         <listitem>
 327           <para>The name of the slice unit to place the unit
 328           in. Defaults to <filename>system.slice</filename> for all
 329           non-instantiated units of all unit types (except for slice
 330           units themselves see below). Instance units are by default
 331           placed in a subslice of <filename>system.slice</filename>
 332           that is named after the template name.</para>
 333
 334           <para>This option may be used to arrange systemd units in a
 335           hierarchy of slices each of which might have resource
 336           settings applied.</para>
 337
 338           <para>For units of type slice, the only accepted value for
 339           this setting is the parent slice. Since the name of a slice
 340           unit implies the parent slice, it is hence redundant to ever
 341           set this parameter directly for slice units.</para>
 342         </listitem>
 343       </varlistentry>
 344
 345     </variablelist>
 346   </refsect1>
 347
 348   <refsect1>
 349     <title>See Also</title>
 350     <para>
 351       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 352       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 353       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 354       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 355       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 356       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 357       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 358       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 359       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 360       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 361       The documentation for control groups and specific controllers in the Linux kernel:
 362       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
 363       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
 364       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
 365       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 366     </para>
 367   </refsect1>
 368 </refentry>