fail2ban: twenty years of watching your auth log for you

What the daemon actually does, in two sentences

The README describes the mechanism without embellishment. Fail2Ban scans log files like `/var/log/auth.log` and bans IP addresses conducting too many failed login attempts, doing so by updating system firewall rules to reject new connections from those addresses for a configurable amount of time.

So the loop is: read a log, recognise a failure pattern, count failures per source address, and push a rule into the firewall when the threshold is crossed. The log parsing is the part that has grown the most over two decades, because every service logs failures differently, and the firewall part is the part most people never see because it sits behind an abstraction with several backends.

The README also makes the out-of-the-box claim specific rather than general. It comes ready to read many standard log files, such as those for sshd and Apache, and is easily configured to read any log file of your choosing, for any error you wish. That is the real product: not a firewall, but a large library of log patterns plus a generic enforcement mechanism.

IPv6 is handled, and the README flags when that arrived. Since v0.10, fail2ban supports matching of IPv6 addresses, alongside a note from the World IPv6 Launch.

Installing from source and the one command that checks it

The README's first advice is to use your distribution's package, linking to a wiki page on installing packages, and notes that fail2ban is likely already packaged for your Linux distribution. That is the correct path and it is the one most people should take.

The from-GitHub route exists for the rest. Requirements are Python 3.5 or newer, or PyPy3, plus python-setuptools for installation from source. Optional extras are listed by name: pyinotify at version 0.8.3 or newer for file monitoring, which may need Linux 2.6.13 or newer; systemd 204 or newer with the python-systemd package; dnspython; and pyasyncore with pyasynchat, which the README notes are normally bundled within fail2ban for Python 3.12 and newer.

The source install is the traditional sequence:

tar xvfj fail2ban-master.tar.bz2
cd fail2ban-master
sudo python setup.py install

There is a git equivalent that also names the branches you might want, master or 0.11:

git clone https://github.com/fail2ban/fail2ban.git
cd fail2ban
sudo python setup.py install

The install places executable scripts in `/usr/bin` and configuration in `/etc/fail2ban`. Verification is one command, and the README attaches a warning to it:

fail2ban-client -h

You should always use fail2ban-client and never call fail2ban-server directly. `fail2ban-client version` confirms what you actually have installed.

Enabling it as a service is the step people skip

The README flags this explicitly: the system init or service script is not automatically installed by the source install. To enable fail2ban as an automatic service you copy the script for your distro from the `files` directory into `/etc/init.d`. The example given is for a Debian-based system, and it is three commands:

cp files/debian-initd /etc/init.d/fail2ban
update-rc.d fail2ban defaults
service fail2ban start

That example predates systemd, and the 1.1.1 release notes show the project has since moved on it. The 1.1.1 release includes a systemd-managed `fail2ban.socket`, referenced as gh-4220. So on a current Debian or Ubuntu system, installing the package brings a socket unit with it, and the init.d route above is mostly of historical interest.

The `files/` directory in the tree is where per-distro scripts live, which is why the README can say to pick the right one rather than giving a single script.

For a distribution package, none of this applies. The package handles the unit, the configuration path and the log permissions, which is the practical reason to prefer it.

Configuration lives in /etc/fail2ban, not in the daemon

The configuration section of the README is short and points outward, which is a fair signal of how much of this project lives in files rather than in the README.

What it does establish is the shape. You configure fail2ban using the files in `/etc/fail2ban`, and it is possible to configure the server using commands sent to it by `fail2ban-client`. The available commands are described in the fail2ban-client(1) manpage, with further references in the fail2ban(1) and jail.conf(5) manpages.

Three separate manpages for three different audiences is itself informative. The client manpage is the command surface, the main manpage is the daemon, and jail.conf is the policy configuration, which is the file that defines what counts as a failure, how many failures trigger a ban and how long the ban lasts. Nothing in the README restates those settings, which is a deliberate division of labour rather than an omission.

The rest of the documentation is linked from the same paragraph. More documentation, FAQ and HOWTOs live in the fail2ban(1) manpage, the project wiki, the developer documentation on readthedocs, and the website at fail2ban.org. The README describes itself as a quick introduction, and the developer documentation is a separate destination aimed at people writing filters and actions.

Version history, including a twenty year gap

The release naming convention is worth knowing because the version strings carry jokes that make them look like placeholders. The 1.1.1 release from August 2026 is named triple-one-win, 1.0.2 from November 2022 is finally-war-game-test-tape-not-a-nuclear-alarm, and 1.1.0 from April 2024 is object-found--norad-59479-cospar-2024-069a--altitude-36267km.

The functional story across those three is one of Python version compatibility and regression fixes. Version 1.1.0 lists its primary target as providing Python 3.12 and 3.13 compatibility, issue number 3487. Version 1.0.2 lists its primary target as fixing a dovecot filter regression, issue number 3370.

That is a project in maintenance mode rather than feature mode, which is the correct read for a two-decade-old daemon that ships in every distribution. What the releases do show is that Python version support is the recurring work item, and that filters do regress.

The copyright line in `setup.py` is more telling than the release notes: copyright 2004 Cyril Jaquier, 2008 to 2016 Fail2Ban Contributors. The authors are named as Cyril Jaquier, Steven Hiscocks and Yaroslav Halchenko. The README asks that kudos go to the original author or, better, to the mailing list, since fail2ban has been community-driven for years. With 18,655 stars, 1,499 forks and 275 open issues, it is one of the most visible infrastructure projects on GitHub.

The README is candid about what fail2ban cannot do

This paragraph deserves more attention than it usually gets, because it is the honest part:

Though Fail2Ban is able to reduce the rate of incorrect authentication attempts, it cannot eliminate the risk presented by weak authentication. Set up services to use only two factor, or public and private authentication mechanisms if you really want to protect services.

That is a real limitation stated without hedging, and it generalizes beyond authentication. A ban reduces the rate of an attack. It does not stop a distributed attack where each address fails a few times, and it does nothing about a credential that is already known. The README's advice, two factor or key-based auth, is the part that actually reduces risk.

The GPLv2 licence is the other thing to note. The tree contains a `COPYING` file and the README carries the standard redistribution notice, so fail2ban is free software with copyleft obligations if you distribute a modified version. Repository metadata reports the licence as NOASSERTION and the topics include `gplv2`.

The codebase itself is a small Python package, `fail2ban/`, next to `bin/`, `config/`, `man/`, `files/`, `doc/` and `misc/` directories. There is a Vagrantfile for development environments, an `FILTERS` directory, a `ChangeLog`, a `DEVELOP` file and a `THANKS` file, plus CI configuration in `.github/`. The default branch is master, and the last push was on 2026-09-11.

Editorial conclusion

fail2ban is good at the narrow job it names, turning a stream of failed authentication attempts into firewall rules without you writing a parser, and it has been doing that since 2004 with a GPLv2 licence and a package in essentially every Linux distribution. What it will not do is protect a service from weak authentication, which the README states plainly, so pairing it with public key login or two factor is the real configuration decision. On a modern host, use your distribution package rather than `setup.py`, install the systemd unit, and remember that `fail2ban-client` is the interface you are meant to talk to rather than the server. The jail configuration in `/etc/fail2ban` and the man pages, fail2ban(1), fail2ban-client(1) and jail.conf(5), are where the actual policy lives.

Frequently asked questions

Official sources

1. fail2ban/fail2ban on GitHub
2. Issues
3. Project website
4. README
5. Releases