Getting Started with the Cisco Meraki Integration for NetBox

This guide will help you set up and start using the Cisco Meraki Integration for NetBox.

• Prerequisites
• Host Requirements
  • System
  • Network
• NetBox Setup
  • Generate Diode Client Credentials
• Agent Setup and Configuration
  • Step 1: Authenticate to the NetBox Labs Image Registry
  • Step 2: Configure the Agent
  • Scope Configuration
  • Mapping Networks to Sites
  • Specifying the Country (Regional Dashboard)
  • Bootstrap Mode (First-Time Setup)
  • Optional - Dry Run Mode
  • Step 3: Run the Agent
    • Method 1: Set Environment Variables Manually
    • Method 2: Use a .env File (Recommended)
  • Expected Output
• View and Apply Discovered Data in NetBox Assurance
  • Accessing NetBox Assurance
  • Explore Deviation Types
  • View Active Deviations
  • Apply Deviations
• View the Cisco Meraki Data in NetBox
• Additional Resources
  • Related Documentation
  • Support

---

Prerequisites

Before you begin, ensure you have the following:

• NetBox Cloud or NetBox Enterprise with NetBox Assurance
• Orb Agent Pro credentials (required to download the integration agent image)
• Cisco Meraki Dashboard with API access
• Host System with Docker support
• Network connectivity between your host(s) and both NetBox instance and the Cisco Meraki Dashboard

Host Requirements

System

• Operating System: Linux, macOS, or Windows with Docker support
• Memory: Minimum 2GB RAM (4GB recommended)
• Storage: 1GB free disk space
• Network: Stable internet connection for pulling Docker images
• Docker: Version 20.10 or later

Network

• Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
• Outbound HTTP/HTTPS access to your Cisco Meraki Dashboard (typically port 443 for HTTPS)
• DNS resolution for both NetBox and Cisco Meraki Dashboard hostnames
• Firewall rules configured to allow the above connections from your agent host

---

NetBox Setup

Generate Diode Client Credentials

1. Log into your NetBox instance
2. Navigate to Diode → Client Credentials
3. Click + Add a Credential
4. Enter a descriptive name (e.g., "Meraki Integration")
5. Click Create
6. Important: Copy and securely store the Client ID and Client Secret as you will reference this in the agent configuration file in later steps
7. Navigate to Diode → Settings
8. Copy the value of the Diode target as you will reference this in the agent configuration file in later steps

---

Agent Setup and Configuration

info

If you have multiple Organisations in the Meraki Dashboard, you can deploy multiple agents configured to sync data for each Organisation. Data from each organization will be tagged in Netbox so it's easily searchable.

Step 1: Authenticate to the NetBox Labs Image Registry

From your host machine, authenticate to the NetBox Labs registry, using the CUSTOMER-IDENTIFIER and Token that you have been provided by the NetBox Labs team:

docker login -u<CUSTOMER-IDENTIFIER> netboxlabs.jfrog.io

Example session

% docker login -u<customer-abc123> netboxlabs.jfrog.io # note there are no spaces after -u
# Use the Token provided as the password when prompted
Password:
Login Succeeded

Step 2: Configure the Agent

1. Create the configuration file (you can name the file anything you like):

touch agent.yaml

2. Edit the configuration file with your preferred editor and add the following configuration. Important: Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode > Settings > Diode target in the NetBox UI:

orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: meraki_agent_1  # Use a meaningful name to identify this agent
  policies:
    worker:
      cisco_meraki_worker:
        config:
          package: nbl_cisco_meraki
          schedule: "0 2 * * *" # Daily at 2:00 AM. Set your desired schedule (see examples below)
          MERAKI_API_KEY: ${MERAKI_API_KEY}
          MERAKI_ORG_ID: ${MERAKI_ORG_ID}
          BOOTSTRAP: True  # Set to True for initial setup, False for regular operation
          # defaults: { site: "My-Default-Site" }  # Optional: default NetBox site for unmapped networks (see mapping networks to sites)
        scope:
          networks: ["Chicago", "Dallas"]  # Optional: Limit sync to specific networks (see scope configuration below)
          # network_site_mapping: {"Network-A": "Site-1", "Network-B": "Site-1"}  # Optional: map Meraki networks to NetBox sites (see mapping networks to sites below)

Schedule Examples

The schedule field uses cron syntax. Here are some common examples:

• "0 */6 * * *" - Every 6 hours (e.g., 00:00, 06:00, 12:00, 18:00)
• "0 2 * * *" - Daily at 2:00 AM
• "0 9 * * 1" - Weekly on Monday at 9:00 AM

