ACLClouds
ACLClouds

How do I install and configure Fail2ban on a Debian or Ubuntu VPS?

Install Fail2ban, write a jail.local for SSH and nginx, ban and unban an IP, read jail status and avoid the usual mistakes with nftables or UFW.

Fail2ban reads your services' logs and bans, for a set time, the IP addresses that pile up failures: SSH passwords tried in a loop, scans for admin pages, failed web logins. On a VPS exposed to the Internet, attempts on port 22 start a few minutes after delivery. This guide installs Fail2ban on Debian 12 / 13 or Ubuntu 22.04 / 24.04, protects SSH and nginx, then shows how to check, ban and unban an address.

Step-by-step procedure

  1. Install Fail2ban

    Refresh the package list, then install fail2ban together with nftables and python3-systemd, which let it ban through nftables and read the systemd journal. The service starts right away with the default configuration.

  2. Create the jail.local file

    Never edit /etc/fail2ban/jail.conf, which is overwritten on every update. Put your settings in /etc/fail2ban/jail.local: ban duration, observation window, number of failures, addresses that must never be banned and the nftables action.

  3. Protect SSH

    Enable the [sshd] jail with backend = systemd: on Debian, SSH logs to the systemd journal and the /var/log/auth.log file often does not exist. If SSH listens on a port other than 22, set it with port.

  4. Add the nginx jails

    If nginx runs on the VPS, enable nginx-http-auth for failed HTTP authentication passwords and nginx-botsearch for bots looking for admin pages. Both jails read /var/log/nginx/error.log.

  5. Test, then restart

    Check the syntax with fail2ban-client -t, restart with systemctl restart fail2ban, then list the active jails with fail2ban-client status.

  6. Check, ban and unban

    fail2ban-client status sshd shows the failures counted and the banned addresses. fail2ban-client set sshd unbanip 198.51.100.7 releases an address, fail2ban-client set sshd banip 198.51.100.7 bans it by hand.

Installation on Debian and Ubuntu

apt update
apt install -y fail2ban nftables python3-systemd
systemctl enable --now fail2ban
fail2ban-client version

/etc/fail2ban/jail.local

[DEFAULT]
bantime = 1h
findtime = 10m
maxretry = 5
bantime.increment = true
bantime.maxtime = 1w
ignoreip = 127.0.0.1/8 ::1 203.0.113.10
banaction = nftables-multiport
banaction_allports = nftables-allports

[sshd]
enabled = true
port = ssh
backend = systemd
journalmatch = _SYSTEMD_UNIT=ssh.service + _COMM=sshd + _COMM=sshd-session
maxretry = 4

[nginx-http-auth]
enabled = true

[nginx-botsearch]
enabled = true

Test and apply the configuration

fail2ban-client -t
systemctl restart fail2ban
fail2ban-client status
fail2ban-client status sshd

Ban, unban and list addresses

fail2ban-client banned
fail2ban-client set sshd banip 198.51.100.7
fail2ban-client set sshd unbanip 198.51.100.7
fail2ban-client unban 198.51.100.7
nft list table inet f2b-table

Check that a filter matches failures

fail2ban-regex systemd-journal sshd
fail2ban-regex /var/log/nginx/error.log nginx-botsearch
tail -n 50 /var/log/fail2ban.log

UFW variant

[DEFAULT]
banaction = ufw
banaction_allports = ufw

Before you start

Log in as root with ssh root@IP, or put sudo in front of each command. Write down the public IP address you manage the VPS from and add it to ignoreip: otherwise, mistyping your own password a few times is enough to ban yourself.

  • Fail2ban complements key-based SSH login, it does not replace it: once the key is installed, turn off password authentication (see "What should I secure before my first VPS deployment?").
  • The addresses 203.0.113.10 and 198.51.100.7 in the examples are documentation addresses: replace them with your own.
  • If you lock yourself out, the noVNC console in the ACLClouds panel does not go through SSH: you can always use it to unban your address.

Understanding the jail.local settings

