fail2ban

How it actually decides to ban an address

fail2ban watches specific log files for patterns matching failed login attempts, and once a source IP crosses a configured threshold of failures within a set time window, it instructs the server's firewall to block that address, either temporarily or permanently.

Why it complements, not replaces, other controls

fail2ban reduces the volume of brute-force attempts that even reach the point of being tried against your login system, but it does nothing to strengthen the login itself, which is why it is typically paired with key-based authentication rather than used alone.

For installation, jail configuration and testing, follow our fail2ban setup guide.

Check the filter against your real logs

An enabled jail can still be blind. The usual cause is a filter that does not match the log format on your distribution, and fail2ban lets you test that without banning anyone. The fail2ban-regex(1) manual page describes a tool that reads a log (a file name or systemd-journal) and a filter, then reports which lines matched. Run it next to a configuration test:

sudo fail2ban-client -t
sudo fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf
sudo fail2ban-regex systemd-journal /etc/fail2ban/filter.d/sshd.conf

The first command tests the configuration, as the fail2ban-client(1) page documents. If the filter matches nothing in a log that clearly contains failed logins, add --print-all-missed to see the lines it skipped: that mismatch is the reason the jail will never ban. The jail.conf(5) page adds two details worth remembering. A logpath glob only covers files that exist when fail2ban starts, and the default auto backend switches to the journal only when no log files are found and a journalmatch is set. After any change to log layout, reload and test again.

Run a test ban from start to finish

The only proof that a ban works is a ban you can see in the firewall. Ban a reserved documentation address by hand, confirm it appears, then undo it:

sudo fail2ban-client set sshd banip 203.0.113.9
sudo fail2ban-client get sshd banip --with-time
sudo nft list ruleset
sudo iptables -S
sudo fail2ban-client set sshd unbanip 203.0.113.9

Use whichever of the two firewall listing commands matches your host. The default ban action is iptables-multiport according to jail.conf(5), so on a server whose firewall is managed through nftables or another tool, check that the banaction your distribution configured really produces a rule you can see. If fail2ban reports an address as banned but the firewall shows nothing, the jail is decorative. Also remember that ignoreself defaults to true, so failed logins from the server's own addresses never trigger a ban, which can fool a test run from the machine itself.

Once a change passes, apply it with sudo fail2ban-client reload, which re-reads the configuration without restarting the server. For the full jail layout, see the setup guide, and for the SSH side of the same defence, the SSH hardening guide.

Related terms: fail2ban jail, Intrusion prevention, Brute-force attack, Rate limiting, MaxAuthTries, journalctl.