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