WebCP

Custom Fail2Ban Action

Creating custom fail2ban actions are actually quite easy, just not terribly well documented. There is documentation on the Fail2Ban website, but its not very complete.

What we use custom actions in Fail2Ban for with WebCP, web hosting control panel is when want to pass info to a script when an IP address is banned so that we can display banned IPs to the server admins:

So, when an IP address is blocked, lets say for trying to crack exim passwords we have Fail2Ban block that IP for some time. We also want Fail2Ban to notify us of the block and again when the block is lifted (ban / unban).

To do that we first create a custom action in ../fail2ban/action.d/. We called ours webcp.conf, but call it something descriptive for your application.

Here’s what we put in webcp.conf:

# Fail2Ban configuration file
#
# Author: John McMurray <john@s0ftsmart.co.za>
#
#

[Definition]

actionstart = touch /var/run/fail2ban/fail2ban.webcp

actionstop = rm -f /var/run/fail2ban/fail2ban.webcp

actioncheck = 

actionban = /scripts/fail2ban/ban.sh <name> <bantime> <ip>

actionunban = /scripts/fail2ban/unban.sh <ip>

[Init]

init = WebCP notifications

The actionstart and actionstop are actions that happen when you start and stop fail2ban. In our case we just place a text file. Probably not necessary but it does allow you to quickly see if the action is working if you see / don’t see your text file when you restart fail2ban. In our case we’re not really concerned about start or stop notices, so its not really important what’s in there.

The actionban action is set to call our own bash script. It uses the fail2ban action tag replacements <ip>, <name> and <bantime>.

The <ip> fail2ban action tag is populated for you. There are several other tags available which you can see in the man pages (man jail.conf). For us, the only real useful one in the action tags was <ip>, but of course we wanted to know WHICH jail we were being notified about and for how long that ban would be in effect. We used the <name> and <bantime> tags for that, but those are not “built in” fail2ban action tags. Those are passed in from the jail.local config file.

Updating the fail2ban jail.local file to use our custom action

To use our new fail2ban custom action we make a small change to our jail.local config file. Lets see for our exim jail what that looks like:

[exim]
findtime  = 3600
maxretry = 3
port   = smtp,465,submission
logpath = %(exim_main_log)s
enabled = true
action = webcp[name=exim, bantime=600]

The relevant part of this snippet is the last line:

action = webcp[name=exim, bantime=600]

This line instructs fail2ban to call the action called webcp. Remember that the custom action we created above in the action.d folder is called webcp.conf, so its name is webcp!

We also pass in some parameters, name and bantime. This is how we’re able to use the name and bantime tags in our action to pass to our script.

restart fail2ban and your new action should be in place.