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.cgroup">
27 <title>systemd.cgroup</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.cgroup</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.cgroup</refname>
47 <refpurpose>Control Group configuration 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 which configure the control group settings
67 for spawned processes.</para>
69 <para>Control Groups is a concept for organizing processes in a
70 hierarch tree of named groups for the purpose of resource
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>,
83 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
84 for more information on the specific unit configuration files. The
85 execution-specific configuration options are configured in the
86 [Slice], [Scope], [Service], [Socket], [Mount], or [Swap]
87 sections, depending on the unit type.</para>
91 <title>Options</title>
93 <para>Units of the types listed above can have settings
94 for cgroup configuration:</para>
96 <variablelist class='unit-directives'>
99 <term><varname>CPUAccounting=</varname></term>
102 <para>Turn on CPU usage accounting for this unit. Takes a
103 boolean argument. Note that turning on CPU accounting for
104 one unit might also implicitly turn it on for all units
105 contained in the same slice and for all its parent slices and
106 the units contained therein.</para>
111 <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
114 <para>Assign the specified overall CPU time share weight to
115 the processes executed. Takes an integer value. This
116 controls the <literal>cpu.shares</literal> control group
117 attribute, which defaults to 1024. For details about this
118 control group attribute, see <ulink
119 url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
121 <para>Implies <literal>CPUAccounting=true</literal>.</para>
126 <term><varname>MemoryAccounting=</varname></term>
129 <para>Turn on process and kernel memory accounting for this
130 unit. Takes a boolean argument. Note that turning on memory
131 accounting for one unit might also implicitly turn it on for
132 all units contained in the same slice and for all its parent
133 slices and the units contained therein.</para>
138 <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
139 <term><varname>MemorySoftLimit=<replaceable>bytes</replaceable></varname></term>
142 <para>Specify the hard and soft limits on maximum memory
143 usage of the executed processes. The "hard" limit specifies
144 how much process and kernel memory can be used by tasks in
145 this unit, when there is no memory contention. If the kernel
146 detects memory contention, memory reclaim will be performed
147 until the memory usage is within the "soft" limit. Takes a
148 memory size in bytes. If the value is suffixed with K, M, G
149 or T, the specified memory size is parsed as Kilobytes,
150 Megabytes, Gigabytes, or Terabytes (with the base 1024),
151 respectively. This controls the
152 <literal>memory.limit_in_bytes</literal> and
153 <literal>memory.soft_limit_in_bytes</literal> control group
154 attributes. For details about these control group attributes,
156 url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
158 <para>Implies <literal>MemoryAccounting=true</literal>.</para>
163 <term><varname>BlockIOAccounting=</varname></term>
166 <para>Turn on Block IO accounting for this unit. Takes a
167 boolean argument. Note that turning on block IO accounting
168 for one unit might also implicitly turn it on for all units
169 contained in the same slice and all for its parent slices and
170 the units contained therein.</para>
175 <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
177 <listitem><para>Set the default
178 overall block IO weight for the
179 executed processes. Takes a single
180 weight value (between 10 and 1000) to
181 set the default block IO weight. This
183 <literal>blkio.weight</literal>
184 control group attribute, which
185 defaults to 1000. For details about
186 this control group attribute, see
188 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
191 <literal>BlockIOAccounting=true</literal>.</para>
196 <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
199 <para>Set the per-device overall block IO weight for the
200 executed processes. Takes a space-separated pair of a file
201 path and a weight value to specify the device specific
202 weight value, between 10 and 1000. (Example: "/dev/sda
203 500"). The file path may be specified as path to a block
204 device node or as any other file in which case the backing
205 block device of the file system of the file is
206 determined. This controls the
207 <literal>blkio.weight_device</literal> control group
208 attribute, which defaults to 1000. Use this option multiple
209 times to set weights for multiple devices. For details about
210 this control group attribute, see <ulink
211 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
214 <literal>BlockIOAccounting=true</literal>.</para>
219 <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
220 <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
223 <para>Set the per-device overall block IO bandwidth limit
224 for the executed processes. Takes a space-separated pair of
225 a file path and a bandwidth value (in bytes per second) to
226 specify the device specific bandwidth. The file path may be
227 a path to a block device node, or as any other file in which
228 case the backing block device of the file system of the file
229 is used. If the bandwidth is suffixed with K, M, G, or T,
230 the specified bandwidth is parsed as Kilobytes, Megabytes,
231 Gigabytes, or Terabytes, respectively (Example:
232 "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
233 controls the <literal>blkio.read_bps_device</literal> and
234 <literal>blkio.write_bps_device</literal> control group
235 attributes. Use this option multiple times to set bandwidth
236 limits for multiple devices. For details about these control
237 group attributes, see
238 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
242 <literal>BlockIOAccounting=true</literal>.</para>
247 <term><varname>DeviceAllow=</varname></term>
250 <para>Control access to specific device nodes by the
251 executed processes. Takes two space-separated strings: a
252 device node path (such as <filename>/dev/null</filename>)
253 followed by a combination of <constant>r</constant>,
254 <constant>w</constant>, <constant>m</constant> to control
255 <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
256 or creation of the specific device node by the unit
257 (<emphasis>m</emphasis>knod), respectively. This controls
258 the <literal>devices.allow</literal> and
259 <literal>devices.deny</literal> control group
260 attributes. For details about these control group attributes,
262 url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
267 <term><varname>DevicePolicy=auto|closed|strict</varname></term>
271 Control the policy for allowing device access:
275 <term><option>strict</option></term>
277 <para>means to only allow types of access that are
278 explicitly specified.</para>
283 <term><option>closed</option></term>
285 <para>in addition, allows access to standard pseudo
287 <filename>/dev/null</filename>,
288 <filename>/dev/zero</filename>,
289 <filename>/dev/full</filename>,
290 <filename>/dev/random</filename>, and
291 <filename>/dev/urandom</filename>.
297 <term><option>auto</option></term>
300 in addition, allows access to all devices if no
301 explicit <varname>DeviceAllow=</varname> is present.
311 <term><varname>Slice=</varname></term>
314 <para>The name of the slice unit to place the unit
315 in. Defaults to <filename>system.slice</filename> for all
316 non-instantiated units of all unit types (except for slice
317 units themselves see below). Instance units are by default
318 placed in a subslice of <filename>system.slice</filename>
319 that is named after the template name.</para>
321 <para>This option may be used to arrange systemd units in a
322 hierarchy of slices each of which might have resource
323 settings applied.</para>
325 <para>For units of type slice, the only accepted value for
326 this setting is the parent slice. Since the name of a slice
327 unit implies the parent slice, it is hence redundant to ever
328 set this parameter directly for slice units.</para>
336 <title>See Also</title>
338 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
339 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
340 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
341 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
342 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
343 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
344 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
345 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
346 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
347 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
348 The documentation for control groups and specific controllers in the Linux kernel:
349 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
350 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
351 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
352 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.