path: root/system/earlyoom/earlyoom.8

.TH "earlyoom" "8" "August 2023" "1.7" "Linux System Administrator's Manual"
.hy
.SH NAME
.PP
earlyoom - Early OOM Daemon
.SH SYNOPSIS
.PP
\f[B]earlyoom\f[R] [\f[B]OPTION\f[R]]\&...
.SH DESCRIPTION
.PP
The oom-killer generally has a bad reputation among Linux users.
One may have to sit in front of an unresponsive system, listening to the
grinding disk for minutes, and press the reset button to quickly get
back to what one was doing after running out of patience.
.PP
\f[B]earlyoom\f[R] checks the amount of available memory and free swap
up to 10 times a second (less often if there is a lot of free memory).
If \f[B]both\f[R] memory \f[B]and\f[R] swap are below 10%, it will kill
the largest process (highest \f[C]oom_score\f[R]).
The percentage value is configurable via command line arguments.
.PP
If there is a failure when trying to kill a process, \f[B]earlyoom\f[R]
sleeps for 1 second to limit log spam due to recurring errors.
.SH OPTIONS
.SS -m PERCENT[,KILL_PERCENT]
.PP
set available memory minimum to PERCENT of total (default 10 %).
.PP
earlyoom starts sending SIGTERM once \f[B]both\f[R] memory \f[B]and\f[R]
swap are below their respective PERCENT setting.
It sends SIGKILL once \f[B]both\f[R] are below their respective
KILL_PERCENT setting (default PERCENT/2).
.PP
Use the same value for PERCENT and KILL_PERCENT if you always want to
use SIGKILL.
.PP
Examples:
.IP
.nf
\f[C]
earlyoom              # sets PERCENT=10, KILL_PERCENT=5
earlyoom -m 30        # sets PERCENT=30, KILL_PERCENT=15
earlyoom -m 20,18     # sets PERCENT=20, KILL_PERCENT=18
\f[R]
.fi
.SS -s PERCENT[,KILL_PERCENT]
.PP
set free swap minimum to PERCENT of total (default 10 %).
Send SIGKILL if at or below KILL_PERCENT (default PERCENT/2), otherwise
SIGTERM.
.PP
You can use \f[C]-s 100\f[R] to have earlyoom effectively ignore swap
usage: Processes are killed once available memory drops below the
configured minimum, no matter how much swap is free.
.PP
Use the same value for PERCENT and KILL_PERCENT if you always want to
use SIGKILL.
.SS -M SIZE[,KILL_SIZE]
.PP
As an alternative to specifying a percentage of total memory,
\f[C]-M\f[R] sets the available memory minimum to SIZE KiB.
The value is internally converted to a percentage.
If you pass both \f[C]-M\f[R] and \f[C]-m\f[R], the lower value is used.
Example: Reserve 10% of RAM but at most 1 GiB:
.IP
.nf
\f[C]
earlyoom -m 10 -M 1048576
\f[R]
.fi
.PP
earlyoom sends SIGKILL if at or below KILL_SIZE (default SIZE/2),
otherwise SIGTERM.
.SS -S SIZE[,KILL_SIZE]
.PP
As an alternative to specifying a percentage of total swap, \f[C]-S\f[R]
sets the free swap minimum to SIZE KiB.
The value is internally converted to a percentage.
If you pass both \f[C]-S\f[R] and \f[C]-s\f[R], the lower value is used.
.PP
Send SIGKILL if at or below KILL_SIZE (default SIZE/2), otherwise
SIGTERM.
.SS -k
.PP
removed in earlyoom v1.2, ignored for compatibility
.SS -i
.PP
removed in earlyoom v1.7, ignored for compatibility
.SS -d
.PP
enable debugging messages
.SS -v
.PP
print version information and exit
.SS -r INTERVAL
.PP
Time between printing periodic memory reports, in seconds (default 1.0).
A memory report looks like this:
.IP
.nf
\f[C]
mem avail: 21790 of 23909 MiB (91.14%), swap free:    0 of    0 MiB ( 0.00%)
\f[R]
.fi
.PP
Set to 3600 to print a report every hour, to 86400 to print once a day
etc.
Set to 0 to disable printing periodic memory reports.
Free memory monitoring and low-memory killing runs independently of this
option at an adaptive poll rate that only depends on free memory.
Due to the adaptive poll rate, when there is a lot of free memory, the
actual interval may be up to 1 second longer than the setting.
.SS -p
.PP
Increase earlyoom\[cq]s priority: set niceness of earlyoom to -20 and
oom_score_adj to -100.
.PP
When earlyoom is run through its default systemd service, the
\f[C]-p\f[R] switch doesn\[cq]t work.
To achieve the same effect, enter the following three lines into
\f[C]sudo systemctl edit earlyoom\f[R]:
.IP
.nf
\f[C]
[Service]
OOMScoreAdjust=-100
Nice=-20
\f[R]
.fi
.SS -n
.PP
Enable notifications via d-bus.
.PP
To actually see the notifications in your GUI session, you need to have
systembus-notify (https://github.com/rfjakob/systembus-notify) running
as your user.
.SS -N /PATH/TO/SCRIPT
.PP
Run the given script for each process killed.
Must be an absolute path.
.PP
Within the script, information about the killed process can be obtained
via the following environment variables:
.IP
.nf
\f[C]
EARLYOOM_PID     Process PID
EARLYOOM_NAME    Process name truncated to 16 bytes (as reported in /proc/PID/comm)
EARLYOOM_UID     UID of the user running the process
\f[R]
.fi
.PP
WARNING: \f[C]EARLYOOM_NAME\f[R] can contain spaces, newlines, special
characters and is controlled by the user, or it can be empty!
Make sure that your notification script can handle that!
.SS -g
.PP
Kill all processes that have same process group id (PGID) as the process
with excessive memory usage.
.PP
For example, with this flag turned on, the whole application will be
killed when one of its subprocess consumes too much memory (as long as
they all have the same PGID, of course).
.PP
Enable this flag when completely cleaning up the \[lq]entire
application\[rq] is more desirable, and you are sure that the
application puts all its processes in the same PGID.
.PP
Note that some desktop environments (GNOME, for example) put all desktop
application in the same process group as \f[C]gnome-shell\f[R].
earlyoom might kill all such processes including \f[C]gnome-shell\f[R]
when this flag is turned on.
.PP
Be sure to check how your environment behaves beforehand.
Use
.IP
.nf
\f[C]
pstree -gT
\f[R]
.fi
.PP
to show all processes with the PGID in brackets.
.SS --prefer REGEX
.PP
prefer killing processes matching REGEX (adds 300 to oom_score)
.SS --avoid REGEX
.PP
avoid killing processes matching REGEX (subtracts 300 from oom_score)
.SS --ignore REGEX
.PP
ignore processes matching REGEX.
.PP
Unlike the --avoid option, this option disables any potential killing of
the matched processes that might have occurred due to the processes
attaining a high oom_score.
.PP
Use this option with caution as other processes might be sacrificed in
place of the ignored processes when earlyoom determines to kill
processes.
.SS --dryrun
.PP
dry run (do not kill any processes)
.SS -h, --help
.PP
this help text
.SH EXIT STATUS
.PP
0: Successful program execution.
.PP
1: Other error - inspect message for details
.PP
2: Switch conflict.
.PP
4: Could not cd to /proc
.PP
5: Could not open proc
.PP
7: Could not open /proc/sysrq-trigger
.PP
13: Unknown options.
.PP
14: Wrong parameters for other options.
.PP
15: Wrong parameters for memory threshold.
.PP
16: Wrong parameters for swap threshold.
.PP
102: Could not open /proc/meminfo
.PP
103: Could not read /proc/meminfo
.PP
104: Could not find a specific entry in /proc/meminfo
.PP
105: Could not convert number when parse the contents of /proc/meminfo
.SH Why not trigger the kernel oom killer?
.PP
Earlyoom does not use \f[C]echo f > /proc/sysrq-trigger\f[R] because the
Chrome people made their browser always be the first (innocent!)
victim by setting \f[C]oom_score_adj\f[R] very high.
Instead, earlyoom finds out itself by reading through
\f[C]/proc/*/status\f[R] (actually \f[C]/proc/*/statm\f[R], which
contains the same information but is easier to parse programmatically).
.PP
Additionally, in recent kernels (tested on 4.0.5), triggering the kernel
oom killer manually may not work at all.
That is, it may only free some graphics memory (that will be allocated
immediately again) and not actually kill any process.
.SH MEMORY USAGE
.PP
About 2 MiB VmRSS.
All memory is locked using mlockall() to make sure earlyoom does not
slow down in low memory situations.
.SH BUGS
.PP
If there is zero total swap on earlyoom startup, any \f[C]-S\f[R]
(uppercase \[lq]S\[rq]) values are ignored, a warning is printed, and
default swap percentages are used.
.PP
For processes matched by \f[C]--prefer\f[R], negative
\f[C]oom_score_adj\f[R] values are not taken into account, and the
process gets an effective \f[C]oom_score\f[R] of at least 300.
See https://github.com/rfjakob/earlyoom/issues/159 for details.
.SH AUTHOR
.PP
The author of earlyoom is Jakob Unterwurzacher
<jakobunt@gmail.com>.
.PP
This manual page was written by Yangfl <mmyangfl@gmail.com>,
for the Debian project (and may be used by others).