Tune OOM-Killer Preference Safely with oom_score_adj

You will adjust the Linux OOM-killer preference for one running process, verify the value, and restore it when the test is over. The examples use 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 require 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. A higher adjustment makes that process more attractive to the OOM-killer; a lower adjustment makes it less attractive.

The adjustment accepts values from -1000 to 1000. -1000 is special: the task's resulting badness score is always zero, which disables OOM-killing for that task. That is not a general reliability setting. If the process keeps allocating memory, protecting it can leave less memory for the rest of the system.

The exact meaning of the underlying score 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 is convenient for a harmless read-only check:

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

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

Checkpoint: record the original adjustment before experimenting:

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 the process rather than writing to a reused PID.

3. Apply a temporary adjustment with choom

The installed choom command provides 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

Use sudo before choom only if the operation is rejected by your host's permissions policy:

$ sudo choom --pid 12345 --adjust 300

Do not use -1000 as a quick fix for a service that must survive. It can prevent the kernel from reclaiming that process by OOM-killing it, while the process and its memory use continue. Also avoid changing a database, init system or monitoring process during an incident unless you understand the recovery consequences.

4. Verify the live value

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

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

The second output 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 changing observation.

If the value is unchanged, check that the PID is still the intended process and inspect 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

Temporary experiments should end 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. That makes a parent or service manager's value relevant to children, but it does not turn a one-off write to an existing PID into persistent service configuration. If a service needs a lasting policy, document and configure that through the service's own deployment mechanism, then test the complete launch path.

6. Avoid the legacy interface

You may encounter /proc/PID/oom_adj in older scripts. It is the deprecated predecessor, with a different range and a special value of -17. On current kernels, use oom_score_adj instead. The kernel maps writes between the two interfaces when the legacy file is available, so mixing them can make reviews and verification harder.

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.