06 Self Update

Self-Update

abuseipdb-upgrade compares the installed version with updater.json on GitHub, verifies the release archive with SHA-256 and runs the project installer without touching the key file, configuration, queue or jail list.

---

Commands

abuseipdb-upgrade --check
#   0  already up to date
#   10 update available
#   1  error (network, invalid manifest, ...)

abuseipdb-upgrade --check --json          # machine-readable
abuseipdb-upgrade --check --quiet         # exit code only

sudo abuseipdb-upgrade --upgrade          # confirm interactively
sudo abuseipdb-upgrade --upgrade --yes    # non-interactive
abuseipdb-upgrade --upgrade --dry-run     # print the plan, download nothing

Binary path: /usr/local/sbin/abuseipdb-upgrade (installed by install.sh). From a checkout: python3 bin/abuseipdb-upgrade.

Manifest

updater.json in the repository root is the only source of truth:

{
  "name": "Fail2Ban_AbuseIPDB",
  "version": "1.1.1",
  "released": "2026-10-20",
  "requires_python": ">=3.9",
  "tarball": "https://github.com/paulmann/Fail2Ban_AbuseIPDB/releases/download/v1.1.1/Fail2Ban_AbuseIPDB-1.1.1.tar.gz",
  "sha256": "4d612d52ff3be034cff0303d4d913ab5f9891c08be41157b9390f232facd77a3",
  "release_notes": "https://github.com/paulmann/Fail2Ban_AbuseIPDB/releases/tag/v1.1.1",
  "changelog": "https://github.com/paulmann/Fail2Ban_AbuseIPDB/blob/main/CHANGELOG.md",
  "notes": "Short human-readable summary"
}

Override the URL with --manifest-url or [update] manifest_url in reporter.conf (mirrors, air-gapped staging, tests).

What --upgrade does, step by step

1. Fetch the manifest; compare version with the installed __version__ (semantic compare). --force installs even when the remote version is not newer.
2. Download the tarball over HTTPS into a temporary directory.
3. Require sha256 in the manifest and verify the archive. A mismatch or a missing checksum aborts before anything is extracted or executed.
4. Extract with a safe extractor: absolute paths, .. traversal, symlinks, hard links and device entries are rejected.
5. Snapshot /etc/abuseipdb/.abuseipdb.key (content + mode).
6. Run install.sh from the extracted tree. The installer:
   • keeps an existing key file untouched;
   • keeps reporter.conf (only api_key_file is ensured inside [abuseipdb]);
   • keeps the SQLite queue;
   • keeps the configured jail list (detected from 50-abuseipdb-reporter.local);
   • backs up every replaced file to /var/backups/fail2ban-abuseipdb/pristine-<ts>/;
   • validates fail2ban-client -t before restarting.
7. If the installer fails or the key file disappeared, restore the snapshot and report an error.

The release archive contains no key, configuration, queue or logs.

Weekly availability check

sudo ./install.sh --with-update-check

• systemd: abuseipdb-upgrade-check.timer — Monday 04:30 with 30-minute jitter;
• cron: /etc/cron.d/abuseipdb-upgrade-check.

It runs abuseipdb-upgrade --check --quiet only. It never installs an update. Automatic installation is intentionally absent: a production firewall host should choose its restart window.

Verified on a live host

The project was updated in place on a production server:

$ abuseipdb-upgrade --check
Installed version: 1.1.0
Latest version:    1.1.1
Update available:  https://github.com/paulmann/Fail2Ban_AbuseIPDB/releases/tag/v1.1.1
$ sudo abuseipdb-upgrade --upgrade --yes
Downloading https://github.com/.../Fail2Ban_AbuseIPDB-1.1.1.tar.gz
Running installer: bash /tmp/abuseipdb-update-.../Fail2Ban_AbuseIPDB/install.sh --yes
Updated to 1.1.1. API key file and configuration were preserved.

$ sha256sum /etc/abuseipdb/.abuseipdb.key
<same checksum before and after>     # key preserved

Rollback

Situation	Action
installer failed during update	updater restores the key snapshot; nothing was installed
bad release after a successful update	restore files from /var/backups/fail2ban-abuseipdb/pristine-<ts>/ or reinstall a known-good tag
want to pin a version	disable the check timer; install the desired release archive manually with install.sh
key concerns	key file is untouched by updates; it can be restored from your own backup

The queue, configuration and key file are independent of the code and therefore survive a code rollback.

Security notes

• The manifest is fetched over HTTPS; the archive is additionally pinned by SHA-256.
• --check and --dry-run work as an unprivileged user; --upgrade requires root.
• Only the project's own install.sh is executed from the archive.
• The key is never transmitted by the updater.

---

Next: Report Anatomy · Troubleshooting · Development & Testing