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">
7 This file is part of systemd.
9 Copyright 2013 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
25 <refentry id="systemd.resource-control">
27 <title>systemd.resource-control</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.resource-control</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.resource-control</refname>
47 <refpurpose>Resource control unit settings</refpurpose>
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>
62 <title>Description</title>
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>
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>,
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>
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>
94 <title>Options</title>
96 <para>Units of the types listed above can have settings
97 for resource control configuration:</para>
99 <variablelist class='unit-directives'>
102 <term><varname>CPUAccounting=</varname></term>
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
109 and the units contained therein. The system default for this
110 setting maybe controlled with
111 <varname>DefaultCPUAccounting=</varname> in
112 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
117 <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
118 <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>
121 <para>Assign the specified CPU time share weight to the
122 processes executed. Takes an integer value. This controls
123 the <literal>cpu.shares</literal> control group attribute,
124 which defaults to 1024. For details about this control group
125 attribute, see <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 one
128 slice relative to their CPU time share weight.</para>
130 <para>While <varname>StartupCPUShares=</varname> only
131 applies to the startup phase of the system,
132 <varname>CPUShares=</varname> applies to the later runtime
133 of the system, and if the former is not set also to the
134 startup phase. This allows priorizing specific services at
135 boot-up differently than during runtime.</para>
137 <para>Implies <literal>CPUAccounting=true</literal>.</para>
142 <term><varname>CPUQuota=</varname></term>
145 <para>Assign the specified CPU time quota to the processes
146 executed. Takes a percentage value (suffixed with "%") or an
147 absolute time (suffixed by one of the common time units, us,
148 ms, s, ...). The percentage specifies how much CPU time the
149 unit shall get at maximum, relative to the total CPU time
150 available on one CPU. Use values > 100% for alloting CPU
151 time on more than one CPU. If an absolute time is specified
152 the processes of this unit will get this much absolute time
153 within each quota period, at maximum. This controls the
154 <literal>cpu.cfs_quota_us</literal> control group
155 attribute. For details about this control group attribute,
157 url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
159 <para>Example: <varname>CPUShares=20%</varname> ensures that
160 the executed processes will never get more than 20% CPU time
163 <para>Implies <literal>CPUAccounting=true</literal>.</para>
168 <term><varname>CPUQuotaPeriodSec=</varname></term>
171 <para>Specify the CPU quota period to use. Defaults to
172 100ms. This controls the <literal>cpu.cfs_period_us</literal>
173 control group attribute. For details about this control
174 group attribute, see <ulink
175 url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
177 <para>Implies <literal>CPUAccounting=true</literal>.</para>
182 <term><varname>MemoryAccounting=</varname></term>
185 <para>Turn on process and kernel memory accounting for this
186 unit. Takes a boolean argument. Note that turning on memory
187 accounting for one unit might also implicitly turn it on for
188 all its parent slices. The system default for this setting
189 maybe controlled with
190 <varname>DefaultMemoryAccounting=</varname> in
191 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
196 <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
199 <para>Specify the limit on maximum memory usage of the
200 executed processes. The limit specifies how much process and
201 kernel memory can be used by tasks in this unit. Takes a
202 memory size in bytes. If the value is suffixed with K, M, G
203 or T, the specified memory size is parsed as Kilobytes,
204 Megabytes, Gigabytes, or Terabytes (with the base 1024),
205 respectively. This controls the
206 <literal>memory.limit_in_bytes</literal> control group
207 attribute. For details about this control group attribute,
209 url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
211 <para>Implies <literal>MemoryAccounting=true</literal>.</para>
216 <term><varname>BlockIOAccounting=</varname></term>
219 <para>Turn on Block IO accounting for this unit. Takes a
220 boolean argument. Note that turning on block IO accounting
221 for one unit might also implicitly turn it on for all units
222 contained in the same slice and all for its parent slices
223 and the units contained therein. The system default for this
224 setting maybe controlled with
225 <varname>DefaultBlockIOAccounting=</varname> in
226 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
231 <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
232 <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
234 <listitem><para>Set the default overall block IO weight for
235 the executed processes. Takes a single weight value (between
236 10 and 1000) to set the default block IO weight. This controls
237 the <literal>blkio.weight</literal> control group attribute,
238 which defaults to 1000. For details about this control group
239 attribute, see <ulink
240 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
241 The available IO bandwidth is split up among all units within
242 one slice relative to their block IO weight.</para>
244 <para>While <varname>StartupBlockIOWeight=</varname> only
245 applies to the startup phase of the system,
246 <varname>BlockIOWeight=</varname> applies to the later runtime
247 of the system, and if the former is not set also to the
248 startup phase. This allows priorizing specific services at
249 boot-up differently than during runtime.</para>
252 <literal>BlockIOAccounting=true</literal>.</para>
257 <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
260 <para>Set the per-device overall block IO weight for the
261 executed processes. Takes a space-separated pair of a file
262 path and a weight value to specify the device specific
263 weight value, between 10 and 1000. (Example: "/dev/sda
264 500"). The file path may be specified as path to a block
265 device node or as any other file, in which case the backing
266 block device of the file system of the file is
267 determined. This controls the
268 <literal>blkio.weight_device</literal> control group
269 attribute, which defaults to 1000. Use this option multiple
270 times to set weights for multiple devices. For details about
271 this control group attribute, see <ulink
272 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
275 <literal>BlockIOAccounting=true</literal>.</para>
280 <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
281 <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
284 <para>Set the per-device overall block IO bandwidth limit
285 for the executed processes. Takes a space-separated pair of
286 a file path and a bandwidth value (in bytes per second) to
287 specify the device specific bandwidth. The file path may be
288 a path to a block device node, or as any other file in which
289 case the backing block device of the file system of the file
290 is used. If the bandwidth is suffixed with K, M, G, or T,
291 the specified bandwidth is parsed as Kilobytes, Megabytes,
292 Gigabytes, or Terabytes, respectively, to the base of
294 "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
295 controls the <literal>blkio.read_bps_device</literal> and
296 <literal>blkio.write_bps_device</literal> control group
297 attributes. Use this option multiple times to set bandwidth
298 limits for multiple devices. For details about these control
299 group attributes, see <ulink
300 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
304 <literal>BlockIOAccounting=true</literal>.</para>
309 <term><varname>DeviceAllow=</varname></term>
312 <para>Control access to specific device nodes by the
313 executed processes. Takes two space-separated strings: a
314 device node specifier followed by a combination of
315 <constant>r</constant>, <constant>w</constant>,
316 <constant>m</constant> to control
317 <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
318 or creation of the specific device node(s) by the unit
319 (<emphasis>m</emphasis>knod), respectively. This controls
320 the <literal>devices.allow</literal> and
321 <literal>devices.deny</literal> control group
322 attributes. For details about these control group
323 attributes, see <ulink
324 url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
326 <para>The device node specifier is either a path to a device
327 node in the file system, starting with
328 <filename>/dev/</filename>, or a string starting with either
329 <literal>char-</literal> or <literal>block-</literal>
330 followed by a device group name, as listed in
331 <filename>/proc/devices</filename>. The latter is useful to
332 whitelist all current and future devices belonging to a
333 specific device group at once. The device group is matched
334 according to file name globbing rules, you may hence use the
335 <literal>*</literal> and <literal>?</literal>
336 wildcards. Examples: <filename>/dev/sda5</filename> is a
337 path to a device node, referring to an ATA or SCSI block
338 device. <literal>char-pts</literal> and
339 <literal>char-alsa</literal> are specifiers for all pseudo
340 TTYs and all ALSA sound devices,
341 respectively. <literal>char-cpu/*</literal> is a specifier
342 matching all CPU related device groups.</para>
347 <term><varname>DevicePolicy=auto|closed|strict</varname></term>
351 Control the policy for allowing device access:
355 <term><option>strict</option></term>
357 <para>means to only allow types of access that are
358 explicitly specified.</para>
363 <term><option>closed</option></term>
365 <para>in addition, allows access to standard pseudo
367 <filename>/dev/null</filename>,
368 <filename>/dev/zero</filename>,
369 <filename>/dev/full</filename>,
370 <filename>/dev/random</filename>, and
371 <filename>/dev/urandom</filename>.
377 <term><option>auto</option></term>
380 in addition, allows access to all devices if no
381 explicit <varname>DeviceAllow=</varname> is present.
391 <term><varname>Slice=</varname></term>
394 <para>The name of the slice unit to place the unit
395 in. Defaults to <filename>system.slice</filename> for all
396 non-instantiated units of all unit types (except for slice
397 units themselves see below). Instance units are by default
398 placed in a subslice of <filename>system.slice</filename>
399 that is named after the template name.</para>
401 <para>This option may be used to arrange systemd units in a
402 hierarchy of slices each of which might have resource
403 settings applied.</para>
405 <para>For units of type slice, the only accepted value for
406 this setting is the parent slice. Since the name of a slice
407 unit implies the parent slice, it is hence redundant to ever
408 set this parameter directly for slice units.</para>
416 <title>See Also</title>
418 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
419 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
420 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
421 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
422 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
423 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
424 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
425 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
426 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
427 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
428 The documentation for control groups and specific controllers in the Linux kernel:
429 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
430 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
431 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
432 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.