man/systemd.resource-control.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2013 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd.resource-control">
  28   <refentryinfo>
  29     <title>systemd.resource-control</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>systemd.resource-control</refentrytitle>
  44     <manvolnum>5</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>systemd.resource-control</refname>
  49     <refpurpose>Resource control unit settings</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <para>
  54       <filename><replaceable>slice</replaceable>.slice</filename>,
  55       <filename><replaceable>scope</replaceable>.scope</filename>,
  56       <filename><replaceable>service</replaceable>.service</filename>,
  57       <filename><replaceable>socket</replaceable>.socket</filename>,
  58       <filename><replaceable>mount</replaceable>.mount</filename>,
  59       <filename><replaceable>swap</replaceable>.swap</filename>
  60     </para>
  61   </refsynopsisdiv>
  62
  63   <refsect1>
  64     <title>Description</title>
  65
  66     <para>Unit configuration files for services, slices, scopes,
  67     sockets, mount points, and swap devices share a subset of
  68     configuration options for resource control of spawned
  69     processes. Internally, this relies on the Control Groups
  70     kernel concept for organizing processes in a hierarchical tree of
  71     named groups for the purpose of resource management.</para>
  72
  73     <para>This man page lists the configuration options shared by
  74     those six unit types. See
  75     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  76     for the common options of all unit configuration files, and
  77     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  78     <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  79     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  80     <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  81     <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  82     and
  83     <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  84     for more information on the specific unit configuration files. The
  85     resource control configuration options are configured in the
  86     [Slice], [Scope], [Service], [Socket], [Mount], or [Swap]
  87     sections, depending on the unit type.</para>
  88
  89     <para>See the <ulink
  90     url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New
  91     Control Group Interfaces</ulink> for an introduction on how to make
  92     use of resource control APIs from programs.</para>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Options</title>
  97
  98     <para>Units of the types listed above can have settings
  99     for resource control configuration:</para>
 100
 101     <variablelist class='unit-directives'>
 102
 103       <varlistentry>
 104         <term><varname>CPUAccounting=</varname></term>
 105
 106         <listitem>
 107           <para>Turn on CPU usage accounting for this unit. Takes a
 108           boolean argument. Note that turning on CPU accounting for
 109           one unit might also implicitly turn it on for all units
 110           contained in the same slice and for all its parent slices
 111           and the units contained therein. The system default for this
 112           setting maybe controlled with
 113           <varname>DefaultCPUAccounting=</varname> in
 114           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 115         </listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
 120         <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>
 121
 122         <listitem>
 123           <para>Assign the specified CPU time share weight to the
 124           processes executed. Those options take an integer value and
 125           control the <literal>cpu.shares</literal> control group
 126           attribute, which defaults to 1024. For details about this
 127           control group attribute, see <ulink
 128           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.
 129           The available CPU time is split up among all units within
 130           one slice relative to their CPU time share weight.</para>
 131
 132           <para>While <varname>StartupCPUShares=</varname> only
 133           applies to the startup phase of the system,
 134           <varname>CPUShares=</varname> applies to normal runtime of
 135           the system, and if the former is not set also to the startup
 136           phase. Using <varname>StartupCPUShares=</varname> allows
 137           prioritizing specific services at boot-up differently than
 138           during normal runtime.</para>
 139
 140           <para>Those options imply
 141           <literal>CPUAccounting=true</literal>.</para>
 142         </listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term><varname>CPUQuota=</varname></term>
 147
 148         <listitem>
 149           <para>Assign the specified CPU time quota to the processes
 150           executed. Takes a percentage value, suffixed with "%". The
 151           percentage specifies how much CPU time the unit shall get at
 152           maximum, relative to the total CPU time available on one
 153           CPU. Use values &gt; 100% for allotting CPU time on more than
 154           one CPU. This controls the
 155           <literal>cpu.cfs_quota_us</literal> control group
 156           attribute. For details about this control group attribute,
 157           see <ulink
 158           url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
 159
 160           <para>Example: <varname>CPUQuota=20%</varname> ensures that
 161           the executed processes will never get more than 20% CPU time
 162           on one CPU.</para>
 163
 164           <para>Implies <literal>CPUAccounting=true</literal>.</para>
 165         </listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><varname>MemoryAccounting=</varname></term>
 170
 171         <listitem>
 172           <para>Turn on process and kernel memory accounting for this
 173           unit. Takes a boolean argument. Note that turning on memory
 174           accounting for one unit might also implicitly turn it on for
 175           all its parent slices. The system default for this setting
 176           maybe controlled with
 177           <varname>DefaultMemoryAccounting=</varname> in
 178           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 179         </listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
 184
 185         <listitem>
 186           <para>Specify the limit on maximum memory usage of the
 187           executed processes. The limit specifies how much process and
 188           kernel memory can be used by tasks in this unit. Takes a
 189           memory size in bytes. If the value is suffixed with K, M, G
 190           or T, the specified memory size is parsed as Kilobytes,
 191           Megabytes, Gigabytes, or Terabytes (with the base 1024),
 192           respectively. This controls the
 193           <literal>memory.limit_in_bytes</literal> control group
 194           attribute. For details about this control group attribute,
 195           see <ulink
 196           url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
 197
 198           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
 199         </listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><varname>BlockIOAccounting=</varname></term>
 204
 205         <listitem>
 206           <para>Turn on Block IO accounting for this unit. Takes a
 207           boolean argument. Note that turning on block IO accounting
 208           for one unit might also implicitly turn it on for all units
 209           contained in the same slice and all for its parent slices
 210           and the units contained therein. The system default for this
 211           setting maybe controlled with
 212           <varname>DefaultBlockIOAccounting=</varname> in
 213           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 214         </listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
 219         <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
 220
 221         <listitem><para>Set the default overall block IO weight for
 222         the executed processes. Takes a single weight value (between
 223         10 and 1000) to set the default block IO weight. This controls
 224         the <literal>blkio.weight</literal> control group attribute,
 225         which defaults to 1000. For details about this control group
 226         attribute, see <ulink
 227         url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 228         The available IO bandwidth is split up among all units within
 229         one slice relative to their block IO weight.</para>
 230
 231         <para>While <varname>StartupBlockIOWeight=</varname> only
 232         applies to the startup phase of the system,
 233         <varname>BlockIOWeight=</varname> applies to the later runtime
 234         of the system, and if the former is not set also to the
 235         startup phase. This allows prioritizing specific services at
 236         boot-up differently than during runtime.</para>
 237
 238         <para>Implies
 239         <literal>BlockIOAccounting=true</literal>.</para>
 240         </listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 245
 246         <listitem>
 247           <para>Set the per-device overall block IO weight for the
 248           executed processes. Takes a space-separated pair of a file
 249           path and a weight value to specify the device specific
 250           weight value, between 10 and 1000. (Example: "/dev/sda
 251           500"). The file path may be specified as path to a block
 252           device node or as any other file, in which case the backing
 253           block device of the file system of the file is
 254           determined. This controls the
 255           <literal>blkio.weight_device</literal> control group
 256           attribute, which defaults to 1000. Use this option multiple
 257           times to set weights for multiple devices. For details about
 258           this control group attribute, see <ulink
 259           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
 260
 261           <para>Implies
 262           <literal>BlockIOAccounting=true</literal>.</para>
 263         </listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 268         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 269
 270         <listitem>
 271           <para>Set the per-device overall block IO bandwidth limit
 272           for the executed processes. Takes a space-separated pair of
 273           a file path and a bandwidth value (in bytes per second) to
 274           specify the device specific bandwidth. The file path may be
 275           a path to a block device node, or as any other file in which
 276           case the backing block device of the file system of the file
 277           is used. If the bandwidth is suffixed with K, M, G, or T,
 278           the specified bandwidth is parsed as Kilobytes, Megabytes,
 279           Gigabytes, or Terabytes, respectively, to the base of
 280           1000. (Example:
 281           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
 282           controls the <literal>blkio.read_bps_device</literal> and
 283           <literal>blkio.write_bps_device</literal> control group
 284           attributes. Use this option multiple times to set bandwidth
 285           limits for multiple devices. For details about these control
 286           group attributes, see <ulink
 287           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 288           </para>
 289
 290           <para>Implies
 291           <literal>BlockIOAccounting=true</literal>.</para>
 292         </listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><varname>DeviceAllow=</varname></term>
 297
 298         <listitem>
 299           <para>Control access to specific device nodes by the
 300           executed processes. Takes two space-separated strings: a
 301           device node specifier followed by a combination of
 302           <constant>r</constant>, <constant>w</constant>,
 303           <constant>m</constant> to control
 304           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
 305           or creation of the specific device node(s) by the unit
 306           (<emphasis>m</emphasis>knod), respectively. This controls
 307           the <literal>devices.allow</literal> and
 308           <literal>devices.deny</literal> control group
 309           attributes. For details about these control group
 310           attributes, see <ulink
 311           url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
 312
 313           <para>The device node specifier is either a path to a device
 314           node in the file system, starting with
 315           <filename>/dev/</filename>, or a string starting with either
 316           <literal>char-</literal> or <literal>block-</literal>
 317           followed by a device group name, as listed in
 318           <filename>/proc/devices</filename>. The latter is useful to
 319           whitelist all current and future devices belonging to a
 320           specific device group at once. The device group is matched
 321           according to file name globbing rules, you may hence use the
 322           <literal>*</literal> and <literal>?</literal>
 323           wildcards. Examples: <filename>/dev/sda5</filename> is a
 324           path to a device node, referring to an ATA or SCSI block
 325           device. <literal>char-pts</literal> and
 326           <literal>char-alsa</literal> are specifiers for all pseudo
 327           TTYs and all ALSA sound devices,
 328           respectively. <literal>char-cpu/*</literal> is a specifier
 329           matching all CPU related device groups.</para>
 330         </listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
 335
 336         <listitem>
 337           <para>
 338             Control the policy for allowing device access:
 339           </para>
 340           <variablelist>
 341             <varlistentry>
 342               <term><option>strict</option></term>
 343               <listitem>
 344                 <para>means to only allow types of access that are
 345                 explicitly specified.</para>
 346               </listitem>
 347             </varlistentry>
 348
 349             <varlistentry>
 350               <term><option>closed</option></term>
 351               <listitem>
 352                 <para>in addition, allows access to standard pseudo
 353                 devices including
 354                 <filename>/dev/null</filename>,
 355                 <filename>/dev/zero</filename>,
 356                 <filename>/dev/full</filename>,
 357                 <filename>/dev/random</filename>, and
 358                 <filename>/dev/urandom</filename>.
 359                 </para>
 360               </listitem>
 361             </varlistentry>
 362
 363             <varlistentry>
 364               <term><option>auto</option></term>
 365               <listitem>
 366                 <para>
 367                   in addition, allows access to all devices if no
 368                   explicit <varname>DeviceAllow=</varname> is present.
 369                   This is the default.
 370                 </para>
 371               </listitem>
 372             </varlistentry>
 373           </variablelist>
 374         </listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><varname>Slice=</varname></term>
 379
 380         <listitem>
 381           <para>The name of the slice unit to place the unit
 382           in. Defaults to <filename>system.slice</filename> for all
 383           non-instantiated units of all unit types (except for slice
 384           units themselves see below). Instance units are by default
 385           placed in a subslice of <filename>system.slice</filename>
 386           that is named after the template name.</para>
 387
 388           <para>This option may be used to arrange systemd units in a
 389           hierarchy of slices each of which might have resource
 390           settings applied.</para>
 391
 392           <para>For units of type slice, the only accepted value for
 393           this setting is the parent slice. Since the name of a slice
 394           unit implies the parent slice, it is hence redundant to ever
 395           set this parameter directly for slice units.</para>
 396         </listitem>
 397       </varlistentry>
 398
 399       <varlistentry>
 400         <term><varname>Delegate=</varname></term>
 401
 402         <listitem>
 403           <para>Turns on delegation of further resource control
 404           partitioning to processes of the unit. For unprivileged
 405           services (i.e. those using the <varname>User=</varname>
 406           setting) this allows processes to create a subhierarchy
 407           beneath its control group path. For privileged services and
 408           scopes this ensures the processes will have all control
 409           group controllers enabled.</para>
 410         </listitem>
 411       </varlistentry>
 412
 413     </variablelist>
 414   </refsect1>
 415
 416   <refsect1>
 417     <title>See Also</title>
 418     <para>
 419       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 420       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 421       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 422       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 423       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 424       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 425       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 426       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 427       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 428       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 429       The documentation for control groups and specific controllers in the Linux kernel:
 430       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
 431       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
 432       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
 433       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
 434     </para>
 435   </refsect1>
 436 </refentry>