Check fail2ban¶
Overview¶
Checks the number of currently banned IP addresses across all fail2ban jails. Reports the total ban count and a per-jail breakdown. Jails can be excluded from the check with a regular expression. Alerts when the number of banned IPs in any jail exceeds the configured thresholds. Alerts as well when fail2ban bans an address that must stay reachable, such as the reverse proxy in front of this host or the monitoring server, so a lockout of everybody behind a proxy shows up at once. Requires root or sudo.
Data Collection:
- Runs
fail2ban-client pingto verify the fail2ban server is alive - Runs
fail2ban-client statusto discover all configured jails - Runs
fail2ban-client status <jail>for each jail to get the current number of banned IPs and, with--trusted-ip, the list of banned addresses
Fact Sheet¶
| Fact | Value |
|---|---|
| Check Plugin Download | https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/fail2ban |
| Nagios/Icinga Check Name | check_fail2ban |
| Check Interval Recommendation | Every minute |
| Can be called without parameters | Yes |
| Runs on | Linux |
| Compiled for Windows | No |
Help¶
usage: fail2ban [-h] [-V] [--always-ok] [-c CRIT] [--ignore IGNORE]
[--no-match-severity {ok,warn,crit,unknown}] [--no-perfdata]
[--socket SOCKET] [--timeout TIMEOUT]
[--trusted-ip TRUSTED_IP] [-w WARN]
Checks the number of currently banned IP addresses across all fail2ban jails.
Reports the total ban count and a per-jail breakdown. Jails can be excluded
from the check with a regular expression. Alerts when the number of banned IPs
in any jail exceeds the configured thresholds. Alerts as well when fail2ban
bans an address that must stay reachable, such as the reverse proxy in front
of this host or the monitoring server, so a lockout of everybody behind a
proxy shows up at once. Requires root or sudo.
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
--always-ok Always returns OK.
-c, --critical CRIT CRIT threshold for the number of banned IPs per jail.
Supports Nagios ranges. Default: 10000
--ignore IGNORE Exclude jails whose name matches this Python regular
expression. Case-sensitive by default; use `(?i)` for
case-insensitive matching. Can be specified multiple
times. Example: `--ignore="^recidive$"`. Default: None
--no-match-severity {ok,warn,crit,unknown}
State to report when no item matches the filters and
nothing is checked. Default: ok
--no-perfdata Suppress the performance data section from the output.
The status message and the exit code are unaffected,
so alerting keeps working while trending data is
dropped.
--socket SOCKET Path to the fail2ban server Unix socket. Passed to
`fail2ban-client --socket`. Must resolve within /run
or /var/run, and nobody but root may be able to
replace it. Default: None
--timeout TIMEOUT Network timeout in seconds. Default: 8 (seconds)
--trusted-ip TRUSTED_IP
IP address or network that fail2ban must never ban,
such as a reverse proxy in front of this host. Alerts
with CRIT if a jail bans it. IPv4 or IPv6, a single
address or a network in CIDR notation. Can be
specified multiple times. Example: `--trusted-
ip=192.0.2.10 --trusted-ip=2001:db8::/64`
-w, --warning WARN WARN threshold for the number of banned IPs per jail.
Supports Nagios ranges. Default: 2500
Documentation:
https://linuxfabrik.github.io/monitoring-plugins/check-plugins/fail2ban/
Usage Examples¶
./fail2ban --warning=2500 --critical=10000 --ignore='^recidive$'
Output:
7406 IPs banned
Jail ! Banned ! Status
---------+--------+----------
sshd ! 5432 ! [WARNING]
portscan ! 1974 ! [OK]
Alert when fail2ban bans the reverse proxy in front of this host. Behind a proxy that Apache logs as the client, a jail that counts failed logins or missing files bans the proxy, and everybody behind it loses access:
./fail2ban --trusted-ip=192.0.2.10 --trusted-ip=2001:db8::/64
Output:
3 IPs banned, 1 trusted address among them [CRITICAL]
Trusted addresses banned:
* 192.0.2.10 in apache-auth, lift the ban with `sudo fail2ban-client set apache-auth unbanip 192.0.2.10`
Add the trusted addresses to `ignoreip` in fail2ban so they are not banned again.
Jail ! Banned ! Status
------------+--------+-----------
apache-auth ! 3 ! [CRITICAL]
sshd ! 0 ! [OK]
States¶
- OK if the number of banned IPs in every checked jail is within
--warning(default: 2500). - WARN if the number of banned IPs in any jail exceeds
--warning(default: 2500). - CRIT if the number of banned IPs in any jail exceeds
--critical(default: 10000). - CRIT if a jail bans an address or network given by
--trusted-ip, whatever the number of banned IPs. - WARN if a
fail2ban-clientcall does not return within--timeout(default: 8 seconds), typically because the fail2ban server hangs. - UNKNOWN if
fail2ban-client pingfails orfail2ban-client statusreturns an error. - UNKNOWN if a
--trusted-ipvalue is neither an IP address nor a network in CIDR notation. - UNKNOWN if
--socketresolves outside/runor/var/run, or if anybody but root could replace the socket or a directory above it. --warningand--criticalaccept Nagios range expressions.- Jails matching
--ignoreare excluded from both the output and the alerting. --no-match-severitysets the state reported when the filters match no jail and nothing is checked (default:ok); set it towarn,crit, orunknownto alert on an empty selection (for example a filter typo or a missing jail) instead of silently returning OK.--always-oksuppresses all alerts and always returns OK.
Perfdata / Metrics¶
| Name | Type | Description |
|---|---|---|
<jail> |
Number | Number of banned IP addresses per jail. |
Troubleshooting¶
Permission denied to socket: /var/run/fail2ban/fail2ban.sock (you must be root)¶
The fail2ban client works only with user root by default. Fail2ban does not have individual permission or a user privilege model. If you allow the fail2ban client accessing the fail2ban server for non-root, you could stop the server, change runtime config, ban, unban, etc.
There are two ways to let a non-root user like nagios or icinga run the check: change the socket permissions, or grant sudo access.
Granting access by changing socket permissions¶
Tested on Debian 11.
The communication takes place via unix-socket /var/run/fail2ban/fail2ban.sock which has the following permissions:
srwx------ 1 root root ... /var/run/fail2ban/fail2ban.sock
Grant access to fail2ban.sock for a user like nagios or icinga:
sudo groupadd fail2ban
sudo usermod --append --groups fail2ban nagios
sudo chown root:fail2ban /var/run/fail2ban/fail2ban.sock
sudo chmod g+w /var/run/fail2ban/fail2ban.sock
After that, this (and the check plugin) should work:
sudo -u nagios /usr/bin/fail2ban-client status
sudo -u nagios /usr/lib64/nagios/plugins/fail2ban
To persist on a system where fail2ban is managed by systemd, add the following to the fail2ban service override file:
sudo systemctl edit fail2ban
[Service]
ExecStartPost=/usr/bin/sh -c "while ! [ -S /var/run/fail2ban/fail2ban.sock ]; do sleep 1; done"
ExecStartPost=/usr/bin/chgrp fail2ban /var/run/fail2ban/fail2ban.sock
ExecStartPost=/usr/bin/chmod g+w /var/run/fail2ban/fail2ban.sock
Granting access using sudo¶
Tested on RHEL 7+.
As an alternative you might add a sudoers rule, for example in /etc/sudoers.d/fail2ban:
icinga ALL = NOPASSWD: /usr/lib64/nagios/plugins/fail2ban
Click this link to find a list of sudoers files for all main Linux distributions for Icinga.
Credits, License¶
- Authors: Linuxfabrik GmbH, Zurich
- License: The Unlicense, see LICENSE file.