netbox-meraki 1.1.0

NetBox plugin for synchronizing Cisco Meraki Dashboard networks, devices, VLANs, and prefixes

NetBox Meraki Sync Plugin

A comprehensive NetBox plugin for synchronizing Cisco Meraki infrastructure with NetBox. Automatically import and manage networks, devices, VLANs, IP prefixes, and wireless LANs from your Meraki Dashboard.

Author: Tarani Debnath
License: Apache 2.0
Status: Production Ready

Features

Core Synchronization

• Organizations & Networks: Sync single or multiple Meraki organizations with selective network filtering
• Sites: Meraki networks mapped to NetBox sites with customizable name rules
• Devices: Device inventory with models, roles, and serial numbers
  • Device role assignment based on product type (MX, MS, MR, MG, MV, MT)
  • Firmware version tracking via custom fields
  • MAC address storage
  • Device status monitoring
• VLANs: Import VLANs from MX security appliances
• IP Prefixes/Subnets: Prefix discovery with site association
• Interfaces:
  • WAN interfaces with public IP assignments for MX devices
  • SVI (VLAN) interfaces for configured VLANs on MX appliances
  • Wireless interfaces for access points
• Wireless LANs: NetBox Wireless LAN objects for SSIDs
  • Organization-wide SSID management
  • Association with access points
  • Authentication and encryption tracking

Advanced Features

• Three Sync Modes:
  • Auto Sync: Changes apply immediately
  • Review Mode: Stage changes for manual approval
  • Dry Run: Preview changes without modifications
• Cleanup: Automatic removal of objects no longer in Meraki
• Filtering:
  • Organization selection
  • Network-specific sync
  • Prefix filtering with include/exclude rules
  • Site name transformation rules
• Name Transformations: Standardize naming across devices, sites, VLANs, and SSIDs
• Tag Management: Optional tagging for synchronized objects
• API Rate Limiting: Throttling to respect Meraki API limits
• Scheduled Syncs: Background job support with configurable intervals
• Progress Tracking: Real-time sync status with detailed logs

Requirements

• NetBox 4.4.x or higher
• Python 3.10+
• Meraki Dashboard API access with valid API key

Installation

Standard Installation (Recommended)

For NetBox installed directly on a server:

# Activate virtual environment
source /opt/netbox/venv/bin/activate

# Clone repository
cd /opt
git clone https://github.com/yourusername/netbox-meraki.git
cd netbox-meraki

# Install plugin
pip install .

# Run migrations
cd /opt/netbox/netbox
python manage.py migrate netbox_meraki

# Collect static files
python manage.py collectstatic --no-input

# Restart services
sudo systemctl restart netbox netbox-rq

Docker Installation

For NetBox running in Docker:

Step 1: Clone the Repository

cd /opt
git clone https://github.com/tkdebnath/netbox-meraki.git

Step 2: Update Docker Compose

Edit your docker-compose.yml:

services:
  netbox:
    image: netboxcommunity/netbox:latest
    # ... other configuration ...
    volumes:
      - /opt/netbox-meraki:/opt/netbox-meraki:ro
      - ./extra-requirements.txt:/opt/netbox/extra-requirements.txt:ro

Step 3: Create Requirements File

Create extra-requirements.txt in your NetBox directory:

/opt/netbox-meraki

Step 4: Rebuild and Restart

docker-compose down
docker-compose build --no-cache netbox
docker-compose up -d

Step 5: Run Migrations

docker-compose exec netbox python /opt/netbox/netbox/manage.py migrate netbox_meraki
docker-compose exec netbox python /opt/netbox/netbox/manage.py collectstatic --no-input

Step 6: Restart Services

docker-compose restart netbox

Configuration

Edit your NetBox configuration.py file (located at /opt/netbox/netbox/netbox/configuration.py):

# At the top of configuration.py, ensure you have:
import os

# Enable the plugin
PLUGINS = [
    'netbox_meraki',
]

