Debian Codegraph @

upstream/debian-unstable/man5/oomd.conf.5

raw
1 '\" t
2 .TH "OOMD\&.CONF" "5" "" "systemd 261~rc3" "oomd.conf"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 oomd.conf, oomd.conf.d \- Global \fBsystemd\-oomd\fR configuration files
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /etc/systemd/oomd\&.conf
28 .RE
29 .RS 4
30 /run/systemd/oomd\&.conf
31 .RE
32 .RS 4
33 /usr/local/lib/systemd/oomd\&.conf
34 .RE
35 .RS 4
36 /usr/lib/systemd/oomd\&.conf
37 .RE
38 .RS 4
39 /etc/systemd/oomd\&.conf\&.d/*\&.conf
40 .RE
41 .RS 4
42 /run/systemd/oomd\&.conf\&.d/*\&.conf
43 .RE
44 .RS 4
45 /usr/local/lib/systemd/oomd\&.conf\&.d/*\&.conf
46 .RE
47 .RS 4
48 /usr/lib/systemd/oomd\&.conf\&.d/*\&.conf
49 .RE
50 .SH "DESCRIPTION"
51 .PP
52 These files configure the various parameters of the
53 \fBsystemd\fR(1)
54 userspace out\-of\-memory (OOM) killer,
55 \fBsystemd-oomd.service\fR(8)\&. See
56 \fBsystemd.syntax\fR(7)
57 for a general description of the syntax\&.
58 .SH "CONFIGURATION DIRECTORIES AND PRECEDENCE"
59 .PP
60 The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used:
61 /etc/systemd/,
62 /run/systemd/,
63 /usr/local/lib/systemd/
64 \&\s-2\u[1]\d\s+2,
65 /usr/lib/systemd/\&. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can also be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in
66 /etc/
67 if it is shipped under
68 /usr/), however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&.
69 .PP
70 In addition to the main configuration file, drop\-in configuration snippets are read from
71 /usr/lib/systemd/*\&.conf\&.d/,
72 /usr/local/lib/systemd/*\&.conf\&.d/, and
73 /etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the
74 *\&.conf\&.d/
75 configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&.
76 .PP
77 When packages need to customize the configuration, they can install drop\-ins under
78 /usr/\&. Files in
79 /etc/
80 are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering\&. This also defines a concept of drop\-in priorities to allow OS vendors to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. It is recommended to use the range 10\-40 for drop\-ins in
81 /usr/
82 and the range 60\-90 for drop\-ins in
83 /etc/
84 and
85 /run/, to make sure that local and transient drop\-ins take priority over drop\-ins shipped by the OS vendor\&.
86 .PP
87 To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to
88 /dev/null
89 in the configuration directory in
90 /etc/, with the same filename as the vendor configuration file\&.
91 .SH "PREKILL EVENT"
92 .PP
93 \fBsystemd\-oomd\fR
94 supports notifying external components before killing a control group\&. This is done by sending a notification over varlink to all sockets found in
95 /run/systemd/oomd\&.prekill\&.hook/
96 folder\&. Each socket should implement the
97 \fBio\&.systemd\&.oom\&.Prekill\fR
98 interface\&. The notification contains the control group path to allow the hook to identify which control group is being killed\&. This allows external components to perform any necessary cleanup or logging before the control group is terminated\&. The hook is not intended as a way to avoid the kill, but rather as a notification mechanism\&. Note that this is a privileged option as, even if it has a timeout, is synchronous and delays the kill, so use with care\&. The typically preferable mechanism to process memory pressure is to do what
99 \m[blue]\fBResource Pressure Handling\fR\m[]\&\s-2\u[2]\d\s+2
100 describes which is unprivileged, asynchronous and does not delay the kill\&.
101 .SH "OOM RULESETS"
102 .PP
103 \fBsystemd\-oomd\fR
104 supports custom rulesets that define conditions and actions for OOM handling on a per\-unit basis\&. Ruleset files use the
105 \&.oomrule
106 extension and are loaded from
107 /etc/systemd/oomd/rules\&.d/,
108 /run/systemd/oomd/rules\&.d/,
109 /usr/local/lib/systemd/oomd/rules\&.d/, and
110 /usr/lib/systemd/oomd/rules\&.d/\&. Units opt into rulesets via the
111 \fIOOMRules=\fR
112 setting in
113 \fBsystemd.resource-control\fR(5), which takes a space\-separated list of ruleset names (the file name without the
114 \&.oomrule
115 extension)\&.
116 .PP
117 Each ruleset file contains a
118 "[Rule]"
119 section with the following options\&. At least one of
120 \fIMemoryPressureAbove=\fR
121 or
122 \fISwapUsageMax=\fR
123 must be configured; rulesets with no conditions are ignored\&. If both are set, the conditions are combined with AND, i\&.e\&. the action is only triggered when both thresholds are exceeded simultaneously\&.
124 .PP
125 \fIMemoryPressureAbove=\fR
126 .RS 4
127 Sets the memory pressure threshold above which the rule\*(Aqs action will be triggered\&. The memory pressure represents the fraction of time in a 10 second window in which all tasks in the control group were delayed (PSI
128 "full avg10")\&. Takes a value specified in percent (when suffixed with
129 "%"), permille ("‰") or permyriad ("‱"), between 0% and 100%, inclusive\&. If unset, this condition is not evaluated\&. A value of
130 "100%"
131 can never be exceeded and is therefore rejected with a warning; a value of
132 "0%"
133 makes the condition true on any observed pressure, which is usually not useful\&.
134 .sp
135 Added in version 261\&.
136 .RE
137 .PP
138 \fISwapUsageMax=\fR
139 .RS 4
140 Sets the system\-wide swap usage threshold above which the rule\*(Aqs action will be triggered\&. Takes a value specified in percent (when suffixed with
141 "%"), permille ("‰") or permyriad ("‱"), between 0% and 100%, inclusive\&. If unset, this condition is not evaluated\&. A value of
142 "100%"
143 can never be exceeded and is therefore rejected with a warning; a value of
144 "0%"
145 fires as soon as any swap is in use, which is usually not useful\&.
146 .sp
147 Added in version 261\&.
148 .RE
149 .PP
150 \fIAction=\fR
151 .RS 4
152 Specifies the action to take when the rule\*(Aqs conditions are met\&. Takes one of
153 "kill\-all",
154 "kill\-by\-pgscan", or
155 "kill\-by\-swap"\&. This setting is mandatory; rulesets without
156 \fIAction=\fR
157 are ignored\&.
158 .sp
159 .RS 4
160 .ie n \{\
161 \h'-04'\(bu\h'+03'\c
162 .\}
163 .el \{\
164 .sp -1
165 .IP \(bu 2.3
166 .\}
167 "kill\-all"
168 sends
169 \fBSIGKILL\fR
170 to every process in the unit\*(Aqs cgroup hierarchy, including any descendant cgroups\&.
171 .RE
172 .sp
173 .RS 4
174 .ie n \{\
175 \h'-04'\(bu\h'+03'\c
176 .\}
177 .el \{\
178 .sp -1
179 .IP \(bu 2.3
180 .\}
181 "kill\-by\-pgscan"
182 selects and kills the descendant cgroup with the highest recent page scan (reclaim) rate\&.
183 .RE
184 .sp
185 .RS 4
186 .ie n \{\
187 \h'-04'\(bu\h'+03'\c
188 .\}
189 .el \{\
190 .sp -1
191 .IP \(bu 2.3
192 .\}
193 "kill\-by\-swap"
194 selects and kills the descendant cgroup with the highest swap usage\&.
195 .RE
196 .sp
197 Added in version 261\&.
198 .RE
199 .PP
200 \fILastingSec=\fR
201 .RS 4
202 Sets the duration the conditions must be continuously met before the action is taken\&. Takes a time span value, see
203 \fBsystemd.time\fR(7)
204 for details on the permitted syntax\&. Defaults to 0, i\&.e\&. the action is taken immediately when the conditions are met\&.
205 .sp
206 Added in version 261\&.
207 .RE
208 .SH "[OOM] SECTION OPTIONS"
209 .PP
210 The following options are available in the [OOM] section:
211 .PP
212 \fISwapUsedLimit=\fR
213 .RS 4
214 Sets the limit for memory and swap usage on the system before
215 \fBsystemd\-oomd\fR
216 will take action\&. If the fraction of memory used and the fraction of swap used on the system are both more than what is defined here,
217 \fBsystemd\-oomd\fR
218 will act on eligible descendant control groups with swap usage greater than 5% of total swap, starting from the ones with the highest swap usage\&. Which control groups are monitored and what action gets taken depends on what the unit has configured for
219 \fIManagedOOMSwap=\fR\&. Takes a value specified in percent (when suffixed with "%"), permille ("‰") or permyriad ("‱"), between 0% and 100%, inclusive\&. Defaults to 90%\&.
220 .sp
221 Added in version 247\&.
222 .RE
223 .PP
224 \fIDefaultMemoryPressureLimit=\fR
225 .RS 4
226 Sets the limit for memory pressure on the unit\*(Aqs control group before
227 \fBsystemd\-oomd\fR
228 will take action\&. A unit can override this value with
229 \fIManagedOOMMemoryPressureLimit=\fR\&. The memory pressure for this property represents the fraction of time in a 10 second window in which all tasks in the control group were delayed\&. For each monitored control group, if the memory pressure on that control group exceeds the limit set for longer than the duration set by
230 \fIDefaultMemoryPressureDurationSec=\fR,
231 \fBsystemd\-oomd\fR
232 will act on eligible descendant control groups, starting from the ones with the most reclaim activity to the least reclaim activity\&. Which control groups are monitored and what action gets taken depends on what the unit has configured for
233 \fIManagedOOMMemoryPressure=\fR\&. Takes a fraction specified in the same way as
234 \fISwapUsedLimit=\fR
235 above\&. Defaults to 60%\&.
236 .sp
237 Added in version 247\&.
238 .RE
239 .PP
240 \fIDefaultMemoryPressureDurationSec=\fR
241 .RS 4
242 Sets the amount of time a unit\*(Aqs control group needs to have exceeded memory pressure limits before
243 \fBsystemd\-oomd\fR
244 will take action\&. A unit can override this value with
245 \fIManagedOOMMemoryPressureDurationSec=\fR\&. Memory pressure limits are defined by
246 \fIDefaultMemoryPressureLimit=\fR
247 and
248 \fIManagedOOMMemoryPressureLimit=\fR\&. Must be set to 0, or at least 1 second\&. Defaults to 30 seconds when unset or 0\&.
249 .sp
250 Added in version 248\&.
251 .RE
252 .PP
253 \fIPrekillHookTimeoutSec=\fR
254 .RS 4
255 Sets the amount of time
256 \fBsystemd\-oomd\fR
257 will wait for pre\-kill hooks to complete, before proceeding with the control group termination\&. Pre\-kill hooks work by placing varlink socket to
258 /run/systemd/oomd\&.prekill\&.hook/
259 folder\&. Each socket should implement interface for notification to work\&.
260 \fBsystemd\-oomd\fR
261 sends a notification before killing a control group for each discovered socket\&. The timeout is intended to be global and not per hook\&. If all hooks return earlier, the kill is performed as soon as possible\&. The timeout must be at least 1s\&. Defaults to 0, which means
262 \fBsystemd\-oomd\fR
263 will not wait and no notifications will be sent\&.
264 .sp
265 Added in version 260\&.
266 .RE
267 .SH "SEE ALSO"
268 .PP
269 \fBsystemd\fR(1), \fBsystemd.resource-control\fR(5), \fBsystemd-oomd.service\fR(8), \fBoomctl\fR(1)
270 .SH "NOTES"
271 .IP " 1." 4
272 💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If
273 /usr/local/
274 is a separate partition, it may not be available during early boot, and must not be used for configuration.
275 .IP " 2." 4
276 Resource Pressure Handling
277 .RS 4
278 \%https://systemd.io/PRESSURE
279 .RE