diff options
Diffstat (limited to 'system/earlyoom/earlyoom.8')
| -rw-r--r-- | system/earlyoom/earlyoom.8 | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/system/earlyoom/earlyoom.8 b/system/earlyoom/earlyoom.8 new file mode 100644 index 0000000000..9431b55a44 --- /dev/null +++ b/system/earlyoom/earlyoom.8 @@ -0,0 +1,270 @@ +.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). |