Getting Started

This guide walks you through setting up the Cisco Nexus Dashboard Integration for NetBox.

• Prerequisites
• Host Requirements
  • System
  • Network
• Nexus Dashboard Requirements
  • Choose an Authentication Method
  • Login Domains
  • TLS Verification
• 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
  • 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 Nexus Dashboard 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 Nexus Dashboard 4.x reachable from your agent host, with either a username and password or an API key that can read fabric inventory through the Manage API
• Host system with Docker support
• Network connectivity between your host and both your NetBox instance and Nexus Dashboard

Host Requirements

System

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

Network

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

Nexus Dashboard Requirements

The integration reads the Nexus Dashboard 4.x unified Manage API (/api/v1/manage/). Apart from the login request, every call it makes is a GET, so an identity with read access to fabric inventory is sufficient. It never writes to Nexus Dashboard or to the fabric.

The endpoints it calls are:

Choose an Authentication Method

Credentials are read from the policy config block. Provide one of the two pairs below - the run fails with a configuration error if neither pair is complete.

When both pairs are supplied, the API key takes precedence.

Keep secrets out of the policy file

Write ${ND_PASSWORD} in the policy rather than the password itself. When the agent loads the policy, a config value that is exactly a ${...} reference is replaced with the matching environment variable from the agent process. The .env file in Step 3 is what supplies those variables.

Two details matter in practice:

• The reference must be the whole value. ${ND_PASSWORD} is substituted; prefix-${ND_PASSWORD} is not.
• An unset variable is not caught as a missing credential. If the environment variable does not exist, the literal text ${ND_PASSWORD} is passed through as the credential and the login fails when Nexus Dashboard rejects it. See FAQ & Troubleshooting for that case.

