netbox-unifi 1.0.0

Production-ready NetBox plugin for UniFi synchronization

NetBox UniFi

netbox_unifi is a fork of netbox-unifi-sync to make changes along with special feature use cases. netbox_unifi is a NetBox 4.2+ plugin that syncs your UniFi controller to NetBox to create a source of truth.

All credits go to the team at unifi2netbox. Without them, this repo wouldn't exist and cool stuff wouldn't happen 😉

Visual Overview

flowchart LR
    U["UniFi Controller(s)"] --> P["netbox_unifi plugin<br/>NetBox Jobs (RQ)"]
    P --> N["NetBox DCIM/IPAM/Wireless"]
    A["Plugin UI<br/>Settings/Controllers/Mappings"] --> P

---

Architecture & Internal Flow

Runtime Execution Flow

flowchart TD
    A[Scheduled Job / Manual Trigger] --> B[NetBox RQ Worker]
    B --> C[Load Plugin Settings]
    C --> D[Authenticate to UniFi]
    D --> E[Fetch Data from UniFi API]
    E --> F[Normalize / Map Data]
    F --> G[Create / Update NetBox Objects]
    G --> H[Write Audit Log]

---

Detailed Sync Pipeline

flowchart LR
    U[UniFi API] --> V[Devices]
    U --> W[VLANs]
    U --> X[WLANs]
    U --> Y[DHCP Scopes]

    V --> M1[Device Mapping]
    W --> M2[VLAN Mapping]
    X --> M3[Wireless Mapping]
    Y --> M4[IP Range Mapping]

    M1 --> NB[NetBox ORM]
    M2 --> NB
    M3 --> NB
    M4 --> NB

    NB --> DB[(NetBox Database)]

---

Object Lifecycle Logic

flowchart TD
    A[UniFi Object] --> B{Exists in NetBox?}
    B -- Yes --> C[Update Object]
    B -- No --> D[Create Object]
    C --> E[Mark as Synced]
    D --> E
    E --> F{Cleanup Enabled?}
    F -- Yes --> G[Remove Stale Objects]
    F -- No --> H[Keep Orphaned Objects]

---

Authentication Flow

flowchart LR
    A[Plugin Settings] --> B{Auth Mode}
    B -- API Key --> C[Attach Authorization Header]
    B -- Username/Password --> D[Session Login]
    D --> E[Optional MFA]
    C --> F[Authenticated API Session]
    E --> F
    F --> G[Execute Requests]

---

Error Handling & Retry Logic

flowchart TD
    A[API Request] --> B{Success?}
    B -- Yes --> C[Process Response]
    B -- No --> D{Retry < Max Attempts?}
    D -- Yes --> E[Backoff + Retry]
    D -- No --> F[Log Error]
    F --> G[Mark Job Failed]

---

Features

• Device sync (devices, interfaces, VLANs, prefixes, WLANs, uplink relations, IP assignments)
• Security Appliance sync — VLAN subinterfaces and gateway IPs created correctly, including Integration API controllers
• MAC address sync — per-port MACs (Legacy API) or device base MAC on Port 1 (Integration API); NetBox 4.5 MACAddress model compatible
• DHCP scope sync to NetBox IP Ranges
• Client IP sync to NetBox IPAM with unifi-client tagging, stable MAC markers, descriptions, and interface assignment by MAC when NetBox has a matching DCIM or virtualization interface
• NetBox Change Log support for global settings, controllers, and site mappings
• UniFi auth via API key or legacy login (username/password + optional MFA)
• Manual and scheduled sync jobs
• Runtime settings stored in plugin models (Settings, Controllers, Site mappings)

[!NOTE] Normal sync direction is UniFi -> NetBox. DHCP-to-static writeback is the only UniFi write path, and it runs only when dhcp_writeback_enabled is explicitly enabled.

---

Quick Start

1. Install

pip install netbox-unifi

PyPI project page: https://pypi.org/project/netbox-unifi/

For netbox-docker, add the package to local_requirements.txt before build:

echo "netbox-unifi" >> local_requirements.txt

