diff --git a/Makefile b/Makefile index 43cb103..66ce5fc 100644 --- a/Makefile +++ b/Makefile @@ -15,7 +15,13 @@ MANDIR ?= $(DATADIR)/man all: @ echo "Use: make install, make install-openrc, make uninstall" -base: +manpages: + -pandoc docs/nohang.manpage.md -s -t man > man/nohang.8 + -pandoc docs/oom-sort.manpage.md -s -t man > man/oom-sort.1 + -pandoc docs/psi2log.manpage.md -s -t man > man/psi2log.1 + -pandoc docs/psi-top.manpage.md -s -t man > man/psi-top.1 + +base: manpages install -d $(DESTDIR)$(SBINDIR) install -m0755 src/nohang $(DESTDIR)$(SBINDIR)/nohang @@ -86,6 +92,11 @@ daemon-reload: build_deb: base units +reinstall-deb: + set -v + deb/build.sh + sudo apt install --reinstall ./deb/package.deb + install: base units chcon daemon-reload openrc: diff --git a/docs/nohang.manpage.md b/docs/nohang.manpage.md new file mode 100644 index 0000000..761502c --- /dev/null +++ b/docs/nohang.manpage.md @@ -0,0 +1,79 @@ +% nohang(8) | Linux System Administrator's Manual + +# NAME +nohang - A sophisticated low memory handler + +# SYNOPSIS +**nohang** [**OPTION**]... + +# DESCRIPTION +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. + +# REQUIREMENTS + +#### For basic usage: +- Linux (>= 3.14, since MemAvailable appeared in /proc/meminfo) +- Python (>= 3.3) + +#### To respond to PSI metrics (optional): +- Linux (>= 4.20) with CONFIG_PSI=y + +#### To show GUI notifications (optional): +- notification server (most of desktop environments use their own implementations) +- libnotify (Arch Linux, Fedora, openSUSE) or libnotify-bin (Debian GNU/Linux, Ubuntu) +- sudo if nohang started with UID=0. + +# OPTIONS + +#### -h, --help +show this help message and exit + +#### -v, \-\-version +show version of installed package and exit + +#### -m, \-\-memload +consume memory until 40 MiB (MemAvailable + SwapFree) remain free, and terminate the process + +#### -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 and exit. This should only be used with -c/--config CONFIG option + +#### --monitor +start monitoring. This should only be used with -c/--config CONFIG option + +#### --tasks +show tasks state and exit. This should only be used with -c/--config CONFIG option + +# HOW TO CONFIGURE +The program can be configured 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 +- 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. Restart the daemon to apply the changes. + +# HOW TO TEST +The safest way is to run **nohang --memload**. This causes memory consumption, and the process will exits before OOM occurs. Another way is to run **tail /dev/zero**. 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. + +# 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 logging in **/var/log/nohang/nohang.log**. diff --git a/docs/oom-sort.manpage.md b/docs/oom-sort.manpage.md new file mode 100644 index 0000000..d7c55e4 --- /dev/null +++ b/docs/oom-sort.manpage.md @@ -0,0 +1,9 @@ +% oom-sort(1) | General Commands Manual + +# NAME + +oom-sort - sort processes by oom_score + +# SYNOPSIS + +**oom-sort** [**OPTION**]... diff --git a/docs/psi-top.manpage.md b/docs/psi-top.manpage.md new file mode 100644 index 0000000..c441d9f --- /dev/null +++ b/docs/psi-top.manpage.md @@ -0,0 +1,9 @@ +% psi-top(1) | General Commands Manual + +# NAME + +psi-top + +# SYNOPSIS + +**psi-top** [**OPTION**]... diff --git a/docs/psi2log.manpage.md b/docs/psi2log.manpage.md new file mode 100644 index 0000000..1463dc4 --- /dev/null +++ b/docs/psi2log.manpage.md @@ -0,0 +1,9 @@ +% psi2log(1) | General Commands Manual + +# NAME + +psi2log \- PSI metrics monitor and logger + +# SYNOPSIS + +**psi2log** [**OPTION**]... diff --git a/man/nohang.8 b/man/nohang.8 index b406da7..58faa4e 100644 --- a/man/nohang.8 +++ b/man/nohang.8 @@ -1,109 +1,115 @@ -.TH nohang 8 - +.\" 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 -.B nohang -.RB [ OPTION ]... - +.PP +\f[B]nohang\f[] [\f[B]OPTION\f[]]... .SH DESCRIPTION - -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. - +.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 - -.B For basic usage: - - - Linux 3.14+ (since MemAvailable appeared in /proc/meminfo) - - - Python 3.3+ (not tested with previous) - -.B To show GUI notifications: - - - Notification server (most of desktop environments use their own implementations) - - - libnotify (Fedora, Arch Linux) or libnotify-bin (Debian GNU/Linux, Ubuntu) - - - sudo if nohang started with UID=0 - -.B To use PSI: - - - It needs Linux 4.20+ with CONFIG_PSI=y. - +.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 OPTIONS - - -h, --help show this help message and exit - - -v, --version show version of installed package and exit - - -m, --memload consume memory until 40 MiB (MemAvailable + SwapFree) - remain free, and terminate the process - - -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 and exit. This should - only be used with -c/--config CONFIG option - - --monitor start monitoring. This should only be used with - -c/--config CONFIG option - - --tasks show tasks state and exit. This should only be used - with -c/--config CONFIG option - +.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 HOW TO CONFIGURE - +.PP The program can be configured by editing the config file. - -.B 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 - - - 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 - +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. - -Please restart nohang to apply the changes. - -Default path to the config after installing is /etc/nohang/nohang.conf. - +Restart the daemon to apply the changes. .SH HOW TO TEST - -- The safest way is to run `nohang --memload`. This causes memory consumption, and the process will exits before OOM occurs. -- Another way is to run `tail /dev/zero`. 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. - +.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): - -$ sudo journalctl -eu nohang - -See also man journalctl. - -You can also enable separate_log in the config to logging in /var/log/nohang/nohang.log. - -.SH SEE ALSO - -https://github.com/hakavlad/nohang +.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[]. diff --git a/man/oom-sort.1 b/man/oom-sort.1 index 1340da6..93f5a52 100644 --- a/man/oom-sort.1 +++ b/man/oom-sort.1 @@ -1,5 +1,10 @@ -.TH oom-sort 1 - +.\" Automatically generated by Pandoc 1.17.2 +.\" +.TH "oom\-sort" "1" "" "" "General Commands Manual" +.hy .SH NAME - -oom-sort \- sort processes by oom_score +.PP +oom\-sort \- sort processes by oom_score +.SH SYNOPSIS +.PP +\f[B]oom\-sort\f[] [\f[B]OPTION\f[]]... diff --git a/man/psi-top.1 b/man/psi-top.1 index 98e646e..b9f0fd7 100644 --- a/man/psi-top.1 +++ b/man/psi-top.1 @@ -1,5 +1,10 @@ -.TH psi-top 1 - +.\" Automatically generated by Pandoc 1.17.2 +.\" +.TH "psi\-top" "1" "" "" "General Commands Manual" +.hy .SH NAME - -psi-top \- psi-top +.PP +psi\-top +.SH SYNOPSIS +.PP +\f[B]psi\-top\f[] [\f[B]OPTION\f[]]... diff --git a/man/psi2log.1 b/man/psi2log.1 index 46b61b0..54f0533 100644 --- a/man/psi2log.1 +++ b/man/psi2log.1 @@ -1,5 +1,10 @@ -.TH psi2log 1 - +.\" Automatically generated by Pandoc 1.17.2 +.\" +.TH "psi2log" "1" "" "" "General Commands Manual" +.hy .SH NAME - +.PP psi2log \- PSI metrics monitor and logger +.SH SYNOPSIS +.PP +\f[B]psi2log\f[] [\f[B]OPTION\f[]]...