nohang(8)

📦
version 0.3.0 · 3 versions
, in ubuntu resolute, ubuntu stonking

✨ nohang(8) ✨

okay bestie, gather round, because we're about to talk about the Linux System Administrator's Manual entry for nohang and honestly? she's iconic.

💖 NAME 💖

nohang — a sophisticated low memory handler. yes. sophisticated. she has layers. 🎀

🌸 SYNOPSIS 🌸

nohang [OPTION]...

that's it. that's the whole summoning ritual. 💅

🦋 DESCRIPTION 🦋

so nohang is a highly configurable daemon for Linux, and what she does is correctly prevent out of memory (OOM) and keep your system's responsiveness alive when memory gets low. like, she's not out here panicking when things get tight — she's the friend who stays calm and fixes everything while everyone else is screaming. main character energy fr. 👑

🫶 REQUIREMENTS 🫶

for basic usage (the bare minimum, the essentials, the vibe check):

  • Linux (>= 3.14, because that's when MemAvailable showed up in /proc/meminfo)
  • Python (>= 3.3)

to respond to PSI metrics (optional, but make it fancy):

  • Linux (>= 4.20) with CONFIG_PSI=y

to show GUI notifications (optional, the aesthetic tier):

  • a notification server (most desktop environments use their own implementations)
  • libnotify (on Arch Linux, Fedora, openSUSE) or libnotify-bin (on Debian GNU/Linux, Ubuntu)
  • sudo if nohang was started with UID=0

⭐ COMMAND-LINE OPTIONS ⭐

okay this is the part where you actually learn the buttons, pay attention bestie:

  • -h, --help — show this help message and dip. 🚪
  • -v, --version — show the version of the installed package and exit
  • -m, --memload — consume memory until 40 MiB (MemAvailable + SwapFree) remain free, then terminate the process. yes she will eat your RAM on purpose, that's the point, it's a test 💀
  • -c CONFIG, --config CONFIG — path to the config file. this should only be used with one of the following options: --monitor, --tasks, --check
  • --check — check and show the configuration, then exit. this should only be used with the -c/--config CONFIG option
  • --monitor — start monitoring. this should only be used with the -c/--config CONFIG option
  • --tasks — show tasks state and exit. this should only be used with the -c/--config CONFIG option

🎀 FILES 🎀

  • :SYSCONFDIR:/nohang/nohang.conf — path to the vanilla nohang configuration file
  • :SYSCONFDIR:/nohang/nohang-desktop.conf — path to the configuration file with settings optimized for desktop usage
  • :DATADIR:/nohang/nohang.conf — path to the file with default nohang.conf values
  • :DATADIR:/nohang/nohang-desktop.conf — path to the file with default nohang-desktop.conf values
  • /var/log/nohang/nohang.log — optional log file that stores entries if separate_log=True in the config
  • /etc/logrotate.d/nohang — logrotate config file that controls rotation in /var/log/nohang/

🌈 nohang.conf vs nohang-desktop.conf 🌈

it's giving sibling rivalry, but make it config files:

  • nohang.conf gives you vanilla default settings — no PSI checking enabled, no badness correction, and no GUI notifications enabled. minimal. clean. raw. 🍃
  • nohang-desktop.conf gives you default settings optimized for desktop usage. she's dressed up, she's ready to go out. ✨

💀 PROBLEMS 💀

ngl bestie, these next problems can happen with out-of-tree kernels and modules. read carefully.
  • The ZFS ARC cache is memory-reclaimable, like the Linux buffer cache. However, in contrast to the buffer cache, it currently does not count toward MemAvailable [1]. See also [2] and [3].
  • Linux kernels without CONFIG_CGROUP_CPUACCT=y (linux-ck, for example) provide incorrect PSI metrics, see this thread [4].

💅 HOW TO CONFIGURE 💅

you configure the program by editing the config file. the configuration includes the following sections:

  • Memory levels to respond to as an OOM threat
  • Response on PSI memory metrics
  • The frequency of checking the level of available memory (and CPU usage)
  • The prevention of killing innocent victims 😭 (protect the innocent!!)
  • Impact on the badness of processes via matching their names, cmdlines and UIDs with regular expressions
  • The execution of a specific command or sending any signal instead of sending the SIGTERM signal
  • GUI notifications:
    • notifications of corrective actions taken
    • low memory warnings
  • Verbosity
  • Misc

Just read the description of the parameters and edit the values. Then restart the daemon to apply the changes. no cap, the restart is not optional. 🔁

🔍 CHECK CONFIG 🔍

check the config for errors, like so:

$ nohang --check --config /path/to/config

🧪 HOW TO TEST 🧪

The safest way is to run nohang --memload. This causes memory consumption, and the process will exit before OOM occurs. 🛟

Another way is to run tail /dev/zero. This causes fast memory consumption and causes OOM at the end. 💀

If testing occurs while nohang is running, these processes should be terminated before OOM occurs.

📜 LOGGING 📜

To view the latest entries in the log (for systemd users):

$ sudo journalctl -eu nohang.service

or

$ sudo journalctl -eu nohang-desktop.service

You can also enable separate_log in the config to log into /var/log/nohang/nohang.log. 📝

🚨 SIGNALS 🚨

Sending SIGTERM, SIGINT, SIGQUIT or SIGHUP signals to the nohang process causes it to display corrective action stats and exit. so basically, she'll show you the receipts on her way out. 💅

🙈 REPORTING BUGS 🙈

Please ask any questions and report bugs at https://github.com/hakavlad/nohang/issues. don't be shy, they don't bite 🫶

👑 AUTHOR 👑

Written by Alexey Avramov <hakavlad@gmail.com>.

🏠 HOMEPAGE 🏠

Homepage is https://github.com/hakavlad/nohang.

🦋 SEE ALSO 🦋

oom-sort(1), psi-top(1), psi2log(1)

📎 NOTES 📎

  1. https://github.com/openzfs/zfs/issues/10255
  2. https://github.com/rfjakob/earlyoom/pull/191#issuecomment-622314296
  3. https://github.com/hakavlad/nohang/issues/89
  4. https://github.com/hakavlad/nohang/issues/25#issuecomment-521390412

and that's the whole page bestie!! 🌸 this one lives in the Linux System Administrator's Manual as nohang(8), and she's been serving since... well, the footer doesn't say a date, so let's just say she's timeless. ✨ mwah, go protect your RAM. 💖🎀🦋

📦 where this page comes from