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>
141 <para>Specify the limit on maximum memory usage of the
142 executed processes. The limit specifies how much process and
143 kernel memory can be used by tasks in this unit. Takes a
144 memory size in bytes. If the value is suffixed with K, M, G
145 or T, the specified memory size is parsed as Kilobytes,
146 Megabytes, Gigabytes, or Terabytes (with the base 1024),
147 respectively. This controls the
148 <literal>memory.limit_in_bytes</literal> control group
149 attribute. For details about this control group attribute,
151 url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
153 <para>Implies <literal>MemoryAccounting=true</literal>.</para>
158 <term><varname>BlockIOAccounting=</varname></term>
161 <para>Turn on Block IO accounting for this unit. Takes a
162 boolean argument. Note that turning on block IO accounting
163 for one unit might also implicitly turn it on for all units
164 contained in the same slice and all for its parent slices and
165 the units contained therein.</para>
170 <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
172 <listitem><para>Set the default
173 overall block IO weight for the
174 executed processes. Takes a single
175 weight value (between 10 and 1000) to
176 set the default block IO weight. This
178 <literal>blkio.weight</literal>
179 control group attribute, which
180 defaults to 1000. For details about
181 this control group attribute, see
183 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
186 <literal>BlockIOAccounting=true</literal>.</para>
191 <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
194 <para>Set the per-device overall block IO weight for the
195 executed processes. Takes a space-separated pair of a file
196 path and a weight value to specify the device specific
197 weight value, between 10 and 1000. (Example: "/dev/sda
198 500"). The file path may be specified as path to a block
199 device node or as any other file in which case the backing
200 block device of the file system of the file is
201 determined. This controls the
202 <literal>blkio.weight_device</literal> control group
203 attribute, which defaults to 1000. Use this option multiple
204 times to set weights for multiple devices. For details about
205 this control group attribute, see <ulink
206 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
209 <literal>BlockIOAccounting=true</literal>.</para>
214 <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
215 <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
218 <para>Set the per-device overall block IO bandwidth limit
219 for the executed processes. Takes a space-separated pair of
220 a file path and a bandwidth value (in bytes per second) to
221 specify the device specific bandwidth. The file path may be
222 a path to a block device node, or as any other file in which
223 case the backing block device of the file system of the file
224 is used. If the bandwidth is suffixed with K, M, G, or T,
225 the specified bandwidth is parsed as Kilobytes, Megabytes,
226 Gigabytes, or Terabytes, respectively (Example:
227 "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
228 controls the <literal>blkio.read_bps_device</literal> and
229 <literal>blkio.write_bps_device</literal> control group
230 attributes. Use this option multiple times to set bandwidth
231 limits for multiple devices. For details about these control
232 group attributes, see
233 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
237 <literal>BlockIOAccounting=true</literal>.</para>
242 <term><varname>DeviceAllow=</varname></term>
245 <para>Control access to specific device nodes by the
246 executed processes. Takes two space-separated strings: a
247 device node path (such as <filename>/dev/null</filename>)
248 followed by a combination of <constant>r</constant>,
249 <constant>w</constant>, <constant>m</constant> to control
250 <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
251 or creation of the specific device node by the unit
252 (<emphasis>m</emphasis>knod), respectively. This controls
253 the <literal>devices.allow</literal> and
254 <literal>devices.deny</literal> control group
255 attributes. For details about these control group attributes,
257 url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
262 <term><varname>DevicePolicy=auto|closed|strict</varname></term>
266 Control the policy for allowing device access:
270 <term><option>strict</option></term>
272 <para>means to only allow types of access that are
273 explicitly specified.</para>
278 <term><option>closed</option></term>
280 <para>in addition, allows access to standard pseudo
282 <filename>/dev/null</filename>,
283 <filename>/dev/zero</filename>,
284 <filename>/dev/full</filename>,
285 <filename>/dev/random</filename>, and
286 <filename>/dev/urandom</filename>.
292 <term><option>auto</option></term>
295 in addition, allows access to all devices if no
296 explicit <varname>DeviceAllow=</varname> is present.
306 <term><varname>Slice=</varname></term>
309 <para>The name of the slice unit to place the unit
310 in. Defaults to <filename>system.slice</filename> for all
311 non-instantiated units of all unit types (except for slice
312 units themselves see below). Instance units are by default
313 placed in a subslice of <filename>system.slice</filename>
314 that is named after the template name.</para>
316 <para>This option may be used to arrange systemd units in a
317 hierarchy of slices each of which might have resource
318 settings applied.</para>
320 <para>For units of type slice, the only accepted value for
321 this setting is the parent slice. Since the name of a slice
322 unit implies the parent slice, it is hence redundant to ever
323 set this parameter directly for slice units.</para>
331 <title>See Also</title>
333 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
334 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
335 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
336 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
337 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
338 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
339 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
340 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
341 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
342 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
343 The documentation for control groups and specific controllers in the Linux kernel:
344 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
345 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
346 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
347 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.