Fail2ban: automatically block attacks on SSH

Fail2ban watches login records and temporarily blocks an IP address in the firewall when it enters a wrong password again and again. You'll install it, set sensible rules including a harsher penalty for repeat attackers, and learn how to unblock an address if it happens to you.

What fail2ban does#

Fail2ban works with jails. Each jail watches one service and has three parts:

When an address makes maxretry failures within findtime, fail2ban blocks it for bantime. When the time is up, it unblocks it by itself.

Installation#

This applies to both Ubuntu 24.04 and Debian 13.

1. Update the package list and install fail2ban:

   apt update
   apt install fail2ban

   • fail2ban – the program itself. python3-systemd is installed as a dependency too, which lets it read the system journal.

2. Check that the nft tool, which fail2ban uses for blocking, is available:

   command -v nft || apt install nftables

   • command -v nft – prints the path to the nft program if it exists.
   • || – the next command runs only if the previous one failed, meaning when nft is missing.
   • apt install nftables – installs the tool. Installing it doesn't turn on any rules or change UFW.

3. Check that the service is running:

   systemctl status fail2ban

   Look for the line Active: active (running). Quit the output with q.

Right after installation, fail2ban already protects SSH with the distribution's default settings: the sshd jail is on, reads records from the system journal and blocks through nftables. But the default ban is only 10 minutes, so adjust the settings.

Why jail.local and not jail.conf#

The default settings are in /etc/fail2ban/jail.conf and in /etc/fail2ban/jail.d/defaults-debian.conf. Don't edit these files; a package update could overwrite them. Your own settings go in /etc/fail2ban/jail.local. Fail2ban reads the files in the order jail.conf › jail.d/*.conf › jail.local › jail.d/*.local, and a later value always overrides an earlier one.

Configuration line by line#

1. Create the file:

   nano /etc/fail2ban/jail.local

2. Put this in it:

   [DEFAULT]
   # Addresses that are never banned (separated by spaces)
   ignoreip = 127.0.0.1/8 ::1
   # Length of the first ban
   bantime = 1h
   # Window in which failed attempts are counted
   findtime = 10m
   # Number of failed attempts that triggers a ban
   maxretry = 5
   # Ban repeat offenders for longer
   bantime.increment = true
   bantime.factor = 1
   bantime.maxtime = 1w
   
   [sshd]
   enabled = true
   port = ssh
   backend = systemd
   
   [recidive]
   enabled = true
   backend = auto
   logpath = /var/log/fail2ban.log
   banaction = %(banaction_allports)s
   bantime = 1w
   findtime = 1d
   maxretry = 5

3. Save (Ctrl+O, Enter) and close the editor (Ctrl+X).

Sections in square brackets: [DEFAULT] applies to all jails; [sshd] and [recidive] apply only to that jail and take precedence over [DEFAULT].

Recidive: a harsher penalty for repeat attackers#

The recidive jail reads fail2ban's own records (/var/log/fail2ban.log). When the same address gets at least maxretry (5) blocks in any jail within findtime (1 day), recidive blocks it for bantime (1 week) and on all ports. An attacker who keeps coming back thus loses access to the VPS completely.

That's why recidive reads a file (backend = auto) and not the journal: fail2ban writes its records to the file /var/log/fail2ban.log, not to the journal.

For fail2ban to remember the block history long enough (for bantime.increment and for restoring week-long blocks after a restart), extend how long it's kept in the database:

nano /etc/fail2ban/fail2ban.local

[Definition]
dbpurgeage = 8d

Starting and checking#

1. Check the configuration:

   fail2ban-client -t

   • -t – configuration test. On success it prints OK: configuration test is successful. On an error it names the file and the problem.

2. Restart fail2ban so it loads the new settings:

   systemctl restart fail2ban

3. List the active jails:

   fail2ban-client status

   Status
   |- Number of jail:	2
   `- Jail list:	recidive, sshd

4. Show the status of the sshd jail:

   fail2ban-client status sshd

   Status for the jail: sshd
   |- Filter
   |  |- Currently failed:	2
   |  |- Total failed:	57
   |  `- Journal matches:	_SYSTEMD_UNIT=ssh.service + _COMM=sshd
   `- Actions
      |- Currently banned:	3
      |- Total banned:	12
      `- Banned IP list:	198.51.100.25 198.51.100.40 198.51.100.77

