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