<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="systemd.resource-control">

<refentryinfo>

<title>systemd.resource-control</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>systemd.resource-control</refentrytitle>

<manvolnum>5</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd.resource-control</refname>

<refpurpose>Resource control unit settings</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para>

<filename><replaceable>slice</replaceable>.slice</filename>,

<filename><replaceable>scope</replaceable>.scope</filename>,

<filename><replaceable>service</replaceable>.service</filename>,

<filename><replaceable>socket</replaceable>.socket</filename>,

<filename><replaceable>mount</replaceable>.mount</filename>,

<filename><replaceable>swap</replaceable>.swap</filename>

</para>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>Unit configuration files for services, slices, scopes,

sockets, mount points, and swap devices share a subset of

configuration options for resource control of spawned

processes. Internally, this relies on the Control Groups

kernel concept for organizing processes in a hierarchical tree of

named groups for the purpose of resource management.</para>

<para>This man page lists the configuration options shared by

those six unit types. See

<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for the common options of all unit configuration files, and

<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

and

<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for more information on the specific unit configuration files. The

resource control configuration options are configured in the

[Slice], [Scope], [Service], [Socket], [Mount], or [Swap]

sections, depending on the unit type.</para>

<para>See the <ulink

url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New

Control Group Interfaces</ulink> for an introduction on how to make

use of resource control APIs from programs.</para>

</refsect1>

<refsect1>

<title>Options</title>

<para>Units of the types listed above can have settings

for resource control configuration:</para>

<variablelist class='unit-directives'>

<varlistentry>

<term><varname>CPUAccounting=</varname></term>

<listitem>

<para>Turn on CPU usage accounting for this unit. Takes a

boolean argument. Note that turning on CPU accounting for

one unit will also implicitly turn it on for all units

contained in the same slice and for all its parent slices

and the units contained therein. The system default for this

setting may be controlled with

<varname>DefaultCPUAccounting=</varname> in

<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>CPUShares=<replaceable>weight</replaceable></varname></term>

<term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term>

<listitem>

<para>Assign the specified CPU time share weight to the

processes executed. These options take an integer value and

control the <literal>cpu.shares</literal> control group

attribute. The allowed range is 2 to 262144. Defaults to

1024. For details about this control group attribute, see

<ulink

url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.

The available CPU time is split up among all units within

one slice relative to their CPU time share weight.</para>

<para>While <varname>StartupCPUShares=</varname> only

applies to the startup phase of the system,

<varname>CPUShares=</varname> applies to normal runtime of

the system, and if the former is not set also to the startup

phase. Using <varname>StartupCPUShares=</varname> allows

prioritizing specific services at boot-up differently than

during normal runtime.</para>

<para>These options imply

<literal>CPUAccounting=true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>CPUQuota=</varname></term>

<listitem>

<para>Assign the specified CPU time quota to the processes

executed. Takes a percentage value, suffixed with "%". The

percentage specifies how much CPU time the unit shall get at

maximum, relative to the total CPU time available on one

CPU. Use values &gt; 100% for allotting CPU time on more than

one CPU. This controls the

<literal>cpu.cfs_quota_us</literal> control group

attribute. For details about this control group attribute,

see <ulink

url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para>

<para>Example: <varname>CPUQuota=20%</varname> ensures that

the executed processes will never get more than 20% CPU time

on one CPU.</para>

<para>Implies <literal>CPUAccounting=true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>MemoryAccounting=</varname></term>

<listitem>

<para>Turn on process and kernel memory accounting for this

unit. Takes a boolean argument. Note that turning on memory

accounting for one unit will also implicitly turn it on for

all units contained in the same slice and for all its parent

slices and the units contained therein. The system default

for this setting may be controlled with

<varname>DefaultMemoryAccounting=</varname> in

<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term>

<listitem>

<para>Specify the limit on maximum memory usage of the

executed processes. The limit specifies how much process and

kernel memory can be used by tasks in this unit. Takes a

