netbox-unifi-sync 0.3.21

Production-ready NetBox plugin for UniFi synchronization

netbox-unifi-sync

[!WARNING] We are aware that there are issues in the codebase. This is a hobby project maintained in spare time. Fixes and improvements are implemented when time allows. Do not deploy in production without proper validation.

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

---

[!IMPORTANT] NetBox should be treated as the Source of Truth. Objects created or managed by this plugin should not be manually modified unless you understand how future sync runs will affect them.

---

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
• 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] Sync is strictly one-way: UniFi -> NetBox. No configuration is ever pushed back to UniFi.

---

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

[!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_sync"]

PLUGINS_CONFIG = {
    "netbox_unifi_sync": {}
}

---

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_sync_run --dry-run --json
python manage.py netbox_unifi_sync_run
python manage.py netbox_unifi_sync_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.

---

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_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).

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