Metadata-Version: 2.4
Name: netbox-vmanage-sync
Version: 0.1.0
Summary: Discover Cisco Catalyst SD-WAN Edge devices in vManage and sync them into NetBox.
Author-email: Lukasz Luczak <bleblas@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bleblas2/netbox-vmanage-sync
Project-URL: Repository, https://github.com/bleblas2/netbox-vmanage-sync.git
Project-URL: Issues, https://github.com/bleblas2/netbox-vmanage-sync/issues
Keywords: netbox,netbox-plugin,SD-WAN,vManage,network-automation,ipam,dcim
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# NetBox vManage Sync

NetBox vManage Sync is a NetBox 4.6 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.
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](#what-it-does)
- [Safety Model](#safety-model)
- [Site Matching](#site-matching)
- [Installation](#installation)
- [First Run](#first-run)
- [Screenshots](#screenshots)
- [vManage API Endpoints](#vmanage-api-endpoints)
- [Data Rules](#data-rules)
- [Development](#development)
- [Acknowledgements](#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

- 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:

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

Enable the plugin in the NetBox configuration:

```python
PLUGINS = [
    "netbox_vmanage_sync",
]
```

Then migrate and restart NetBox and its worker:

```bash
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`:

```python
PLUGINS = [
    "netbox_vmanage_sync",
]
```

### Default Configuration

These defaults can be overridden in `PLUGINS_CONFIG`:

```python
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

Screenshots used below are stored under `docs/images/`.

### Settings

![vManage Sync settings](docs/images/settings.jpg)

### Discovered Devices

![Discovered vManage devices](docs/images/devices_sync.jpg)

### Device Mapping

![vManage device mapping](docs/images/device_edit.jpg)

### Sync Preview

![vManage sync preview](docs/images/devices_sync_preview.jpg)


### Sync Runs

![vManage sync runs](docs/images/sync_runs.jpg)

### Sync Run Details

![vManage sync run details](docs/images/sync_runs_detail.jpg)

### NetBox Device Result

![NetBox device result](docs/images/dcim_devices.jpg)

### Site Mapping Result

![NetBox Sites with vManage site ID](docs/images/dcim_sites.jpg)

## 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:

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

## Acknowledgements

Development of this plugin was assisted by OpenAI Codex.
