Home > computers > linux > fail2ban > HowFail2BanWorks | About

Big picture

My description of fail2ban :

Fail2ban will perform $action on any host (IP or hostname) that is not $ignoreip for $bantime seconds if there's at least $maxretry lines in $logpath that matches the $filter within $findtime seconds.

All bold words are of course variables you can set in configuration files.

Configuration files

File structure

Everything lives in /etc/fail2ban/

root@messagerie-secours[] ~ # tree /etc/fail2ban/
├── action.d
│   ├── complain.conf
│   ├── ...
│   └── shorewall.conf
├── fail2ban.conf
├── filter.d
│   ├── apache-auth.conf
│   ├── ...
│   └── xinetd-fail.conf
├── jail.conf
├── jail.local
└── jail.local-

2 directories, 58 files
root@messagerie-secours[] ~ # 

the /etc/fail2ban/ directory consists of 4 parts :


This is where global configuration occurs, like configuring the output of fail2ban (logfile)

jail.conf and jail.local

This is where jails are defined (rules). A jail is simply a filter associated with one or more actions. Here's an example jail for courier :

enabled  = false
port     = smtp,ssmtp,imap2,imap3,imaps,pop3,pop3s
filter   = courierlogin
logpath  = /var/log/mail.log
  1. filter will contain a filename without the .conf extension. In our example, fail2ban will look for a file named courierlogin.conf in /etc/fail2ban/filter.d/ and read the filter from there.
  2. logpath is the file where fail2ban will apply the filter. If the filter matches, then action is taken. Here, action isn't defined in the jail itself, so fail2ban will apply the action defined in the global configuration file /etc/fail2ban/fail2ban.conf in the [DEFAULT] section. Usually, action will be iptable or shorewall. Like for filters, action will be the name of the file, without the .conf extension, that lives in /etc/fail2ban/action.d/ and which fail2ban will read and execute against any host on which the rule (jail) applies.

is the directory containing the default filters that are shipped with fail2ban, they cover a good amount of software already and there are good chances you don't need to add anything to it or edit anything.


is the directory containing the default actions that are shipped with fail2ban, they also cover a good amount of software already like iptable and shorewall. When you write a rule in jail.local (and not jail.conf, you'll see why later), you only mention the name of the file in the action parameter. For example, if you put

action: iptable

inside a jail specification (remember that jail is the fail2ban jargon for rule), then fail2ban will read the instructions it finds in /etc/fail2ban/action.d/iptable.conf and apply them to the hosts that match the associated filter.

Likewise, filter is also the name of the file (without the .conf extension) that fail2ban should read to match against.

You don't need to touch any of these files

Really. The only file you need to care about will be jail.local. Leave jail.conf untouched so that in the next upgrade of the software your changes won't be discarded. Instead, put your changes in jail.local. This file takes precedence over jail.conf so that your changes will always be applied no matter what.

...unless you want to monitor your own software

In that case you would probably add a filter in filter.d and add your new jail to jail.local. If all you want to do is ban/unban, use the ipfilter or shorewall action files already shipped with fail2ban.

Important variables

In the order they were mentionned in the upper description. All these variables belong to each jail in jail.conf but you can/should override them in jail.local :

  1. action : This is what will be performed against the attackers IP. action will actually be a name that points to a file that describes what to do in more details. Fail2ban ships with a minimal amount of action files that cover most cases. You often want to set action to either iptable or shorewall. I personnaly prefer shorewall because of it has a simpler interface.
  2. ignoreip : this is the whitelist. You want to add localhost and any of your IPs here so that you won't get banned. If the local IP gets banned for some reason (this can easily happen on a mail server when at least one user enters its password wrong for a specified amount of times, locking the whole mail server out of itself), then services such as mail might suddenly stop, and troubleshooting that is really hard.
  3. bantime : this is in seconds. The banned host will be deined access to your machine for that much time.
  4. maxretry : this is the tolerence threshold you set on failed attempts to access your machine. Passed that, the offender is banned if it's not in the ignoreip whitelist and if they occured within findtime seconds.
  5. logpath : the logfile to inspect for failed connexion attempts. This is a per-service configuration.
  6. findtime : the amount of time for which maxretry have to happen. If there are maxretry failed attempts in that time window, ban applies if the host is not whitelisted.

A jail example


enabled  = true
port     = smtp
filter   = sasl
action   = shorewall
logpath  = /var/log/mail.warn
maxretry = 3
findtime = 600

This jail (rule) reads : watch the /var/log/mail.warn file for any 3 matches of the sasl filter (filter.d/sasl.conf) that happen in 600 seconds (10 minutes) time window and ban that host using the shorewall action (action.d/shorewall.conf).

Just for the sake of completeness, here's the filter that is shipped with fail2ban for sasl
root@messagerie-secours[] ~ # removeblanks /etc/fail2ban/filter.d/sasl.conf[Definition]
failregex = : warning: [-._\w]+\[<HOST>\]: SASL (?:LOGIN|PLAIN|(?:CRAM|DIGEST)-MD5) authentication failed
ignoreregex = 
root@messagerie-secours[] ~ # 

The important variables here is failregex of course. By the way, you can test a regex against any file with the fail2ban-regex command, like this :

root@messagerie-secours[] ~ # fail2ban-regex /var/log/mail.warn /etc/fail2ban/filter.d/sasl.conf
Running tests

Use regex file : /etc/fail2ban/filter.d/sasl.conf
Use log file   : /var/log/mail.warn


|- Regular expressions:
|  [1] : warning: [-._\w]+\[<HOST>\]: SASL (?:LOGIN|PLAIN|(?:CRAM|DIGEST)-MD5) authentication failed
`- Number of matches:
   [1] 1873 match(es)

|- Regular expressions:
`- Number of matches:


Addresses found:
[1] (Tue Jul 14 16:07:15 2015) (Tue Jul 14 16:10:03 2015) (Tue Jul 14 16:12:47 2015) (Tue Jul 14 16:12:47 2015) (Tue Jul 14 16:15:20 2015) (Tue Jul 14 16:15:20 2015) (Tue Jul 14 16:27:43 2015) (Tue Jul 14 16:30:09 2015) (Tue Jul 14 16:32:43 2015)
Date template hits:
4546 hit(s): MONTH Day Hour:Minute:Second
0 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): Day/MONTH/Year:Hour:Minute:Second
0 hit(s): Month/Day/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): Day-Month-Year Hour:Minute:Second
0 hit(s): TAI64N
0 hit(s): Epoch
0 hit(s): ISO 8601
0 hit(s): Hour:Minute:Second
0 hit(s): <Month/Day/Year@Hour:Minute:Second>

Success, the total number of match is 1873

However, look at the above section 'Running tests' which could contain important
root@messagerie-secours[] ~ # 


and here's the shorewall action
root@messagerie-secours[] ~ # removeblanks /etc/fail2ban/action.d/shorewall.conf
protocol = all
actionstart = 
actionstop = 
actioncheck = 
actionban = shorewall logdrop <ip>
actionunban = shorewall allow <ip>
root@messagerie-secours[] ~ # 

The important variables here are actionban (actionban = shorewall drop <ip>) and actionunban (actionunban = shorewall allow <ip>) which will be issued when fail2ban needs to ban/uban a host.


This article was written with after reading SelvaGaneshan S'. "Fail2Ban Howto: Block IP Address Using Fail2ban and IPTables" over at the geek stuff

contact : @ychaouche yacinechaouche at yahoocom

QR Code
QR Code Big picture (generated for current page)