chiark / gitweb /
man: bring machinectl man page up-to-date
[elogind.git] / man / systemd.resource-control.xml
1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
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">
5
6 <!--
7 This file is part of systemd.
8
9 Copyright 2013 Zbigniew JÄ™drzejewski-Szmek
10
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.
15
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.
20
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/>.
23 -->
24
25 <refentry id="systemd.resource-control">
26   <refentryinfo>
27     <title>systemd.resource-control</title>
28     <productname>systemd</productname>
29
30     <authorgroup>
31       <author>
32         <contrib>Developer</contrib>
33         <firstname>Lennart</firstname>
34         <surname>Poettering</surname>
35         <email>lennart@poettering.net</email>
36       </author>
37     </authorgroup>
38   </refentryinfo>
39
40   <refmeta>
41     <refentrytitle>systemd.resource-control</refentrytitle>
42     <manvolnum>5</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>systemd.resource-control</refname>
47     <refpurpose>Resource control unit settings</refpurpose>
48   </refnamediv>
49
50   <refsynopsisdiv>
51     <para>
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>
58     </para>
59   </refsynopsisdiv>
60
61   <refsect1>
62     <title>Description</title>
63
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>
70
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>,
80     and
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>
86
87     <para>See the <ulink
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>
91   </refsect1>
92
93   <refsect1>
94     <title>Options</title>
95
96     <para>Units of the types listed above can have settings
97     for resource control configuration:</para>
98
99     <variablelist class='unit-directives'>
100
101       <varlistentry>
102         <term><varname>CPUAccounting=</varname></term>
103
104         <listitem>
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>
113         </listitem>
114       </varlistentry>
115
116       <varlistentry>
117         <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
118         <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>
119
120         <listitem>
121           <para>Assign the specified CPU time share weight to the
122           processes executed. Those options take an integer value and
123           control the <literal>cpu.shares</literal> control group
124           attribute, which defaults to 1024. For details about this
125           control group 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
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           priorizing specific services at boot-up differently than
136           during normal runtime.</para>
137
138           <para>Those 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 alloting 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 might also implicitly turn it on for
173           all its parent slices. The system default for this setting
174           maybe controlled with
175           <varname>DefaultMemoryAccounting=</varname> in
176           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
177         </listitem>
178       </varlistentry>
179
180       <varlistentry>
181         <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
182
183         <listitem>
184           <para>Specify the limit on maximum memory usage of the
185           executed processes. The limit specifies how much process and
186           kernel memory can be used by tasks in this unit. Takes a
187           memory size in bytes. If the value is suffixed with K, M, G
188           or T, the specified memory size is parsed as Kilobytes,
189           Megabytes, Gigabytes, or Terabytes (with the base 1024),
190           respectively. This controls the
191           <literal>memory.limit_in_bytes</literal> control group
192           attribute. For details about this control group attribute,
193           see <ulink
194           url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
195
196           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
197         </listitem>
198       </varlistentry>
199
200       <varlistentry>
201         <term><varname>BlockIOAccounting=</varname></term>
202
203         <listitem>
204           <para>Turn on Block IO accounting for this unit. Takes a
205           boolean argument. Note that turning on block IO accounting
206           for one unit might also implicitly turn it on for all units
207           contained in the same slice and all for its parent slices
208           and the units contained therein. The system default for this
209           setting maybe controlled with
210           <varname>DefaultBlockIOAccounting=</varname> in
211           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
212         </listitem>
213       </varlistentry>
214
215       <varlistentry>
216         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
217         <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
218
219         <listitem><para>Set the default overall block IO weight for
220         the executed processes. Takes a single weight value (between
221         10 and 1000) to set the default block IO weight. This controls
222         the <literal>blkio.weight</literal> control group attribute,
223         which defaults to 1000. For details about this control group
224         attribute, see <ulink
225         url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
226         The available IO bandwidth is split up among all units within
227         one slice relative to their block IO weight.</para>
228
229         <para>While <varname>StartupBlockIOWeight=</varname> only
230         applies to the startup phase of the system,
231         <varname>BlockIOWeight=</varname> applies to the later runtime
232         of the system, and if the former is not set also to the
233         startup phase. This allows priorizing specific services at
234         boot-up differently than during runtime.</para>
235
236         <para>Implies
237         <literal>BlockIOAccounting=true</literal>.</para>
238         </listitem>
239       </varlistentry>
240
241       <varlistentry>
242         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
243
244         <listitem>
245           <para>Set the per-device overall block IO weight for the
246           executed processes. Takes a space-separated pair of a file
247           path and a weight value to specify the device specific
248           weight value, between 10 and 1000. (Example: "/dev/sda
249           500"). The file path may be specified as path to a block
250           device node or as any other file, in which case the backing
251           block device of the file system of the file is
252           determined. This controls the
253           <literal>blkio.weight_device</literal> control group
254           attribute, which defaults to 1000. Use this option multiple
255           times to set weights for multiple devices. For details about
256           this control group attribute, see <ulink
257           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
258
259           <para>Implies
260           <literal>BlockIOAccounting=true</literal>.</para>
261         </listitem>
262       </varlistentry>
263
264       <varlistentry>
265         <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
266         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
267
268         <listitem>
269           <para>Set the per-device overall block IO bandwidth limit
270           for the executed processes. Takes a space-separated pair of
271           a file path and a bandwidth value (in bytes per second) to
272           specify the device specific bandwidth. The file path may be
273           a path to a block device node, or as any other file in which
274           case the backing block device of the file system of the file
275           is used. If the bandwidth is suffixed with K, M, G, or T,
276           the specified bandwidth is parsed as Kilobytes, Megabytes,
277           Gigabytes, or Terabytes, respectively, to the base of
278           1000. (Example:
279           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
280           controls the <literal>blkio.read_bps_device</literal> and
281           <literal>blkio.write_bps_device</literal> control group
282           attributes. Use this option multiple times to set bandwidth
283           limits for multiple devices. For details about these control
284           group attributes, see <ulink
285           url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
286           </para>
287
288           <para>Implies
289           <literal>BlockIOAccounting=true</literal>.</para>
290         </listitem>
291       </varlistentry>
292
293       <varlistentry>
294         <term><varname>DeviceAllow=</varname></term>
295
296         <listitem>
297           <para>Control access to specific device nodes by the
298           executed processes. Takes two space-separated strings: a
299           device node specifier followed by a combination of
300           <constant>r</constant>, <constant>w</constant>,
301           <constant>m</constant> to control
302           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
303           or creation of the specific device node(s) by the unit
304           (<emphasis>m</emphasis>knod), respectively. This controls
305           the <literal>devices.allow</literal> and
306           <literal>devices.deny</literal> control group
307           attributes. For details about these control group
308           attributes, see <ulink
309           url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
310
311           <para>The device node specifier is either a path to a device
312           node in the file system, starting with
313           <filename>/dev/</filename>, or a string starting with either
314           <literal>char-</literal> or <literal>block-</literal>
315           followed by a device group name, as listed in
316           <filename>/proc/devices</filename>. The latter is useful to
317           whitelist all current and future devices belonging to a
318           specific device group at once. The device group is matched
319           according to file name globbing rules, you may hence use the
320           <literal>*</literal> and <literal>?</literal>
321           wildcards. Examples: <filename>/dev/sda5</filename> is a
322           path to a device node, referring to an ATA or SCSI block
323           device. <literal>char-pts</literal> and
324           <literal>char-alsa</literal> are specifiers for all pseudo
325           TTYs and all ALSA sound devices,
326           respectively. <literal>char-cpu/*</literal> is a specifier
327           matching all CPU related device groups.</para>
328         </listitem>
329       </varlistentry>
330
331       <varlistentry>
332         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
333
334         <listitem>
335           <para>
336             Control the policy for allowing device access:
337           </para>
338           <variablelist>
339             <varlistentry>
340               <term><option>strict</option></term>
341               <listitem>
342                 <para>means to only allow types of access that are
343                 explicitly specified.</para>
344               </listitem>
345             </varlistentry>
346
347             <varlistentry>
348               <term><option>closed</option></term>
349               <listitem>
350                 <para>in addition, allows access to standard pseudo
351                 devices including
352                 <filename>/dev/null</filename>,
353                 <filename>/dev/zero</filename>,
354                 <filename>/dev/full</filename>,
355                 <filename>/dev/random</filename>, and
356                 <filename>/dev/urandom</filename>.
357                 </para>
358               </listitem>
359             </varlistentry>
360
361             <varlistentry>
362               <term><option>auto</option></term>
363               <listitem>
364                 <para>
365                   in addition, allows access to all devices if no
366                   explicit <varname>DeviceAllow=</varname> is present.
367                   This is the default.
368                 </para>
369               </listitem>
370             </varlistentry>
371           </variablelist>
372         </listitem>
373       </varlistentry>
374
375       <varlistentry>
376         <term><varname>Slice=</varname></term>
377
378         <listitem>
379           <para>The name of the slice unit to place the unit
380           in. Defaults to <filename>system.slice</filename> for all
381           non-instantiated units of all unit types (except for slice
382           units themselves see below). Instance units are by default
383           placed in a subslice of <filename>system.slice</filename>
384           that is named after the template name.</para>
385
386           <para>This option may be used to arrange systemd units in a
387           hierarchy of slices each of which might have resource
388           settings applied.</para>
389
390           <para>For units of type slice, the only accepted value for
391           this setting is the parent slice. Since the name of a slice
392           unit implies the parent slice, it is hence redundant to ever
393           set this parameter directly for slice units.</para>
394         </listitem>
395       </varlistentry>
396
397       <varlistentry>
398         <term><varname>Delegate=</varname></term>
399
400         <listitem>
401           <para>Turns on delegation of further resource control
402           partitioning to processes of the unit. For unpriviliged
403           services (i.e. those using the <varname>User=</varname>
404           setting) this allows processes to create a subhierarchy
405           beneath its control group path. For priviliged services and
406           scopes this ensures the processes will have all control
407           group controllers enabled.</para>
408         </listitem>
409       </varlistentry>
410
411     </variablelist>
412   </refsect1>
413
414   <refsect1>
415     <title>See Also</title>
416     <para>
417       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
418       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
419       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
420       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
421       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
422       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
423       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
424       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
425       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
426       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
427       The documentation for control groups and specific controllers in the Linux kernel:
428       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
429       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
430       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
431       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
432     </para>
433   </refsect1>
434 </refentry>