memory size in bytes. If the value is suffixed with K, M, G

or T, the specified memory size is parsed as Kilobytes,

Megabytes, Gigabytes, or Terabytes (with the base 1024),

respectively. If assigned the special value

<literal>infinity</literal>, no memory limit is applied. This

controls the <literal>memory.limit_in_bytes</literal>

control group attribute. For details about this control

group attribute, see <ulink

url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para>

<para>Implies <literal>MemoryAccounting=true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>TasksAccounting=</varname></term>

<listitem>

<para>Turn on task accounting for this unit. Takes a

boolean argument. If enabled, the system manager will keep

track of the number of tasks in the unit. The number of

tasks accounted this way includes both kernel threads and

userspace processes, with each thread counting

individually. Note that turning on tasks accounting for one

unit will also implicitly turn it on for all units contained

in the same slice and for all its parent slices and the

units contained therein. The system default for this setting

may be controlled with

<varname>DefaultTasksAccounting=</varname> in

<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>TasksMax=<replaceable>N</replaceable></varname></term>

<listitem>

<para>Specify the maximum number of tasks that may be

created in the unit. This ensures that the number of tasks

accounted for the unit (see above) stays below a specific

limit. If assigned the special value

<literal>infinity</literal>, no tasks limit is applied. This

controls the <literal>pids.max</literal> control group

attribute. For details about this control group attribute,

see <ulink

url="https://www.kernel.org/doc/Documentation/cgroups/pids.txt">pids.txt</ulink>.</para>

<para>Implies <literal>TasksAccounting=true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>BlockIOAccounting=</varname></term>

<listitem>

<para>Turn on Block I/O accounting for this unit. Takes a

boolean argument. Note that turning on block I/O accounting

for one unit will also implicitly turn it on for all units

contained in the same slice and all for its parent slices

and the units contained therein. The system default for this

setting may be controlled with

<varname>DefaultBlockIOAccounting=</varname> in

<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>

<term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>

<listitem><para>Set the default overall block I/O weight for

the executed processes. Takes a single weight value (between

10 and 1000) to set the default block I/O weight. This controls

the <literal>blkio.weight</literal> control group attribute,

which defaults to 500. For details about this control group

attribute, see <ulink

url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.

The available I/O bandwidth is split up among all units within

one slice relative to their block I/O weight.</para>

<para>While <varname>StartupBlockIOWeight=</varname> only

applies to the startup phase of the system,

<varname>BlockIOWeight=</varname> applies to the later runtime

of the system, and if the former is not set also to the

startup phase. This allows prioritizing specific services at

boot-up differently than during runtime.</para>

<para>Implies

<literal>BlockIOAccounting=true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>

<listitem>

<para>Set the per-device overall block I/O weight for the

executed processes. Takes a space-separated pair of a file

path and a weight value to specify the device specific