# Plugin configuration
PLUGINS_CONFIG = {
    'netbox_meraki': {
        # Required: Meraki API key (can use environment variable)
        'meraki_api_key': os.environ.get('MERAKI_API_KEY', 'your_meraki_api_key_here'),
        
        # Optional: Meraki API base URL (default shown)
        'meraki_base_url': 'https://api.meraki.com/api/v1',
        
        # Optional: Auto-creation settings (all default to True)
        'auto_create_sites': True,
        'auto_create_device_types': True,
        'auto_create_device_roles': True,
        'auto_create_manufacturers': True,
        
        # Optional: Default values
        'default_site_group': None,  # Site group name or None
        'default_manufacturer': 'Cisco Meraki',
        
        # Optional: Override default device role names
        'mx_device_role': 'Meraki Firewall',
        'ms_device_role': 'Meraki Switch',
        'mr_device_role': 'Meraki AP',
        'mg_device_role': 'Meraki Cellular Gateway',
        'mv_device_role': 'Meraki Camera',
        'mt_device_role': 'Meraki Sensor',
        'default_device_role': 'Meraki Unknown',
    }
}

Configuration Options

Using Environment Variables (Recommended)

For security, it's recommended to use environment variables for sensitive data:

# Add to /opt/netbox/netbox/netbox/configuration.py
import os

PLUGINS_CONFIG = {
    'netbox_meraki': {
        'meraki_api_key': os.environ.get('MERAKI_API_KEY', ''),
        # ... other settings
    }
}

Then set the environment variable in your NetBox systemd service or .env file:

MERAKI_API_KEY=your_actual_api_key_here

Auto-Creation Settings

Control automatic object creation during sync:

• auto_create_sites (default: True): Automatically create sites from Meraki networks
• auto_create_device_types (default: True): Automatically create device types for Meraki models
• auto_create_device_roles (default: True): Automatically create device roles if they don't exist
• auto_create_manufacturers (default: True): Automatically create the Cisco Meraki manufacturer

Default Values

• default_site_group (default: None): Site group name to assign to all created sites
• default_manufacturer (default: 'Cisco Meraki'): Manufacturer name for all Meraki devices
• meraki_base_url (default: 'https://api.meraki.com/api/v1'): Meraki Dashboard API base URL

Device Role Name Customization

Device role names can be customized in two ways:

1. In configuration.py (recommended for consistent defaults):

   • Add role name overrides to PLUGINS_CONFIG as shown above
   • These apply globally and persist across plugin database resets
   • Changes require a NetBox restart

2. In the Web UI (Plugins > Meraki Sync > Configuration > Device Role Mappings):

   • Customize role names on a per-installation basis
   • Changes take effect immediately
   • Stored in the plugin database

Priority: Web UI settings take precedence over configuration.py defaults.

Complete Configuration Reference

Parameter	Type	Default	Description
meraki_api_key	string	''	Required. Meraki Dashboard API key
meraki_base_url	string	'https://api.meraki.com/api/v1'	Meraki API base URL
auto_create_sites	boolean	True	Auto-create sites from Meraki networks
auto_create_device_types	boolean	True	Auto-create device types for Meraki models
auto_create_device_roles	boolean	True	Auto-create device roles if missing
auto_create_manufacturers	boolean	True	Auto-create Cisco Meraki manufacturer
default_site_group	string/null	None	Site group name for all created sites
default_manufacturer	string	'Cisco Meraki'	Manufacturer name for devices
mx_device_role	string	'Meraki Firewall'	Device role for MX (Security Appliance)
ms_device_role	string	'Meraki Switch'	Device role for MS (Switch)
mr_device_role	string	'Meraki AP'	Device role for MR (Wireless AP)
mg_device_role	string	'Meraki Cellular Gateway'	Device role for MG (Cellular Gateway)
mv_device_role	string	'Meraki Camera'	Device role for MV (Camera)
mt_device_role	string	'Meraki Sensor'	Device role for MT (Sensor)
default_device_role	string	'Meraki Unknown'	Fallback device role for unknown types

