1earlyoom(1)                 General Commands Manual                earlyoom(1)
2
3
4

NAME

6       earlyoom - Early OOM Daemon
7

SYNOPSIS

9       earlyoom [OPTION]...
10

DESCRIPTION

12       The  oom-killer  generally has a bad reputation among Linux users.  One
13       may have to sit in front of an unresponsive system,  listening  to  the
14       grinding  disk  for  minutes, and press the reset button to quickly get
15       back to what one was doing after running out of patience.
16
17       earlyoom checks the amount of available memory and free swap up  to  10
18       times  a second (less often if there is a lot of free memory).  If both
19       memory and swap are below 10%, it will kill the largest process  (high‐
20       est  oom_score).  The percentage value is configurable via command line
21       arguments.
22
23       If there is a failure when trying to kill a  process,  earlyoom  sleeps
24       for 1 second to limit log spam due to recurring errors.
25

OPTIONS

27   -m PERCENT[,KILL_PERCENT]
28       set available memory minimum to PERCENT of total (default 10 %).
29
30       earlyoom  starts  sending  SIGTERM  once both memory and swap are below
31       their respective PERCENT setting.  It sends SIGKILL once both are below
32       their respective KILL_PERCENT setting (default PERCENT/2).
33
34       Use  the  same value for PERCENT and KILL_PERCENT if you always want to
35       use SIGKILL.
36
37       Examples:
38
39              earlyoom              # sets PERCENT=10, KILL_PERCENT=5
40              earlyoom -m 30        # sets PERCENT=30, KILL_PERCENT=15
41              earlyoom -m 20,18     # sets PERCENT=20, KILL_PERCENT=18
42
43   -s PERCENT[,KILL_PERCENT]
44       set free swap minimum to PERCENT of total (default 10 %).  Send SIGKILL
45       if at or below KILL_PERCENT (default PERCENT/2), otherwise SIGTERM.
46
47       You can use -s 100 to have earlyoom effectively ignore swap usage: Pro‐
48       cesses are killed once available memory drops below the configured min‐
49       imum, no matter how much swap is free.
50
51       Use  the  same value for PERCENT and KILL_PERCENT if you always want to
52       use SIGKILL.
53
54   -M SIZE[,KILL_SIZE]
55       As an alternative to specifying a percentage of total memory,  -M  sets
56       the available memory minimum to SIZE KiB.  The value is internally con‐
57       verted to a percentage.  If you pass both -M and -m, the lower value is
58       used.  Example: Reserve 10% of RAM but at most 1 GiB:
59
60              earlyoom -m 10 -M 1048576
61
62       earlyoom  sends SIGKILL if at or below KILL_SIZE (default SIZE/2), oth‐
63       erwise SIGTERM.
64
65   -S SIZE[,KILL_SIZE]
66       As an alternative to specifying a percentage of total swap, -S sets the
67       free  swap minimum to SIZE KiB.  The value is internally converted to a
68       percentage.  If you pass both -S and -s, the lower value is used.
69
70       Send SIGKILL if at  or  below  KILL_SIZE  (default  SIZE/2),  otherwise
71       SIGTERM.
72
73   -k
74       removed in earlyoom v1.2, ignored for compatibility
75
76   -i
77       removed in earlyoom v1.7, ignored for compatibility
78
79   -d
80       enable debugging messages
81
82   -v
83       print version information and exit
84
85   -r INTERVAL
86       Time  between  printing  periodic  memory  reports, in seconds (default
87       1.0).  A memory report looks like this:
88
89              mem avail: 21790 of 23909 MiB (91.14%), swap free:    0 of    0 MiB ( 0.00%)
90
91       Set to 3600 to print a report every hour, to 86400 to print once a  day
92       etc.  Set to 0 to disable printing periodic memory reports.  Free memo‐
93       ry monitoring and low-memory killing runs independently of this  option
94       at  an adaptive poll rate that only depends on free memory.  Due to the
95       adaptive poll rate, when there is a lot of free memory, the actual  in‐
96       terval may be up to 1 second longer than the setting.
97
98   -p
99       Increase  earlyoom’s  priority:  set  niceness  of  earlyoom to -20 and
100       oom_score_adj to -100.
101
102       When earlyoom is run through its default systemd service, the -p switch
103       doesn’t  work.   To  achieve the same effect, enter the following three
104       lines into sudo systemctl edit earlyoom:
105
106              [Service]
107              OOMScoreAdjust=-100
108              Nice=-20
109
110   -n
111       Enable notifications via d-bus.
112
113       To actually see the notifications in your GUI session, you need to have
114       systembus-notify  (https://github.com/rfjakob/systembus-notify) running
115       as your user.
116
117   -N /PATH/TO/SCRIPT
118       Run the given script for each process  killed.   Must  be  an  absolute
119       path.
120
121       Within the script, information about the killed process can be obtained
122       via the following environment variables:
123
124              EARLYOOM_PID     Process PID
125              EARLYOOM_NAME    Process name truncated to 16 bytes (as reported in /proc/PID/comm)
126              EARLYOOM_UID     UID of the user running the process
127
128       WARNING: EARLYOOM_NAME can contain spaces, newlines, special characters
129       and is controlled by the user, or it can be empty!  Make sure that your
130       notification script can handle that!
131
132   -g
133       Kill all processes that have  same  process  group  id  (PGID)  as  the
134       process with excessive memory usage.
135
136       For  example,  with  this flag turned on, the whole application will be
137       killed when one of its subprocess consumes too much memory (as long  as
138       they all have the same PGID, of course).
139
140       Enable  this  flag when completely cleaning up the “entire application”
141       is more desirable, and you are sure that the application puts  all  its
142       processes in the same PGID.
143
144       Note  that some desktop environments (GNOME, for example) put all desk‐
145       top application in the same process  group  as  gnome-shell.   earlyoom
146       might  kill  all such processes including gnome-shell when this flag is
147       turned on.
148
149       Be sure to check how your environment behaves beforehand.  Use
150
151              pstree -gT
152
153       to show all processes with the PGID in brackets.
154
155   --prefer REGEX
156       prefer killing processes matching REGEX (adds 300 to oom_score)
157
158   --avoid REGEX
159       avoid killing processes matching REGEX (subtracts 300 from oom_score)
160
161   --dryrun
162       dry run (do not kill any processes)
163
164   -h, --help
165       this help text
166

EXIT STATUS

168       0: Successful program execution.
169
170       1: Other error - inspect message for details
171
172       2: Switch conflict.
173
174       4: Could not cd to /proc
175
176       5: Could not open proc
177
178       7: Could not open /proc/sysrq-trigger
179
180       13: Unknown options.
181
182       14: Wrong parameters for other options.
183
184       15: Wrong parameters for memory threshold.
185
186       16: Wrong parameters for swap threshold.
187
188       102: Could not open /proc/meminfo
189
190       103: Could not read /proc/meminfo
191
192       104: Could not find a specific entry in /proc/meminfo
193
194       105: Could not convert number when parse the contents of /proc/meminfo
195

Why not trigger the kernel oom killer?

197       Earlyoom does not use echo f > /proc/sysrq-trigger because  the  Chrome
198       people  made  their  browser always be the first (innocent!)  victim by
199       setting oom_score_adj very high.  Instead, earlyoom finds out itself by
200       reading  through /proc/*/status (actually /proc/*/statm, which contains
201       the same information but is easier to parse programmatically).
202
203       Additionally, in recent kernels (tested on 4.0.5), triggering the  ker‐
204       nel oom killer manually may not work at all.  That is, it may only free
205       some graphics memory (that will be allocated immediately again) and not
206       actually kill any process.
207

MEMORY USAGE

209       About  2 MiB VmRSS.  All memory is locked using mlockall() to make sure
210       earlyoom does not slow down in low memory situations.
211

BUGS

213       If there is zero total swap on earlyoom startup, any -S (uppercase “S”)
214       values  are ignored, a warning is printed, and default swap percentages
215       are used.
216
217       For processes matched by --prefer, negative  oom_score_adj  values  are
218       not  taken into account, and the process gets an effective oom_score of
219       at least 300.  See  https://github.com/rfjakob/earlyoom/issues/159  for
220       details.
221

AUTHOR

223       The author of earlyoom is Jakob Unterwurzacher ⟨jakobunt@gmail.com⟩.
224
225       This  manual  page  was written by Yangfl ⟨mmyangfl@gmail.com⟩, for the
226       Debian project (and may be used by others).
227
228
229
230                                                                   earlyoom(1)
Impressum