weight value, between 10 and 1000. (Example: "/dev/sda

500"). The file path may be specified as path to a block

device node or as any other file, in which case the backing

block device of the file system of the file is

determined. This controls the

<literal>blkio.weight_device</literal> control group

attribute, which defaults to 1000. Use this option multiple

times to set weights for multiple devices. For details about

this control group attribute, see <ulink

url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para>

<para>Implies

<literal>BlockIOAccounting=true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>

<term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>

<listitem>

<para>Set the per-device overall block I/O bandwidth limit

for the executed processes. Takes a space-separated pair of

a file path and a bandwidth value (in bytes per second) to

specify the device specific bandwidth. The file path may be

a path to a block device node, or as any other file in which

case the backing block device of the file system of the file

is used. If the bandwidth is suffixed with K, M, G, or T,

the specified bandwidth is parsed as Kilobytes, Megabytes,

Gigabytes, or Terabytes, respectively, to the base of

1000. (Example:

"/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This

controls the <literal>blkio.read_bps_device</literal> and

<literal>blkio.write_bps_device</literal> control group

attributes. Use this option multiple times to set bandwidth

limits for multiple devices. For details about these control

group attributes, see <ulink

url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.

</para>

<para>Implies

<literal>BlockIOAccounting=true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>DeviceAllow=</varname></term>

<listitem>

<para>Control access to specific device nodes by the

executed processes. Takes two space-separated strings: a

device node specifier followed by a combination of

<constant>r</constant>, <constant>w</constant>,

<constant>m</constant> to control

<emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting,

or creation of the specific device node(s) by the unit

(<emphasis>m</emphasis>knod), respectively. This controls

the <literal>devices.allow</literal> and

<literal>devices.deny</literal> control group

attributes. For details about these control group

attributes, see <ulink

url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para>

<para>The device node specifier is either a path to a device

node in the file system, starting with

<filename>/dev/</filename>, or a string starting with either

<literal>char-</literal> or <literal>block-</literal>

followed by a device group name, as listed in

<filename>/proc/devices</filename>. The latter is useful to

whitelist all current and future devices belonging to a

specific device group at once. The device group is matched

according to file name globbing rules, you may hence use the

<literal>*</literal> and <literal>?</literal>

wildcards. Examples: <filename>/dev/sda5</filename> is a

path to a device node, referring to an ATA or SCSI block

device. <literal>char-pts</literal> and

<literal>char-alsa</literal> are specifiers for all pseudo

TTYs and all ALSA sound devices,

respectively. <literal>char-cpu/*</literal> is a specifier

matching all CPU related device groups.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>DevicePolicy=auto|closed|strict</varname></term>

<listitem>

<para>

Control the policy for allowing device access:

</para>

<variablelist>

<varlistentry>

<term><option>strict</option></term>

<listitem>

<para>means to only allow types of access that are

explicitly specified.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>closed</option></term>

<listitem>

<para>in addition, allows access to standard pseudo

devices including

<filename>/dev/null</filename>,

<filename>/dev/zero</filename>,

<filename>/dev/full</filename>,

<filename>/dev/random</filename>, and

<filename>/dev/urandom</filename>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>auto</option></term>

<listitem>

<para>

in addition, allows access to all devices if no

explicit <varname>DeviceAllow=</varname> is present.

This is the default.

</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>NetClass=</varname></term>

<listitem><para>Configures a network class number to assign to the

unit. This value will be set to the

<literal>net_cls.class_id</literal> property of the

<literal>net_cls</literal> cgroup of the unit. The directive

accepts a numerical value (for fixed number assignment) and the keyword

<literal>auto</literal> (for dynamic allocation). Network traffic of

all processes inside the unit will have the network class ID assigned

by the kernel. Also see

the kernel docs for

<ulink url="https://www.kernel.org/doc/Documentation/cgroups/net_cls.txt">net_cls controller</ulink>

and

<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.

</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>Slice=</varname></term>

<listitem>

<para>The name of the slice unit to place the unit

in. Defaults to <filename>system.slice</filename> for all

non-instantiated units of all unit types (except for slice

units themselves see below). Instance units are by default

placed in a subslice of <filename>system.slice</filename>

that is named after the template name.</para>

<para>This option may be used to arrange systemd units in a

hierarchy of slices each of which might have resource

settings applied.</para>

<para>For units of type slice, the only accepted value for

this setting is the parent slice. Since the name of a slice

unit implies the parent slice, it is hence redundant to ever

set this parameter directly for slice units.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>Delegate=</varname></term>

<listitem>

<para>Turns on delegation of further resource control

partitioning to processes of the unit. For unprivileged

services (i.e. those using the <varname>User=</varname>

setting), this allows processes to create a subhierarchy

beneath its control group path. For privileged services and

scopes, this ensures the processes will have all control

group controllers enabled.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

The documentation for control groups and specific controllers in the Linux kernel:

<ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>,

<ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>,

<ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>,

<ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.

</para>

</refsect1>

</refentry>