chiark / gitweb /
machined: optionally, allow registration of pre-existing units (scopes
[elogind.git] / man / systemd.resource-control.xml
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">
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 and
109           the units contained therein.</para>
110         </listitem>
111       </varlistentry>
112
113       <varlistentry>
114         <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>
115
116         <listitem>
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>
123
124           <para>Implies <literal>CPUAccounting=true</literal>.</para>
125         </listitem>
126       </varlistentry>
127
128       <varlistentry>
129         <term><varname>MemoryAccounting=</varname></term>
130
131         <listitem>
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>
137         </listitem>
138       </varlistentry>
139
140       <varlistentry>
141         <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>
142
143         <listitem>
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,
153           see <ulink
154           url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>
155
156           <para>Implies <literal>MemoryAccounting=true</literal>.</para>
157         </listitem>
158       </varlistentry>
159
160       <varlistentry>
161         <term><varname>BlockIOAccounting=</varname></term>
162
163         <listitem>
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>
169         </listitem>
170       </varlistentry>
171
172       <varlistentry>
173         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
174
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
180         controls the
181         <literal>blkio.weight</literal>
182         control group attribute, which
183         defaults to 1000. For details about
184         this control group attribute, see
185         <ulink
186             url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
187
188         <para>Implies
189         <literal>BlockIOAccounting=true</literal>.</para>
190         </listitem>
191       </varlistentry>
192
193       <varlistentry>
194         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
195
196         <listitem>
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>
210
211           <para>Implies
212           <literal>BlockIOAccounting=true</literal>.</para>
213         </listitem>
214       </varlistentry>
215
216       <varlistentry>
217         <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
218         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
219
220         <listitem>
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 (Example:
230           "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
231           controls the <literal>blkio.read_bps_device</literal> and
232           <literal>blkio.write_bps_device</literal> control group
233           attributes. Use this option multiple times to set bandwidth
234           limits for multiple devices. For details about these control
235           group attributes, see
236           <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
237           </para>
238
239           <para>Implies
240           <literal>BlockIOAccounting=true</literal>.</para>
241         </listitem>
242       </varlistentry>
243
244       <varlistentry>
245         <term><varname>DeviceAllow=</varname></term>
246
247         <listitem>
248           <para>Control access to specific device nodes by the
249           executed processes. Takes two space-separated strings: a
250           device node path (such as <filename>/dev/null</filename>)
251           followed by a combination of <constant>r</constant>,
252           <constant>w</constant>, <constant>m</constant> to control
253           <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,
254           or creation of the specific device node by the unit
255           (<emphasis>m</emphasis>knod), respectively. This controls
256           the <literal>devices.allow</literal> and
257           <literal>devices.deny</literal> control group
258           attributes. For details about these control group attributes,
259           see <ulink
260           url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>
261         </listitem>
262       </varlistentry>
263
264       <varlistentry>
265         <term><varname>DevicePolicy=auto|closed|strict</varname></term>
266
267         <listitem>
268           <para>
269             Control the policy for allowing device access:
270           </para>
271           <variablelist>
272             <varlistentry>
273               <term><option>strict</option></term>
274               <listitem>
275                 <para>means to only allow types of access that are
276                 explicitly specified.</para>
277               </listitem>
278             </varlistentry>
279
280             <varlistentry>
281               <term><option>closed</option></term>
282               <listitem>
283                 <para>in addition, allows access to standard pseudo
284                 devices including
285                 <filename>/dev/null</filename>,
286                 <filename>/dev/zero</filename>,
287                 <filename>/dev/full</filename>,
288                 <filename>/dev/random</filename>, and
289                 <filename>/dev/urandom</filename>.
290                 </para>
291               </listitem>
292             </varlistentry>
293
294             <varlistentry>
295               <term><option>auto</option></term>
296               <listitem>
297                 <para>
298                   in addition, allows access to all devices if no
299                   explicit <varname>DeviceAllow=</varname> is present.
300                   This is the default.
301                 </para>
302               </listitem>
303             </varlistentry>
304           </variablelist>
305         </listitem>
306       </varlistentry>
307
308       <varlistentry>
309         <term><varname>Slice=</varname></term>
310
311         <listitem>
312           <para>The name of the slice unit to place the unit
313           in. Defaults to <filename>system.slice</filename> for all
314           non-instantiated units of all unit types (except for slice
315           units themselves see below). Instance units are by default
316           placed in a subslice of <filename>system.slice</filename>
317           that is named after the template name.</para>
318
319           <para>This option may be used to arrange systemd units in a
320           hierarchy of slices each of which might have resource
321           settings applied.</para>
322
323           <para>For units of type slice, the only accepted value for
324           this setting is the parent slice. Since the name of a slice
325           unit implies the parent slice, it is hence redundant to ever
326           set this parameter directly for slice units.</para>
327         </listitem>
328       </varlistentry>
329
330     </variablelist>
331   </refsect1>
332
333   <refsect1>
334     <title>See Also</title>
335     <para>
336       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
337       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
338       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
339       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
340       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
341       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
342       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
343       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
344       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
345       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
346       The documentation for control groups and specific controllers in the Linux kernel:
347       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,
348       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,
349       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,
350       <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.
351     </para>
352   </refsect1>
353 </refentry>