Fail2Ban is a security tool that monitors system logs for repeated failed authentication attempts and temporarily blocks the IP addresses responsible.
It is particularly useful for protecting services such as SSH from brute-force attacks.
In this guide, we will configure Fail2Ban on Ubuntu to:
- Monitor SSH login attempts
- Ban an IP after repeated failures
- Use
systemdas the logging backend - Keep an IP banned for one day
- Whitelist trusted subnet addresses
- Test and verify the configuration
1. Install Fail2Ban
First, update the package information and install Fail2Ban:
1
2
sudo apt update
sudo apt install fail2ban
Verify that the service is running:
1
sudo systemctl status fail2ban
2. Create a Local Configuration
Fail2Ban provides a default configuration file:
1
/etc/fail2ban/jail.conf
It is recommended not to modify jail.conf directly because package upgrades may overwrite it.
Create a local configuration instead:
1
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
Fail2Ban gives priority to settings in jail.local.
3. Configure SSH Protection
Open the local configuration:
1
sudo vim /etc/fail2ban/jail.local
Find the [sshd] section and configure it as follows:
1
2
3
4
5
6
7
8
9
10
11
12
[sshd]
# mode = normal
port = ssh
logpath = %(sshd_log)s
# backend = %(sshd_backend)s
backend = systemd
maxretry = 2
findtime = 10m
bantime = 1d
Configuration Explained
port = ssh
This tells Fail2Ban that the protected service is SSH.
The ssh value normally resolves to the SSH service port configured on the system.
logpath = %(sshd_log)s
This uses Fail2Ban’s predefined SSH log path.
backend = systemd
This tells Fail2Ban to read logs through the systemd journal.
On modern Ubuntu systems, SSH authentication events are commonly available through journald.
The default backend setting is therefore commented out:
1
# backend = %(sshd_backend)s
and explicitly replaced with:
1
backend = systemd
maxretry = 2
An IP address will be banned after 2 failed authentication attempts within the configured findtime period.
1
2
3
4
Attempt 1 → Failed
Attempt 2 → Failed
↓
IP banned
This is a strict setting. If you frequently mistype your credentials, consider using a higher value such as 3 or 5.
findtime = 10m
Fail2Ban looks for failed login attempts occurring within a 10-minute window.
bantime = 1d
The offending IP address will remain banned for one day.
4. Test the Configuration
Before restarting Fail2Ban, validate the configuration:
1
sudo fail2ban-client -t
If there is a syntax or configuration error, Fail2Ban will report it here.
5. Restart Fail2Ban
Once the configuration passes validation, restart the service:
1
sudo systemctl restart fail2ban
Verify the service:
1
sudo systemctl status fail2ban
You should see:
1
Active: active (running)
6. Check the SSH Jail
Fail2Ban organizes protection rules into jails.
The SSH jail is called sshd.
Check its status:
1
sudo fail2ban-client status sshd
Example output:
1
2
3
4
5
6
7
8
Status for the jail: sshd
|- Filter
| |- Currently failed: 0
| |- Total failed: 0
|
`- Actions
|- Currently banned: 0
|- Total banned: 0
The exact numbers depend on activity on your server.
7. Whitelist Trusted IP Addresses
When Fail2Ban is protecting SSH, make sure trusted internal networks cannot accidentally get banned.
Edit the local configuration:
1
sudo vim /etc/fail2ban/jail.local
Add the following under the [DEFAULT] section:
1
2
3
[DEFAULT]
ignoreip = 127.0.0.1/8 100.20.0.0/16 ::1
What These Addresses Mean
1
127.0.0.1/8
The local IPv4 loopback network.
1
::1
The IPv6 loopback address.
1
100.20.0.0/16
The trusted internal subnet.
The 100.20.0.0/16 network covers:
1
100.20.0.0 - 100.20.255.255
Addresses included in ignoreip are excluded from Fail2Ban bans.
Important: Only whitelist networks that you fully trust. An incorrectly configured
ignoreipcan prevent Fail2Ban from protecting those addresses.
8. Apply the Whitelist Configuration
After changing ignoreip, test the configuration again:
1
sudo fail2ban-client -t
Then restart Fail2Ban:
1
sudo systemctl restart fail2ban
Check the SSH jail:
1
sudo fail2ban-client status sshd
9. Check Banned IP Addresses
To see currently banned IP addresses:
1
sudo fail2ban-client status sshd
Look for:
1
Currently banned
and:
1
Banned IP list
Example:
1
2
|- Currently banned: 1
`- Banned IP list: 203.0.113.10
10. Manually Unban an IP
If you accidentally ban a trusted IP, manually remove the ban:
1
sudo fail2ban-client set sshd unbanip <IP_ADDRESS>
For example:
1
sudo fail2ban-client set sshd unbanip 203.0.113.10
Then verify the jail status:
1
sudo fail2ban-client status sshd
11. Useful Fail2Ban Commands
Check Fail2Ban service
1
sudo systemctl status fail2ban
Start Fail2Ban
1
sudo systemctl start fail2ban
Stop Fail2Ban
1
sudo systemctl stop fail2ban
Restart Fail2Ban
1
sudo systemctl restart fail2ban
Test configuration
1
sudo fail2ban-client -t
List active jails
1
sudo fail2ban-client status
Check SSH jail
1
sudo fail2ban-client status sshd
Unban an IP
1
sudo fail2ban-client set sshd unbanip <IP_ADDRESS>
12. Final Configuration
A simple configuration based on this setup can look like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
[DEFAULT]
ignoreip = 127.0.0.1/8 100.20.0.0/16 ::1
[sshd]
port = ssh
logpath = %(sshd_log)s
backend = systemd
maxretry = 2
findtime = 10m
bantime = 1d
The resulting behavior is:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
SSH Server
│
▼
Failed SSH Login
│
▼
Fail2Ban monitors
the event
│
▼
┌─────────────────────┐
│ Failed attempts │
│ within 10 minutes │
└─────────────────────┘
│
2 failures
│
▼
BAN IP
│
▼
1 day
Trusted addresses configured through ignoreip are excluded from this process.