Scope Configuration

The scope section allows you to limit the data synchronization to specific networks, reducing the amount of data processed and improving performance.

Configuration Options:

• ["*"] or omitted: Syncs all networks (default)
• ["Network-A", "Network-B"]: Syncs only specified networks and their devices
  • Devices from filtered networks are excluded from synchronization
  • Devices without network assignment are always included
  • Invalid network names raise an error with available network list

Example:

scope:
  networks: ["Chicago", "Dallas"]  # Only sync these specific networks

Mapping Networks to Sites

You can control how Meraki networks map to NetBox sites. By default, each Meraki network creates its own NetBox site using the network name. Use network-to-site mapping to consolidate multiple networks into one site or to use custom site names.

Configuration:

Location	Key	Description
scope	network_site_mapping	Dictionary mapping Meraki network names to NetBox site names. Mapped networks use the specified site; multiple networks can map to the same site.
config	defaults.site	(Optional) Default site name for networks that are not listed in network_site_mapping. If omitted, unmapped networks create a site using the Meraki network name.

Site assignment order:

1. If the network is in network_site_mapping, use the mapped site name.
2. Else if defaults.site is set, use that site for all unmapped networks.
3. Else use the Meraki network name as the site name (one site per network).

Example 1: Multiple networks to one site

Consolidate several Meraki networks (e.g. per-floor) into a single NetBox site:

config:
  package: nbl_cisco_meraki
  schedule: "0 2 * * *"
  MERAKI_API_KEY: ${MERAKI_API_KEY}
  MERAKI_ORG_ID: ${MERAKI_ORG_ID}
  BOOTSTRAP: False
scope:
  networks: ["*"]
  network_site_mapping:
    "Office-Network-Floor-1": "Corporate-HQ"
    "Office-Network-Floor-2": "Corporate-HQ"
    "Office-Network-Floor-3": "Corporate-HQ"

All three networks are represented as one NetBox site Corporate-HQ. The site’s meraki_networks custom field still lists each network and its metadata.

Example 2: Custom site names with default for unmapped networks

Map some networks to specific sites and send all others to a default site:

config:
  package: nbl_cisco_meraki
  schedule: "0 2 * * *"
  MERAKI_API_KEY: ${MERAKI_API_KEY}
  MERAKI_ORG_ID: ${MERAKI_ORG_ID}
  BOOTSTRAP: False
  defaults:
    site: "Unmapped-Networks"
scope:
  networks: ["*"]
  network_site_mapping:
    "Main-Office-Network": "SITE-001"
    "Branch-Office-A": "SITE-002"
    "Branch-Office-B": "SITE-002"

• Main-Office-Network → SITE-001
• Branch-Office-A and Branch-Office-B → SITE-002
• Any other Meraki network → Unmapped-Networks

Example 3: All networks to a single default site

Send every network to one NetBox site (e.g. when you do not need per-network sites):

config:
  package: nbl_cisco_meraki
  schedule: "0 2 * * *"
  MERAKI_API_KEY: ${MERAKI_API_KEY}
  MERAKI_ORG_ID: ${MERAKI_ORG_ID}
  BOOTSTRAP: False
  defaults:
    site: "Corporate-HQ"
scope:
  networks: ["*"]

Notes:

• Network names in network_site_mapping are case-sensitive and must match the Meraki dashboard exactly.
• Every key in network_site_mapping must be allowed by scope.networks (e.g. list the network or use ["*"]). The agent validates this at runtime and will error with the list of allowed networks if a mapped name is not allowed.
• When multiple networks map to the same site, the site’s main fields (e.g. location, tags, SiteGroup) are taken from the first network in the group; each network’s metadata is still stored in the site’s meraki_networks custom field.

Specifying the Country (Regional Dashboard)

If your Cisco Meraki dashboard is hosted in a regional data center (outside the default US endpoint), set the optional MERAKI_COUNTRY parameter in config. The integration uses it to select the correct Meraki API base URL for your region.

Valid values:

Value	Region
canada	Canada
china	China
india	India
united-states-fedramp	United States (FedRAMP)

If you omit MERAKI_COUNTRY, the integration uses the default US Meraki dashboard URL.

Example: Default (US) – no change needed

config:
  package: nbl_cisco_meraki
  schedule: "0 2 * * *"
  MERAKI_API_KEY: ${MERAKI_API_KEY}
  MERAKI_ORG_ID: ${MERAKI_ORG_ID}
  BOOTSTRAP: False

