July 15, 2011

Weekend Project: Keep Out Repeat Offenders with Fail2ban on Linux

Tired of automated attacks on your systems? Want to beef up security a bit by denying would-be attackers a third or fourth chance? Then you need Fail2ban. Fail2ban watches logs and then bans IP addresses, based on too many password failures, by updating the firewall rules. Specific rules can be defined by the user and multiple log files can be monitored. This weekend, let's get started on improving security with Fail2ban.

Out of the box, Fail2ban will protect against SSH brute force attacks, but why not give that server (or desktop) even more security. Let's dig in and install Fail2ban and, once installed, tighten up our system security as much as possible.


The developers of Fail2ban work closely with the Debian community, so naturally the installation on a Debian-based computer is about as simple as it gets. If you're on a Debian-based system, the installation for Fail2ban is as simple as:

  1. Open a terminal window.
  2. Issue the command sudo apt-get install fail2ban.
  3. Type the sudo password and hit Enter.
  4. Allow for any dependencies to be installed.

That's it, Fail2ban is now up and running, and ready to be configured. Before I dig into the configuration, let's cover a few terms you'll need to know:

  • Filter: This is a regular expression used to watch for log-in failures.
  • Action: An action is a command (or collection of commands) that are executed at a given moment.
  • Jail: This is a combination of a filter and one ore more actions.

All clear? Let's get started!

Server and Client

When Fail2ban installs, it installs two pieces:

  • fail2ban-server: This is the server portion which is a multi-threaded application that listens for commands.
  • fail2ban-client: This is the front-end which connects to the fail2ban-server. The client can either read the fail2ban configuration file, can be issued from the command line with arguments to send a command to the server, or can be started in interactive mode.

I'll address the configuration of Fail2ban in a moment. First I want to address these two pieces and how they are used. First, the fail2ban-server tool. This tool should not be used directly, unless using for debugging purposes. To options that can be issued with the fail2ban-server command are:

  • -b: Start server in background.
  • -f: Start server in foreground.
  • -s [FILE]: Socket path.
  • -x: Force kill the server.

The fail2ban-client command, on the other hand, is the front-end for fail2ban-server and is readily available for use. The possible options for this command are:

  • -c: Configuration directory.
  • -s: Socket path.
  • -d: Dump configuration (for debugging).
  • -i: Interactive mode.
  • -v: Verbose mode.
  • -q: Decrease verbosity.
  • -x: Force kill the server.

Now, before I set off showing how to start and use the fail2ban-client command, I must first introduce how this service is configured.

Configuring fail2ban

Within the /etc/fail2ban directory there are two particular files of note:

  • fail2ban.conf: This file contains the general options for fail2ban. Most likely the default options will work just fine.
  • jail.conf: This is the meat and potatoes of fail2ban. In this file jails are created for specific security needs.

Since jail.conf is the more important (and more complex) file, I want to focus on the configuration therein. This configuration is broken into two sections: Default and Jails. Each section is started with either [Section Name] (such as [Default] or [ssh]). An example of a jail that is configured out of the box is the ssh jail. That configuration looks like:



enabled = true
port    = ssh
filter  = sshd
logpath  = /var/log/auth.log
maxretry = 6


This is a fairly simple jail, so it makes for a perfect example. Let's look at this line-by-line.

  • enabled: This instructs fail2ban that this jail is enabled.
  • port: This instructs fail2ban which port to be watching -- in this case port 22 for ssh.
  • filter: This instructs fail2ban which filter to use from the /etc/fail2ban/filter.d/ folder.
  • logpath: This instructs fail2ban what log file to watch.
  • maxretry: This instructs fail2ban how many failures to allow before blocking the IP address.

Take a look in the /etc/fail2ban/filter.d/ folder. In that folder there lives approximately twenty-seven pre-configured filters (covering everything from apache-auth to xinetd-fail). Each of these filters can be edited to better match specific needs. In the SSH example above, say a non-standard port for SSH is used, that can be changed by simply editing the port entry.

Of course the SSH example is a fairly straightforward one. Remember, Fail2ban takes advantage of regular expressions (which I will not get into — that's another tutorial all together), so filters can get fairly complex. Take, for instance, the pam-generic filter (which can watch all log-in attempts). In this filter, the line:


failregex = \s\S+ \S+%(__pam_combs_re)s\s+authentication failure; logname=\S* uid=\S* euid=\S* tty=%(_ttys_re)s ruser=\S* rhost=(?:\s+user=.*)?\s*$

watches for failures in the logfile.

Once you have your filters created and/or set up correctly (within the filter.d folder) these filters can then be used within the jail.conf file. By default, fail2ban will have many of these filters already configured in jails in jail.conf, but most of them will be set to enable = false. Go through jail.conf file and, should there be a jail that should be used on a particular system, change the enabled entry to enabled = true, save the file, and restart the daemon with the command fail2ban-server reload.

Now with the Fail2ban server running it will be watching the configured jails and, should an offending connection match the criteria of a filter, that connection will be blocked, with the help of iptables.

To start the Fail2ban system, issue the following command: sudo /etc/init.d/fail2ban start. To restart the system, issue the command sudo /etc/init.d/fail2ban restart.

Another Filter Example

Here's another handy Fail2ban filter that can be used as an Apache Proxy filter. This filter will ban any user on the network that tries to set up a proxy via Apache. The first step is to create /etc/fail2ban/filter.d/apache-proxy.conf file. Here you'll need:


# Fail2Ban configuration file

# Matches lines such as:
# - - "GET http://www.infodownload.info/proxyheader.php ...
failregex = ^(?:(?![0-9\.]* -.*"[A-Z]* /)<HOST>)
ignoreregex =


The next step is to open up (or create) /etc/fail2ban/jail.local and add the following:

enabled = true
port = http,https
filter = apache-proxy
logpath = /var/log/apache/*access.log
maxretry = 0
findtime = 604800
bantime = 604800

Want More?

Since this is an open source tool, naturally the community at large contributes in many ways. One way is a community repository of filters (and other bits of information). Check out the wiki for various filters that aren't available in the default installation.

Click Here!