man/systemd-oomd.service.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-oomd.service" conditional='ENABLE_OOMD'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-oomd.service</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-oomd.service</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-oomd.service</refname>
  21     <refname>systemd-oomd</refname>
  22     <refpurpose>A userspace out-of-memory (OOM) killer</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para><filename>systemd-oomd.service</filename></para>
  27     <para><filename>/usr/lib/systemd/systemd-oomd</filename></para>
  28   </refsynopsisdiv>
  29
  30   <refsect1>
  31     <title>Description</title>
  32
  33     <para><command>systemd-oomd</command> is a system service that uses cgroups-v2 and pressure stall
  34     information (PSI) to monitor and take corrective action before an OOM occurs in the kernel space.</para>
  35
  36     <para>You can enable monitoring and actions on units by setting <varname>ManagedOOMSwap=</varname> and
  37     <varname>ManagedOOMMemoryPressure=</varname> in the unit configuration, see
  38     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  39     <command>systemd-oomd</command> retrieves information about such units from
  40     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  41     when it starts and watches for subsequent changes.</para>
  42
  43     <para>Cgroups of units with <varname>ManagedOOMSwap=</varname> or
  44     <varname>ManagedOOMMemoryPressure=</varname> set to <option>kill</option> will be monitored.
  45     <command>systemd-oomd</command> periodically polls PSI statistics for the system and those cgroups to
  46     decide when to take action. If the configured limits are exceeded, <command>systemd-oomd</command> will
  47     select a cgroup to terminate, and send <constant>SIGKILL</constant> to all processes in it. Note that
  48     only descendant cgroups are eligible candidates for killing; the unit with its property set to
  49     <option>kill</option> is not a candidate (unless one of its ancestors set their property to
  50     <option>kill</option>). Also only leaf cgroups and cgroups with <filename>memory.oom.group</filename> set
  51     to <constant>1</constant> are eligible candidates; see <varname>OOMPolicy=</varname> in
  52     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  53     </para>
  54
  55     <para><citerefentry><refentrytitle>oomctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> can
  56     be used to list monitored cgroups and pressure information.</para>
  57
  58     <para>See <citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  59     for more information about the configuration of this service.</para>
  60   </refsect1>
  61
  62   <refsect1>
  63     <title>System requirements and configuration</title>
  64
  65     <para>The system must be running systemd with a full unified cgroup hierarchy for the expected cgroups-v2 features.
  66     Furthermore, memory accounting must be turned on for all units monitored by <command>systemd-oomd</command>.
  67     The easiest way to turn on memory accounting is by ensuring the value for <varname>DefaultMemoryAccounting=</varname>
  68     is set to <constant>true</constant> in
  69     <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  70
  71     <para>The kernel must be compiled with PSI support. This is available in Linux 4.20 and above.</para>
  72
  73     <para>It is highly recommended for the system to have swap enabled for <command>systemd-oomd</command> to
  74     function optimally. With swap enabled, the system spends enough time swapping pages to let
  75     <command>systemd-oomd</command> react.  Without swap, the system enters a livelocked state much more
  76     quickly and may prevent <command>systemd-oomd</command> from responding in a reasonable amount of
  77     time. See <ulink url="https://chrisdown.name/2018/01/02/in-defence-of-swap.html">"In defence of swap:
  78     common misconceptions"</ulink> for more details on swap. Any swap-based actions on systems without swap
  79     will be ignored. While <command>systemd-oomd</command> can perform pressure-based actions on such a
  80     system, the pressure increases will be more abrupt and may require more tuning to get the desired
  81     thresholds and behavior.</para>
  82
  83     <para>Be aware that if you intend to enable monitoring and actions on <filename>user.slice</filename>,
  84     <filename>user-$UID.slice</filename>, or their ancestor cgroups, it is highly recommended that your
  85     programs be managed by the systemd user manager to prevent running too many processes under the same
  86     session scope (and thus avoid a situation where memory intensive tasks trigger
  87     <command>systemd-oomd</command> to kill everything under the cgroup). If you're using a desktop
  88     environment like GNOME or KDE, it already spawns many session components with the systemd user manager.
  89     </para>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Usage Recommendations</title>
  94
  95     <para><varname>ManagedOOMSwap=</varname> works with the system-wide swap values, so setting it on the root slice
  96     <filename>-.slice</filename>, and allowing all descendant cgroups to be eligible candidates may make the most
  97     sense.</para>
  98
  99     <para><varname>ManagedOOMMemoryPressure=</varname> tends to work better on the cgroups below the root
 100     slice. For units which tend to have processes that are less latency sensitive (e.g.
 101     <filename>system.slice</filename>), a higher limit like the default of 60% may be acceptable, as those
 102     processes can usually ride out slowdowns caused by lack of memory without serious consequences. However,
 103     something like <filename>user@$UID.service</filename> may prefer a much lower value like 40%.</para>
 104   </refsect1>
 105
 106   <refsect1>
 107     <title>Options</title>
 108
 109     <variablelist>
 110       <varlistentry>
 111         <term><option>--dry-run</option></term>
 112
 113         <listitem><para>Do a dry run of <command>systemd-oomd</command>: when a kill is triggered, print it
 114         to the log instead of killing the cgroup.</para>
 115
 116         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 117       </varlistentry>
 118     </variablelist>
 119
 120     <xi:include href="standard-options.xml" xpointer="help" />
 121     <xi:include href="standard-options.xml" xpointer="version" />
 122   </refsect1>
 123
 124   <refsect1>
 125     <title>See Also</title>
 126     <para><simplelist type="inline">
 127       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 128       <member><citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 129       <member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 130       <member><citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 131       <member><citerefentry><refentrytitle>oomctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 132     </simplelist></para>
 133   </refsect1>
 134 </refentry>