Skip to content

Commit 61a6613

Browse files
markuslfmarkuslf
committed
Revert "fix(docs): restrict Compatibility to platform only, move requirements to Important Notes"
This reverts commit 24a3254.
1 parent 24a3254 commit 61a6613

File tree

108 files changed

+10882
-284
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

108 files changed

+10882
-284
lines changed

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -912,7 +912,7 @@ Each plugin README follows a fixed structure. See [check-plugins/example/README.
912912
1. **Overview**: Describes *what* the plugin does. A leading sentence stating the main purpose. This must include at least the text from the plugin's `DESCRIPTION` variable. Followed by subsections:
913913

914914
* **Data Collection**: How data is gathered (shell command, API, psutil, etc.), filtering options, SQLite usage, non-blocking measurement.
915-
* **Compatibility**: Supported platforms only (Linux, Windows, Cross-platform). No version requirements, no tool dependencies, no module requirements - those belong in Important Notes or the Fact Sheet.
915+
* **Compatibility**: Supported platforms, required tools or modules.
916916
* **Important Notes** (optional): Operational edge cases the admin must know before deploying, for example: "Requires sudo", "Only works with Redis 3.0+", "First run returns OK with 'Waiting for more data.'", "After a reboot, counters reset and the check waits for a new baseline". No implementation details - only things that affect deployment and daily operations.
917917

918918
2. **Fact Sheet**: Key properties as a table (download link, check name, check interval, parameters required, Windows support, 3rd party modules, state file path, etc.). Only list applicable rows.

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

Lines changed: 215 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,220 @@ Monitors Apache httpd performance via the mod_status endpoint (server-status?aut
1313

1414
**Compatibility:**
1515

16-
* Cross-platform
16+
* Works with any Apache httpd version that provides `mod_status`
17+
* Some metrics (connection stats, load averages, processes) are only available in newer versions of `mod_status`
1718

19+
**Important Notes:**
1820

19-
**
21+
* `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.
22+
* The check alerts on the percentage of busy workers relative to the total number of worker slots (busy + idle + free)
23+
* Workers in the "Gracefully finishing" (G) state are counted as idle workers, not busy workers
24+
25+
Busy workers (workers serving requests) are:
26+
27+
* `C`: Closing connection
28+
* `D`: DNS Lookup
29+
* `G`: Gracefully finishing
30+
* `I`: Idle cleanup of worker
31+
* `K`: Keepalive (read)
32+
* `L`: Logging
33+
* `R`: Reading Request
34+
* `S`: Starting up
35+
* `W`: Sending Reply
36+
37+
Idle workers are:
38+
39+
* `_`: Waiting for Connection
40+
41+
Free workers are:
42+
43+
* `.`: Open slot with no current process
44+
45+
Load the Apache module:
46+
47+
```text
48+
LoadModule status_module modules/mod_status.so
49+
```
50+
51+
If you want to configure `/server-status` in your main Apache config file:
52+
53+
```text
54+
<IfModule status_module>
55+
# the alias prevents the processing of .htaccess files, which could contain RewriteRules
56+
# that interfere with server-status
57+
Alias /server-status /dev/null
58+
ExtendedStatus On
59+
<Location /server-status>
60+
SetHandler server-status
61+
Require local
62+
</Location>
63+
</IfModule>
64+
```
65+
66+
If you want to configure `/server-status` in a virtual host:
67+
68+
```text
69+
<IfModule status_module>
70+
ExtendedStatus On
71+
</IfModule>
72+
73+
<VirtualHost *:80>
74+
ServerName localhost
75+
<IfModule status_module>
76+
# the alias prevents the processing of .htaccess files, which could contain RewriteRules
77+
# that interfere with server-status
78+
Alias /server-status /dev/null
79+
<Location /server-status>
80+
SetHandler server-status
81+
Require local
82+
</Location>
83+
</IfModule>
84+
</VirtualHost>
85+
```
86+
87+
88+
## Fact Sheet
89+
90+
| Fact | Value |
91+
|----|----|
92+
| Check Plugin Download | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/apache-httpd-status> |
93+
| Nagios/Icinga Check Name | `check_apache_httpd_status` |
94+
| Check Interval Recommendation | Every minute |
95+
| Can be called without parameters | Yes |
96+
| Compiled for Windows | No |
97+
| Uses State File | `$TEMP/linuxfabrik-monitoring-plugins-apache-httpd-status.db` |
98+
99+
100+
## Help
101+
102+
```text
103+
usage: apache-httpd-status [-h] [-V] [--always-ok] [-c CRIT] [--insecure]
104+
[--no-proxy] [--test TEST] [--timeout TIMEOUT]
105+
[-u URL] [-w WARN]
106+
107+
Monitors Apache httpd performance via the mod_status endpoint (server-
108+
status?auto). Alerts when worker usage exceeds the configured thresholds.
109+
Reports busy and idle workers, request rates, bytes served, CPU load,
110+
connection states, and system load averages. Requires "ExtendedStatus On" in
111+
the Apache configuration for full metrics. Uses a local SQLite database to
112+
calculate per-second rates from cumulative counters.
113+
114+
options:
115+
-h, --help show this help message and exit
116+
-V, --version show program's version number and exit
117+
--always-ok Always returns OK.
118+
-c, --critical CRIT CRIT threshold for the percentage of workers processing
119+
requests. Default: >= 95
120+
--insecure This option explicitly allows insecure SSL connections.
121+
--no-proxy Do not use a proxy.
122+
--test TEST For unit tests. Needs "path-to-stdout-file,path-to-
123+
stderr-file,expected-retc".
124+
--timeout TIMEOUT Network timeout in seconds. Default: 8 (seconds)
125+
-u, --url URL Apache Server Status URL. Default:
126+
http://localhost/server-status
127+
-w, --warning WARN WARN threshold for the percentage of workers processing
128+
requests. Default: >= 80
129+
```
130+
131+
132+
## Usage Examples
133+
134+
```bash
135+
./apache-httpd-status --url http://apache-httpd/server-status --warning 80 --critical 90
136+
```
137+
138+
Output:
139+
140+
```text
141+
192.168.122.97: 2/400 workers busy (0.5%; 0 "G"), 98 idle, 300 free; 54.0 accesses, 122.0KiB traffic; Up 1W 1D
142+
143+
Key ! Value
144+
-------------------------------+-----------------------------------------------------
145+
Current Time ! Wednesday, 28-Jul-2021 14:40:48 CEST
146+
Restart Time ! Monday, 19-Jul-2021 20:17:11 CEST
147+
Check Interval ! 3m 52s
148+
Uptime ! 1W 1D
149+
Requests ! 54.0
150+
Bytes ! 122.0KiB
151+
Request Duration ! 10s 28ms
152+
Load1 ! 0.08
153+
Load5 ! 0.06
154+
Load15 ! 0.01
155+
Workers Total ! 400
156+
Busy ! 2
157+
Idle ! 98
158+
Usage (%) ! 0.5
159+
Parent Server ConfigGeneration ! 19
160+
Parent Server MPMGeneration ! 18
161+
Server Name ! 192.168.122.97
162+
Server MPM ! worker
163+
Server Version ! Apache/2.4.48 (Fedora) OpenSSL/1.1.1k mod_qos/11.66
164+
Server Built ! Jun 2 2021 00:00:00
165+
```
166+
167+
168+
## States
169+
170+
* OK if the percentage of busy workers is below the warning threshold.
171+
* OK with "Waiting for more data." on the first run or after an Apache restart.
172+
* WARN if the percentage of busy workers is >= `--warning` (default: 80).
173+
* CRIT if the percentage of busy workers is >= `--critical` (default: 95).
174+
* `--always-ok` suppresses all alerts and always returns OK.
175+
176+
177+
## Perfdata / Metrics
178+
179+
| Name | Type | Description |
180+
|----|----|----|
181+
| Accesses | Number | Total number of accesses during the check interval. |
182+
| BusyWorkers | Number | Number of workers currently processing requests. |
183+
| Bytes | Bytes | Total bytes served during the check interval. |
184+
| ConnsAsyncClosing | Number | Number of async connections in closing state. |
185+
| ConnsAsyncKeepAlive | Number | Number of async connections in keep-alive state. |
186+
| ConnsAsyncWriting | Number | Number of async connections in writing state. |
187+
| ConnsTotal | Number | Total number of connections. |
188+
| CPULoad | Number | CPU load of the Apache process. |
189+
| IdleWorkers | Number | Number of idle workers (finishing + waiting). |
190+
| Load1 | Number | System load average, 1 minute. |
191+
| Load15 | Number | System load average, 15 minutes. |
192+
| Load5 | Number | System load average, 5 minutes. |
193+
| ParentServerConfigGeneration | Number | Apache configuration generation counter. |
194+
| ParentServerMPMGeneration | Number | Apache MPM generation counter. |
195+
| Processes | Number | Number of Apache processes. |
196+
| Stopping | Number | Number of stopping processes. |
197+
| Total Duration | Seconds | Total duration of all requests during the check interval. |
198+
| TotalWorkers | Number | Total number of worker slots (busy + idle + free). |
199+
| Uptime | Seconds | Time the server has been running. |
200+
| WorkerUsagePercentage | Percentage | Percentage of workers currently processing requests. |
201+
| workers_closing | Number | Workers closing connections ("C" in scoreboard). |
202+
| workers_dns | Number | Workers performing DNS lookup ("D" in scoreboard). |
203+
| workers_finishing | Number | Workers gracefully finishing ("G" in scoreboard). |
204+
| workers_free | Number | Open slots with no current process ("." in scoreboard). |
205+
| workers_idle | Number | Workers in idle cleanup ("I" in scoreboard). |
206+
| workers_keepalive | Number | Workers in keepalive read ("K" in scoreboard). |
207+
| workers_logging | Number | Workers logging ("L" in scoreboard). |
208+
| workers_reading | Number | Workers reading request ("R" in scoreboard). |
209+
| workers_replying | Number | Workers sending reply ("W" in scoreboard). |
210+
| workers_starting | Number | Workers starting up ("S" in scoreboard). |
211+
| workers_waiting | Number | Workers waiting for connection ("_" in scoreboard). |
212+
213+
214+
## Troubleshooting
215+
216+
From <https://httpd.apache.org/docs/2.4/mod/mod_status.html#troubleshoot>:
217+
218+
> The check may be used as a starting place for troubleshooting a situation where your server is consuming all available resources (CPU or memory), and you wish to identify which requests or clients are causing the problem.
219+
>
220+
> First, ensure that you have `ExtendedStatus` set on, so that you can see the full request and client information for each child or thread.
221+
>
222+
> Now look in your process list (using top, or similar process viewing utility) to identify the specific processes that are the main culprits. Order the output of top by CPU usage, or memory usage, depending on what problem you're trying to address.
223+
>
224+
> Reload the server-status page, and look for those process ids, and you'll be able to see what request is being served by that process, for what client. Requests are transient, so you may need to try several times before you catch it in the act, so to speak.
225+
>
226+
> This process should give you some idea what client, or what type of requests, are primarily responsible for your load problems. Often you will identify a particular web application that is misbehaving, or a particular client that is attacking your site.
227+
228+
229+
## Credits, License
230+
231+
* Authors: [Linuxfabrik GmbH, Zurich](https://www.linuxfabrik.ch)
232+
* License: The Unlicense, see [LICENSE file](https://unlicense.org/).

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

Lines changed: 84 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,91 @@ Checks the installed Apache httpd version against the endoflife.date API and ale
1212

1313
**Compatibility:**
1414

15-
* Cross-platform
16-
17-
**Important Notes:**
18-
1915
* Runs on all systems where the Apache binary is named either `httpd` or `apache2`
2016
* Must run on the Apache httpd server itself to detect the installed version
2117

2218

23-
##
19+
## Fact Sheet
20+
21+
| Fact | Value |
22+
|----|----|
23+
| Check Plugin Download | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/apache-httpd-version> |
24+
| Nagios/Icinga Check Name | `check_apache_httpd_version` |
25+
| Check Interval Recommendation | Once a day |
26+
| Can be called without parameters | Yes |
27+
| Compiled for Windows | No |
28+
| Uses State File | `$TEMP/linuxfabrik-lib-version.db` |
29+
30+
31+
## Help
32+
33+
```text
34+
usage: apache-httpd-version [-h] [-V] [--always-ok] [--check-major]
35+
[--check-minor] [--check-patch] [--insecure]
36+
[--no-proxy] [--offset-eol OFFSET_EOL]
37+
[--timeout TIMEOUT]
38+
39+
Checks the installed Apache httpd version against the endoflife.date API and
40+
alerts if the version is end-of-life or if newer major, minor, or patch
41+
releases are available. By default, alerts 30 days before the official EOL
42+
date. The offset is configurable.
43+
44+
options:
45+
-h, --help show this help message and exit
46+
-V, --version show program's version number and exit
47+
--always-ok Always returns OK.
48+
--check-major Alert when a new major release is available, even if
49+
the current version is not yet EOL. Example: running
50+
v26 (not yet EOL) and v27 is available.
51+
--check-minor Alert when a new major.minor release is available,
52+
even if the current version is not yet EOL. Example:
53+
running v26.2 (not yet EOL) and v26.3 is available.
54+
--check-patch Alert when a new major.minor.patch release is
55+
available, even if the current version is not yet EOL.
56+
Example: running v26.2.7 (not yet EOL) and v26.2.8 is
57+
available.
58+
--insecure This option explicitly allows insecure SSL
59+
connections.
60+
--no-proxy Do not use a proxy.
61+
--offset-eol OFFSET_EOL
62+
Alert n days before ("-30") or after an EOL date ("30"
63+
or "+30"). Default: -30 days
64+
--timeout TIMEOUT Network timeout in seconds. Default: 8 (seconds)
65+
```
66+
67+
68+
## Usage Examples
69+
70+
```bash
71+
./apache-httpd-version --offset-eol=-30
72+
```
73+
74+
Output:
75+
76+
```text
77+
Apache httpd v2.4.37 (EOL unknown, patch 2.4.57 available)
78+
```
79+
80+
81+
## States
82+
83+
* OK if the installed version is not EOL and no newer releases are flagged.
84+
* WARN if the installed version is EOL (or will be within `--offset-eol` days, default: -30).
85+
* WARN if `--check-major` is set and a newer major version is available.
86+
* WARN if `--check-minor` is set and a newer minor version is available.
87+
* WARN if `--check-patch` is set and a newer patch version is available.
88+
* UNKNOWN if Apache httpd is not found.
89+
* `--always-ok` suppresses all alerts and always returns OK.
90+
91+
92+
## Perfdata / Metrics
93+
94+
| Name | Type | Description |
95+
|----|----|----|
96+
| apache-httpd-version | Number | Installed Apache httpd version as float, e.g. "2.4.57" becomes "2.457". |
97+
98+
99+
## Credits, License
100+
101+
* Authors: [Linuxfabrik GmbH, Zurich](https://www.linuxfabrik.ch)
102+
* License: The Unlicense, see [LICENSE file](https://unlicense.org/).

0 commit comments

Comments
 (0)