04 Configuration Reference

Configuration Reference

One INI file: /etc/abuseipdb/reporter.conf, mode 600. The API key is not in it — see API Key Management.

---

Where the file lives

Default path	/etc/abuseipdb/reporter.conf
Permissions	600 root:root (the file itself contains no secret, but it is root-only by policy)
Override	abuseipdb-report --config /path/file, or ABUSEIPDB_REPORTER_CONFIG env var
Generated by	install.sh from config/reporter.conf.example
Applied	on every worker run — no restart needed for changes to this file

[abuseipdb]

Option	Default	Meaning
api_key_file	/etc/abuseipdb/.abuseipdb.key	file that stores the key (mode 600)
api_key	(empty)	deprecated legacy key in the config; use --migrate-key
api_url	https://api.abuseipdb.com/api/v2/report	report endpoint
check_url	https://api.abuseipdb.com/api/v2/check	endpoint used by --check-key
enabled	yes	no pauses sending; bans keep being queued
timeout	25	HTTP timeout, seconds
min_interval_ip	1200	min seconds between two reports for one IP (AbuseIPDB requires ≥900)
max_reports_per_run	25	cap per timer tick
max_reports_per_day	900	daily budget (free plan: 1000 requests/day)
comment_max_bytes	1000	comment truncation (API hard limit 1024)
evidence_max_lines	4	how many evidence lines/URLs to include
skip_jails	recidive	comma-separated jails never reported

[database]

Option	Default	Meaning
path	/var/lib/abuseipdb/abuseipdb.sqlite3	queue + report journal (SQLite, WAL)
fail2ban_db	/var/lib/fail2ban/fail2ban.sqlite3	fail2ban's database (evidence source)
retention_days	30	finished events and old attempts are deleted after this period
max_attempts	10	transient errors are retried, then marked “gave up”

[report]

Option	Default	Meaning
server_ip	auto-detected by installer	shown in the comment as the reporting server
hostname	auto-detected	reserved for comments/logs
attribution	yes	append the project credit to every report
attribution_text	Reported via Fail2Ban_AbuseIPDB Monitor: https://github.com/paulmann/Fail2Ban_AbuseIPDB	the credit text; replace with your own or a neutral phrase

The attribution footer is appended after the body is truncated, so it never gets cut off. Disable with attribution = no for fully neutral reports.

[update]

Option	Default	Meaning
manifest_url	https://raw.githubusercontent.com/paulmann/Fail2Ban_AbuseIPDB/main/updater.json	manifest used by abuseipdb-upgrade; change for mirrors/testing

[ignore]

ranges — comma/whitespace separated CIDR list that must never be reported.

The example file ships with:

• private, loopback, link-local, documentation, reserved space;
• Cloudflare IPv4/IPv6 ranges (if your sites are behind Cloudflare, the logged address is a CDN edge, not the real client — never report it);
• placeholders for your own management addresses.

[ignore]
ranges = 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8,
         203.0.113.10/32, 2001:db8::/32,
         173.245.48.0/20, 103.21.244.0/22, ...

Add your own public addresses, office/partner networks, monitoring and backup hosts. An automatically banned address never matches ignoreip because fail2ban already filters it, but manual bans and edge cases do — be explicit.

[category_map]

Maps a fail2ban jail to one or more AbuseIPDB category IDs. Default:

Jail	Categories	Meaning
sshd	18,22	Brute-Force, SSH
proftpd	18,5	Brute-Force, FTP Brute-Force
exim-auth-fail	18	Brute-Force (SMTP AUTH)
exim-isp	18,11	Brute-Force, Email Spam
nginx-attack-scan	21,19	Web App Attack, Bad Web Bot
nginx-wp-login	21,18	Web App Attack, Brute-Force
nginx-php-probe	21,15	Web App Attack, Hacking
nginx-forbidden	21	Web App Attack

SQL-injection patterns (UNION SELECT, information_schema, OR 1=1, sleep(, load_file() add category 16 automatically. Add your own jails:

[category_map]
my-dovecot-jail = 18,11
my-api-abuse-jail = 21,15

Unknown jails fall back to 21 (Web App Attack).

Minimal configuration

Only the endpoint policy is required; everything else has safe defaults:

[abuseipdb]
api_key_file = /etc/abuseipdb/.abuseipdb.key

A production-minded configuration

[abuseipdb]
api_key_file = /etc/abuseipdb/.abuseipdb.key
min_interval_ip = 1200
max_reports_per_run = 25
max_reports_per_day = 900
comment_max_bytes = 1000
evidence_max_lines = 4
skip_jails = recidive

[database]
path = /var/lib/abuseipdb/abuseipdb.sqlite3
fail2ban_db = /var/lib/fail2ban/fail2ban.sqlite3
retention_days = 30
max_attempts = 10

[report]
server_ip = 203.0.113.10
attribution = yes

[ignore]
ranges = 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16,
         172.16.0.0/12, 192.168.0.0/16, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24,
         224.0.0.0/4, 240.0.0.0/4, ::1/128, fc00::/7, fe80::/10, 2001:db8::/32,
         203.0.113.10/32   # your own management IP

[category_map]
sshd = 18,22
nginx-attack-scan = 21,19
nginx-wp-login = 21,18
nginx-php-probe = 21,15
proftpd = 18,5
exim-auth-fail = 18

Environment variables

Variable	Used by	Meaning
ABUSEIPDB_API_KEY / ABUSEIPDB_KEY	report/installer/updater	key override (not persisted)
ABUSEIPDB_KEY_FILE	report	key file path override
ABUSEIPDB_REPORTER_CONFIG	CLI	config path when --config is omitted

Validation and reload

# configuration is read on every run
/usr/local/sbin/abuseipdb-report --key-status
/usr/local/sbin/abuseipdb-report --stats
/usr/local/sbin/abuseipdb-report --dry-run

# fail2ban action/jail changes need a config test and a reload/restart
fail2ban-client -t && systemctl restart fail2ban

Restart vs reload: adding or changing an action in a jail is reliable only after a restart on some fail2ban versions. The installer always restarts fail2ban; do the same when you edit 50-abuseipdb-reporter.local by hand.

---

Next: API Key Management · Report Anatomy · Fail2Ban Fundamentals