Custom Fail2Ban Action

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:

Custom Fail2Ban Action


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>


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 = 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:

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.





Alex 2 years ago

Thank for the info, is there a way to install Fail2Ban where it does not do anything with Iptables and only use it for catching offending IP addresses (e.g for Apache) and then run a custom script, I have a custom IPtables setup and like to run my own scripts to add offending ip addresses to block list etc...

jsmcm 2 years ago

Hello, You should be able to... NOTE: I have not tested the below so it may need some tweaking... In your jail.local file where you define your "traps", define one with zero ban time. Also give it an action. This action is to a script you create: [my-trap] enabled = true port = "0:65535" bantime = 0 action = my-action[name=my-trap, bantime=0] Then in the directory action.d you crate a file (in this case called my-trap) and in this file: # Fail2Ban configuration file # Author: John Mc [Definition] actionstart = touch /var/run/fail2ban/fail2ban.my-trap actionstop = rm -f /var/run/fail2ban/fail2ban.my-trap actioncheck = actionban = /home/john/ban_notice.sh actionunban = /home/john/unban_notice.sh [Init] init = My Trap notifications This tells fail2ban to call the script you define in actionban with name, bantime and ip address (which you set in the jail.local file above). Same thing when something is unbanned (in your case you probably will not use the actionunban). Then lastly you create your own script, /home/john/ban_notice.sh (we use shell scripts but I guess you could call python, php, etc): #!/bin/bash Name=$1 BanTime=$2 IP=$3 $(mysql ban_table -se "INSERT INTO fail2ban VALUES (0, '$IP', '', '', '', '*', 0, 'inout', '$(date +\%Y-\%m-\%d\ \%H:\%M:\%S)', $BanTime, '$Name', '$Name', '$Name');") Hope that helps, let us know how you get along


Your email address will not be published. Required fields are marked *