From cf3e57884e8a61548684df44dab3f44b5a7f1748 Mon Sep 17 00:00:00 2001 From: Anita Zhang Date: Wed, 9 Sep 2020 01:04:36 -0700 Subject: [PATCH] man: document systemd-oomd and related items --- man/oomctl.xml | 86 ++++++++++++++++++++++++++++ man/oomd.conf.xml | 88 ++++++++++++++++++++++++++++ man/rules/meson.build | 3 + man/systemd-oomd.service.xml | 98 ++++++++++++++++++++++++++++++++ man/systemd.resource-control.xml | 44 ++++++++++++++ 5 files changed, 319 insertions(+) create mode 100644 man/oomctl.xml create mode 100644 man/oomd.conf.xml create mode 100644 man/systemd-oomd.service.xml diff --git a/man/oomctl.xml b/man/oomctl.xml new file mode 100644 index 00000000000..10633b92fca --- /dev/null +++ b/man/oomctl.xml @@ -0,0 +1,86 @@ + + + + + + + + oomctl + systemd + + + + oomctl + 1 + + + + oomctl + Analyze the state stored in systemd-oomd + + + + + oomctl + OPTIONS + COMMAND + + + + + Description + + oomctl may be used to get information about the various contexts read in by + the systemd1 userspace + out-of-memory (OOM) killer, + systemd-oomd8. + + + + + Commands + + The following commands are understood: + + + + dump + + Show the current state of the cgroup(s) and system context(s) stored by + systemd-oomd. + + + + + + + + Options + + The following options are understood: + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code otherwise. + + + + See Also + + systemd1, + systemd-oomd.service8, + oomd.conf5 + + + + diff --git a/man/oomd.conf.xml b/man/oomd.conf.xml new file mode 100644 index 00000000000..e6be947c5bc --- /dev/null +++ b/man/oomd.conf.xml @@ -0,0 +1,88 @@ + + + + + + + oomd.conf + systemd + + + + oomd.conf + 5 + + + + oomd.conf + oomd.conf.d + Global systemd-oomd configuration files + + + + /etc/systemd/oomd.conf + /etc/systemd/oomd.conf.d/*.conf + /usr/lib/systemd/oomd.conf.d/*.conf + + + + Description + + These files configure the various parameters of the + systemd1 userspace + out-of-memory (OOM) killer, + systemd-oomd.service8. + See systemd.syntax7 + for a general description of the syntax. + + + + + + + [OOM] Section Options + + The following options are available in the [OOM] section: + + + + SwapUsedLimitPercent= + + Sets the limit for swap usage on the system before systemd-oomd will + take action. If the percentage of swap used on the system is more than what is defined here, + systemd-oomd will act on eligible descendant cgroups, starting from the ones with the + highest swap usage to the lowest swap usage. Which cgroups are monitored and what + action gets taken depends on what the unit has configured for ManagedOOMSwap=. + Takes a percentage value between 0% and 100%, inclusive. Defaults to 90%. + + + + DefaultMemoryPressureLimitPercent= + + Sets the limit for memory pressure on the unit's cgroup before systemd-oomd + will take action. A unit can override this value with ManagedOOMMemoryPressureLimitPercent=. + The memory pressure for this property represents the fraction of time in a 10 second window in which all tasks + in the cgroup were delayed. For each monitored cgroup, if the memory pressure on that cgroup exceeds the + limit set for more than 30 seconds, systemd-oomd will act on eligible descendant cgroups, + starting from the ones with the most reclaim activity to the least reclaim activity. Which cgroups are + monitored and what action gets taken depends on what the unit has configured for + ManagedOOMMemoryPressure=. Takes a percentage value between 0% and 100%, inclusive. + Defaults to 60%. + + + + + + + See Also + + systemd1, + systemd.resource-control5, + systemd-oomd.service8, + oomctl1 + + + + diff --git a/man/rules/meson.build b/man/rules/meson.build index 00cd57420e8..806561a4125 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -45,6 +45,8 @@ manpages = [ ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'], ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], + ['oomctl', '1', [], 'ENABLE_OOMD'], + ['oomd.conf', '5', ['oomd.conf.d'], 'ENABLE_OOMD'], ['org.freedesktop.LogControl1', '5', [], ''], ['org.freedesktop.home1', '5', [], 'ENABLE_HOMED'], ['org.freedesktop.hostname1', '5', [], 'ENABLE_HOSTNAMED'], @@ -907,6 +909,7 @@ manpages = [ ['systemd-networkd.service', '8', ['systemd-networkd'], 'ENABLE_NETWORKD'], ['systemd-notify', '1', [], ''], ['systemd-nspawn', '1', [], ''], + ['systemd-oomd.service', '8', ['systemd-oomd'], 'ENABLE_OOMD'], ['systemd-path', '1', [], ''], ['systemd-portabled.service', '8', ['systemd-portabled'], 'ENABLE_PORTABLED'], ['systemd-pstore.service', '8', ['systemd-pstore'], 'ENABLE_PSTORE'], diff --git a/man/systemd-oomd.service.xml b/man/systemd-oomd.service.xml new file mode 100644 index 00000000000..9d72373d1ef --- /dev/null +++ b/man/systemd-oomd.service.xml @@ -0,0 +1,98 @@ + + + + + + + + systemd-oomd.service + systemd + + + + systemd-oomd.service + 8 + + + + systemd-oomd.service + systemd-oomd + A userspace out-of-memory (OOM) killer + + + + systemd-oomd.service + /usr/lib/systemd/systemd-oomd + + + + Description + + systemd-oomd is a system service that uses cgroups-v2 and pressure stall information (PSI) + to monitor and take action on processes before an OOM occurs in kernel space. + + You can enable monitoring and actions on units by setting ManagedOOMSwap= and/or + ManagedOOMMemoryPressure= to the appropriate value. systemd-oomd will + periodically poll enabled units' cgroup data to detect when corrective action needs to occur. When an action needs + to happen, it will only be performed on the descendant cgroups of the enabled units. More precisely, only cgroups with + memory.oom.group set to 1 and leaf cgroup nodes are eligible candidates. + Action will be taken recursively on all of the processes under the chosen candidate. + + See + oomd.conf5 + for more information about the configuration of this service. + + + + Setup Information + + The system must be running systemd with a full unified cgroup hierarchy for the expected cgroups-v2 features. + Furthermore, resource accounting must be turned on for all units monitored by systemd-oomd. + The easiest way to turn on resource accounting is by ensuring the values for DefaultCPUAccounting, + DefaultIOAccounting, DefaultMemoryAccounting, and + DefaultTasksAccounting are set to true in + systemd-system.conf5. + + You will need a kernel compiled with PSI support. This is available in Linux 4.20 and above. + + The system must also have swap enabled for systemd-oomd to function correctly. With swap + enabled, the system spends enough time swapping pages to let systemd-oomd react. + Without swap, the system enters a livelocked state much more quickly and may prevent systemd-oomd + from responding in a reasonable amount of time. See + "In defence of swap: common misconceptions" + for more details on swap. + + Be aware that if you intend to enable monitoring and actions on user.slice, + user-$UID.slice, or their ancestor cgroups, it is highly recommended that your programs be + managed by the systemd user manager to prevent running too many processes under the same session scope (and thus + avoid a situation where memory intensive tasks trigger systemd-oomd to kill everything under the + cgroup). If you're using a desktop environment like GNOME, it already spawns many session components with the + systemd user manager. + + + + Usage Recommendations + + ManagedOOMSwap= works with the system-wide swap values, so setting it on the root slice + -.slice, and allowing all descendant cgroups to be eligible candidates may make the most + sense. + + ManagedOOMMemoryPressure= tends to work better on the cgroups below the root slice + -.slice. For units which tend to have processes that are less latency sensitive (e.g. + system.slice), a higher limit like the default of 60% may be acceptable, as those processes + can usually ride out slowdowns caused by lack of memory without serious consequences. However, something like + user@$UID.service may prefer a much lower value like 40%. + + + + See Also + + systemd1, + systemd-system.conf5, + systemd.resource-control5, + oomd.conf5, + oomctl1 + + + diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index d72f9048e7c..b40fa861454 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -869,6 +869,49 @@ DeviceAllow=/dev/loop-control + + + ManagedOOMSwap=auto|kill + ManagedOOMMemoryPressure=auto|kill + + + Specifies how + systemd-oomd.service8 + will act on this unit's cgroups. Defaults to . + + When set to , systemd-oomd will actively monitor this unit's + cgroup metrics to decide whether it needs to act. If the cgroup passes the limits set by + oomd.conf5 or its + overrides, systemd-oomd will send a SIGKILL to all of the processes + under the chosen candidate cgroup. Note that only descendant cgroups can be eligible candidates for killing; + the unit that set its property to is not a candidate (unless one of its ancestors set + their property to ). You can find more details on candidates and kill behavior at + systemd-oomd.service8 + and oomd.conf5. Setting + either of these properties to will also automatically acquire + After= and Wants= dependencies on + systemd-oomd.service unless DefaultDependencies=no. + + + When set to , systemd-oomd will not actively use this cgroup's + data for monitoring and detection. However, if an ancestor cgroup has one of these properties set to + , a unit with can still be an eligible candidate for + systemd-oomd to act on. + + + + + ManagedOOMMemoryPressureLimitPercent= + + + Overrides the default memory pressure limit set by + oomd.conf5 for this unit + (cgroup). Takes a percentage value between 0% and 100%, inclusive. This property is ignored unless + ManagedOOMMemoryPressure=. Defaults to 0%, which means use the + default set by oomd.conf5. + + + @@ -1030,6 +1073,7 @@ DeviceAllow=/dev/loop-control systemd.exec5, systemd.directives7, systemd.special7, + systemd-oomd.service8, The documentation for control groups and specific controllers in the Linux kernel: Control Groups v2.