Skip to content

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 ping to verify the fail2ban server is alive
  • Runs fail2ban-client status to 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-client call does not return within --timeout (default: 8 seconds), typically because the fail2ban server hangs.
  • UNKNOWN if fail2ban-client ping fails or fail2ban-client status returns an error.
  • UNKNOWN if a --trusted-ip value is neither an IP address nor a network in CIDR notation.
  • UNKNOWN if --socket resolves outside /run or /var/run, or if anybody but root could replace the socket or a directory above it.
  • --warning and --critical accept Nagios range expressions.
  • Jails matching --ignore are excluded from both the output and the alerting.
  • --no-match-severity sets the state reported when the filters match no jail and nothing is checked (default: ok); set it to warn, crit, or unknown to alert on an empty selection (for example a filter typo or a missing jail) instead of silently returning OK.
  • --always-ok suppresses 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