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 and
109 the units contained therein.</para>
114 <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
117 <para>Assign the specified overall CPU time share weight to
118 the processes executed. Takes an integer value. This
119 controls the <literal>cpu.shares</literal> control group
120 attribute, which defaults to 1024. For details about this
121 control group attribute, see <ulink
122 url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>
124 <para>Implies <literal>CPUAccounting=true</literal>.</para>
129 <term><varname>MemoryAccounting=</varname></term>
132 <para>Turn on process and kernel memory accounting for this
133 unit. Takes a boolean argument. Note that turning on memory
134 accounting for one unit might also implicitly turn it on for
135 all units contained in the same slice and for all its parent
136 slices and the units contained therein.</para>
141 <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
144 <para>Specify the limit on maximum memory usage of the
145 executed processes. The limit specifies how much process and
146 kernel memory can be used by tasks in this unit. Takes a
147 memory size in bytes. If the value is suffixed with K, M, G
148 or T, the specified memory size is parsed as Kilobytes,
149 Megabytes, Gigabytes, or Terabytes (with the base 1024),
150 respectively. This controls the
151 <literal>memory.limit_in_bytes</literal> control group
152 attribute. For details about this control group attribute,
154 url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
156 <para>Implies <literal>MemoryAccounting=true</literal>.</para>
161 <term><varname>BlockIOAccounting=</varname></term>
164 <para>Turn on Block IO accounting for this unit. Takes a
165 boolean argument. Note that turning on block IO accounting
166 for one unit might also implicitly turn it on for all units
167 contained in the same slice and all for its parent slices and
168 the units contained therein.</para>
173 <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
175 <listitem><para>Set the default
176 overall block IO weight for the
177 executed processes. Takes a single
178 weight value (between 10 and 1000) to
179 set the default block IO weight. This
181 <literal>blkio.weight</literal>
182 control group attribute, which
183 defaults to 1000. For details about
184 this control group attribute, see
186 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
189 <literal>BlockIOAccounting=true</literal>.</para>
194 <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
197 <para>Set the per-device overall block IO weight for the
198 executed processes. Takes a space-separated pair of a file
199 path and a weight value to specify the device specific
200 weight value, between 10 and 1000. (Example: "/dev/sda
201 500"). The file path may be specified as path to a block
202 device node or as any other file, in which case the backing
203 block device of the file system of the file is
204 determined. This controls the
205 <literal>blkio.weight_device</literal> control group
206 attribute, which defaults to 1000. Use this option multiple
207 times to set weights for multiple devices. For details about
208 this control group attribute, see <ulink
209 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
212 <literal>BlockIOAccounting=true</literal>.</para>
217 <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
218 <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
221 <para>Set the per-device overall block IO bandwidth limit
222 for the executed processes. Takes a space-separated pair of
223 a file path and a bandwidth value (in bytes per second) to
224 specify the device specific bandwidth. The file path may be
225 a path to a block device node, or as any other file in which
226 case the backing block device of the file system of the file
227 is used. If the bandwidth is suffixed with K, M, G, or T,
228 the specified bandwidth is parsed as Kilobytes, Megabytes,
229 Gigabytes, or Terabytes, respectively, to the base of
231 "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
232 controls the <literal>blkio.read_bps_device</literal> and
233 <literal>blkio.write_bps_device</literal> control group
234 attributes. Use this option multiple times to set bandwidth
235 limits for multiple devices. For details about these control
236 group attributes, see <ulink
237 url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
241 <literal>BlockIOAccounting=true</literal>.</para>
246 <term><varname>DeviceAllow=</varname></term>
249 <para>Control access to specific device nodes by the
250 executed processes. Takes two space-separated strings: a
251 device node specifier followed by a combination of
252 <constant>r</constant>, <constant>w</constant>,
253 <constant>m</constant> to control
254 <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
255 or creation of the specific device node(s) by the unit
256 (<emphasis>m</emphasis>knod), respectively. This controls
257 the <literal>devices.allow</literal> and
258 <literal>devices.deny</literal> control group
259 attributes. For details about these control group
260 attributes, see <ulink
261 url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
263 <para>The device node specifier is either a path to a device
264 node in the file system, starting with
265 <filename>/dev/</filename>, or a string starting with either
266 <literal>char-</literal> or <literal>block-</literal>
267 followed by a device group name, as listed in
268 <filename>/proc/devices</filename>. The latter is useful to
269 whitelist all current and future devices belonging to a
270 specific device group at once. Examples:
271 <filename>/dev/sda5</filename> is a path to a device node,
272 referring to an ATA or SCSI block
273 device. <literal>char-pts</literal> and
274 <literal>char-alsa</literal> are specifiers for all pseudo
275 TTYs and all ALSA sound devices, respectively.</para>
280 <term><varname>DevicePolicy=auto|closed|strict</varname></term>
284 Control the policy for allowing device access:
288 <term><option>strict</option></term>
290 <para>means to only allow types of access that are
291 explicitly specified.</para>
296 <term><option>closed</option></term>
298 <para>in addition, allows access to standard pseudo
300 <filename>/dev/null</filename>,
301 <filename>/dev/zero</filename>,
302 <filename>/dev/full</filename>,
303 <filename>/dev/random</filename>, and
304 <filename>/dev/urandom</filename>.
310 <term><option>auto</option></term>
313 in addition, allows access to all devices if no
314 explicit <varname>DeviceAllow=</varname> is present.
324 <term><varname>Slice=</varname></term>
327 <para>The name of the slice unit to place the unit
328 in. Defaults to <filename>system.slice</filename> for all
329 non-instantiated units of all unit types (except for slice
330 units themselves see below). Instance units are by default
331 placed in a subslice of <filename>system.slice</filename>
332 that is named after the template name.</para>
334 <para>This option may be used to arrange systemd units in a
335 hierarchy of slices each of which might have resource
336 settings applied.</para>
338 <para>For units of type slice, the only accepted value for
339 this setting is the parent slice. Since the name of a slice
340 unit implies the parent slice, it is hence redundant to ever
341 set this parameter directly for slice units.</para>
349 <title>See Also</title>
351 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
352 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
353 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
354 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
355 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
356 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
357 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
358 <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
359 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
360 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
361 The documentation for control groups and specific controllers in the Linux kernel:
362 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
363 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
364 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
365 <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.