docs: rewrite all 244 READMEs to consistent structure (Overview, Fact Sheet, States, Perfdata, Troubleshooting)

Author: markuslf

CHANGELOG.md

@@ -34,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * CONTRIBUTING: run pylint without `--disable` flags
 * CONTRIBUTING: remove inline `pylint: disable` comments from code examples
 * All plugins: improve and expand DESCRIPTION to clearly explain what each plugin does for the admin deploying it
+* All plugins: rewrite all READMEs to follow consistent structure (Overview, Fact Sheet, Help, Usage Examples, States, Perfdata, Troubleshooting, Credits)
 * example: rewrite as comprehensive skeleton covering all standard patterns (argparse, SQLite delta calculations, regex filtering, `--lengthy` table output, human-readable formatting, get_state/get_worst, Grafana-compatible perfdata)
 * example: rewrite README as skeleton template with Overview, Fact Sheet, States, Perfdata, and Troubleshooting sections
 * Update and extend pre-commit hooks (add `check-added-large-files`, `check-merge-conflict`, `check-yaml`; update all hook versions)

CONTRIBUTING.md

@@ -920,7 +920,7 @@ Each plugin README follows a fixed structure. See [check-plugins/example/README.
     | Fact | Value |
     |----|----|
     | Check Plugin Download                 | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/example> |
-    | Nagios/Icinga Check Name              | `check_example` (for SEO: helps admins find the plugin when searching for the traditional Nagios-style name) |
+    | Nagios/Icinga Check Name              | `check_example` (for SEO: helps admins find the plugin when searching for the traditional Nagios-style name). Always use underscores, never dashes. |
     | Check Interval Recommendation         | Every minute, Every 5/15/30 minutes, Every hour, Every 4/8/12 hours, Every day, Every week |
     | Can be called without parameters      | Yes/No |
     | Compiled for Windows                  | Yes (when `.windows` file exists)/No (runs with Python interpreter) |

check-plugins/about-me/README.md

@@ -2,28 +2,33 @@
 
 ## Overview
 
-Reports an overview about the host dimensions, its network interfaces, deployed software and recurring jobs:
+Collects and displays key system information: OS and kernel version, CPU configuration (physical, logical, and usable cores plus frequency), RAM, disk count, virtualization type, network interfaces, listening ports, systemd services and timers, cron jobs, installed packages, and user accounts. Optionally queries dmidecode for firmware and hardware details, and fetches the public IP address. This check is purely informational and never raises alerts. Requires root or sudo.
 
-* System and hardware information (OS, CPUs, disks, ram, UEFI y/n etc.)
-* Interfaces: All network interfaces with their IP address
-* Listening TCP and UDP ports
-* Non-default software (software that was added later)
-* Non-default system users
-* systemctl get-default: Default systemd target that will be booted into
-* systemctl list-unit-files: List of all systemd services, mounts and automounts (excluding user units)
-* systemctl list-timers: List of all system systemd timers (excluding user timers)
-* crontab: List of crontabs that are found in the usual locations. Note that this might not be complete.
+**Data Collection:**
 
-Have a look at the output example below.
+* Gathers hardware and OS data via `psutil` (if available), `lsblk`, `stat`, `/proc/mounts`, and various `systemctl` commands
+* Optionally runs `dmidecode` (via `--dmidecode`) to retrieve BIOS, chassis, base board, processor, and system boot information
+* Optionally fetches the public IP address from one or more configurable "what is my IP" services (via `--public-ip-url`)
+* Lists all network interfaces with IPv4 addresses, listening TCP/UDP ports, non-default packages, non-default users, systemd services/mounts/automounts/timers, and cron jobs
+* Optionally guesses Icinga Director tags for automated host classification (via `--tags`)
 
-Plugin execution may take up to 30 seconds, depending on the amount or type of installed software.
+**Compatibility:**
+
+* Linux only (relies on `systemctl`, `lsblk`, `/proc/mounts`, package managers like `rpm`/`dpkg`)
+
+**Important Notes:**
+
+* Plugin execution may take up to 30 seconds, depending on the amount or type of installed software
+* The `--dmidecode` option requires sudo permissions
+* If `psutil` is not installed, some metrics (CPU frequency, network interfaces) will be unavailable
 
 
 ## Fact Sheet
 
 | Fact | Value |
 |----|----|
 | Check Plugin Download                 | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/about-me> |
+| Nagios/Icinga Check Name              | `check_about_me` |
 | Check Interval Recommendation         | Once a day or once a week |
 | Can be called without parameters      | Yes |
 | Compiled for Windows                  | No |
@@ -74,7 +79,6 @@ options:
 Shortened output example:
 
 ```text
-Plugin Output
 server.example.com: Fedora Linux 42 (Workstation Edition) Kernel 6.16.4-200.fc42.x86_64 on Bare-Metal, Dell Inc. XPS 13 9350, Firmware: 1.20, SerNo: 12345678, Proc: Intel Core Ultra 7 258V, CPUs: 8/8/8 (phys/lcpu/onln), Current Speed: 3943 MHz, 30.9GiB/4.0GiB RAM (virtmem/max; reboot recommended), Disk nvme0n1 1.8T, UEFI boot, Display Server x11, tuned profile "throughput-performance", born 2024-03-20. About-me v2025090901
 
 Hardware Info from `dmidecode`:
@@ -155,13 +159,13 @@ crontab:
 
 | Name | Type | Description |
 |----|----|----|
-| cpu_logical | Number | Number of physical cores multiplied by the number of threads that can run on each core (this is known as Hyper Threading) |
-| cpu_physical | Number | Number of physical cores |
-| cpu_usable | Number | The number of usable CPUs. This may not necessarily be equivalent to the actual number of CPUs the current process can use. That can vary in case process CPU affinity has been changed, Linux cgroups are being used or (in case of Windows) on systems using processor groups or having more than 64 CPUs. |
-| cpu_freq | Number | On Linux reports the current real-time value, on all other platforms this usually represents the nominal "fixed" value (never changing) |
-| disks | Number | Number of disks |
-| osversion | None | 'Fedora 33' becomes '33', 'CentOS 7.4.1708' becomes '741708' - to see when an upgrade happened |
-| ram | Bytes | Size of memory |
+| cpu_freq | Number | Current CPU frequency in MHz. On Linux, reports the real-time value; on other platforms, usually the nominal fixed value. |
+| cpu_logical | Number | Number of logical CPUs (physical cores multiplied by threads per core, i.e. Hyper-Threading). |
+| cpu_physical | Number | Number of physical CPU cores. |
+| cpu_usable | Number | Number of usable CPUs (may differ from total due to CPU affinity, cgroups, or processor groups). |
+| disks | Number | Number of disks. |
+| osversion | None | OS version as a comparable number, e.g. "Fedora 33" becomes "33", "CentOS 7.4.1708" becomes "741708". |
+| ram | Bytes | Total RAM size. |
 
 
 ## Credits, License

check-plugins/apache-httpd-status/README.md

@@ -2,7 +2,25 @@
 
 ## Overview
 
-This check "allows a server administrator to find out how well their server is performing". For the check plugin to work you have to enable `mod_status` and set `ExtendedStatus` to `On`. Have a look at <https://httpd.apache.org/docs/2.4/mod/mod_status.html>.
+Monitors Apache httpd performance via the mod_status endpoint (server-status?auto). Alerts when worker usage exceeds the configured thresholds. Reports busy and idle workers, request rates, bytes served, CPU load, connection states, and system load averages. Requires "ExtendedStatus On" in the Apache configuration for full metrics. Uses a local SQLite database to calculate per-second rates from cumulative counters.
+
+**Data Collection:**
+
+* Fetches data from the Apache `mod_status` machine-readable endpoint (`server-status?auto`)
+* Parses the scoreboard to count workers in each state (reading, replying, keepalive, DNS lookup, closing, logging, starting, finishing, waiting, free slots)
+* Uses a local SQLite database to store previous values and calculate per-interval deltas for accesses, bytes, and duration
+* On the first run (or after a restart), returns "Waiting for more data." until at least two measurements are available
+
+**Compatibility:**
+
+* Works with any Apache httpd version that provides `mod_status`
+* Some metrics (connection stats, load averages, processes) are only available in newer versions of `mod_status`
+
+**Important Notes:**
+
+* `mod_status` must be loaded and `ExtendedStatus On` must be set in the Apache configuration for full metrics. Without `ExtendedStatus`, only worker counts and scoreboard data are reported.
+* The check alerts on the percentage of busy workers relative to the total number of worker slots (busy + idle + free)
+* Workers in the "Gracefully finishing" (G) state are counted as idle workers, not busy workers
 
 Busy workers (workers serving requests) are:
 
@@ -72,11 +90,11 @@ If you want to configure `/server-status` in a virtual host:
 | Fact | Value |
 |----|----|
 | Check Plugin Download                 | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/apache-httpd-status> |
-| Check Interval Recommendation         | Once a minute |
+| Nagios/Icinga Check Name              | `check_apache_httpd_status` |
+| Check Interval Recommendation         | Every minute |
 | Can be called without parameters      | Yes |
 | Compiled for Windows                  | No |
-| Requirements                          | Enable `mod_status` and set `ExtendedStatus` to `On` |
-| Uses SQLite DBs                       | `$TEMP/linuxfabrik-monitoring-plugins-apache-httpd-status.db` |
+| Uses State File                       | `$TEMP/linuxfabrik-monitoring-plugins-apache-httpd-status.db` |
 
 
 ## Help
@@ -149,44 +167,48 @@ Server Built                   ! Jun  2 2021 00:00:00
 
 ## States
 
-* WARN or CRIT if more than 80% or 95% busy workers compared to the total possible number of workers found.
+* OK if the percentage of busy workers is below the warning threshold.
+* OK with "Waiting for more data." on the first run or after an Apache restart.
+* WARN if the percentage of busy workers is >= `--warning` (default: 80).
+* CRIT if the percentage of busy workers is >= `--critical` (default: 95).
+* `--always-ok` suppresses all alerts and always returns OK.
 
 
 ## Perfdata / Metrics
 
 | Name | Type | Description |
 |----|----|----|
-| Accesses | Number | A total number of accesses and byte count served |
-| BusyWorkers | Number | workers_closing + workers_dns + workers_idle + workers_keepalive + workers_logging + workers_reading + workers_replying + workers_starting |
-| Bytes | Number | Bytes sent |
-| ConnsAsyncClosing | Number |  |
-| ConnsAsyncKeepAlive | Number |  |
-| ConnsAsyncWriting | Number |  |
-| ConnsTotal | Number |  |
-| CPULoad | Number |  |
-| IdleWorkers | Number | workers_finishing + workers_waiting |
-| Load1 | Number |  |
-| Load15 | Number |  |
-| Load5 | Number |  |
-| ParentServerConfigGeneration | Number |  |
-| ParentServerMPMGeneration | Number |  |
-| Processes | Number |  |
-| Stopping | Number |  |
-| Total Duration | Seconds |  |
-| TotalWorkers | Number |  |
-| Uptime | Seconds | The time the server has been running for |
-| WorkerUsagePercentage | Percentage |  |
-| workers_closing | Number | BusyWorkers; Closing connection, 'C' in Apache Scoreboard (SERVER_CLOSING) |
-| workers_dns | Number | BusyWorkers; DNS Lookup,'D' in Apache Scoreboard (SERVER_BUSY_DNS) |
-| workers_finishing | Number | IdleWorkers; Gracefully finishing, 'G' in Apache Scoreboard (SERVER_GRACEFUL) |
-| workers_free | Number | Open slot with no current process, '.' in Apache Scoreboard (SERVER_DEAD) |
-| workers_idle | Number | BusyWorkers; Idle cleanup of worker, 'I' in Apache Scoreboard (SERVER_IDLE_KILL) |
-| workers_keepalive | Number | BusyWorkers; Keepalive (read), 'K' in Apache Scoreboard (SERVER_BUSY_KEEPALIVE) |
-| workers_logging | Number | BusyWorkers; Logging, 'L' in Apache Scoreboard (SERVER_BUSY_LOG) |
-| workers_reading | Number | BusyWorkers; Reading Request, 'R' in Apache Scoreboard (SERVER_BUSY_READ) |
-| workers_replying | Number | BusyWorkers; Sending Reply, 'W' in Apache Scoreboard (SERVER_BUSY_WRITE) |
-| workers_starting | Number | BusyWorkers; Starting up, 'S' in Apache Scoreboard (SERVER_STARTING) |
-| workers_waiting | Number | IdleWorkers; Waiting for Connection, '\_' in Apache Scoreboard (SERVER_READY) |
+| Accesses | Number | Total number of accesses during the check interval. |
+| BusyWorkers | Number | Number of workers currently processing requests. |
+| Bytes | Bytes | Total bytes served during the check interval. |
+| ConnsAsyncClosing | Number | Number of async connections in closing state. |
+| ConnsAsyncKeepAlive | Number | Number of async connections in keep-alive state. |
+| ConnsAsyncWriting | Number | Number of async connections in writing state. |
+| ConnsTotal | Number | Total number of connections. |
+| CPULoad | Number | CPU load of the Apache process. |
+| IdleWorkers | Number | Number of idle workers (finishing + waiting). |
+| Load1 | Number | System load average, 1 minute. |
+| Load15 | Number | System load average, 15 minutes. |
+| Load5 | Number | System load average, 5 minutes. |
+| ParentServerConfigGeneration | Number | Apache configuration generation counter. |
+| ParentServerMPMGeneration | Number | Apache MPM generation counter. |
+| Processes | Number | Number of Apache processes. |
+| Stopping | Number | Number of stopping processes. |
+| Total Duration | Seconds | Total duration of all requests during the check interval. |
+| TotalWorkers | Number | Total number of worker slots (busy + idle + free). |
+| Uptime | Seconds | Time the server has been running. |
+| WorkerUsagePercentage | Percentage | Percentage of workers currently processing requests. |
+| workers_closing | Number | Workers closing connections ("C" in scoreboard). |
+| workers_dns | Number | Workers performing DNS lookup ("D" in scoreboard). |
+| workers_finishing | Number | Workers gracefully finishing ("G" in scoreboard). |
+| workers_free | Number | Open slots with no current process ("." in scoreboard). |
+| workers_idle | Number | Workers in idle cleanup ("I" in scoreboard). |
+| workers_keepalive | Number | Workers in keepalive read ("K" in scoreboard). |
+| workers_logging | Number | Workers logging ("L" in scoreboard). |
+| workers_reading | Number | Workers reading request ("R" in scoreboard). |
+| workers_replying | Number | Workers sending reply ("W" in scoreboard). |
+| workers_starting | Number | Workers starting up ("S" in scoreboard). |
+| workers_waiting | Number | Workers waiting for connection ("_" in scoreboard). |
 
 
 ## Troubleshooting

check-plugins/apache-httpd-version/README.md

@@ -2,24 +2,30 @@
 
 ## Overview
 
-This plugin lets you track if Apache httpd is End-of-Life (EOL). To compare against the current/installed version of Apache httpd, the check has to run on the Apache httpd server itself.
+Checks the installed Apache httpd version against the endoflife.date API and alerts if the version is end-of-life or if newer major, minor, or patch releases are available. By default, alerts 30 days before the official EOL date. The offset is configurable.
 
-This check plugin alerts n days before or after the EOL date is reached. Optionally, it can also alert on available major, minor or patch releases (each independently).
+**Data Collection:**
 
-Hints:
+* Detects the installed Apache httpd version by running `httpd -v` (RHEL) or `apache2 -v` (Debian-based systems)
+* Queries the [endoflife.date API](https://endoflife.date/api/apache.json) to determine EOL status and available releases
+* Caches the API response in a local SQLite database to reduce network calls
 
-* Runs on all systems where the Apache is named either "httpd" or "apache2".
+**Compatibility:**
+
+* Runs on all systems where the Apache binary is named either `httpd` or `apache2`
+* Must run on the Apache httpd server itself to detect the installed version
 
 
 ## Fact Sheet
 
 | Fact | Value |
 |----|----|
 | Check Plugin Download                 | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/apache-httpd-version> |
+| Nagios/Icinga Check Name              | `check_apache_httpd_version` |
 | Check Interval Recommendation         | Once a day |
 | Can be called without parameters      | Yes |
 | Compiled for Windows                  | No |
-| Uses SQLite DBs                       | `$TEMP/linuxfabrik-lib-version.db` |
+| Uses State File                       | `$TEMP/linuxfabrik-lib-version.db` |
 
 
 ## Help
@@ -74,17 +80,20 @@ Apache httpd v2.4.37 (EOL unknown, patch 2.4.57 available)
 
 ## States
 
-* WARN if software is EOL
-* Optional: WARN when new major version is available
-* Optional: WARN when new minor version is available
-* Optional: WARN when new patch version is available
+* OK if the installed version is not EOL and no newer releases are flagged.
+* WARN if the installed version is EOL (or will be within `--offset-eol` days, default: -30).
+* WARN if `--check-major` is set and a newer major version is available.
+* WARN if `--check-minor` is set and a newer minor version is available.
+* WARN if `--check-patch` is set and a newer patch version is available.
+* UNKNOWN if Apache httpd is not found.
+* `--always-ok` suppresses all alerts and always returns OK.
 
 
 ## Perfdata / Metrics
 
 | Name | Type | Description |
 |----|----|----|
-| apache-httpd-version | Number | Installed Apache httpd version as float. "2.2.34" becomes "2.234". |
+| apache-httpd-version | Number | Installed Apache httpd version as float, e.g. "2.4.57" becomes "2.457". |
 
 
 ## Credits, License