UniFi Toolkit

A set of Python scripts for auditing, backing up, and safely applying configuration to a UniFi gateway through its local HTTP API — with drift detection and a "diagnose before you touch anything" workflow.

The problem it solves

Making changes to a UniFi gateway by hand through the web UI is easy to get wrong and hard to undo. This toolkit captures a full configuration snapshot, checks the live state against a desired baseline, and applies fixes idempotently — so every change is backed up first, verifiable, and repeatable.

Tech stack

• Python 3 (standard library + requests)
• The UniFi controller's local HTTP/JSON API
• OS keyring for credential storage, with an encrypted file fallback

Key features

• Diagnostic dump — capture a full, timestamped snapshot of the current configuration before anything changes
• Drift detection — compare live state to a desired baseline and report PASS / DRIFT / ERROR per check
• Idempotent apply — apply fixes that are safe to re-run, with an automatic pre-change backup every time
• Manual update control — check for firmware updates and install them only when you choose, so the gateway never surprise-reboots mid-game at 2 a.m.
• Offline verification — a test suite that validates logic against captured fixtures without touching a live device
• Secure credentials — store controller credentials in the OS keyring instead of in plaintext

Screenshots

Staying in control of updates

A UniFi console will happily update and reboot itself in the middle of the night, dropping your internet. This toolkit keeps that on your terms:

python unifi_update.py                       # read-only: what updates are available?
python unifi_update.py --install --all --apply --yes   # install them now, on your schedule
python unifi_apply.py --verify               # reports auto-update posture (no-auto-updates check)

Device firmware auto-update is disabled by the no-auto-firmware fix and is verified by --verify. The UniFi OS console and Network-application self-update toggles are GUI-managed (Settings → System → Updates) and are not exposed to the Network API, so turn them off there yourself — --verify reminds you but cannot read their state.

Setup

1. Install dependencies:

   pip install -r requirements.txt

2. On first run you will be prompted for your controller address and credentials, which are stored in your OS keyring (never written to the repo).
3. Capture a snapshot before making changes:

   python unifi_diagnostic_v2.py

See UNIFI_DIAGNOSTIC_README.md for the full operational runbook.

Note for reusers

The device inventory (IP addresses, MAC addresses, and device names) in unifi_apply.py reflects one specific home network. Replace those values with your own before using the apply step against your gateway.