From: Zbigniew Jędrzejewski-Szmek Date: Wed, 10 Jul 2013 05:25:02 +0000 (-0400) Subject: man: document the slice and scope units, add systemd.cgroup(5) X-Git-Tag: v206~120 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=d868475ad62547f0a034dfaf038aff31b3d05372 man: document the slice and scope units, add systemd.cgroup(5) --- diff --git a/Makefile-man.am b/Makefile-man.am index bef749af8..e74cceaad 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -76,6 +76,7 @@ MANPAGES += \ man/systemd-update-utmp.service.8 \ man/systemd.1 \ man/systemd.automount.5 \ + man/systemd.cgroup.5 \ man/systemd.device.5 \ man/systemd.exec.5 \ man/systemd.journal-fields.7 \ @@ -83,7 +84,9 @@ MANPAGES += \ man/systemd.mount.5 \ man/systemd.path.5 \ man/systemd.preset.5 \ + man/systemd.scope.5 \ man/systemd.service.5 \ + man/systemd.slice.5 \ man/systemd.snapshot.5 \ man/systemd.socket.5 \ man/systemd.special.7 \ diff --git a/man/systemd.cgroup.xml b/man/systemd.cgroup.xml new file mode 100644 index 000000000..504c9685a --- /dev/null +++ b/man/systemd.cgroup.xml @@ -0,0 +1,308 @@ + + + + + + + + + systemd.cgroup + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.cgroup + 5 + + + + systemd.cgroup + Cgroup configuration unit settings + + + + + slice.slice, + scope.scope, + service.service, + socket.socket, + mount.mount, + swap.swap + + + + + Description + + Unit configuration files for services, slices, scopes, + sockets, mount points, and swap devices share a subset of + configuration options which configure the control group settings + for spawned processes. + + This man page lists the configuration options shared by + those six unit types. See + systemd.unit5 + for the common options of all unit configuration files, and + systemd.slice5, + systemd.scope5, + systemd.service5, + systemd.socket5, + systemd.mount5, + and + systemd.swap5 + for more information on the specific unit configuration files. The + execution specific configuration options are configured in the + [Slice], [Scope], [Service], [Socket], [Mount], or [Swap] + sections, depending on the unit type. + + + + Options + + Units of the types listed above can have settings + for cgroup configuration: + + + + CPUAccounting= + + + Turn on the CPU usage accounting for this + unit. + + + + + BlockIOAccounting= + + + Turn on the Block IO bandwidth accounting + for this unit. + + + + + MemoryAccounting= + + + Turn on the process and kernel memory + accounting for this unit. + + + + + + CPUShares=weight + + + Assign the specified overall CPU time share weight to + the processes executed. Takes an integer value. This + controls the cpu.shares control group + attribute, which defaults to 1024. For details about this + control group attribute see sched-design-CFS.txt. + + Implies CPUAccounting=true. + + + + + MemoryLimit=bytes + MemorySoftLimit=bytes + + + Specify the hard and soft limits on maximum memory + usage of the executed processes. The "hard" limit specifies + how much process and kernel memory can be used by tasks in + this unit, when there is no memory contention. If the kernel + detects memory contention, memory reclaim will be performed + until the memory usage is within the "soft" limit. 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. This controls the + memory.limit_in_bytes and + memory.soft_limit_in_bytes control group + attributes. For details about these control group attributes + see memory.txt. + + Implies MemoryAccounting=true. + + + + + BlockIOWeight=weight + + Set the default + overall block IO weight for the + executed processes. Takes a single + weight value (between 10 and 1000) to + set the default block IO weight. This + controls the + blkio.weight + control group attribute, which + defaults to 1000. For details about + this control group attribute see + blkio-controller.txt. + + + + BlockIODeviceWeight=device weight + + + Set the per-device overall block IO 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 + blkio.weight_device 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 blkio-controller.txt. + + + + + BlockIOReadBandwidth=device bytes + BlockIOWriteBandwidth=device bytes + + + Set the per-device overall block IO 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 (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This + controls the blkio.read_bps_device and + blkio.write_bps_device control group + attributes. Use this option multiple times to set bandwidth + limits for multiple devices. For details about these control + group attributes see + blkio-controller.txt. + + + + + + DeviceAllow= + + + Control access to specific device nodes by the + executed processes. Takes two space-separated strings: a + device node path (such as /dev/null) + followed by a combination of r, + w, m to control + reading, writing, + or creating of the specific device node by the unit + (mknod), respectively. This controls + the devices.allow and + devices.deny control group + attributes. For details about these control group attributes + see devices.txt. + + + + + DevicePolicy=auto|closed|strict + + + + Control the policy for allowing device access: + + + + + + means to only allow types of access that are + explicitly specified. + + + + + + + in addition allows access to standard pseudo + devices including + /dev/null, + /dev/zero, + /dev/full, + /dev/random, and + /dev/urandom. + + + + + + + + + in addition allows access to all devices if no + explicit DeviceAllow= is present. + This is the default. + + + + + + + + + + + See Also + + systemd1, + systemd.unit5, + systemd.service5, + systemd.slice5, + systemd.scope5, + systemd.socket5, + systemd.mount5, + systemd.swap5, + systemd.directives7, + The documentation for control groups and specific controllers in the Linux kernel: + cgroups.txt, + cpuacct.txt, + memory.txt, + blkio-controller.txt. + + + diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 4294e54a5..d299fc038 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -58,7 +58,7 @@ Description Unit configuration files for services, sockets, - mount points and swap devices share a subset of + mount points, and swap devices share a subset of configuration options which define the execution environment of spawned processes. @@ -69,7 +69,7 @@ files, and systemd.service5, systemd.socket5, - systemd.swap5 + systemd.swap5, and systemd.mount5 for more information on the specific unit @@ -945,124 +945,6 @@ - - CPUShares= - - Assign the specified - overall CPU time shares to the - processes executed. Takes an integer - value. This controls the - cpu.shares control - group attribute, which defaults to - 1024. For details about this control - group attribute see sched-design-CFS.txt. - - - - MemoryLimit= - MemorySoftLimit= - - Limit the overall memory usage - of the executed processes to a certain - size. 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 (to the base - 1024), respectively. This controls the - memory.limit_in_bytes - and - memory.soft_limit_in_bytes - control group attributes. For details - about these control group attributes - see memory.txt. - - - - DeviceAllow= - DeviceDeny= - - Control access to - specific device nodes by the executed processes. Takes two - space-separated strings: a device node - path (such as - /dev/null) - followed by a combination of r, w, m - to control reading, writing, or - creating of the specific device node - by the unit, respectively. This controls the - devices.allow - and - devices.deny - control group attributes. For details - about these control group attributes - see devices.txt. - - - - BlockIOWeight= - - Set the default or - per-device overall block IO weight - value for the executed - processes. Takes either a single - weight value (between 10 and 1000) to - set the default block IO weight, or a - space-separated pair of a file path - and a weight value to specify the - device specific weight value (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 - blkio.weight and - blkio.weight_device - control group attributes, which - default to 1000. Use this option - multiple times to set weights for - multiple devices. For details about - these control group attributes see - blkio-controller.txt. - - - - BlockIOReadBandwidth= - BlockIOWriteBandwidth= - - Set the per-device - overall block IO 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 - 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. - If the bandwidth is suffixed with K, M, - G, or T the specified bandwidth is - parsed as Kilobytes, Megabytes, - Gigabytes, or Terabytes, respectively (Example: - "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 - 5M"). This controls the - blkio.read_bps_device - and - blkio.write_bps_device - control group attributes. Use this - option multiple times to set bandwidth - limits for multiple devices. For - details about these control group - attributes see blkio-controller.txt. - - ReadWriteDirectories= ReadOnlyDirectories= diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index c57f61329..214f40c74 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -73,12 +73,16 @@ which define the execution environment the mount8 binary is executed in, and in - systemd.kill5 - which define the way the processes are - terminated. Note that the User= and Group= options are - not particularly useful for mount units specifying a - Type= option or using configuration - not specified in /etc/fstab; + systemd.kill5, + which define the way the processes are terminated, and + in + systemd.cgroup5, + which configure control group settings for the + processes of the service. Note that the User= and + Group= options are not particularly useful for mount + units specifying a Type= option or + using configuration not specified in + /etc/fstab; mount8 will refuse options that aren't listed in /etc/fstab if it is not run as @@ -298,6 +302,7 @@ systemd.unit5, systemd.exec5, systemd.kill5, + systemd.cgroup5, systemd.service5, systemd.device5, proc5, diff --git a/man/systemd.scope.xml b/man/systemd.scope.xml new file mode 100644 index 000000000..31f2d6f5a --- /dev/null +++ b/man/systemd.scope.xml @@ -0,0 +1,100 @@ + + + + + + + + + systemd.scope + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.scope + 5 + + + + systemd.scope + Scope unit configuration + + + + scope.scope + + + + Description + + A unit configuration file whose name ends in + .scope encodes information about a unit created + by systemd to encapsulate processes launched not by systemd + itself. This management is performed by creating a node in the + control group tree. Processes are moved into the scope by means + of the DBus API. + systemd-run can be + used to easily launch a command in a new scope unit. + + See + systemd.unit5 + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + scope specific configuration options are configured in + the [Scope] section. Currently, only generic cgroup settings + as described in + systemd.cgroup7 are allowed. + + + Unless DefaultDependencies=false + is used, scope units will implicitly have dependencies of + type Conflicts= and + Before= on + shutdown.target. These ensure + that scope units are removed prior to system + shutdown. Only scope units involved with early boot or + late system shutdown should disable this option. + + + + + See Also + + systemd1, + systemd-run1, + systemd.unit5, + systemd.cgroup5, + systemd.service5, + systemd.directives7. + + + + diff --git a/man/systemd.service.xml b/man/systemd.service.xml index abe3a8d67..238a49a25 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -73,9 +73,12 @@ systemd.exec5, which define the execution environment the commands are executed in, and in - systemd.kill5 + systemd.kill5, which define the way the processes of the service are - terminated. + terminated, and in + systemd.cgroup5, + which configure control group settings for the + processes of the service. Unless DefaultDependencies= is set to , service units will @@ -994,6 +997,7 @@ systemctl8, systemd.unit5, systemd.exec5, + systemd.cgroup5, systemd.kill5, systemd.directives7 diff --git a/man/systemd.slice.xml b/man/systemd.slice.xml new file mode 100644 index 000000000..537692168 --- /dev/null +++ b/man/systemd.slice.xml @@ -0,0 +1,99 @@ + + + + + + + + + systemd.slice + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.slice + 5 + + + + systemd.slice + Slice unit configuration + + + + slice.slice + + + + Description + + A unit configuration file whose name ends in + .slice encodes information about a slice + created by systemd to manage resources used by a certain group of + processes. This management is performed by creating a node in the + control group tree. Those processes are part of different units, + usually .service units (see + systemd.unit5). + + + See + systemd.unit5 + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + slice specific configuration options are configured in + the [Slice] section. Currently, only generic cgroup settings + as described in + systemd.cgroup7 are allowed. + + + Unless DefaultDependencies=false + is used, slice units will implicitly have dependencies of + type Conflicts= and + Before= on + shutdown.target. These ensure + that slice units are removed prior to system + shutdown. Only slice units involved with early boot or + late system shutdown should disable this option. + + + + + See Also + + systemd1, + systemd.unit5, + systemd.cgroup5, + systemd.service5, + systemd.directives7. + + + + diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 1b899c46a..fad5c2b8c 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -77,9 +77,12 @@ and commands are executed in, and in - systemd.kill5 + systemd.kill5, which define the way the processes are - terminated. + terminated, and in + systemd.cgroup5, + which configure control group settings for the + processes of the service. For each socket file a matching service file (see @@ -709,6 +712,7 @@ systemd.unit5, systemd.exec5, systemd.kill5, + systemd.cgroup5, systemd.service5, systemd.directives7 diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml index d931c46e8..5e339ea18 100644 --- a/man/systemd.swap.xml +++ b/man/systemd.swap.xml @@ -73,9 +73,12 @@ which define the execution environment the swapon8 binary is executed in, and in - systemd.kill5 + systemd.kill5, which define the way the processes are - terminated. + terminated, and in + systemd.cgroup5, + which configure control group settings for the + processes of the service. Swap units must be named after the devices or files they control. Example: the swap device @@ -203,6 +206,7 @@ systemd.unit5, systemd.exec5, systemd.kill5, + systemd.cgroup5, systemd.device5, systemd.mount5, swapon8,