Example: Canada dashboard

config:
  package: nbl_cisco_meraki
  schedule: "0 2 * * *"
  MERAKI_API_KEY: ${MERAKI_API_KEY}
  MERAKI_ORG_ID: ${MERAKI_ORG_ID}
  MERAKI_COUNTRY: "canada"
  BOOTSTRAP: False

Example: India dashboard

config:
  MERAKI_API_KEY: ${MERAKI_API_KEY}
  MERAKI_ORG_ID: ${MERAKI_ORG_ID}
  MERAKI_COUNTRY: "india"

The value is case-insensitive (e.g. "Canada" and "canada" both work). For more on Meraki base URIs, see Meraki API getting started.

Bootstrap Mode (First-Time Setup)

Bootstrap mode is used for the initial setup only of the integration. When enabled, it creates static content in NetBox that the integration requires to function properly.

What Bootstrap Mode Does:

• Creates required Manufacturers
• Creates necessary Tags
• Creates required Custom Fields
• Sets up initial data structures

Configuration:

config:
  BOOTSTRAP: True  # Set to True for initial setup, False for regular operation

First-Time Run Process:

1. Run the agent with BOOTSTRAP: True in your configuration
2. Monitor the output for the text executed successfully
3. Stop the agent immediately by pressing Ctrl+C in your terminal once you see executed successfully
4. Apply the deviations in NetBox Assurance (see Apply Deviations section below)
5. Set BOOTSTRAP: False for all future runs

Important Notes:

• Bootstrap mode is only for first-time setup - do not run it on a schedule
• You must stop the agent manually with Ctrl+C after seeing executed successfully
• After bootstrap, you'll see deviations for Custom Fields, Manufacturers, etc. that must be applied
• Once deviations are applied, set BOOTSTRAP: False for regular operation

Optional - Dry Run Mode

The agent can be run in Dry Run mode, which means discovered data is written to a json formatted file instead of to NetBox. This can be useful for troubleshooting - for example you could share the file with the NetBox Labs support team to investigate issues ingesting certain data.

Enable this in the Diode section of your agent configuration file, by adding the dry_run key and setting the value to true (it is false by default) and set the dry_run_output_dir value to the location you want the file to be saved.

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/ # this will save the output file into the same directory that you run the agent from

Step 3: Run the Agent

Run the agent to synchronize data Cisco Meraki into NetBox:

Method 1: Set Environment Variables Manually

1. Export Diode credentials as environment variables:

export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"

2. Export Meraki credentials as environment variables:

export MERAKI_API_KEY="your-meraki-api-token"
export MERAKI_ORG_ID="your-meraki-organisation-id"

3. Run the agent with the following command:

docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e MERAKI_API_KEY \
  -e MERAKI_ORG_ID \
  netboxlabs.jfrog.io/obs-orb-agent-pro/orb-agent-pro \
  run -c /opt/orb/agent.yaml

Method 2: Use a .env File (Recommended)

1. Create a .env file in your current directory:

touch .env

2. Edit the .env file with your preferred editor and add the following content:

# NetBox Diode credentials (from Step 1)
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

# Cisco Meraki credentials
MERAKI_API_KEY=your-meraki-api-token
MERAKI_ORG_ID=your-meraki-organisation-id

Important

Replace the placeholder values with your actual credentials:

• your-client-id and your-client-secret from the NetBox Diode setup
• your-meraki-api-token and your-meraki-organisation-id with your Cisco Meraki credentials

1. Run the agent with the following command:

docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  netboxlabs.jfrog.io/obs-orb-agent-pro/orb-agent-pro \
  run -c /opt/orb/agent.yaml

Security Best Practice

When using Method 2, add .env to your .gitignore file to prevent accidentally committing sensitive credentials to version control:

echo ".env" >> .gitignore

Expected Output

After you issue the command to run the agent, depending on the schedule you defined in the configuration file, you should see similar to the output below:

