NetBox vCenter Server Plugin

A NetBox plugin for viewing and importing VMs from VMware vCenter servers.

Features

• Multi-vCenter Support - Connect to multiple vCenter servers (cached separately)
• VM Dashboard - View all VMs from vCenter with power state, vCPUs, memory, and disk
• VM Import - Import VMs from vCenter into NetBox with one click
• Comparison View - Compare vCenter VMs with NetBox to find differences
• Manual Cache Control - Data persists until you click Refresh
• MFA/2FA Support - Works with environments requiring multi-factor authentication

Requirements

• NetBox 4.0 or higher
• Python 3.10+
• VMware vSphere 7.0+ (tested with vSphere 8.0.3)

Installation

From PyPI (recommended)

pip install netbox-vcenter-server

From Source

git clone https://github.com/sieteunoseis/netbox-vcenter-server.git
cd netbox-vcenter-server
pip install -e .

Docker Installation

Add to your NetBox Docker requirements file:

# requirements-extra.txt
netbox-vcenter-server

Configuration

Add the plugin to your NetBox configuration:

# configuration.py or plugins.py

PLUGINS = [
    'netbox_vcenter',
]

PLUGINS_CONFIG = {
    'netbox_vcenter': {
        # Required: List of vCenter servers to choose from
        'vcenter_servers': [
            'vc-server1.example.com',
            'vc-server2.example.com',
        ],
        # Optional: saved credentials per server, to skip the manual login form.
        # Intended for a dedicated read-only service account that does not require
        # MFA - servers without an entry here still show the manual login form
        # (e.g. for MFA-enabled accounts).
        'vcenter_credentials': {
            'vc-server1.example.com': {
                'username': 'svc-netbox@vsphere.local',
                'password': 'changeme',
            },
        },
        # Connection settings
        'timeout': 60,       # Timeout for vCenter connections (seconds)
        'verify_ssl': False, # SSL verification (False for self-signed certs)
        # MFA/2FA settings (optional)
        'mfa_enabled': True,  # Show MFA warning in UI
        'mfa_label': 'MFA',   # Label shown in UI (e.g., "Duo", "2FA", "MFA")
        'mfa_message': 'Check your authenticator after clicking Connect & Sync.',
        # Name matching for duplicate detection
        # Options: "exact" (full name), "hostname" (strip domain), "regex"
        'name_match_mode': 'hostname',
        'name_match_pattern': r'^([^.]+)',  # Used with "regex" mode
        # Import settings
        'normalize_imported_name': True,  # "WebServer01.example.com" -> "webserver01"
        'default_tag': '',      # Tag slug to apply (e.g., "vcenter-sync")
        'default_role': '',     # Role slug (e.g., "server")
        'default_platform': '', # Platform slug (e.g., "vmware")
        'default_vrf': '',      # VRF name to scope IP dedup/creation (e.g., "management")
        'default_tenant': '',   # Tenant slug applied to IP addresses created during import
    }
}

All of a VM's network adapters are synced, not just the primary one: each becomes a NetBox VMInterface named to match vSphere's own adapter number (vSphere's "Network Adapter 1" becomes NetBox interface eth1), with its MAC address, connected/enabled state, and IP addresses attached. IP lookups reuse an existing IPAM record for the address whenever one already exists (regardless of its prefix length), instead of creating a duplicate /32. When a new record does need to be created, its prefix length is derived from the most specific containing NetBox Prefix. Set default_vrf if you use VRFs, so lookups and new records stay scoped to the correct one; set default_tenant to tag newly created IP addresses with a tenant. Per-interface MTU is not synced yet (vSphere reports this at the vSwitch/portgroup level, not directly on the adapter).

Each of a VM's hard disks is also synced as a NetBox VirtualDisk (name and size). Disks and interfaces removed from a VM in vCenter are left in place in NetBox rather than deleted.

Usage

Syncing VMs from vCenter

1. Navigate to Plugins > vCenter Dashboard
2. Select a vCenter server from the dropdown
3. Enter your username and password
4. Click Connect & Sync
5. If MFA is enabled, approve the authentication prompt
6. VMs will be fetched and cached (data persists until you click Refresh)

Importing VMs to NetBox

1. From the VM list, check the boxes next to VMs you want to import
2. Click Import Selected to NetBox
3. Select the target NetBox cluster
4. Click Import
5. VMs are created in NetBox with vCPUs, memory, disk, and status

Comparing vCenter with NetBox

1. Navigate to Plugins > Compare with NetBox
2. Select a vCenter server
3. View:
   • Only in vCenter - VMs that can be imported
   • Only in NetBox - VMs not found in vCenter (orphaned?)
   • Spec Differences - VMs with mismatched vCPUs, memory, or disk

Screenshots

Coming soon

Troubleshooting

Connection errors

• Verify vCenter hostname is reachable from the NetBox server
• Check that credentials are correct (use domain\username format)
• For self-signed certificates, set verify_ssl: False
• If using MFA/2FA, ensure you approve the authentication prompt promptly

Authentication issues

• Use format DOMAIN\username or username@domain
• Ensure the account has at least read-only access to vCenter

Development

Setup

git clone https://github.com/sieteunoseis/netbox-vcenter-server.git
cd netbox-vcenter-server
pip install -e ".[dev]"

Code Style

black netbox_vcenter/
isort netbox_vcenter/
flake8 netbox_vcenter/

Changelog

See CHANGELOG.md for release history.

Support

If you find this plugin helpful, consider supporting development:

License

Apache License 2.0 - See LICENSE for details.

Author

sieteunoseis (@sieteunoseis)