.\" Automatically generated by Pandoc 1.17.2
.\"
.TH "nohang" "8" "" "" "Linux System Administrator\[aq]s Manual"
.hy
.SH NAME
.PP
nohang \- A sophisticated low memory handler
.SH SYNOPSIS
.PP
\f[B]nohang\f[] [\f[B]OPTION\f[]]...
.SH DESCRIPTION
.PP
nohang is a highly configurable daemon for Linux which is able to
correctly prevent out of memory (OOM) and keep system responsiveness in
low memory conditions.
.SH REQUIREMENTS
.SS For basic usage:
.IP \[bu] 2
Linux (>= 3.14, since MemAvailable appeared in /proc/meminfo)
.IP \[bu] 2
Python (>= 3.3)
.SS To respond to PSI metrics (optional):
.IP \[bu] 2
Linux (>= 4.20) with CONFIG_PSI=y
.SS To show GUI notifications (optional):
.IP \[bu] 2
notification server (most of desktop environments use their own
implementations)
.IP \[bu] 2
libnotify (Arch Linux, Fedora, openSUSE) or libnotify\-bin (Debian
GNU/Linux, Ubuntu)
.IP \[bu] 2
sudo if nohang started with UID=0.
.SH COMMAND\-LINE OPTIONS
.SS \-h, \-\-help
.PP
show this help message and exit
.SS \-v, \-\-version
.PP
show version of installed package and exit
.SS \-m, \-\-memload
.PP
consume memory until 40 MiB (MemAvailable + SwapFree) remain free, and
terminate the process
.SS \-c CONFIG, \-\-config CONFIG
.PP
path to the config file.
This should only be used with one of the following options: \-\-monitor,
\-\-tasks, \-\-check
.SS \-\-check
.PP
check and show the configuration and exit.
This should only be used with \-c/\-\-config CONFIG option
.SS \-\-monitor
.PP
start monitoring.
This should only be used with \-c/\-\-config CONFIG option
.SS \-\-tasks
.PP
show tasks state and exit.
This should only be used with \-c/\-\-config CONFIG option
.SH FILES
.SS /etc/nohang/nohang.conf
.PP
path to vanilla nohang configuration file
.SS /etc/nohang/nohang\-desktop.conf
.PP
path to configuration file with settings optimized for desktop usage
.SS /usr/share/nohang/nohang.conf
.PP
path to file with \f[I]default\f[] nohang.conf values
.SS /usr/share/nohang/nohang\-desktop.conf
.PP
path to file with \f[I]default\f[] nohang\-desktop.conf values
.SS /var/log/nohang/nohang.log
.PP
optional log file that stores entries if separate_log=True in the config
.SS /etc/logrotate.d/nohang
.PP
logrotate config file that controls rotation in /var/log/nohang/
.SH nohang.conf vs nohang\-desktop.conf
.IP \[bu] 2
nohang.conf provides vanilla default settings without PSI checking
enabled, without any badness correction and without GUI notifications
enabled.
.IP \[bu] 2
nohang\-desktop.conf provides default settings optimized for desktop
usage.
.SH PROBLEMS
.PP
The next problems can occur with out\-of\-tree kernels and modules:
.IP \[bu] 2
The ZFS ARC cache is memory\-reclaimable, like the Linux buffer cache.
However, in contrast to the buffer cache, it currently does not count to
MemAvailable [1].
See also [2] and [3].
.IP \[bu] 2
Linux kernels without CONFIG_CGROUP_CPUACCT=y (linux\-ck, for example)
provide incorrect PSI metrics, see this thread [4].
.SH HOW TO CONFIGURE
.PP
The program can be configured by editing the config file.
The configuration includes the following sections:
.IP \[bu] 2
Memory levels to respond to as an OOM threat
.IP \[bu] 2
Response on PSI memory metrics
.IP \[bu] 2
The frequency of checking the level of available memory (and CPU usage)
.IP \[bu] 2
The prevention of killing innocent victims
.IP \[bu] 2
Impact on the badness of processes via matching their names, cmdlines
and UIDs with regular expressions
.IP \[bu] 2
The execution of a specific command or sending any signal instead of
sending the SIGTERM signal
.IP \[bu] 2
GUI notifications:
.RS 2
.IP \[bu] 2
notifications of corrective actions taken
.IP \[bu] 2
low memory warnings
.RE
.IP \[bu] 2
Verbosity
.IP \[bu] 2
Misc
.PP
Just read the description of the parameters and edit the values.
Restart the daemon to apply the changes.
.SH CHECK CONFIG
.PP
Check the config for errors:
.PP
$ nohang \-\-check \-\-config /path/to/config
.SH HOW TO TEST
.PP
The safest way is to run \f[B]nohang \-\-memload\f[].
This causes memory consumption, and the process will exits before OOM
occurs.
Another way is to run \f[B]tail /dev/zero\f[].
This causes fast memory comsumption and causes OOM at the end.
If testing occurs while nohang is running, these processes should be
terminated before OOM occurs.
.SH LOGGING
.PP
To view the latest entries in the log (for systemd users):
.PP
$ \f[B]sudo journalctl \-eu nohang.service\f[]
.PP
or
.PP
$ \f[B]sudo journalctl \-eu nohang\-desktop.service\f[]
.PP
You can also enable \f[B]separate_log\f[] in the config to logging in
\f[B]/var/log/nohang/nohang.log\f[].
.SH SIGNALS
.PP
Sending SIGTERM, SIGINT, SIGQUIT or SIGHUP signals to the nohang process
causes it displays corrective action stats and exits.
.SH REPORTING BUGS
.PP
Please ask any questions and report bugs at
<https://github.com/hakavlad/nohang/issues>.
.SH AUTHOR
.PP
Written by Alexey Avramov <hakavlad@gmail.com>.
.SH HOMEPAGE
.PP
Homepage is <https://github.com/hakavlad/nohang>.
.SH SEE ALSO
.PP
oom\-sort(1), psi\-top(1), psi2log(1)
.SH NOTES
.IP "1." 3
https://github.com/openzfs/zfs/issues/10255
.IP "2." 3
https://github.com/rfjakob/earlyoom/pull/191#issuecomment\-622314296
.IP "3." 3
https://github.com/hakavlad/nohang/issues/89
.IP "4." 3
https://github.com/hakavlad/nohang/issues/25#issuecomment\-521390412