Obtaining a Meraki API Key

1. Log in to the Meraki Dashboard
2. Navigate to Organization > Settings > Dashboard API access
3. Enable API access
4. Generate a new API key
5. Copy the key to your NetBox configuration
6. Restart NetBox after updating configuration

Usage

Quick Start Guide

1. Access the Plugin

Navigate to Plugins > Meraki Sync > Dashboard in NetBox.

2. Start a Sync

Click the Sync Now button to open the synchronization interface.

3. Choose Sync Mode

Select your preferred sync mode:

• Auto Sync: Changes apply immediately to NetBox
• Sync with Review: Review and approve changes before applying
• Dry Run: Preview changes without making any modifications

4. Filter Options (Optional)

• Organization: Select a specific organization or sync all
• Networks: Choose specific networks or sync all networks in the organization

5. Start Synchronization

Click Start Synchronization and monitor the live progress logs.

Configuration Options

Access Plugins > Meraki Sync > Configuration to customize behavior:

Device Role Mappings Tab

Configure which NetBox device role to use for each Meraki product type:

Product Type	Default Role	Description
MX	Meraki Firewall	Security appliances and firewalls
MS	Meraki Switch	Network switches
MR	Meraki AP	Wireless access points
MG	Meraki Cellular Gateway	Cellular gateways
MV	Meraki Camera	Security cameras
MT	Meraki Sensor	Environmental sensors

Note: Device role names can be overridden in configuration.py (see Configuration section above) or customized in the web UI. The plugin will automatically create device roles if they don't exist.

Name Transformations Tab

Standardize naming conventions for all synchronized objects:

• Device Names: Transform device names (UPPERCASE, lowercase, Title Case, Keep Original)
• Site Names: Transform site names
• VLAN Names: Transform VLAN names
• SSID Names: Transform wireless SSID names

Site Name Rules Tab

Define regex patterns to transform Meraki network names into NetBox site names:

Example:

Pattern: ^(?P<region>[A-Z]{2})-(?P<site>[A-Z]{3})-.*
Template: {region}-{site}
Priority: 1

Result: AMER-ABC-ALBERTA becomes AMER-ABC

Prefix Filters Tab

Control which subnets are synchronized to NetBox:

Include Rules:

• Add patterns for prefixes to sync (e.g., 10.0.0.0/8)
• Supports CIDR notation and wildcard patterns

Exclude Rules:

• Block specific prefixes (e.g., management networks)
• Takes precedence over include rules

Tag Configuration Tab

Add tags to all synchronized objects:

• Site Tags: Tags for sites created from Meraki networks
• Device Tags: Tags for all devices
• VLAN Tags: Tags for VLANs
• Prefix Tags: Tags for IP prefixes

Scheduled Synchronization

Automate syncs using the plugin's built-in scheduling interface:

Creating Scheduled Jobs

1. Navigate to Plugins > Meraki Sync > Scheduled Jobs
2. Click Create Scheduled Job
3. Configure job parameters:
   • Job Name: Descriptive name (e.g., "Daily Production Sync")
   • Interval: How often to run (Run Once, Hourly, Daily, Weekly, or Custom)
   • Sync Mode: Choose Auto Sync, Review Mode, or Dry Run
   • Organization: Select specific organization or sync all
   • Networks: Choose specific networks or sync all
4. Click Create Scheduled Job

Managing Scheduled Jobs

• View Jobs: See all scheduled jobs with status and configuration
• Edit Jobs: Modify job settings, intervals, or filters
• Delete Jobs: Remove scheduled jobs when no longer needed
• Dashboard View: Monitor recent job executions and logs from the main dashboard

Alternative: NetBox Native Scheduling

You can also use NetBox's native job scheduling:

