oomctl

Show the current state of the cgroups and system contexts stored by systemd-oomd

$ oomctl dump

oomctl [OPTIONS] COMMAND [ARGUMENTS]

-h, --help
    Displays a help message with available commands and options.

-v, --version
    Shows the version information of the oomctl utility.

--root
    Specifies an alternative root path for the cgroup v2 hierarchy. Useful for testing or custom setups where cgroup v2 is not mounted at its default location.

status [CGROUP]
    Shows the current OOM state and statistics for specified cgroups. If no CGROUP path is provided, it typically shows information for the cgroup from which the command is executed.

set
    Sets an OOM-related property for a specified cgroup. Common properties include memory.oom.group (enables/disables OOM killing for the cgroup as a whole) and memory.oom.group.stat. For example, 'set /sys/fs/cgroup/user.slice/user-1000.slice memory.oom.group 1' enables OOM group killing for that cgroup.

kill
    Manually triggers an OOM kill within the specified cgroup. This can be used for debugging OOM scenarios or to proactively enforce resource limits by terminating processes in a specific cgroup.

oomctl is a utility to inspect and control the Linux kernel's Out-Of-Memory (OOM) killer. It primarily interacts with the OOM killer's behavior within cgroup v2 memory controllers. System administrators can use oomctl to query the OOM status of specific cgroups, configure OOM protection settings for tasks and cgroups, and manually trigger OOM kills for debugging or resource management. This command provides a structured interface to kernel mechanisms that decide which process to terminate when system memory is exhausted, offering finer-grained control than global sysctl settings. It's crucial for managing resource contention in containerized or virtualized environments.

oomctl requires root privileges to operate. It is primarily designed for and interacts exclusively with the Linux kernel's cgroup v2 hierarchy. Incorrect usage, especially with the kill subcommand or by setting incorrect properties, can lead to unexpected process terminations or system instability. Always understand the implications before modifying OOM settings.

The Out-Of-Memory (OOM) killer is a core Linux kernel mechanism that identifies and terminates processes when the system experiences severe memory exhaustion. Its primary goal is to free up memory and prevent the entire system from crashing or becoming unresponsive. oomctl allows administrators to influence how this mechanism behaves within specific cgroups, offering granular control over which processes are targeted.

Control Groups version 2 (cgroup v2) is the unified, hierarchical resource management system in the Linux kernel. It provides a more robust and flexible way to allocate and isolate system resources like CPU, memory, and I/O for groups of processes. Unlike cgroup v1, it offers a single hierarchy. oomctl leverages the memory controller features of cgroup v2 to manage OOM behavior on a per-cgroup basis, enabling fine-grained memory management for applications and containers.

oomctl is a relatively recent addition to Linux utility sets, designed to provide a more structured and user-friendly interface to the cgroup v2 OOM controls. Before its existence, managing OOM behavior within cgroups often involved direct manipulation of cgroup filesystem files (e.g., memory.oom.group) using commands like `echo`. Its development aimed to simplify OOM killer management, particularly in containerized and cloud environments where precise resource control is crucial for stability and efficiency.

dmesg(1), journalctl(1), cgroup(7), cgclassify(1), systemd-cgtop(1)