A NetBox plugin for synchronizing network devices between NetBox and WhatsUp Gold monitoring systems.

New to this plugin? See the Complete Deployment Guide for step-by-step installation instructions.

Already familiar with NetBox plugins? Jump to Installation below.

This plugin provides automated bidirectional synchronization between NetBox and WhatsUp Gold, allowing you to:

• Import devices discovered in WhatsUp Gold into NetBox
• Export devices from NetBox to WhatsUp Gold for monitoring
• Keep device information synchronized between both systems
• Monitor sync status and troubleshoot sync issues
• Manage multiple WhatsUp Gold connections
• Automatically create NetBox sites, device types, and manufacturers from WUG data
• Automatically add NetBox devices to WUG when they are created with active status and IP addresses

• Bidirectional Device Sync:
  • WUG-to-NetBox: Import devices from WhatsUp Gold to NetBox
  • NetBox-to-WUG: Export NetBox devices to WhatsUp Gold for monitoring
• Automatic Sync: Django signals automatically sync new NetBox devices to WUG
• Manual Sync: On-demand synchronization via web UI or API
• Multiple Connections: Support for multiple WhatsUp Gold servers
• Scheduled Sync: Configurable automatic sync intervals
• Selective Sync: Enable/disable sync for individual devices

• Auto-creation: Automatically create NetBox sites, device types, and manufacturers
• Data Mapping: Intelligent mapping of WUG device properties to NetBox fields
• Conflict Resolution: Handle duplicate devices and naming conflicts
• Status Tracking: Monitor sync status and error handling

• Dashboard: Overview of sync status and statistics
• Connection Management: Configure and test WUG connections
• Device Management: View and manage synced devices
• Sync Logs: Detailed logging and audit trails

• Full API Coverage: Manage all plugin functionality via REST API
• Bulk Operations: Perform bulk sync operations
• Status Monitoring: Real-time sync status and statistics
• Integration Ready: Easy integration with external automation tools

• NetBox 4.0.0+
• Python 3.10+
• WhatsUp Gold with REST API access
• Network connectivity between NetBox and WhatsUp Gold servers

# Install from PyPI (when published)
pip install netbox-wug-sync

# Or install from source
git clone https://github.com/yourusername/netbox-wug-sync.git
cd netbox-wug-sync
pip install -e .

Add the plugin to your NetBox configuration in configuration.py:

PLUGINS = [
  'netbox_wug_sync',
]

# Plugin configuration
PLUGINS_CONFIG = {
  'netbox_wug_sync': {
        # Required settings (configure via NetBox UI)
        'wug_host': None,           # Set via connection config
        'wug_username': None,       # Set via connection config  
        'wug_password': None,       # Set via connection config
        
        # Optional settings with defaults
        'wug_port': 9644,
        'wug_use_ssl': True,
        'wug_verify_ssl': False,
        'sync_interval_minutes': 60,
        'auto_create_sites': True,
        'auto_create_device_types': True,
        'default_device_role': 'server',
        'default_device_status': 'active',
        'sync_device_tags': True,
        'debug_mode': False,
        
        # NetBox-to-WUG reverse sync settings
        'enable_automatic_export': True,    # Enable Django signals for auto-sync
        'export_only_active_devices': True, # Only sync devices with active status
        'require_primary_ip': True,         # Only sync devices with primary IP
        'wug_device_template': 'Network Device', # Default WUG device template
        'export_device_comments': True,     # Include NetBox comments in WUG description
    }
}

cd /opt/netbox
python manage.py migrate netbox-wug-sync

# Restart NetBox services
sudo systemctl restart netbox netbox-rq

For Docker deployments, see the complete examples and documentation in the examples/ directory.

1. Build custom NetBox image with plugin:

   cd examples/docker
   ./build.sh

2. Use the docker-compose override:

   cp examples/docker/docker-compose.override.yml /path/to/your/netbox/
   docker-compose up -d

3. Run migrations:

   docker exec netbox python manage.py migrate netbox_wug_sync

For detailed Docker configuration options, troubleshooting, and production deployment guidance, see examples/README.md.

1. Navigate to Plugins > WhatsUp Gold Sync > Connections
2. Click Add Connection
3. Configure the connection parameters:

4. Test the connection using the Test button
5. Save the configuration

Configure sync behavior in the connection settings:

• Sync Interval: How often to automatically sync (in minutes)
• Auto-create Sites: Create NetBox sites from WUG groups
• Auto-create Device Types: Create device types for unknown devices
• Default Device Role: Default role for synced devices

• Access: Plugins > WhatsUp Gold Sync
• View sync statistics and recent activity
• Quick access to connections and devices

• List: View all configured WUG connections
• Add: Create new connection configurations
• Test: Verify connectivity and authentication
• Sync: Trigger manual synchronization

• List: View all devices discovered from WUG
• Filter: Filter by connection, status, vendor, etc.
• Enable/Disable: Control sync for individual devices
• Force Sync: Trigger sync for specific devices

• View History: See detailed sync operation logs
• Troubleshoot: Identify and resolve sync issues
• Statistics: Monitor sync performance and success rates

The plugin provides a comprehensive REST API accessible at /api/plugins/wug-sync/.

# Test connection
curl -X POST -H "Authorization: Token YOUR_TOKEN" \\
  http://netbox.example.com/api/plugins/wug-sync/connections/1/test/

# Trigger sync
curl -X POST -H "Authorization: Token YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"sync_type": "manual"}' \\
  http://netbox.example.com/api/plugins/wug-sync/connections/1/sync/

# Get plugin status
curl -H "Authorization: Token YOUR_TOKEN" \\
  http://netbox.example.com/api/plugins/wug-sync/status/

