Tune OOM-Killer Preference Safely with oom_score_adj

Turning one process into the OOM-killer's favourite target, or its least favourite, is a single write to oom_score_adj. This walkthrough adjusts that preference for one running process, verifies it, and restores it afterwards. It follows the proc_pid_oom_score_adj(5) behaviour documented by the locally installed manpages 6.7-2 package.

Allow about ten minutes. You need a shell and a process you are allowed to inspect. Reading is ordinarily unprivileged; writing another process's setting may need elevated privileges, and changing a production service's score is a security-sensitive operational decision. This guide does not trigger an out-of-memory event or stop a service.

1. Understand what the value changes

Linux computes an OOM badness score for candidate tasks when available memory is exhausted. The score is roughly scaled from 0 to 1000, then the process's oom_score_adj value is added on top. A higher adjustment makes that process more attractive to the OOM-killer; a lower one makes it less attractive.

• Range. The adjustment accepts values from -1000 to 1000.
• The special case. -1000 forces the task's badness score to zero, disabling OOM-killing for it entirely. That is not a general reliability setting: if the process keeps allocating memory, protecting it can leave less for everything else.
• Context matters. What the underlying score is measured against depends on the memory context that ran out: a whole system, a memory limit, a cpuset or a mempolicy. Do not read a value such as 500 as a promise that exactly half of RAM is reserved.

2. Inspect a process before changing it

Use a real target PID. The shell's own PID makes a harmless, read-only warm-up:

$ printf 'PID: %s\n' "$$"
$ cat "/proc/$$/oom_score_adj"
0
$ cat "/proc/$$/oom_score"
666

Your numbers will differ. The first file is the adjustable preference; the second is the kernel's current badness score, useful context but not the setting you write. The value is per process, so changing one PID does not configure every process with the same name.

PID=12345
ORIGINAL=$(cat "/proc/$PID/oom_score_adj")
printf 'PID %s currently has oom_score_adj=%s\n' "$PID" "$ORIGINAL"

Replace 12345 with the target process. If the file is missing, the process may have exited or the PID may be wrong; recheck rather than writing to a reused PID.

3. Apply a temporary adjustment with choom

The installed choom command gives a direct interface. This example makes a process somewhat more likely to be selected, but it does not force an immediate kill:

$ choom --pid 12345 --adjust 300
PID 12345's oom_score_adj is 300

Put sudo before choom only if your host's permissions policy rejects the plain command:

$ sudo choom --pid 12345 --adjust 300

4. Verify the live value

Read the proc file after the write. This is the authoritative check for the process you targeted:

$ cat /proc/12345/oom_score_adj
300
$ cat /proc/12345/oom_score
966

The second line is illustrative, not a fixed result: memory use and the allowed memory context affect the badness score, so a successful adjustment does not imply a predictable new oom_score. Verify the adjustment itself and treat the score as a moving observation.

If the value is unchanged, check the PID is still the intended process and read the error from choom. A permission failure is different from a process that has exited; do not keep retrying with broader privileges without confirming the target.

5. Restore the setting after a test

End a temporary experiment by restoring the value you recorded, not by assuming the default was zero. Run the write as the same user, or with sudo when required:

$ choom --pid 12345 --adjust "$ORIGINAL"
PID 12345's oom_score_adj is 0
$ test "$(cat /proc/12345/oom_score_adj)" = "$ORIGINAL"
$ printf 'restored: %s\n' "$?"
restored: 0

A newly executed process normally inherits its parent's adjustment, which makes a parent or service manager's value relevant to children. That does not turn a one-off write to an existing PID into persistent service configuration. If a service needs a lasting policy, configure that through the service's own deployment mechanism, then test the complete launch path.

Avoid the legacy interface

You may still meet /proc/PID/oom_adj in older scripts. It is the deprecated predecessor, with a different range and a special value of -17. Use oom_score_adj on current kernels instead: the kernel maps writes between the two interfaces when the legacy file is available, so mixing them makes reviews and verification harder than they need to be.

Do not confuse this setting with a memory limit. It does not cap allocation, reserve RAM, change swap, or alter a cgroup's limit. It only changes the preference used when the OOM-killer chooses among eligible tasks.