Overview
Fail2Ban is an intrusion prevention framework written in Python. It scans system logs (e.g., auth logs, mail server logs, web server logs) for patterns matching malicious activities—such as brute-force authentication attacks, port scanning, and vulnerability probing—and dynamically adjusts firewall rules (using iptables, nftables, or UFW) to ban the offending IP addresses for a specified duration.
When to Use
- Hardening SSH access endpoints on public cloud instances.
- Protecting web applications (e.g., Nginx HTTP Basic Auth, WordPress login portals) against dictionary brute-force attacks.
- Mitigating bot probing and search engine crawler spam on public web apps.
- Securing SMTP, IMAP, or database ports from automated connection floods.
Prerequisites
- Linux server (Debian/Ubuntu systems used in examples).
sudo or root access.
- Firewall backend installed (
iptables, nftables, or UFW).
Procedure
Install Fail2Ban
sudo apt update
sudo apt install fail2ban -y
Enable and start the systemd daemon
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
Configure Jails
Never modify jail.conf directly. Always write overriding rules in /etc/fail2ban/jail.local.
# /etc/fail2ban/jail.local - Custom server override rules
[DEFAULT]
bantime = 1h # Duration of the ban (m=minutes, h=hours, d=days)
findtime = 10m # Period within which failed retries trigger a ban
maxretry = 5 # Number of failures allowed within findtime
banaction = nftables-multiport # Firewall backend choice
ignoreip = 127.0.0.1/8 192.168.1.0/24 # Trust local subnets
[sshd]
enabled = true
port = ssh
maxretry = 3 # Stricter retry limits for SSH
bantime = 24h # Ban SSH attackers for a full day
logpath = /var/log/auth.log
[nginx-http-auth]
enabled = true
port = http,https
filter = nginx-http-auth
logpath = /var/log/nginx/error.log
maxretry = 5
[nginx-limit-req]
enabled = true
port = http,https
filter = nginx-limit-req
logpath = /var/log/nginx/error.log
maxretry = 10
bantime = 2h
Create Custom Filters (Optional)
For custom applications, write a filter pattern file in /etc/fail2ban/filter.d/my-app.conf:
# /etc/fail2ban/filter.d/my-app.conf
[Definition]
failregex = ^<HOST> - - \[.*\] "POST /api/login HTTP/.*" 401 .*$
ignoreregex =
Validate Custom Filters
Before activating the filter, validate your regular expression against target log lines:
fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/my-app.conf
Manage Active Bans via Client CLI
# Get overall status
sudo fail2ban-client status
# Get detailed statistics for a specific jail
sudo fail2ban-client status sshd
# Manually ban an offending IP
sudo fail2ban-client set sshd banip 198.51.100.42
# Unban a mistakenly blocked IP
sudo fail2ban-client set sshd unbanip 198.51.100.42
Pitfalls
- Systemd Journal Logs: Modern Linux installations (like Debian 12 or Ubuntu 24.04) log auth attempts via
systemd-journald instead of writing raw text files to /var/log/auth.log. If Fail2Ban is not monitoring attempts, configure the backend parameter: backend = systemd in jail.local.
- Log Rotation Delays: If log rotation utilities compress logs (e.g.,
auth.log.1.gz) too frequently, Fail2Ban can lose track of the open file descriptors, missing failed attempts during rotation windows.
- Lockout Risk: Never configure Fail2Ban without white-listing your local IP ranges or corporate VPN subnets in the
ignoreip parameter. Doing so runs the risk of locking yourself out of your remote server if you mistype your password a few times.
- Proxy Load Balancers: If your application is deployed behind a proxy load balancer (like Cloudflare, AWS ALB, or HAProxy), you must configure your web servers to parse
X-Forwarded-For headers so Fail2Ban logs the real client IP rather than the proxy's IP. Banning the proxy IP will block access for all users.
Verification
- Verify service runtime status
sudo systemctl status fail2ban
- Verify jail status and banned IPs
sudo fail2ban-client status
sudo fail2ban-client status sshd
- Verify custom regex matches
fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/my-app.conf
Related skills
ufw - Uncomplicated Firewall configuration
nftables - Modern Linux firewalling
ssh-hardening - Securing SSH daemon configurations
1---
2name: fail2ban
3description: "Installs Linux Fail2Ban with jail.local overrides so sshd, nginx, and mail log matches become nftables, iptables, or UFW bans, managed through fail2ban-client. Trigger when SSH, HTTP basic-auth, WordPress logins, or SMTP/IMAP face brute-force and bot probes. Not a WAF, IDS, or CDN bot-management product. Do not use on Windows hosts or behind a load balancer without real client IPs in logs."
4version: 1.0.1
5tags:
6 - devops
7 - cloud
8 - automation
9 - operations
10 - security
11tools:
12 - gemini
13 - codex
14metadata:
15 source: https://skillmd.com/skills/kayforkind/fail2ban
16---
17
18## Overview
19Fail2Ban is an intrusion prevention framework written in Python. It scans system logs (e.g., auth logs, mail server logs, web server logs) for patterns matching malicious activities—such as brute-force authentication attacks, port scanning, and vulnerability probing—and dynamically adjusts firewall rules (using `iptables`, `nftables`, or `UFW`) to ban the offending IP addresses for a specified duration.
20
21## When to Use
22- Hardening SSH access endpoints on public cloud instances.
23- Protecting web applications (e.g., Nginx HTTP Basic Auth, WordPress login portals) against dictionary brute-force attacks.
24- Mitigating bot probing and search engine crawler spam on public web apps.
25- Securing SMTP, IMAP, or database ports from automated connection floods.
26
27## Prerequisites
28- Linux server (Debian/Ubuntu systems used in examples).
29- `sudo` or root access.
30- Firewall backend installed (`iptables`, `nftables`, or `UFW`).
31
32## Procedure
33
341. **Install Fail2Ban**
35 ```bash
36 sudo apt update
37 sudo apt install fail2ban -y
38 ```
39
402. **Enable and start the systemd daemon**
41 ```bash
42 sudo systemctl enable fail2ban
43 sudo systemctl start fail2ban
44 ```
45
463. **Configure Jails**
47 Never modify `jail.conf` directly. Always write overriding rules in `/etc/fail2ban/jail.local`.
48 ```ini
49 # /etc/fail2ban/jail.local - Custom server override rules
50
51 [DEFAULT]
52 bantime = 1h # Duration of the ban (m=minutes, h=hours, d=days)
53 findtime = 10m # Period within which failed retries trigger a ban
54 maxretry = 5 # Number of failures allowed within findtime
55 banaction = nftables-multiport # Firewall backend choice
56 ignoreip = 127.0.0.1/8 192.168.1.0/24 # Trust local subnets
57
58 [sshd]
59 enabled = true
60 port = ssh
61 maxretry = 3 # Stricter retry limits for SSH
62 bantime = 24h # Ban SSH attackers for a full day
63 logpath = /var/log/auth.log
64
65 [nginx-http-auth]
66 enabled = true
67 port = http,https
68 filter = nginx-http-auth
69 logpath = /var/log/nginx/error.log
70 maxretry = 5
71
72 [nginx-limit-req]
73 enabled = true
74 port = http,https
75 filter = nginx-limit-req
76 logpath = /var/log/nginx/error.log
77 maxretry = 10
78 bantime = 2h
79 ```
80
814. **Create Custom Filters (Optional)**
82 For custom applications, write a filter pattern file in `/etc/fail2ban/filter.d/my-app.conf`:
83 ```ini
84 # /etc/fail2ban/filter.d/my-app.conf
85 [Definition]
86 failregex = ^<HOST> - - \[.*\] "POST /api/login HTTP/.*" 401 .*$
87 ignoreregex =
88 ```
89
905. **Validate Custom Filters**
91 Before activating the filter, validate your regular expression against target log lines:
92 ```bash
93 fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/my-app.conf
94 ```
95
966. **Manage Active Bans via Client CLI**
97 ```bash
98 # Get overall status
99 sudo fail2ban-client status
100
101 # Get detailed statistics for a specific jail
102 sudo fail2ban-client status sshd
103
104 # Manually ban an offending IP
105 sudo fail2ban-client set sshd banip 198.51.100.42
106
107 # Unban a mistakenly blocked IP
108 sudo fail2ban-client set sshd unbanip 198.51.100.42
109 ```
110
111## Pitfalls
112- **Systemd Journal Logs**: Modern Linux installations (like Debian 12 or Ubuntu 24.04) log auth attempts via `systemd-journald` instead of writing raw text files to `/var/log/auth.log`. If Fail2Ban is not monitoring attempts, configure the backend parameter: `backend = systemd` in `jail.local`.
113- **Log Rotation Delays**: If log rotation utilities compress logs (e.g., `auth.log.1.gz`) too frequently, Fail2Ban can lose track of the open file descriptors, missing failed attempts during rotation windows.
114- **Lockout Risk**: Never configure Fail2Ban without white-listing your local IP ranges or corporate VPN subnets in the `ignoreip` parameter. Doing so runs the risk of locking yourself out of your remote server if you mistype your password a few times.
115- **Proxy Load Balancers**: If your application is deployed behind a proxy load balancer (like Cloudflare, AWS ALB, or HAProxy), you must configure your web servers to parse `X-Forwarded-For` headers so Fail2Ban logs the real client IP rather than the proxy's IP. Banning the proxy IP will block access for all users.
116
117## Verification
1181. **Verify service runtime status**
119 ```bash
120 sudo systemctl status fail2ban
121 ```
1222. **Verify jail status and banned IPs**
123 ```bash
124 sudo fail2ban-client status
125 sudo fail2ban-client status sshd
126 ```
1273. **Verify custom regex matches**
128 ```bash
129 fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/my-app.conf
130 ```
131
132## Related skills
133- `ufw` - Uncomplicated Firewall configuration
134- `nftables` - Modern Linux firewalling
135- `ssh-hardening` - Securing SSH daemon configurations