Fail2Ban Integration

Automatically report banned IPs to IPWhois.net Blacklist. Step-by-step setup guide with code examples.

186,817 IPs 8,265 reports Free API

Quick Install

Ubuntu

Debian

Raspberry Pi

CentOS

RHEL

Fedora

Rocky

AlmaLinux

Alpine

Arch

openSUSE

Amazon Linux

Oracle Linux

Kali

Run this command as root to install Fail2Ban and configure auto-reporting:

No API key needed (500 reports/day):

curl -sL https://bl.ipwhois.net/api/fail2ban/install | sudo bash

No curl? Use wget:

wget -qO- https://bl.ipwhois.net/api/fail2ban/install | sudo bash

Installs Fail2Ban if needed, creates action + jail config, tests API connection.

Requires: Fail2Ban 0.10+ curl or wget Root access

What is Fail2Ban?

Fail2Ban is an intrusion prevention framework that monitors log files (SSH, Apache, Nginx, etc.) for suspicious activity and automatically bans offending IP addresses by updating firewall rules (iptables/nftables).

By adding a custom action, every banned IP gets reported to the IPWhois.net Blacklist, contributing to community threat intelligence with zero manual effort.

Block

Bans attacking IPs locally via iptables/nftables after failed login attempts.

Report

Sends every banned IP to IPWhois.net Blacklist automatically via custom action.

Contents

Installation
Step 1: Create the action file
Step 2: Configure jail (sshd)
Step 3: Other services
Threat types for different jails
Testing & verification
Troubleshooting
Advanced configuration

Installing Fail2Ban

If Fail2Ban is already installed, skip to Step 1.

Ubuntu / Debian

sudo apt update
sudo apt install -y fail2ban curl
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

CentOS / RHEL / Rocky / Alma

sudo dnf install -y epel-release
sudo dnf install -y fail2ban fail2ban-firewalld curl
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Step 1: Create the Action File

Create /etc/fail2ban/action.d/ipwhois-report.conf:

/etc/fail2ban/action.d/ipwhois-report.conf

[Definition]
actionstart =
actionstop =
actionban = curl -s --max-time 10 -X POST "https://bl.ipwhois.net/api/report" \
              -d "ip=" -d "type=" \
              -d "message=Fail2Ban++ban" \
              -d "source=fail2ban" >> /var/log/ipwhois-report.log 2>&1
actionunban =
[Init]
bl_type = brute-force

Important: Make sure the file is owned by root: sudo chmod 644 /etc/fail2ban/action.d/ipwhois-report.conf

Step 2: Configure Jail (sshd)

Edit /etc/fail2ban/jail.local:

/etc/fail2ban/jail.local - sshd jail

[sshd]
enabled  = true
port     = ssh
filter   = sshd
logpath  = /var/log/auth.log
maxretry = 5
findtime = 600
bantime  = 3600

# Ban with firewall AND report to IPWhois.net Blacklist
action   = iptables-multiport[name=sshd, port="ssh", protocol=tcp]
           ipwhois-report[threat_type=brute-force]

CentOS/RHEL: Use logpath = /var/log/secure and firewallcmd-ipset instead of iptables-multiport.

Restart Fail2Ban:

sudo systemctl restart fail2ban
sudo fail2ban-client status sshd

Step 3: Other Services

Postfix (email spam)

[postfix]
enabled  = true
port     = smtp,465,submission
filter   = postfix[mode=auth]
logpath  = /var/log/mail.log
maxretry = 3
bantime  = 7200
action   = iptables-multiport[name=postfix, port="smtp,465,submission"]
           ipwhois-report[threat_type=spam]

Nginx (HTTP auth + bot detection)

[nginx-http-auth]
enabled  = true
port     = http,https
filter   = nginx-http-auth
logpath  = /var/log/nginx/error.log
maxretry = 5
bantime  = 3600
action   = iptables-multiport[name=nginx-auth, port="http,https"]
           ipwhois-report[threat_type=brute-force]

[nginx-botsearch]
enabled  = true
port     = http,https
filter   = nginx-botsearch
logpath  = /var/log/nginx/access.log
maxretry = 3
bantime  = 86400
action   = iptables-multiport[name=nginx-bot, port="http,https"]
           ipwhois-report[threat_type=scan]

Threat Types

Jail	threat_type	Description
`sshd`	`brute-force`	SSH login attempts
`postfix`	`spam`	Email relay / SMTP auth abuse
`dovecot`	`brute-force`	IMAP/POP3 login attempts
`apache-auth`, `nginx-http-auth`	`brute-force`	HTTP authentication attempts
`apache-badbots`	`bot`	Malicious crawler / scraper
`apache-noscript`, `nginx-botsearch`	`scan`	Vulnerability scanning
`recidive`	`brute-force`	Repeat offenders

Testing & Verification

Test the API call manually

curl -sSf -X POST https://bl.ipwhois.net/api/report \
  -d "ip=192.0.2.1" \
  -d "type=brute-force" \
  -d "message=Test+report+from+setup"

Trigger a test ban

sudo fail2ban-client set sshd banip 192.0.2.99
sudo fail2ban-client status sshd
sudo fail2ban-client set sshd unbanip 192.0.2.99

Check syslog

sudo grep "ipwhois-bl" /var/log/syslog | tail -10

Troubleshooting

curl: command not found - Install with apt install -y curl or dnf install -y curl.
Permission denied - Check ownership: sudo chown root:root /etc/fail2ban/action.d/ipwhois-report.conf
API unreachable - Test with curl -v https://bl.ipwhois.net/api/check?ip=8.8.8.8
Fail2Ban fails to start - Check syntax: sudo fail2ban-client -t. Ensure action lines are indented with spaces.
Reports not appearing - Private IPs (10.x, 172.16-31.x, 192.168.x) are rejected. Check rate limits (500/day).

Advanced Configuration

Only report repeat offenders

[recidive]
enabled  = true
filter   = recidive
logpath  = /var/log/fail2ban.log
bantime  = 604800
findtime = 86400
maxretry = 3
action   = iptables-allports[name=recidive]
           ipwhois-report[threat_type=brute-force]

This only reports IPs banned 3+ times within 24 hours, filtering out one-off attempts.

Whitelisting IPs

[DEFAULT]
ignoreip = 127.0.0.1/8 ::1 10.0.0.0/8 192.168.0.0/16 YOUR.OFFICE.IP.HERE

Done! Your server is now automatically reporting threats to the IPWhois.net Blacklist community.