1. Navigate to Jobs → Background Jobs in NetBox
2. Click + Add Scheduled Job
3. Select Job: netbox_meraki.jobs.MerakiSyncJob
4. Configure interval and timing
5. Click Create

Command Line Execution

Trigger a one-time sync via command line:

cd /opt/netbox
source venv/bin/activate
python manage.py runjob netbox_meraki.jobs.MerakiSyncJob

Monitoring

• Dashboard: View scheduled jobs and recent executions
• Job Results: Navigate to Jobs → Job Results in NetBox
• Detailed Logs: Click any job result to see full sync output
• Cancel Jobs: Use Delete button to remove active scheduled jobs

API Performance Tab

Configure API behavior:

API Throttling:

• Enabled (Recommended): Limits requests to 5 per second
• Prevents hitting Meraki API rate limits

Multithreading:

• Disabled (Safe): Sequential processing
• Enabled (Fast): Parallel API requests (3-5 threads)
• ⚠️ May increase API usage

Reviewing Changes (Review Mode)

When using Sync with Review mode:

1. After sync completes, click View Reviews from the dashboard
2. Review all staged changes grouped by type:
   • Sites
   • Device Types
   • VLANs
   • Prefixes
   • Devices
   • Interfaces
   • IP Addresses
   • SSIDs
3. Edit proposed data if needed
4. Approve or Reject individual items
5. Use Approve All or Reject All for bulk actions
6. Click Apply Approved Changes to commit to NetBox

Troubleshooting

Common Issues

API Key Invalid

Symptoms: Authentication errors, "Invalid API key" messages

Solutions:

• Verify API key in NetBox configuration
• Check API access is enabled in Meraki Dashboard
• Ensure key has not expired
• Restart NetBox after configuration changes

Rate Limit Errors

Symptoms: "Rate limit exceeded" errors in logs

Solutions:

• Enable API throttling in API Performance settings
• Reduce max worker threads
• Increase sync interval for scheduled jobs
• Use dry run mode to test before full sync

Objects Not Syncing

Symptoms: Expected devices/networks not appearing

Solutions:

• Check organization and network filters
• Review sync logs for specific errors
• Verify objects exist in Meraki Dashboard
• Check site name rules aren't filtering out networks
• Review prefix filters for IP objects

Duplicate Objects

Symptoms: Multiple entries for same device/site

Solutions:

• Review site name transformation rules
• Check for conflicting regex patterns
• Verify serial numbers are unique
• Use dry run mode to preview changes

Sync Hangs or Times Out

Symptoms: Sync doesn't complete, UI becomes unresponsive

Solutions:

• Check network connectivity to Meraki API
• Disable multithreading
• Sync smaller network batches
• Check NetBox logs for Python errors

Viewing Logs

Dashboard Logs

Navigate to Dashboard to view recent sync logs with:

• Sync date and time
• Sync mode used
• Statistics (sites, devices, VLANs, prefixes created)
• Status (completed, failed, in progress)

Detailed Logs

Standard Installation:

tail -f /opt/netbox/netbox/logs/netbox.log

Docker Installation:

docker-compose logs -f netbox

Admin Interface

Access Django admin for full sync history:

1. Navigate to Admin in NetBox
2. Go to NETBOX_MERAKI section
3. View Sync logs for complete history
4. View Sync reviews for staged changes

Getting Help

If issues persist:

1. Enable debug logging in NetBox configuration
2. Run sync in dry run mode
3. Check GitHub issues for similar problems
4. Provide logs when reporting issues

Support & Contributing

Reporting Issues

Found a bug or have a feature request? Please open an issue on the GitHub repository with:

• NetBox version
• Plugin version
• Detailed description of the issue
• Steps to reproduce
• Relevant log excerpts

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with clear commit messages
4. Test thoroughly
5. Submit a pull request

Compatibility

• NetBox: 4.4.x (tested on 4.4.7)
• Python: 3.10, 3.11, 3.12
• Meraki API: Dashboard API v1

---

Developed by Tarani Debnath