MailCleaner Support
Added about 4 years ago

Fail2ban Usage in MailCleaner

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 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 which gets installed with the mailcleaner-library Python library.

Fail2Ban Filters

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.

Fail2Ban Actions

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.

Fail2Ban Management

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

Query Fail2Ban server:

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

Search ipset directly

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.

Fail2Ban management command

To ban or unban an IP, you can manually run that action from the Fail2Ban wrapper program: unban -j mc-exim-1d -i

where -j mc-exim-1d indicates the jail, and -i 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: unban -j mc-exim -i

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

Extra commands

Enable a jail: jail enable -j <jail>

Enable all jails: general enable

Disable all jails: general disable

Change value of findtime, bantime or maxretry jail change -j <jail> --option <option> -v <value>

Permant Blacklist

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).

Disable blacklist for a specific jail: blacklist disable -j <jail>

Disable blacklist for all jails general disable-bl

Enable blacklist for all jails 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.

Manually blacklist an IP blacklist add -j <jail> -i <ip>

Unblacklist an IP that is currently blacklisted blacklist remove -j <jail> -i <ip>

Permanent Whitelist

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:

Add an IP to the whitelist 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.

Remove a whitelisted IP whitelist remove -j <jail> -i <ip>

Start / Restart Fail2Ban

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

Advanced User

Note : The following section should only be used by user having knowledge of Fail2Ban and is therefore not supported

Create custom jail

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
Value Type
enabled TinyINT (0 or 1)
name, filter, banaction, logpath STRING
port STRING (delimiter ',' )
maxretry, findtime, bantime INT
max_count INT (disabled = 0)

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