Orb Agent can also resolve secrets from an external secret store, including HashiCorp Vault, configured under a separate orb.secrets_manager section of the agent config. Those references use a different form (${vault://...}) - see the Orb Agent documentation for setup.

Login Domains

ND_LOGIN_DOMAIN selects which Nexus Dashboard login domain authenticates the username and password - for example a remote LDAP, RADIUS, or TACACS domain rather than the local one. The value is the domain name as listed by GET /logindomains on your cluster, and it is case-sensitive.

Omit the key to authenticate against the cluster's configured default login domain. When it is omitted the integration sends the server-side DefaultAuth alias rather than leaving the field out, because Nexus Dashboard 4.2 returns a 500 when the domain field is absent entirely.

ND_LOGIN_DOMAIN only applies to username and password authentication. It has no effect when you use an API key.

TLS Verification

By default the Nexus Dashboard server certificate is validated against the host trust store. For a certificate signed by an internal or private CA, add the CA chain to your agent host's trust store and leave the default in place.

Set SKIP_SSL: true to disable certificate verification entirely. This applies to every request the integration makes, including the login request that carries your password, so it exposes the run to a machine-in-the-middle attack. Use it only on trusted networks and for initial testing. For production, provide a proper CA chain and leave SKIP_SSL unset.

NetBox Setup

Generate Diode Client Credentials

1. Log in to your NetBox instance.
2. Navigate to Diode → Client Credentials.
3. Click + Add a Credential.
4. Enter a descriptive name (for example, "Cisco Nexus Dashboard Integration").
5. Click Create.

6. Important: Copy and securely store the Client ID and Client Secret - you will need them in the agent configuration.

7. Navigate to Diode → Settings.
8. Copy the Diode target value - you will use this in the agent configuration file.

Agent Setup and Configuration

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 provided by the NetBox Labs team:

docker login quay.io -u netboxlabs+<CUSTOMER-ID> -p <TOKEN>

Example session:

% docker login quay.io -u netboxlabs+org-abc123def456 -p <token>
Login Succeeded

Then pull the agent image:

docker pull quay.io/netboxlabs/orb-agent-pro:develop

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 and add the following. 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: cisco_nexus_dashboard_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      cisco_nexus_dashboard_worker:
        config:
          package: nbl_cisco_nexus_dashboard
          schedule: "0 */6 * * *"  # Every 6 hours. Set your desired schedule (see examples below)
          timeout: 5
          ND_HOST: ${ND_HOST}              # Nexus Dashboard base URL, e.g. https://nd.example.com
          ND_USERNAME: ${ND_USERNAME}      # Username/password (JWT) authentication
          ND_PASSWORD: ${ND_PASSWORD}      # Resolved from the agent environment, never written in plain text
          # ND_LOGIN_DOMAIN: "your-login-domain"  # Optional: login domain name, case-sensitive (per GET /logindomains)
          # ND_API_KEY: ${ND_API_KEY}      # Alternative to ND_USERNAME/ND_PASSWORD
          # ND_API_USERNAME: ${ND_API_USERNAME}  # Required with ND_API_KEY
          # SKIP_SSL: false                # Optional: set true to disable TLS verification (testing only)
          BOOTSTRAP: false                 # Set to true for initial setup only
        scope:                             # Optional: leave empty to ingest all fabrics
        # scope:                           # Or restrict ingestion to named fabrics:
        #   fabrics:
        #     - evpn-lab
        #     - dc1-fabric

Scope Configuration

The scope section limits which fabrics are synchronized. Configure it under a scope key in the policy, separate from config.

• fabrics - a list of fabric names. Only fabrics whose name matches an entry in the list are ingested, along with all of their switches, interfaces, VRFs, and overlay networks. Use ["*"] or omit the key to ingest every fabric on the cluster.

Names are matched exactly against each fabric's name field in Nexus Dashboard, so they are case-sensitive.

Example:

scope:
  fabrics:
    - evpn-lab
    - dc1-fabric

See Scope Parameters for details.

Bootstrap Mode (First-Time Setup)

Bootstrap mode creates the static content in NetBox that the integration requires before the first full sync. Run it once on initial setup, then disable it for all subsequent runs. In bootstrap mode the integration makes no Nexus Dashboard API calls, so credentials are not required.

What bootstrap mode creates:

• Tags: cisco, nexus-dashboard, discovered
• Custom fields: nd_switch_db_id and nd_segment_id
• The Cisco manufacturer

Device roles are not created in bootstrap mode. They are created on a real sync, and only for the roles the discovered switches actually use, so bootstrap does not leave unused roles in NetBox.

Configuration:

config:
  BOOTSTRAP: true  # Set to true for initial setup, false for regular operation

First-time run process:

1. Set BOOTSTRAP: true in your configuration.
2. Run the agent and monitor the output for executed successfully.
3. Stop the agent by pressing Ctrl+C once you see executed successfully.
4. Apply the deviations in NetBox Assurance (see Apply Deviations below).
5. Set BOOTSTRAP: false for all future runs.

Optional - Dry Run Mode

The agent can run in dry run mode, which writes discovered data to a JSON file instead of sending it to NetBox. This is useful for troubleshooting, for reviewing what the integration will ingest before committing to your NetBox instance, or for sharing data with the NetBox Labs support team.

Add the following to the diode section of your configuration:

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/  # Output file is written to this directory

Step 3: Run the Agent

Run the agent to synchronize Nexus Dashboard fabric inventory into NetBox.

Method 1: Set Environment Variables Manually

1. Export Diode credentials:

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

2. Export Nexus Dashboard connection details:

export ND_HOST="https://nd.example.com"
export ND_USERNAME="your-nexus-dashboard-username"
export ND_PASSWORD="your-nexus-dashboard-password"

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e ND_HOST \
  -e ND_USERNAME \
  -e ND_PASSWORD \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

Method 2: Use a .env File (Recommended)

1. Create a .env file:

touch .env

2. Edit the .env file and add the following:

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

## Cisco Nexus Dashboard connection
ND_HOST=https://nd.example.com
ND_USERNAME=your-nexus-dashboard-username
ND_PASSWORD=your-nexus-dashboard-password

3. Run the agent:

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

echo ".env" >> .gitignore

Expected Output

After starting the agent, depending on the schedule you defined, you will see log output as the integration reads Nexus Dashboard and sends data to NetBox:

{"time":"2026-09-10T06:00:01.123456789Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_nexus_dashboard.nexus_dashboard_diode:Processing Nexus Dashboard at https://nd.example.com"}
{"time":"2026-09-10T06:00:01.234567890Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_nexus_dashboard.client:Authenticated with Nexus Dashboard at https://nd.example.com via username/password"}
{"time":"2026-09-10T06:00:01.345678901Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_nexus_dashboard.nexus_dashboard_diode:Fetched 1 fabrics"}
{"time":"2026-09-10T06:00:01.456789012Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_nexus_dashboard.builders.sites:Created site: evpn-lab"}
{"time":"2026-09-10T06:00:02.567890123Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_nexus_dashboard.nexus_dashboard_diode:Fetched 4 switches for fabric 'evpn-lab'"}
{"time":"2026-09-10T06:00:03.678901234Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_nexus_dashboard.nexus_dashboard_diode:Fetched 1 VRFs for fabric 'evpn-lab'"}
{"time":"2026-09-10T06:00:03.789012345Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_nexus_dashboard.nexus_dashboard_diode:Fetched 3 networks for fabric 'evpn-lab'"}
{"time":"2026-09-10T06:00:05.890123456Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy cisco_nexus_dashboard_worker: Successfully ingested 312 entities in 1 chunks"}
{"time":"2026-09-10T06:00:05.901234567Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run (trigger: cron[month='*', day='*', day_of_week='*', hour='*/6', minute='0'], next run at: 2026-09-10 12:00:00 UTC)\" executed successfully"}

View and Apply Discovered Data in NetBox Assurance

After the agent runs, work with the discovered Nexus Dashboard data in NetBox Assurance.

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

Accessing NetBox Assurance

1. Navigate to your 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 discovered.

2. Click the Name of a deviation type to view deviations of that type.
3. Click the Name of an individual deviation to view its details.

View Active Deviations

1. Click on Active Deviations to view all deviations that have not yet been applied or ignored.

2. Click the Name of a deviation to view its details.

Apply Deviations

1. Select the deviations you want to apply. For large result sets, set Per Page to 500 first.

2. Select the first deviation, hold SHIFT, select the last one, then click Apply Selected.

3. Click Apply X Deviations to write the data to NetBox.

View the Nexus Dashboard Data in NetBox

After running the integration and applying the discovered data, you can navigate the fabric inventory in NetBox.

1. Navigate to Organization → Sites to view a site for each discovered fabric.

2. Navigate to Devices → Devices to view the discovered fabric switches, with their device type, platform, role, site, and primary IP.

3. Click a device to see its interfaces, its serial number, its NX-OS platform, and the nd_switch_db_id custom field value.

4. Navigate to IPAM → VRFs to view the fabric VRFs and their route distinguishers.

5. Navigate to IPAM → VLANs to view the overlay networks, each carrying its VXLAN VNI in the nd_segment_id custom field.

6. Navigate to IPAM → Prefixes and IPAM → IP Addresses to view the overlay gateway subnets and the management, loopback, routed interface, and anycast gateway addresses.

Additional Resources

Related Documentation

• NetBox Assurance Documentation
• Orb Agent Documentation
• Cisco Nexus Dashboard Integration - Technical Information
• Cisco Nexus Dashboard Integration - FAQ & Troubleshooting

Support

Email support@netboxlabs.com for support.