skip to content

System: Fail2Ban 0.8.3 Howto

Since our first article on Fail2Ban and iptables there have been a number of improvements and many of the things we were doing ourselves manually are no included as options by default. That includes special filters to protect against various Apache, Mail and FTP attack vectors.

There are also a range of command-line tools to help query, modify and test your configuration to make sure it's working properly. The following sections should help you get started.

This article assumes that have Fail2Ban installed and are just wondering what to do with the configuration files. All comments relate to version 0.8.3 running on Debian/GNU Linux.

Modifying the jail.conf file

The /etc/fail2ban/jail.conf file includes a number of global settings and then lets you decide whether to enable/disable various built-in filters.


In this section you should make sure that you list (space delimited) any ip addresses that should never be blocked. That should include localhost ( as well as any friendly server or ip address.

ignoreip = bantime = 3600 maxretry = 5

That way you won't find yourself locked out of your own server.


The next interesting section is JAILS where you can enable/disable and set parameters for various pre-configured filters. Each jail has a name (e.g. 'ssh', 'pam-generic', 'apache', ...) which appears as a heading in square brackets.

The parameters immediately after each jail heading apply only to that jail and overrride the defaults.

For example:

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

This filter, when enabled, will monitor the auth.log and after six infractions by a single ip address, will block that address from accessing the ssh port for bantime seconds.

The regular expressions to determine what constitutes an infraction are to be found in the file filter.d/sshd.conf. The filename is based on the filter variable.

In each file in the filter.d directory you will find a failregex variable defined which is made up of one more more regular expressions.

For example, the failregex for apache-auth is defined as:

failregex = [[]client <HOST>[]] user .* authentication failure [[]client <HOST>[]] user .* not found [[]client <HOST>[]] user .* password mismatch

These regular expressions match various errors stemming from failed HTTP-login attempts and extract the IP address, keeping track of how many times a given address has been detected to determine whether to block them from the relevant ports/services.

The simplest way to apply changes to the configuration is to stop and start the Fail2Ban daemon:

/etc/init.d/fail2ban stop # wait a few seconds... /etc/init.d/fail2ban start

A more graceful option is using the fail2ban-client command-line tool (see below).

Testing Fail2Ban filters on your server

Some of the filters provided will be relevant to your server, but others not. That will depend on what services you provide (Mail, FTP, ...) and using which program/daemon.

The simplest way to check whether a filter is appropriate for your server is to test it using the fail2ban-regex script.

The syntax for this is:

fail2ban-regex <logfile> <regex or filter conf file>

You can get the relevant options for each filter from the jail.conf file. For example, to test the apache-auth filter you need to pass it your logfile and the filter file:

fail2ban-regex /var/log/apache2/error.log /etc/fail2ban/filter.d/apache-auth.conf

The output will look something like the following:

Running tests ============= Use regex file : /etc/fail2ban/filter.d/apache-auth.conf Use log file : /var/log/apache2/error.log Results ======= Failregex |- Regular expressions: | [1] [[]client <HOST>[]] user .* authentication failure | [2] [[]client <HOST>[]] user .* not found | [3] [[]client <HOST>[]] user .* password mismatch | `- Number of matches: [1] 0 match(es) [2] 1 match(es) [3] 0 match(es) Ignoreregex |- Regular expressions: | `- Number of matches: Summary ======= Addresses found: [1] [2] XX.173.193.149 (Fri Dec 03 08:47:42 2010) [3] Date template hits: 0 hit(s): Month Day Hour:Minute:Second 1573 hit(s): Weekday Month Day Hour:Minute:Second Year 0 hit(s): Weekday Month Day Hour:Minute:Second 0 hit(s): Year/Month/Day Hour:Minute:Second 0 hit(s): Day/Month/Year Hour:Minute:Second 0 hit(s): Day/Month/Year:Hour:Minute:Second 0 hit(s): Year-Month-Day Hour:Minute:Second 0 hit(s): Day-Month-Year Hour:Minute:Second[.Millisecond] 0 hit(s): TAI64N 0 hit(s): Epoch 0 hit(s): ISO 8601 Success, the total number of match is 1 However, look at the above section 'Running tests' which could contain important information.

You will see firstly a list of the 'Regular expressions' that make up the filter, with each one assigned a number. This is followed by the 'Number of matches' in the supplied logfile, and below in the 'Summary' section a list of all the matched IP addresses.

After this you should see confirmation that Fail2Ban was able to recognise the timestamp of each line of the logfile. If this filter had been enabled, any IP addresses matched more than maxretry times would have been blocked for bantime seconds.

If you don't see any matches you might want to run the same test with an older logfile (e.g. error.log.1) which may have more entries. If still nothing is found then it probably means that the filter in question is not applicable to your server.

If matches are found, you should grep for some of the IP addresses in your logfiles to make sure that they are indeed addresses that you want to have blocked (see ignoreip option above).

# grep XX.173.193.149 /var/log/apache2/error.log [Fri Dec 03 08:47:42 2010] [error] [client XX.173.193.149] user not found

Experienced users will want to peruse the logfiles for different types of errors and think about adjusting the filter failregex to add/remove options. In some cases you might even want to set up your own filters.

Monitoring and tweaking Fail2Ban


As described in more detail in previous articles the Fail2Ban system is implemented using iptables which is essentially a firewall. To monitor what is going on inside iptables we like to use commands such as:

# iptables -vnL --line-numbers

or, for real-time updates:

# watch -d 'iptables -vnL --line-numbers'

This will let you see all traffic passing through your server and which ip addresses are currently caught by the Fail2Ban filters.


Another command-line tool included with Fail2Ban that lets you query and modify the status and parameters of all filters/jails.

# fail2ban-client --help

The simplest usage is to query the status of the jails:

# fail2ban-client status Status |- Number of jail: 5 `- Jail list: proftpd, apache-missing, ssh, sendmail, fail2ban-smtp

You can then look in more detail at the performance individual jails:

# fail2ban-client status proftpd Status for the jail: proftpd |- filter | |- File list: /var/log/proftpd/proftpd.log | |- Currently failed: 0 | `- Total failed: 18 `- action |- Currently banned: 0 | `- IP list: `- Total banned: 2

The numbers cover only the period since the last restart. In this case there were 18 recorded infractions of the ProFTP filter, but only two IP addresses actually blocked, for multiple maxretry infractions within findtime seconds. If any IP addresses are currently banned, they will be tallied and listed.

For more details on the inner workings of Fail2Ban and iptables, please check out our other Fail2Ban articles below.

< System

User Comments

Post your comment or question

28 April, 2011

Thanks for all the Fail2ban articles. However, I'm encountering a problem with Fail2ban sending me multiple emails for 1 ban event. I've checked my jail.local and action.d files but I can't determine the cause of the multiple notifications. Any ideas?