The plugin now supports reverse synchronization from NetBox to WhatsUp Gold, automatically adding NetBox devices to WUG for monitoring.

When you create or update a NetBox device with the following criteria, it will automatically be added to all active WUG connections:

• Device Status: Active
• Primary IP: Must have a primary IPv4 address
• Active Connections: At least one WUG connection must be active

Example: Creating a device that triggers automatic sync:

from dcim.models import Device, Site, DeviceType, DeviceRole
from dcim.choices import DeviceStatusChoices
from ipam.models import IPAddress

# Create device with active status and primary IP
device = Device.objects.create(
    name='router-01',
    site=my_site,
    device_type=my_device_type,
    role=my_role,
    status=DeviceStatusChoices.STATUS_ACTIVE,
    primary_ip4=my_ip_address  # This triggers automatic WUG sync!
)

Dashboard Export Button:

• Navigate to Plugins > WhatsUp Gold Sync
• Click the orange Export button (📤) next to any WUG connection
• This exports all active NetBox devices with primary IPs to that WUG server

Individual Device Sync:

• Use the REST API endpoint: /api/plugins/wug-sync/netbox-device/{device_id}/sync/
• Sync specific NetBox devices to all active WUG connections

Example API Usage:

# Export all NetBox devices to WUG
curl -X POST -H "Authorization: Token YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  http://netbox.example.com/api/plugins/wug-sync/connections/1/export/

# Sync specific NetBox device to all WUG connections
curl -X POST -H "Authorization: Token YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  http://netbox.example.com/api/plugins/wug-sync/netbox-device/123/sync/

When syncing from NetBox to WUG, the plugin:

1. Validates Device: Checks for active status and primary IP
2. Creates WUG Device: Uses PATCH /api/v1/devices/-/config/template endpoint
3. Maps Data: Converts NetBox attributes to WUG device properties
4. Logs Results: Creates sync log entries for tracking
5. Handles Errors: Comprehensive error handling and reporting

Device Mapping:

• IP Address: Primary IPv4 address from NetBox
• Display Name: NetBox device name
• Description: Device type and model information
• Location: NetBox site name
• Device Type: Mapped to WUG device templates

The plugin automatically schedules sync jobs based on the configured interval. Jobs run in the background using NetBox's job queue system.

Create custom scripts for advanced sync scenarios:

from netbox-wug-sync.models import WUGConnection
from netbox-wug-sync.jobs import WUGSyncJob

# Trigger sync for specific connection
connection = WUGConnection.objects.get(name='Production WUG')
job = WUGSyncJob()
result = job.run(connection_id=connection.id, sync_type='manual')

Error: Connection test failed: Connection refused

Solution: Check network connectivity, firewall rules, and WUG API service status.

Error: Authentication failed - check username and password

Solution: Verify WUG credentials and ensure API access is enabled for the user.

Error: SSL certificate verification failed

Solution: Set "Verify SSL" to False for self-signed certificates, or install proper certificates.

Error: Failed to create device: Duplicate name

Solution: Check NetBox device naming rules and handle conflicts in WUG data.

Enable debug mode for detailed logging:

PLUGINS_CONFIG = {
  'netbox-wug-sync': {
        'debug_mode': True,
    }
}

Check NetBox logs for detailed error information:

# NetBox application log
tail -f /opt/netbox/logs/netbox.log

# Background job logs  
tail -f /opt/netbox/logs/rq_worker.log

1. Clone the repository:

git clone https://github.com/yourusername/netbox-wug-sync.git
cd netbox-wug-sync

2. Create virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -e .[dev]

3. Run tests:

pytest

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make changes and add tests
4. Run tests: pytest
5. Submit a pull request

The project uses:

• Black for code formatting
• isort for import sorting
• flake8 for linting

Run code quality checks:

black netbox-wug-sync/
isort netbox-wug-sync/
flake8 netbox-wug-sync/

• Passwords are stored encrypted in the NetBox database
• Use strong, unique passwords for WUG API accounts
• Regularly rotate API credentials

• Use HTTPS/SSL for WUG API connections when possible
• Restrict network access between NetBox and WUG servers
• Consider VPN or dedicated management networks

• Limit WUG API user permissions to read-only where possible
• Use NetBox's permission system to control plugin access
• Audit sync logs for security monitoring

• Adjust sync intervals based on network size and change frequency
• Use selective sync to exclude unnecessary devices
• Monitor sync duration and adjust batch sizes if needed

• Sync jobs run in background queues to avoid blocking the web interface
• Large networks may require increased worker processes
• Monitor database growth and implement log rotation

A: Currently, the plugin supports one-way sync from WUG to NetBox. Bidirectional sync may be added in future versions.

A: The plugin will mark the device as inactive in the sync status but won't delete it from NetBox to preserve data integrity.

A: Field mapping is currently fixed but can be extended through custom fields. Future versions may support configurable mappings.

A: Use selective sync, adjust sync intervals, and ensure adequate system resources. Consider syncing different device groups separately.

• Plugin documentation: GitHub Wiki
• NetBox documentation: netbox.readthedocs.io
• WhatsUp Gold API: Refer to your WUG installation documentation

• GitHub Issues: Report bugs and feature requests
• NetBox Community: netdev.chat

For commercial support and custom development, contact the maintainers.

This project is licensed under the Apache License 2.0. See LICENSE for details.

• Basic device synchronization from WhatsUp Gold to NetBox
• Web interface for connection and device management
• REST API for programmatic access
• Automatic site and device type creation
• Comprehensive logging and error handling

Note: This plugin is not affiliated with or endorsed by NetBox Labs or Ipswitch WhatsUp Gold. It is an independent community project.