Fail2Ban: Install and Configure
Contents
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 injail.local. - Enable the
sshdjail, reload, and check bans withfail2ban-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 thesystemdbackend; 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.localandjail.localin the same directory; Fail2Ban reads.conffirst and then applies your.localoverride on top.jail.d/*.localfiles 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:
bantimeis how long a host stays banned,findtimeis the window that counts as “too many failures”,maxretryis the count,bantime.incrementpunishes repeat offenders with ever-longer bans,banactionis how bans are enforced on the firewall, andbackend/logpathsay where to read failures from.
A few clarifications worth their own lines:
banactionvsbackend. Two different things.backendis how Fail2Ban reads logs;banactionis 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
sshdjail and their configured properties, so you can see the real effective value on your box.
- Lists the actions attached to the
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, andbackend = systemdreads them there; Debian’s ownpaths-debian.confsetssshd_backend = systemdfor you as of the update, so sometimes the line is redundant. Leave it in and it does no harm. port = sshbans port 22, or whatever is declared assshin/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, oraggressive(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.localchanges 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 thef2bchain 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 nearMaxAuthTriesfrom yoursshd_config, so Fail2Ban and the SSH daemon draw the line at about the same place:sudo fail2ban-client set sshd maxretry 6findtime: the counting window for those retries:sudo fail2ban-client set sshd findtime 600bantime: how long the host stays banned, either in plain seconds or the human-friendly syntax (600is the same as10m):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 whenbackendisn’tsystemd, 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!