Unblocking an IP address#

If you've blocked yourself, log in through the browser console (or from a different network, for example over mobile data) and use one of these commands:

Replace 198.51.100.25 with your public IP address. If you don't know it, find it in the Banned IP list by time (block records: grep "Ban " /var/log/fail2ban.log | tail), or open any “what is my IP address” page on the computer you connect from.

You can also find your address while you're logged in over SSH: echo $SSH_CLIENT prints the address you're connecting from as the first value.

How to tell that you're the one blocked#

• SSH suddenly reports Connection refused or Connection timed out, although it worked a moment ago.
• From a different network (mobile data) you connect without a problem.
• If recidive blocked you, other services on the VPS (website, game server) don't work for you either, while they work for other people.
• In the console you see your address in the output of fail2ban-client status sshd.

SSH on a different port#

If you moved SSH (for example to 2222), update the line in the [sshd] section of jail.local:

[sshd]
enabled = true
port = 2222
backend = systemd

• port = 2222 – fail2ban blocks this port for the attacker. With the wrong port, a block would have no effect. For more ports, separate them with a comma: port = 22,2222.

Then run fail2ban-client -t and systemctl restart fail2ban.

More jails: Nginx#

If you run a website with Nginx on the VPS, you can watch it too. Add to jail.local:

[nginx-http-auth]
enabled = true
backend = auto

[nginx-botsearch]
enabled = true
backend = auto

• backend = auto – Nginx writes to the file /var/log/nginx/error.log, not to the journal. Without this line, on Ubuntu the jail would read the journal and find nothing.

Fail2ban and the firewall#

Fail2ban blocks through nftables in its own table f2b-table. It therefore works alongside UFW and the firewall in the customer area and doesn't overwrite any of them. You'll see the blocked addresses with:

nft list table inet f2b-table

• nft list table inet f2b-table – prints fail2ban's table including the sets (addr-set-sshd …) with the blocked addresses.

If you want to see the blocked addresses right in ufw status, set the line banaction = ufw in [DEFAULT] (UFW must be on). Then set banaction = ufw for the recidive jail too. The default nftables is faster, though, and we recommend it.

Fail2ban protects only what runs inside the VPS. It doesn't control the firewall in the customer area.

Verification#

1. Try blocking a test address by hand:

   fail2ban-client set sshd banip 198.51.100.25

2. Check that it's in the firewall: nft list table inet f2b-table must contain the address 198.51.100.25.

3. Unblock it: fail2ban-client set sshd unbanip 198.51.100.25.

4. After an hour or two, check fail2ban-client status sshd. On a public VPS, Total failed and Total banned are usually non-zero soon.

Troubleshooting#

fail2ban-client -t reports an error#

The output names the file and section. Most often it's a typo in a setting name, a missing =, or a value without a unit. Fix the file and run the test again.

Have not found any log file for sshd jail#

The sshd jail is trying to read the file /var/log/auth.log, which doesn't exist on Debian 13. The [sshd] section must contain backend = systemd.

No module named 'asynchat' (Ubuntu 24.04)#

The original fail2ban version in Ubuntu 24.04 didn't work with Python 3.12. The fix is in the distribution updates: run apt update && apt full-upgrade and then systemctl restart fail2ban.

Fail2ban reports addresses as blocked, but the attacker keeps trying passwords#

• Look for action errors in /var/log/fail2ban.log (for example nft: not found). Then install the nftables package.
• Check that the port in the jail matches the actual SSH port.

Where to look for details#

tail -n 50 /var/log/fail2ban.log
journalctl -u fail2ban -n 50

• tail -n 50 /var/log/fail2ban.log – the last 50 lines of the fail2ban log (blocks Ban, unblocks Unban, errors).
• journalctl -u fail2ban -n 50 – the last 50 service entries; useful when fail2ban doesn't start at all.

Further reading#

• Fail2ban: repository and documentation (opens in a new window)
• Fail2ban: default jail.conf with comments (opens in a new window)
• fail2ban-client manual page (opens in a new window)