16 FAQ

FAQ

Short answers. Follow the links for details.

---

Does this replace the fail2ban action? No. It adds a second action (abuseipdb-async) next to your normal firewall action. The ban itself is unchanged; only a queue row is written.

Where is the API key? /etc/abuseipdb/.abuseipdb.key, mode 600. Not in reporter.conf, not in the code, not in releases, not in git. See API Key Management.

What happens on the very first run if I have no key? On a terminal the installer or abuseipdb-report --setup asks once and saves the key. Under systemd/cron it logs a clear error and exits 2 — it never hangs. See Getting Started.

Will an update overwrite my key? No. The key file is not part of the release archive; the installer keeps an existing key file untouched, and the updater snapshots/restores it if the installer fails.

Does the updater install updates automatically? No. abuseipdb-upgrade --upgrade is explicit. The optional timer only runs --check and never installs. See Self-Update.

What exactly is reported? The banned IP, jail, ban counters/time, generic attack patterns, and (for web jails) the attacker's own request URLs. No attempted usernames, no mail content, no client domains. See Report Anatomy.

Can I disable the project credit in reports? Yes: [report] attribution = no, or replace attribution_text with your own line.

Does it slow down bans? The extra action writes one SQLite row (~0.1 s). No network calls happen in the ban path.

What if AbuseIPDB is down? Events stay queued; retries happen every 16 minutes. Nothing is lost, and bans are unaffected.

What about the 1000/day limit? The worker caps at 900 reports/day and 25 per run, 20 minutes per IP. 429s are handled as normal deferrals. See Report Anatomy.

Does it support IPv6? Yes — addresses are validated with Python's ipaddress, fail2ban <HOST> matches IPv6, and the reporter stores/sends it unchanged. Add IPv6 ranges to [ignore] ranges and ignoreip.

Can I use it without systemd? Yes: install.sh --cron. The worker keeps its own per-IP throttle, so the schedule difference does not cause duplicate reports. See Getting Started.

Can I run it on several servers? Yes. Each server has its own queue and key file. Sharing one API key is possible; per-host keys make revocation easier.

How do I see what would be sent before it is sent? /usr/local/sbin/abuseipdb-report --dry-run prints the JSON payloads without calling the API.

How do I check whether my report reached AbuseIPDB? Use the check API with -d verbose and look for your comment/marker in reports[]; see Verification.

What if GitHub is blocked on the server? Use --manifest-url with a mirror, or install release archives manually. The reporter itself does not need GitHub.

Does the installer change my fail2ban thresholds? No. It only adds the action snippet and attaches it to the jails you name. Existing maxretry/findtime/bantime stay untouched. See Fundamentals.

Why does a web jail ban all ports? Because the jail has no port; fail2ban's default is 0:65535. Set port = 80,443. This was measured in production. See Web Protection.

Why does fail2ban-regex show 0 matches? Wrong log path/format, or the regex expects the timestamp — fail2ban strips the date before matching. See Fundamentals.

Can I test a ban with my own IP? No. Manual banip bypasses ignoreip, and a wrong jail/port scope can lock you out. Use a documentation IP or a real attacker IP from logs. See Verification.

How do I uninstall but keep data? sudo ./install.sh --uninstall keeps config, queue and key. --purge deletes them.

Where are the tests? tests/ (88 unit/integration tests), plus CI on Python 3.9–3.13, shellcheck and staged install/uninstall. See Development & Testing.

Is it really dependency-free? Yes — Python standard library only (urllib, sqlite3, ipaddress, tarfile, ...). No pip packages, no venv, no daemons.

What license? MIT. See LICENSE.

---

Next: Troubleshooting · Development & Testing · Home