netbox-unifi-sync

netbox_unifi_sync is a NetBox 4.2+ plugin that runs UniFi -> NetBox sync jobs inside NetBox workers.

Visual Overview

flowchart LR
    U["UniFi Controller(s)"] --> P["netbox_unifi_sync 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)

Quick Start

1. Install

pip install netbox-unifi-sync

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

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

echo "netbox-unifi-sync" >> local_requirements.txt

2. Enable plugin in NetBox

PLUGINS = ["netbox_unifi_sync"]

PLUGINS_CONFIG = {
    "netbox_unifi_sync": {}
}

3. Apply migrations

python manage.py migrate

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)

5. Run first sync

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

CLI:

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

Credentials

Set credentials only in:

Plugins -> UniFi Sync -> Controllers

Scheduled Jobs

The plugin supports NetBox Scheduled Jobs.

Recommended intervals:

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

NetBox Permissions

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

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

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

Security Notes

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

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_sync/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).