Fail2Ban: Install and Configure

Contents

TL;DR

  • Fail2Ban watches your logs and asks the firewall to ban IPs that fail too many logins.
  • Install it from your distro’s packages, and never edit jail.conf; put your settings in jail.local.
  • Enable the sshd jail, reload, and check bans with fail2ban-client status sshd.
  • Ban or unban an IP by hand with fail2ban-client set sshd banip <IP> / unbanip <IP>.

As the description says:

Fail2ban scans log files and bans IPs that show the malicious signs (too many password failures, seeking for exploits, etc). Generally Fail2Ban is then used to update firewall rules to reject the IP addresses for a specified amount of time.

This post was originally published in March 2021 and updated in October 2026. Fail2Ban is still alive and kicking (development happens at github.com/fail2ban/fail2ban), and the modern Linux stack around it has changed quite a bit: systemd journals as the log source and nftables as the default ban backend. The advice below reflects that.

Note on versions: Fail2Ban is almost always installed from your distribution’s packages, so the version you get is “whatever your distro ships”. You can check yours at any time with fail2ban-client --version. Recent releases are in the 1.x series; as of the update, modern Debian, Ubuntu, Fedora and Gentoo all package it. Anywhere below where the exact packaged default could differ between distros, I say so instead of asserting a version.

Installation

Requirements

What Fail2Ban needs to run today:

  • A Python 3 interpreter (any Linux distro from the last few years has one; the packaged Fail2Ban depends on it).
  • A log source to watch: log files, or the systemd journal.
  • A firewall backend to actually ban IPs: nftables (the default on modern Debian and Ubuntu) or iptables; Fedora typically pairs it with firewalld.

Optional extras:

  • A mail transport (sendmail-compatible or a simple mailer) if you want the ban-notification emails.
  • python3-systemd, needed when a jail uses the systemd backend; on Debian and Ubuntu it’s pulled in automatically.

Debian

For Debian based systems (Debian, Ubuntu, and derivatives) it’s as easy as:

sudo apt install fail2ban -y

One line before you move on, and it matters: on modern Debian and Ubuntu, installing Fail2Ban does not activate any jail. There is no jail.local out of the box, so after apt install, nothing is actually being watched. You need to create your jail.local (we do it below), using the example jail.conf as your inspiration. So don’t walk away after installing; half of this post is that step.

Gentoo

emerge fail2ban

Fedora

sudo dnf install fail2ban

The Ubuntu/Debian caveat above applies to Fedora too: the packages install the software, but the jails you want have to be activated by you.

Fail2Ban service

The packages install a systemd service and enable it, so it launches on boot. Here’s how that looked when I first set it up years ago:

...
Created symlink /etc/systemd/system/multi-user.target.wants/fail2ban.service → /lib/systemd/system/fail2ban.service.
...

