NetBox vManage Sync

NetBox vManage Sync is a NetBox plugin for discovering Cisco Catalyst SD-WAN Edge devices from Cisco vManage / Catalyst SD-WAN Manager and synchronizing their inventory into NetBox.

The plugin reads from vManage and writes controlled changes to NetBox: devices, interfaces, IP addresses, MAC addresses, primary IPs, and VRRP/FHRP objects. Access to the vManage API is read-only: the plugin retrieves inventory and operational data but never changes vManage configuration. The authentication POST only establishes a session; all inventory requests use GET. Discovery is safe by default: controllers are ignored, discovered Edge devices are disabled until explicitly enabled, and NetBox writes are add-only unless Update existing is enabled.

Contents

• What It Does
• Safety Model
• Site Matching
• Installation
• First Run
• Screenshots
• vManage API Endpoints
• Data Rules
• Development
• Acknowledgements

What It Does

NetBox vManage Sync helps keep NetBox aligned with Cisco SD-WAN Edge inventory.

• Discovers Edge devices from vManage.
• Maps discovered devices to NetBox Sites.
• Previews changes before applying them.
• Creates or updates NetBox Devices, Interfaces, IP addresses, MAC addresses, primary IP assignments, and FHRP/VRRP objects.
• Records Sync Runs with source snapshots, counters, warnings, and created objects.
• Supports reverting objects created by a selected Apply run.
• Runs manual single-device syncs and bulk sync jobs through NetBox workers.

Safety Model

• vManage is used as a read-only data source; the plugin never pushes configuration changes to it.
• Controllers (vManage, vSmart, and vBond) are never imported.
• Discovered Edge devices are disabled by default, so hubs require an explicit enable.
• The plugin never deletes objects during discovery or sync.
• Revert deletes only objects recorded as created by a selected apply run.
• Existing devices are skipped while Update existing is disabled.
• Passwords and session tokens are never written to plugin logs.

Site matching

The plugin preserves a manual Site selection first. Otherwise it tries, in order:

1. NetBox Site custom field SdwanSiteId equals vManage site-id.
2. Site names match after replacing _ and - with spaces, collapsing whitespace, and comparing case-insensitively.
3. The uniquely nearest Site is within the configured GPS limit (default 1 km).

Ambiguous matches remain unassigned and must be selected in Device vManage Config.

Installation

Install the plugin into the NetBox Python environment:

source /opt/netbox/venv/bin/activate
pip install netbox-vmanage-sync

Enable the plugin in the NetBox configuration:

PLUGINS = [
    "netbox_vmanage_sync",
]

Then migrate and restart NetBox and its worker:

cd /opt/netbox/netbox
python manage.py migrate netbox_vmanage_sync
sudo systemctl restart netbox netbox-rq

Docker

For containerized NetBox deployments, install the plugin into your NetBox image and mount a NetBox configuration file that enables it, for example configuration/plugins.py:

PLUGINS = [
    "netbox_vmanage_sync",
]

Default Configuration

These defaults can be overridden in PLUGINS_CONFIG:

PLUGINS_CONFIG = {
    "netbox_vmanage_sync": {
        "ignored_interface_names": [
            "nvi0",
            "vmanage_system",
            "null0",
            "appnav-compress",
        ],
        "ignored_interface_patterns": [
            r"virtualportgroup\d+",
            r"loopback655\d{2}",
            r"service-engine.*",
        ],
        "default_platform_name": "Cisco SD-WAN",
        "default_platform_slug": "sd-wan-cisco",
        "sdwan_site_id_field": "SdwanSiteId",
        "controller_types": ["vmanage", "vsmart", "vbond", "vedge-vbond"],
        "edge_types": ["vedge", "cedge"],
    },
}

First run

1. Open Plugins → vManage Sync → Settings.
2. Enter the vManage base URL, username, password, SSL settings, and save.
3. Open Device vManage Config and click Discover from vManage.
4. Review automatic Site matches and correct unmatched devices manually.
5. Enable only the Edge devices intended for import.
6. Open an Edge row, select Preview sync, inspect the snapshot, and apply it.
7. After validating several devices, use Sync and Apply all enabled devices on the device list. Confirm the eligible count and follow the queued NetBox job.

Screenshots

Individual screenshots and reusable absolute links are available in docs/images/README.md.

vManage API Endpoints

The client uses the same session flow as the site-creator project:

• POST /j_security_check
• GET /dataservice/client/token
• GET /dataservice/device
• GET /dataservice/device/interface?deviceId=<system-ip>
• GET /dataservice/device/vrrp?deviceId=<system-ip>

Data rules

• IPv4 netmasks returned separately by vManage are converted to CIDR prefixes.
• 0.0.0.0 and zero MAC addresses are ignored.
• A physical interface wins when vManage repeats the same address on Tunnel0.
• IPv6 without an explicit prefix is reported and skipped rather than guessed.
• Ignore disabled interfaces skips interfaces whose vManage Admin Status is down, together with their IP addresses, MAC addresses, and FHRP memberships.
• Interfaces with an all-zero MAC or matching the configured ignored interface rules are removed before Preview and are not stored in Sync Run snapshots. See Default Configuration for the editable defaults.
• The vManage system-ip address becomes primary IPv4 when assigned to the device.
• Preferred primary IPv4 interface can select an interface such as Loopback1000; when it is absent or has no usable address, primary IPv4 falls back to system-ip.
• The first assigned global IPv6 address becomes primary IPv6.
• VRRP data creates a NetBox FHRP group, interface assignment, priority, and VIP.
• Tags selected in vManage Sync Settings are added to every tag-capable object created or synchronized by Apply. Existing tags on those objects are preserved.

Development

The public netbox_vmanage_sync.engine module is a compatibility facade. The implementation is split by responsibility under netbox_vmanage_sync.sync:

• orchestrator.py coordinates Preview and Apply.
• interfaces.py handles interfaces, MAC addresses, and admin-status filtering.
• addresses.py handles IP assignments and primary IP selection.
• fhrp.py handles VRRP groups, memberships, and VIPs.
• sites.py manages the SdwanSiteId written during Apply.
• tags.py propagates tags selected in Settings.
• result.py stores counters, warnings, changes, and synchronized objects.

Run local checks before submitting changes:

python3 -m compileall netbox_vmanage_sync
pytest -q
git diff --check

Acknowledgements

Development of this plugin was assisted by OpenAI Codex.