fail2ban: banning brute-force attackers from your logs

01The idea: a bouncer who reads the guest book

Imagine a club bouncer who checks the logbook every few seconds. If the same person tried the wrong password five times in ten minutes, they are refused entry for an hour. That is fail2ban. Technically it is a Python daemon that follows log files or the systemd journal, matches each new line against regular expressions, counts matches per IP address, and when a threshold is crossed runs an action, usually adding a firewall rule (nftables, iptables or ufw) that drops the attacker's packets. After the ban time it removes the rule. It is called log-based intrusion prevention: it does not inspect traffic itself, it reacts to what your services already log. That makes it lightweight and service-agnostic: anything that logs failures with an IP can be protected.

02Jails, filters and actions

fail2ban is built from three pieces. A filter (filter.d/*.conf) is a set of regular expressions that recognise a failure in a log line and capture the host with the <HOST> tag. An action (action.d/*.conf) says what to do on ban and unban: firewall rules, a Cloudflare API call, an email. A jail ties them together: which log to read, which filter and action to use, and the thresholds. The thresholds are three numbers. maxretry is how many failures trigger a ban. findtime is the window in which those failures must happen. bantime is how long the ban lasts. With bantime.increment, repeat offenders get longer bans each time. The recidive jail goes further: it watches fail2ban's own log and bans IPs that keep getting banned, for days. Never edit jail.conf, which updates overwrite; put your settings in jail.local or jail.d/*.local.

• maxretry = 5, findtime = 10m, bantime = 1h is a sensible starting point.
• ignoreip keeps your own office or VPN addresses from ever being banned.
• On Ubuntu 24.04 and newer the sshd jail reads the systemd journal (backend = systemd), not /var/log/auth.log.

03A practical jail.local for SSH and nginx

This configuration protects SSH and the common nginx cases using filters that ship with fail2ban. nginx-http-auth catches failed basic-auth logins, nginx-botsearch catches bots requesting well-known exploit paths that return 404, and nginx-limit-req bans clients that repeatedly hit an nginx rate limit (it only works if you configured limit_req). Recidive handles persistent attackers. On Ubuntu, install with apt install fail2ban; the package already enables the sshd jail through jail.d/defaults-debian.conf with the nftables action. After editing, run fail2ban-client reload and check the status. If you use ufw and prefer to see bans in ufw status, set banaction = ufw instead.

1# /etc/fail2ban/jail.local
2[DEFAULT]
3bantime  = 1h
4findtime = 10m
5maxretry = 5
6bantime.increment = true
7ignoreip = 127.0.0.1/8 ::1 203.0.113.10
8 
9[sshd]
10enabled  = true
11backend  = systemd
12maxretry = 3
13 
14[nginx-http-auth]
15enabled = true
16[nginx-botsearch]
17enabled = true
18[recidive]
19enabled  = true
20bantime  = 1w
21findtime = 1d

04Writing your own filter

You can protect anything that logs failures. A common example: a Laravel or Next.js site that is constantly probed for WordPress login pages and leaked .env files. Those requests are never legitimate on a non-WordPress site, so a few of them are a strong signal. The filter below matches such requests in the nginx access log (default combined format, where the client IP is the first field). Always test a new filter with fail2ban-regex against a real log before enabling it; it shows how many lines matched and catches regex mistakes that would ban nobody, or everybody. If the site is behind Cloudflare or another proxy, configure nginx's real_ip module first, otherwise the log contains the proxy's IP and you would ban the proxy.

1# /etc/fail2ban/filter.d/nginx-probe.conf
2[Definition]
3failregex = ^<HOST> -.*"(GET|POST|HEAD) /(wp-login\.php|xmlrpc\.php|\.env|\.git/)
4ignoreregex =
5 
6# /etc/fail2ban/jail.d/nginx-probe.local
7[nginx-probe]
8enabled  = true
9port     = http,https
10logpath  = /var/log/nginx/access.log
11maxretry = 2
12bantime  = 1d
13 
14# Test before enabling
15sudo fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/nginx-probe.conf

05Checking, unbanning and debugging

fail2ban-client is the control tool. status shows the active jails, status with a jail name shows current failures and banned IPs, and set jail unbanip removes a ban (for example when a colleague mistyped their password too often). The fail2ban log, /var/log/fail2ban.log, records every ban and unban with the jail name, which is the first place to look when someone says they are locked out. If a jail never bans anything, check three things: the jail is actually enabled (status lists it), it reads the right source (log path or systemd backend), and the filter really matches the lines (fail2ban-regex). If it bans but traffic still arrives, the action may not match your firewall, or the traffic comes through a proxy whose IP is not the attacker's.

1sudo fail2ban-client status                 # list active jails
2sudo fail2ban-client status sshd            # failures and banned IPs for one jail
3sudo fail2ban-client banned                 # all banned IPs, per jail
4sudo fail2ban-client set sshd unbanip 203.0.113.10
5sudo fail2ban-client unban 203.0.113.10     # remove from every jail
6sudo fail2ban-client reload                 # apply config changes
7sudo tail -f /var/log/fail2ban.log
8sudo nft list ruleset | grep -A3 f2b        # see the firewall rules it created

06Limits, and fail2ban vs CrowdSec

fail2ban only sees attacks after they appear in a log, and it judges each IP separately. A distributed attack from thousands of addresses, each trying once or twice, never crosses the threshold. It does nothing against vulnerabilities in your app, and banning at the server firewall does not help when traffic arrives through a CDN proxy, because the connection comes from the CDN; there you need an action that blocks at the edge (fail2ban ships Cloudflare actions) or the CDN's own WAF rules. So treat it as noise reduction on top of real controls: SSH keys only, a default-deny firewall, rate limits in nginx, and a WAF such as Cloudflare in front. CrowdSec is the modern alternative: it parses logs similarly, but separates detection from blocking (bouncers for firewall, nginx or Cloudflare) and shares signals across its community, so an IP attacking others can be blocked before it reaches you. It is more powerful, with more moving parts and an online component.

07Inside the engine: backends, dates and the ban database

Each jail has a backend that delivers new log lines. systemd reads the journal directly and filters by unit, which is what modern Ubuntu needs for SSH. For plain files, auto tries pyinotify and falls back to polling. Every line must contain a timestamp that fail2ban recognises; it uses the time from the log, not the time it read the line, to decide whether a failure falls inside findtime. A wrong datepattern or a timezone mismatch makes failures look old, and the jail silently never bans. Bans are persisted in an SQLite database, /var/lib/fail2ban/fail2ban.sqlite3, so they are restored after a restart or reboot. dbpurgeage, one day by default, decides how long ban history is kept. That matters for recidive and incremental bans: if your recidive findtime is a week but history is purged after a day, repeat offenders are never recognised. Raise dbpurgeage in fail2ban.local to exceed your longest findtime.

1# /etc/fail2ban/fail2ban.local
2[Definition]
3dbpurgeage = 8d      # must be longer than recidive findtime
4 
5# Check which date format and lines a filter matches
6sudo fail2ban-regex systemd-journal sshd
7sudo fail2ban-regex --print-all-missed /var/log/nginx/access.log nginx-probe

08Incremental bans: punishing repeat offenders

A flat one-hour ban teaches a bot to come back in sixty-one minutes. With bantime.increment, fail2ban looks up how often the address was banned before and multiplies the ban. The default formula doubles it each time (ban time times two to the power of the ban count), so 1h becomes 2h, 4h, 8h and so on; bantime.multipliers lets you give an explicit sequence instead. bantime.maxtime caps the growth so a mistake does not lock a real user out for months, and bantime.rndtime adds a random extra so bots cannot time the unban precisely. bantime.overalljails = true counts previous bans from every jail, not only the current one: an address that probed nginx yesterday gets a longer SSH ban today. Together with persistent history, this often makes the separate recidive jail unnecessary, although keeping both is harmless.

1# /etc/fail2ban/jail.local
2[DEFAULT]
3bantime  = 1h
4bantime.increment   = true
5bantime.factor      = 1
6bantime.maxtime     = 1w
7bantime.rndtime     = 10m
8bantime.overalljails = true
9# alternative to the formula:
10# bantime.multipliers = 1 2 4 8 16 32 64

09Actions at scale: nftables sets, IPv6 and the edge

Older iptables actions added one rule per banned address, and every packet walked through that list, which gets slow with thousands of bans. The nftables actions used by Debian and Ubuntu put addresses into a set inside an inet f2b-table, which is a hash lookup regardless of size and covers IPv4 and IPv6 in one table. The allports variant blocks every port, useful for recidive, while multiport blocks only the jail's ports. IPv6 needs thought: fail2ban bans single addresses, but one attacker may control a whole /64 and simply rotate. That is another reason to keep rate limits and keys-only SSH as the real controls. For HTTP behind Cloudflare, the cloudflare-token action creates a zone access rule through the Cloudflare API with a scoped token, so the block happens at the edge where the traffic actually arrives. Combine it with the local action so SSH and direct-to-origin hits are still blocked on the server.

1# See the nftables sets fail2ban maintains
2sudo nft list table inet f2b-table
3 
4# jail.d/nginx-probe.local: block locally and at Cloudflare
5[nginx-probe]
6action = %(action_)s
7         cloudflare-token[cfzone="your_zone_id", cftoken="your_scoped_token"]

10Writing filters that cannot be abused

A filter turns untrusted text into firewall rules, so it is a security boundary. Logs often contain attacker-controlled fields: a username, a URL, a User-Agent. If a regex is not anchored, an attacker can put a victim's IP address inside such a field and make you ban that victim, for example your payment provider or your monitoring service. This log injection risk is why shipped filters anchor on the fixed structure of the line and capture <HOST> only where the service itself writes the client address. Rules for custom filters: anchor with ^ and match the exact log format, capture the host from the field your server controls, keep the pattern specific to one failure meaning, and avoid nested greedy wildcards that are slow on long lines. Use ignoreregex for known-good traffic such as health checks. Test with fail2ban-regex against a week of real logs and look at both matched and missed lines before enabling.