{"time":"2025-09-09T10:15:22.487755639Z","level":"INFO","msg":"worker stderr","log":"    tags {"}
{"time":"2025-09-09T10:15:22.487756472Z","level":"INFO","msg":"worker stderr","log":"      name: \"discovered\""}
{"time":"2025-09-09T10:15:22.48775743Z","level":"INFO","msg":"worker stderr","log":"    }"}
{"time":"2025-09-09T10:15:22.487758389Z","level":"INFO","msg":"worker stderr","log":"  }"}
{"time":"2025-09-09T10:15:22.487759722Z","level":"INFO","msg":"worker stderr","log":"  auth_type: \"wpa-personal\""}
{"time":"2025-09-09T10:15:22.487761264Z","level":"INFO","msg":"worker stderr","log":"  auth_cipher: \"tkip\""}
{"time":"2025-09-09T10:15:22.487762805Z","level":"INFO","msg":"worker stderr","log":"  tags {"}
{"time":"2025-09-09T10:15:22.487764264Z","level":"INFO","msg":"worker stderr","log":"    name: \"cisco\""}
{"time":"2025-09-09T10:15:22.487765222Z","level":"INFO","msg":"worker stderr","log":"  }"}
{"time":"2025-09-09T10:15:22.48776593Z","level":"INFO","msg":"worker stderr","log":"  tags {"}
{"time":"2025-09-09T10:15:22.48776693Z","level":"INFO","msg":"worker stderr","log":"    name: \"meraki\""}
{"time":"2025-09-09T10:15:22.487768389Z","level":"INFO","msg":"worker stderr","log":"  }"}
{"time":"2025-09-09T10:15:22.487769764Z","level":"INFO","msg":"worker stderr","log":"  tags {"}
{"time":"2025-09-09T10:15:22.487771097Z","level":"INFO","msg":"worker stderr","log":"    name: \"discovered\""}
{"time":"2025-09-09T10:15:22.487772639Z","level":"INFO","msg":"worker stderr","log":"  }"}
{"time":"2025-09-09T10:15:22.487774305Z","level":"INFO","msg":"worker stderr","log":"}"}
{"time":"2025-09-09T10:15:22.487777639Z","level":"INFO","msg":"worker stderr","log":"] chunks"}
{"time":"2025-09-09T10:15:22.487779305Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run (trigger: date[2025-09-09 10:13:48 UTC], next run at: 2025-09-09 10:13:48 UTC)\" executed successfully"}

Monitoring and Testing

Success Indicators: Look for the text Successful ingestion in the output, which confirms that data was successfully sent to your NetBox instance via Diode.

Testing Mode: For testing purposes, you can run the agent once and then stop it:

• Press Ctrl+C in your terminal to stop the agent
• This is useful for verifying configuration before setting up continuous operation

Continuous Operation: The agent will continue running according to your schedule until manually stopped or the container is terminated.

View and Apply Discovered Data in NetBox Assurance

You can now work with the Meraki Dashboard data that has been discovered by the agent in the NetBox Assurance UI.

NetBox Assurance gives you control over operational drift by identifying deviations between your operational state and NetBox, and analytics to understand drift and plan for remediation, and ultimately take action.

Understanding Deviations

Deviations are the delta between the data already in NetBox as the Network Source of Truth, versus the actual operational state of the network as discovered by the controller integration.

From an initial run of the integration it could be that ALL discovered data is a deviation as it may not have existed in NetBox previously. Once the initial sync of data has taken place, and NetBox has been updated, then further integration runs would result in new deviations only.

Accessing NetBox Assurance

1. Navigate to the UI of NetBox instance
2. Click on Assurance in the main navigation menu

Explore Deviation Types

1. Click on Deviation Types to view the types of deviations that have been discovered
2. Click on the Name of a deviation type, to view deviations for a particular type
3. Click on the Name of an individual deviation, to view the details

View Active Deviations

1. Click on Active Deviations to view all the deviations that have not yet been Applied or Ignored
2. Click on the Name of a deviation, to view the details

Apply Deviations

1. Select all the deviations that you'd like to apply. If you are working with a large number of deviations, first set the Per Page view to 500:
2. Then select the first deviation, hold down SHIFT and select the last one, and then click Apply Selected:
3. Click Apply X Deviations to apply the deviations to the NetBox database:

Apply Deviations to a Branch

Instead of writing the deviations to the Main NetBox database branch, you can select another branch from the drop down menu and apply the deviations to that branch.

Assurance Docs

For more detailed information on working with NetBox Assurance, please refer to the documentation

View the Cisco Meraki Data in NetBox

Now that you have run the integration at least once and applied the discovered data, you can view the data from the Meraki Dashboard in the NetBox UI

1. Start by clicking on Devices in the main navigation menu, and optionally filter on the NetBox tag for your Meraki Org ID :
2. Select an individual Device to view the details:

---

Additional Resources

Related Documentation

• NetBox Assurance Documentation
• Orb Agent Documentation

Support

Email support@netboxlabs.com for support.