n0nuser@n0nuser:~$ systemctl status fail2ban.service
● fail2ban.service - Fail2Ban Service
     Loaded: loaded (/lib/systemd/system/fail2ban.service; enabled; vendor pres>
     Active: active (running) since Sat 2021-03-06 17:40:44 CET; 21s ago
       Docs: man:fail2ban(1)
    Main PID: 17722 (f2b/server)
      Tasks: 5 (limit: 9335)
      Memory: 14.3M
      CGroup: /system.slice/fail2ban.service
              └─17722 /usr/bin/python3 /usr/bin/fail2ban-server -xf start

mar 06 17:40:44 n0nuser systemd[1]: Starting Fail2Ban Service...
mar 06 17:40:44 n0nuser systemd[1]: Started Fail2Ban Service.
mar 06 17:40:45 n0nuser fail2ban-server[17722]: Server ready

Everything you’ll do below takes effect with a reload instead of a reboot, but if you ever need to manage the service directly, the usual suspects work:

sudo systemctl status fail2ban
sudo systemctl restart fail2ban
sudo systemctl disable fail2ban
  • Check status, restart the daemon, or disable the autostart; the service name is just fail2ban.

If the service refuses to start, the error will be in its journal:

journalctl -u fail2ban -e
  • Prints the end of Fail2Ban’s log from the systemd journal, so you can see the actual failure.

A classic on Debian/Ubuntu: errors like “Have not found any log files” usually mean a jail is enabled without a log source that exists. On modern Debian/Ubuntu, SSH logs live in the journal, and that’s fixed by letting the sshd jail use the systemd backend (again, below). If you see complaints about the systemd backend itself, make sure python3-systemd is installed; the Debian/Ubuntu packages usually take care of it, but as of the update I wouldn’t swear it for every derivative.

Configuration

Fail2Ban is largely configured by default, using two files:

  • /etc/fail2ban/fail2ban.conf: daemon-level settings, meaning where it logs, its socket, and its persistent database.
  • /etc/fail2ban/jail.conf: the jails, that is, which services can be watched, their thresholds, and the ban actions.

It is not advised to modify these files. Package updates can overwrite them. Instead, create fail2ban.local and jail.local in the same directory; Fail2Ban reads .conf first and then applies your .local override on top. jail.d/*.local files work too, one file per jail if you like that tidiness.

The options you’ll actually touch

jail.conf is thousands of lines of commented defaults covering FTP, mail, web, DNS and game servers. You don’t need to read it all; the full annotated list lives in the packaged /etc/fail2ban/jail.conf and in man jail.conf. These are the ones a home or small-server setup actually sets, straight from a trimmed jail.conf excerpt:

[DEFAULT]
; An IP is banned for this long (bantime), after failing this many
; times (maxretry) within this window (findtime):
bantime  = 1h
findtime = 10m
maxretry = 5

; Repeat offenders get exponentially longer bans (x2, x4, x8...)
; if Fail2Ban's persistent database is enabled (it is, by default).
bantime.increment = true

; The firewall backend used to ban: on Debian 12 and newer the distro
; ships nftables as the default banaction; on older setups you'll see
; iptables-multiport, and Fedora often uses its firewalld action.
; Override here only if you want to pin a specific one yourself:
banaction = nftables-multiport

; Which log source the jail reads: file path(s) with "pyinotify" or
; "polling" backends, or the systemd journal with "systemd".
; "auto" picks something sensible for you.
backend  = auto
logpath  = /var/log/auth.log

; IPs and ranges Fail2Ban will never ban (your workstation, your VPN):
ignoreip = 127.0.0.1/8 ::1
  • One line each: bantime is how long a host stays banned, findtime is the window that counts as “too many failures”, maxretry is the count, bantime.increment punishes repeat offenders with ever-longer bans, banaction is how bans are enforced on the firewall, and backend/logpath say where to read failures from.

A few clarifications worth their own lines:

  • banaction vs backend. Two different things. backend is how Fail2Ban reads logs; banaction is how it tells nftables/iptables/firewalld to drop an IP.

  • Which banaction is my default? Don’t guess. Ask:

    fail2ban-client get sshd actions
    fail2ban-client get sshd actionproperties
    
    • Lists the actions attached to the sshd jail and their configured properties, so you can see the real effective value on your box.
  • The time syntax is human-friendly now (10m, 1h, 1d) instead of the old plain seconds.

Caution: before you enable jails on a remote server, add your own IP (or your VPN range) to ignoreip. Getting locked out of SSH by your own ban policy is embarrassing and, over a bad connection, very possible.

Setting up your jail.local

Create your local configuration:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo chmod 644 /etc/fail2ban/jail.local
  • This copies the canonical jail configuration to a new local file, which is a healthy starting point; copy only what you need from it.

Then trim and adapt it as below.

The SSH jail (sshd)

Here’s a blessed jail.local for the most common case, protecting OpenSSH on a modern Debian/Ubuntu box:

[DEFAULT]
; Never ban these — the loopback ranges plus your own LAN/mgmt ranges
; (space- or comma-separated). Put your VPN or office range here too:
ignoreip = 127.0.0.1/8 ::1 192.168.1.0/24

; 1 hour ban, doubling per re-offense:
bantime           = 1h
bantime.increment = true
; ...after 3 failed attempts within a 10 minute window:
findtime          = 10m
maxretry          = 3

; On Debian 12+ this is the default already; shown here so the file
; works the same way on any distro that still defaults to iptables:
banaction = nftables-multiport

[sshd]
enabled = true
backend = systemd
port    = ssh
  • On modern Debian/Ubuntu, the failures show up in the systemd journal instead of /var/log/auth.log, and backend = systemd reads them there; Debian’s own paths-debian.conf sets sshd_backend = systemd for you as of the update, so sometimes the line is redundant. Leave it in and it does no harm.
  • port = ssh bans port 22, or whatever is declared as ssh in /etc/services; useful if the jail matches but you moved SSH to a custom port.
  • If you use a non-default SSH port, set port = 2222 (or yours) explicitly, so Fail2Ban bans with a rule that actually blocks your real SSH port.
  • Want it stiffer? The filter has modes: mode = normal (default), ddos, extra, or aggressive (which combines all of them). Set it in the [sshd] section and it catches more flavors of bad logins.

Force the change to take effect:

sudo fail2ban-client reload
  • Applies your jail.local changes to the running daemon, so no restart is needed.

Check that the jail is ready and watching:

sudo fail2ban-client status sshd

Expected output looks like:

Status for the jail: sshd
|- Filter
|  |- Currently failed: 3
|  |- Total failed:     42
|  `- Journal matches:  _SYSTEMD_UNIT=sshd.service + _COMM=sshd
`- Actions
   |- Currently banned: 2
   |- Total banned:     2
   `- Banned IP list:   203.0.113.25 198.51.100.7
  • The jail was loaded, matches failures from the SSH daemon’s journal, and has already banned two IPs.

One last check before you rely on it: sudo nft list ruleset | grep -i f2b, and verify the f2b chain was created. If Fail2Ban defaults to nftables but your firewall is actually iptables (or firewalld is running and you’d rather have its action), that mismatch is the #1 cause of “jails work, bans do nothing”.

Tuning thresholds

All of the parameters above can also be changed live, without touching files:

  • maxretry: how many failures are tolerated before the ban; a reasonable policy is to keep it near MaxAuthTries from your sshd_config, so Fail2Ban and the SSH daemon draw the line at about the same place:

    sudo fail2ban-client set sshd maxretry 6
    
  • findtime: the counting window for those retries:

    sudo fail2ban-client set sshd findtime 600
    
  • bantime: how long the host stays banned, either in plain seconds or the human-friendly syntax (600 is the same as 10m):

    sudo fail2ban-client set sshd bantime 600
    

But prefer editing jail.local and reloading; set changes don’t survive a daemon restart.

Manual ban/unban

Sometimes you want to ban someone yourself, right now, mid-attack:

sudo fail2ban-client set sshd banip 203.0.113.25
  • Immediately bans that IP for the jail’s configured ban time.

And when you ban yourself (happens; that’s why we set ignoreip first), undo it:

sudo fail2ban-client set sshd unbanip 203.0.113.25
  • Lifts that ban right away.

There are convenience wrappers too, if you like them: fail2ban-client banned, fail2ban-client unban <IP>… but the set sshd ... form is the one you end up pasting from memory.

A few other options the sshd jail takes, for completeness:

  • action: what happens on a ban (see below).
  • maxmatches: how many log lines are kept in the ban ticket for reports.
  • logpath: only relevant when backend isn’t systemd, and then it’s the file(s) to tail, separated by spaces or newlines.

Ban actions

The action parameter rules what happens when an IP gets banned. The default is action = %(action_)s, and there are a few handy variants (pick one):

  • Ban only: action = %(action_)s
  • Ban and send an email with a whois report to destemail: action = %(action_mw)s
  • Ban and send an email with the whois report and the relevant log lines: action = %(action_mwl)s

The email variants require a working mta (the default is sendmail), an actual mailer on the box, and a destemail you actually read. On a server without mail configured, keep the default action_; a banned IP doesn’t need a notification to work. As of the update, a few of the more exotic reporting actions shipped with older versions (badips.com among them) are tied to services that are no longer operational, so treat them as deadwood.

Conclusion

First, a maintenance report so you know the tool’s pulse: Fail2Ban is far from abandoned: as of the update, 1.1.1 shipped in August 2026 with the usual stream of fixes, so the version you’ll get from your distro is being actively looked after by the project.

Fail2Ban is still one of those tools that punch way above their weight: install from packages, a short jail.local, one enable, and the constant background noise of credential guessing turns into an automatically growing nftables ban list instead of something you grep by hand at 3 a.m.

If you fancy something in the same family but bigger, have a look at CrowdSec (open source, MIT-licensed, docs at docs.crowdsec.net). It parses logs just like Fail2Ban, but the interesting bit is the social layer: everyone running it shares ban decisions through communities, so an IP that misbehaves on my server can arrive pre-banned on yours, and it ships with a crowdsourced blocklist you can consume on its own. It covers Linux, Windows, Docker and Kubernetes, and hooks into nftables or firewalld through its “bouncers”, the same idea as Fail2Ban’s actions, one name to remember them by. Don’t feel pushed to switch, though: for a single server, Fail2Ban plus a good jail.local is exactly the right size.

For deeper digging, the project home is github.com/fail2ban/fail2ban, and the man pages man jail.conf and man fail2ban-client are genuinely good: they explain the same options as above, plus all the jails we trimmed out, for every service you can imagine.

For my small home server, sshd is about all I need, and three failed passwords in ten minutes is enough judgment for them.

Happy (safe) banning!

Back to all Posts