A jail combines a filter (the patterns that recognise a failure in a log), a log source and a ban action. The [DEFAULT] section sets the shared values, and each jail can override them.

  • maxretry, findtime and bantime: here, 5 failures within 10 minutes mean a one-hour ban; 4 failures are enough for SSH.
  • bantime.increment = true makes the ban longer for each repeat offence, up to bantime.maxtime (one week).
  • ignoreip accepts addresses and ranges separated by spaces, for both IPv4 and IPv6.
  • banaction = nftables-multiport creates the inet f2b-table table in nftables and blocks banned addresses there, over both IPv4 and IPv6, on the jail's ports.
  • backend = systemd and journalmatch make the [sshd] jail read the systemd journal instead of a file. The journalmatch line covers Ubuntu and Debian, including OpenSSH 10 on Debian 13, where the messages come from sshd-session.

Fail2ban with nftables or UFW

Debian 12 and 13 use nftables. The nftables-multiport action works there with no extra setting, even if UFW is installed: Fail2ban keeps its rules in its own table. On Ubuntu, you may prefer the ufw action (the "UFW variant" block) so that bans show up in ufw status.

Fail2ban blocks traffic coming into the VPS itself. Ports published by Docker go through the FORWARD chain and bypass these rules: to protect a service running in a container, use banaction = iptables-multiport and add chain = DOCKER-USER to its jail.

Common mistakes to avoid

Most setups that "don't ban anything" have one of these causes. fail2ban-client status sshd helps tell them apart: if Total failed stays at 0 while attempts keep coming in, the filter is not reading the right log.

  • Editing jail.conf instead of jail.local: the changes are lost at the next package update.
  • Enabling an nginx jail when nginx is not installed: the log file is missing and Fail2ban refuses to start.
  • Changing the SSH port without updating port in [sshd]: the address is banned on port 22, not on the new one.
  • Leaving your own address out of ignoreip, then banning yourself while testing.
  • Writing backend = systemd in [DEFAULT]: the nginx jails, which read files, no longer see anything.

Quick check

  • systemctl is-active fail2ban returns active.
  • fail2ban-client status lists sshd and, if nginx is installed, the nginx jails.
  • fail2ban-regex systemd-journal sshd finds matching lines.
  • Your own IP address is in ignoreip.
  • nft list table inet f2b-table shows the banned addresses.

Frequently asked questions

Fail2ban does not start and shows Have not found any log file for sshd jail, what should I do?

The jail looks for /var/log/auth.log, which is missing when SSH only logs to the systemd journal, as is common on Debian. Add backend = systemd to the [sshd] section of jail.local, install python3-systemd, then run systemctl restart fail2ban again.

How do I unban an IP address with Fail2ban?

Run fail2ban-client set sshd unbanip 198.51.100.7 with your own jail and address, or fail2ban-client unban 198.51.100.7 to remove it from every jail. If it is your own address and SSH no longer responds, log in through the panel's noVNC console to run the command.

How do I see the banned addresses?

fail2ban-client status sshd shows the number of banned addresses and their list for one jail; fail2ban-client banned gives them for every jail. On the firewall side, nft list table inet f2b-table shows the sets of blocked addresses.

On Ubuntu 24.04, Fail2ban stops with No module named 'asynchat', why?

The first Fail2ban release shipped with Ubuntu 24.04 was not compatible with Python 3.12. The fix is available in the repositories: run apt update && apt install --only-upgrade fail2ban, then systemctl restart fail2ban.

Attempts are coming in but Total failed stays at 0, what should I check?

The filter is not reading the right messages. Test it with fail2ban-regex systemd-journal sshd: the Lines: ... matched line must be above 0. If it is not, check backend = systemd and the journalmatch line of the [sshd] jail, then the service name with systemctl status ssh.

Is Fail2ban enough to protect a VPS?

No. It cuts down brute-force noise and lightens the logs, but an SSH key, password login turned off, a firewall that only lets the needed ports through and regular updates are still essential.