[!IMPORTANT] The plugin must be installed in the same environment as both NetBox and the worker container. Otherwise scheduled jobs will fail.

---

2. Enable plugin in NetBox

PLUGINS = ["netbox_unifi"]

PLUGINS_CONFIG = {
    "netbox_unifi": {}
}

---

3. Apply migrations

python manage.py migrate

[!CAUTION] Skipping migrations will result in database errors and plugin initialization failure.

---

4. Configure in UI

Go to:

Plugins -> UniFi Sync

Configure:

1. Settings (tenant_name, netbox_roles, defaults)
2. Controllers (URL, auth mode, credentials)
3. Site mappings (if UniFi/NetBox site names differ)

[!TIP] Use a dedicated read-only API account in UniFi for synchronization. This limits impact if credentials are exposed.

---

5. Run first sync

UI: Plugins -> UniFi Sync -> Sync Dashboard -> Run now

CLI:

python manage.py netbox_unifi_run --dry-run --json
python manage.py netbox_unifi_run
python manage.py netbox_unifi_run --cleanup

[!IMPORTANT] Always run the first execution with --dry-run to verify intended changes before writing to NetBox.

[!CAUTION] The --cleanup flag removes objects in NetBox that no longer exist in UniFi. Review carefully before using in production.

---

Credentials

Set credentials only in:

Plugins -> UniFi Sync -> Controllers

[!WARNING] Never store UniFi credentials in PLUGINS_CONFIG. Configuration files may end up in version control or logs.

---

Scheduled Jobs

The plugin supports NetBox Scheduled Jobs.

Recommended intervals:

• Small environments: every 30–60 minutes
• Larger environments: every 2–4 hours

[!NOTE] High sync frequency increases load on both the UniFi controller and NetBox worker processes.

---

NetBox Permissions

For normal NetBox users, grant permissions through NetBox object permissions:

• View dashboard/run history: view on netbox_unifi.SyncRun
• Queue a manual sync job: add on netbox_unifi.SyncRun
• Manage controllers: view/add/change/delete on netbox_unifi.UnifiController
• Test controller connectivity: change on netbox_unifi.UnifiController
• Manage site mappings: view/add/change/delete on netbox_unifi.SiteMapping
• Manage global settings: view/change on netbox_unifi.GlobalSyncSettings
• View audit log: view on netbox_unifi.PluginAuditEvent

The legacy custom permission netbox_unifi.run_sync is still accepted by the view for compatibility, but NetBox object permissions map naturally to netbox_unifi.add_syncrun. The legacy custom permission netbox_unifi.test_controller is also accepted, but NetBox object permissions map naturally to netbox_unifi.change_unificontroller.

---

Security Notes

• SSL verification defaults to true
• Secrets are redacted in run history and audit logs
• Timeouts, retries, and backoff are configurable

[!IMPORTANT] If disabling SSL verification for testing, restrict access to the controller network. Never disable SSL verification in production environments.

---

Documentation

• Server install guide
• NetBox plugin mode
• Configuration reference
• Troubleshooting
• Release and PyPI publish
• netbox-docker setup
• Wiki source pages
• GitHub Wiki

---

Maintainer: Release to PyPI

1. Bump version in:
   • pyproject.toml ([project].version)
   • netbox_unifi/version.py (__version__)
   • netbox-plugin.yaml (compatibility[].release)
2. Configure PyPI Trusted Publisher (OIDC) for this repository/workflow.
3. Create tag vX.Y.Z either:
   • via GitHub Actions Create Release Tag (manual) (recommended), or
   • manually with git:
   • git tag -a vX.Y.Z -m "Release vX.Y.Z"
   • git push origin vX.Y.Z
4. release.yml runs on the tag push, gates on lint/tests, and creates the GitHub Release.
5. publish-python-package.yml runs on release: published and publishes to PyPI (can also be run manually for retry).

[!NOTE] GitHub releases created by release.yml use GITHUB_TOKEN. If GitHub does not emit a follow-up release: published workflow event, run Publish Python Package manually from Actions with the same tag.

[!CAUTION] Version mismatch between pyproject.toml, version.py, and netbox-plugin.yaml will break the release pipeline.