Jump straight to unban or whitelist commands.

Fail2Ban is a utility which does what it's name describes. With a specified number of failures, it will ban an IP from future connections. The failures which are detected, number of failures required and duration of failures are all configurable, so lets look at how it works in MailCleaner.

The definition of the jails are defined in /usr/mailcleaner/etc/fail2ban/jail.d. Those files reference filters in filters.d and actions in actions.d. MailCleaner has one group of 4 jails for each of ssh, exim, and webauth services. Those have suffixes 1d, 1w, 1m, and 1y, which indicates the ban duration (1 day, 1 week, 1 month, and 1 year). Each looks back double the previous ban duration for an increasing number of infractions. For instance, mc-exim-1w will look back 2 days for double the number of infractions allowed by mc-exim-1d. This means that rather than banning it a second time for 1 day, it will ban it for a week.It will be banned for 1 month, after the third offense within 2 weeks (with 3 times the 1d infraction), and it will be banned for 1 year with a forth offense within 2 months (with 4 times the 1d infractions).

Most commands issues to fail2ban.py can substitute just the root name (eg. mc-exim) and the action will be taken on all 4 jail durations. This simplifies tasks like whitelisting and blacklisting.

The summary of the search period, number of infractions and ban time are:

Jail          | Hits | Ban duration
--------------+------+-------------
mc-ssh-1d     |    3 | 1 day
mc-ssh-1w     |    6 | 1 week
mc-ssh-1m     |    9 | 1 month
mc-ssh-1y     |   12 | 1 year
mc-exim-1d    |    5 | 1 day
mc-exim-1w    |   10 | 1 week
mc-exim-1m    |   15 | 1 month
mc-exim-1y    |   20 | 1 year
mc-webauth-1d |    5 | 1 day
mc-webauth-1w |   10 | 1 week
mc-webauth-1m |   15 | 1 month
mc-webauth-1y |   20 | 1 year

These jails are maintained in mc_config.fail2ban_jail within the master database, and are dumped by dump_fail2ban_config.py which gets installed with the mailcleaner-library Python library.

Each configuration references a set of filters in the filter.d directory which defines a number of regular expression patterns within a defined log file which indicates a failure status.

Each configuration then executes a ban/unban action defined in the action.d directory. This used to use iptables directly, but this was very slow when Fail2Ban needed to reload the ban list. Now we use ipset which maintains lists of IPs for each policy, rather than a dedicated policy for each IP. This speeds up loading/unloading and querying of the rules and improves the firewall performance. However, it does somewhat complicate the end-user interface to the policies.

The mailcleaner-library python library provides an interface to manage fail2ban (fail2ban.py), as well as to query the fail2ban server (fail2ban-client).

Get a general summary of all jails:

fail2ban-client status

Get a summary of one specific jail by adding the jail name:

fail2ban-client status mc-exim-1d

Since there are 4 jails which could ban an IP for each of the services, you may find it slow to check each using the previous command. In this case, you may find it easier to check the ipset list directly:

ipset list

Again, you can define a specific jail by appending it:

ipset list mc-exim-1d

however, that is no faster than the previous, so you can instead leave the jail name off and search through all with grep to see whether there are any listings, or | less to be able to page through all of the results.

To ban or unban an IP, you can manually run that action from the Fail2Ban wrapper program:

fail2ban.py unban -j mc-exim-1d -i 1.1.1.1

where -j mc-exim-1d indicates the jail, and -i 1.1.1.1 is the IP.

You can also omit the -1d suffix if you would like to remove all bans for any of the mc-exim-1{d,w,m,y} jail durations:

fail2ban.py unban -j mc-exim -i 1.1.1.1

This will both remove them from the Fail2Ban database and immediately remove the listing from the relevant ipset list(s).

fail2ban.py jail enable -j <jail>

fail2ban.py general enable

fail2ban.py general disable

fail2ban.py jail change -j <jail> --option <option> -v <value>

Blacklist in Fail2ban's integration is a specific jail dynamically created for all jails.

After the specified amount of ban (by default: 3) an ip that would be banned again will be moved to this permant jail (-bl).

fail2ban.py blacklist disable -j <jail>

fail2ban.py general disable-bl

fail2ban.py general enable-bl -v X

X = Max number of ban before blacklist [default: 3]

Given that the each jail of a set duration requires an assending number of hits to function correctly, it is best that you don't configure a jail like this except if you wan to override all of our default jails.

fail2ban.py blacklist add -j <jail> -i <ip>

fail2ban.py blacklist remove -j <jail> -i <ip>

If you have specific needs for a certain IP/range that shouldn't ever be banned by a specific jail you can configure these whitelists using the following commands:

fail2ban.py whitelist add -j <jail> -i <ip>

This will also remove any existing bans that might already be in place by calling the unban action internally.

fail2ban.py whitelist remove -j <jail> -i <ip>

/usr/mailcleaner/etc/init.d/fail2ban start | stop | restart 

In order to create a custom jail in MailCleaner, you will need to add a specific DB's entry on the master server

echo "INSERT INTO fail2ban_jail (enabled, name, maxretry, findtime, bantime, port, filter, banaction, logpath, max_count) VALUES (<enabled>, '<name>', <maxretry>, <findtime>, <bantime>, '<port>', '<filter>', '<banaction>', '<logpath>', <max_count>);" | mc_mysql -m mc_config

Note: For the banaction please add mc-custom to fully integrate your jail in MailCleaner