02 Getting Started

Getting Started

From a clean Linux host to a verified AbuseIPDB report in about ten minutes.

---

Requirements

Item	Value	Notes
OS	Linux	systemd (recommended) or cron; tested on Debian/Ubuntu
Python	3.9+	standard library only; no pip packages, no venv
Fail2Ban	0.10+	tested on 1.1.0; fail2ban-client must be available
Privileges	root	installation writes to /etc, /usr/local, /var/lib
Egress	HTTPS 443 to api.abuseipdb.com	plus raw.githubusercontent.com / github.com for update checks
Account	free AbuseIPDB API key	free plan: 1000 reports + checks/day

⚠️ The API key is a secret. Never paste it into a chat, a ticket, a commit or a shell history you keep. The installer hides the prompt and writes the key to a mode-600 file. See API Key Management.

---

Quick install

git clone https://github.com/paulmann/Fail2Ban_AbuseIPDB.git
cd Fail2Ban_AbuseIPDB
sudo ./install.sh

On a terminal the installer asks for the API key once, hides the input and saves it to /etc/abuseipdb/.abuseipdb.key (mode 600). Non-interactive equivalent:

sudo ./install.sh --api-key "YOUR_ABUSEIPDB_API_KEY"

Attach the action to more than the default sshd jail:

sudo ./install.sh --api-key "YOUR_ABUSEIPDB_API_KEY" \
  --jails "sshd nginx-attack-scan nginx-wp-login nginx-php-probe proftpd exim-auth-fail"

Everything enabled:

sudo ./install.sh --api-key "YOUR_ABUSEIPDB_API_KEY" --all-jails --with-update-check

--all-jails attaches the action to every enabled jail except the aggregate recidive (which would only duplicate reports). --with-update-check adds a weekly check-only timer; it never installs updates automatically.

What the installer does

Step	Result
Pre-flight	root, Python ≥ 3.9, project files, fail2ban availability
API key	prompt / --api-key / env / existing key file / legacy config — then saved to the key file, mode 600
Code	/usr/local/lib/abuseipdb_reporter, /usr/local/sbin/abuseipdb-{report,enqueue,upgrade}
Configuration	/etc/abuseipdb/reporter.conf, mode 600 (no secrets inside)
fail2ban	action /etc/fail2ban/action.d/abuseipdb-async.conf, generated snippet /etc/fail2ban/jail.d/50-abuseipdb-reporter.local
Validation	fail2ban-client -t before any restart; abort + backup on failure
Scheduling	systemd timer abuseipdb-report.timer (16 min) or /etc/cron.d/abuseipdb-reporter
Update check	optional weekly abuseipdb-upgrade --check timer/cron
Backup	every replaced file under /var/backups/fail2ban-abuseipdb/pristine-<ts>/ + install state
Restart	fail2ban restarted (bans are restored from its DB; norestored = 1 prevents re-reporting)
Key check	one /check call validates the key online

The installer is idempotent: re-running it upgrades the code, keeps the existing key file untouched, keeps reporter.conf, the queue and the previously configured jail list (when --jails is omitted).

Verify the installation

# 1. the action is attached
fail2ban-client get sshd actions
#    The jail sshd has the following actions: nftables, abuseipdb-async

# 2. the key is found where it should be
/usr/local/sbin/abuseipdb-report --key-status
#    API key source: key file /etc/abuseipdb/.abuseipdb.key
#    key: 3078ab...0072

# 3. queue and journal
/usr/local/sbin/abuseipdb-report --stats

# 4. schedule
systemctl list-timers abuseipdb-report.timer

Produce the first report

The cleanest way is to let a real ban happen and wait at most one timer tick. To verify immediately, queue a ban for a real attacker address from your logs (never your own management IP):

# pick an address that actually attacked you, e.g. from
#   journalctl -u ssh | grep 'Failed password' | tail
/usr/local/sbin/abuseipdb-enqueue --ip 198.51.100.7 --jail sshd \
  --bantime 86400 --failures 4

# see exactly what would be sent — no API call
/usr/local/sbin/abuseipdb-report --dry-run

# send it now instead of waiting for the timer
/usr/local/sbin/abuseipdb-report

Expected log line:

reported ip=198.51.100.7 jail=sshd cats=18,22 size=402 -> 200 {"data":{"abuseConfidenceScore":100}}

⚠️ Never test with your own IP. fail2ban-client set <jail> banip <addr> bypasses ignoreip — this is fail2ban behaviour. With a web jail that bans all ports for the address, you can lock yourself out. If it happens, use an out-of-band console/VPS to run fail2ban-client set <jail> unbanip <addr>.

Schedule: systemd timer vs cron

	systemd timer (default)	cron (--cron)
Interval	exactly 16 min (OnUnitActiveSec), missed tick after downtime (Persistent=true)	*/16 — fires :00,:16,:32,:48 (12-minute gap before the hour)
Logs	file /var/log/abuseipdb-reporter.log (journald is not persistent on every host)	same file via redirection
Per-IP guarantee	20-minute throttle in the worker in both cases	same

Both schedules are safe: a /run lock prevents concurrent workers.

Upgrade

sudo /usr/local/sbin/abuseipdb-upgrade --check     # 10 = update available
sudo /usr/local/sbin/abuseipdb-upgrade --upgrade   # SHA-256 checked, key/config/queue kept

or re-run install.sh from a fresh checkout (it detects the configured jails and preserves the key file). Details: Self-Update.

Uninstall

sudo ./install.sh --uninstall          # removes code/action/timer; keeps config, queue, KEY FILE
sudo ./install.sh --uninstall --purge  # removes everything, including the key

Uninstall restores files that existed before the first installation (tracked in /var/lib/fail2ban-abuseipdb/install-state) and restarts fail2ban.

Non-root experiments

# full file layout under /tmp/stage, no systemd/fail2ban changes
sudo ./install.sh --root /tmp/stage --api-key "..." --cron --skip-api-check --no-restart

# print every action, change nothing
./install.sh --root /tmp/stage --api-key "..." --dry-run

--root is what the CI uses to test install/uninstall on every push.

Exit codes and staging

Code	Meaning
0	success / up to date
10	abuseipdb-upgrade --check: update available
1	installer, key check or updater error
2	bad arguments or missing key in a non-interactive run

Troubleshooting

If something does not work, start with Troubleshooting. The three diagnostic commands that answer most questions:

/usr/local/sbin/abuseipdb-report --stats
tail -n 50 /var/log/abuseipdb-reporter.log
fail2ban-client get <jail> actions

---

Next: Architecture · Configuration Reference · Fail2Ban Fundamentals