Skip to main content
CloudEnterprise

Getting Started with the Cisco Catalyst Center Integration for NetBox

This guide will help you set up and start using the Catalyst Center Integration for NetBox.

Prerequisites

Before using this guide you should ensure all prerequisites have been met.

Table of Contents​

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., "Catalyst Center Integration")
  5. Click Create Add client credentials
  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 copy client credentials
  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 copy Diode target

Agent Setup and Configuration​

info

You can deploy multiple agents configured to sync data from more than one Catalyst Center Controller

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
  1. Edit the configuration file with your preferred editor and add the following configuration. Important: Replace your-instance.netboxcloud.com with your actual NetBox instance hostname:
orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: cisco_catalyst_center_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      cisco_catalyst_center_worker:
        config:
          package: nbl_cisco_catalyst_center
          schedule: "* * * * *"  # Set your desired schedule (see examples below)
          timeout: 5
          CCC_HOST: ${CCC_HOST}
          CCC_USER: ${CCC_USER}
          CCC_PWD: ${CCC_PWD}
        scope:
Schedule Examples

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

  • "* * * * *" - Every minute
  • "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

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 from your Catalyst Center Controller 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"
  1. Export Catalyst Center credentials as environment variables:
export CCC_HOST="https://your-catalyst-center-host"
export CCC_USER="your-catalyst-center-username"
export CCC_PWD="your-catalyst-center-password"
  1. Run the agent with the following command:
docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e CCC_HOST \
  -e CCC_USER \
  -e CCC_PWD \
  netboxlabs.jfrog.io/obs-orb-agent-pro/orb-agent-pro \
  run -c /opt/orb/agent.yaml
  1. Create a .env file in your current directory:
touch .env
  1. 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 Catalyst Center credentials
CCC_HOST="https://your-catalyst-center-host"
CCC_USER="your-catalyst-center-username"
CCC_PWD="your-catalyst-center-password"
Important

Replace the placeholder values with your actual credentials:

  • your-client-id and your-client-secret from the NetBox Diode setup
  • your-catalyst-center-host with your Catalyst Center controller URL
  • your-catalyst-center-username and your-catalyst-center-password with your Catalyst Center 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-07-20T15:15:05.667656922Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_catalyst_center.ccc_diode:Processing interface: GigabitEthernet0/0 on device sw4"}
{"time":"2025-07-20T15:15:05.667767339Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_catalyst_center.ccc_diode:Added interface entity: GigabitEthernet0/0 with type 1000base-t"}
{"time":"2025-07-20T15:15:05.667782006Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_catalyst_center.ccc_diode:Added MAC address entity: 52:54:00:0F:1C:07 for interface GigabitEthernet0/0"}
{"time":"2025-07-20T15:15:05.667917714Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_catalyst_center.ccc_diode:Added IP address entity: 10.10.20.178/24 for interface GigabitEthernet0/0"}
{"time":"2025-07-20T15:15:05.988165881Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy cisco_catalyst_center_worker: Successful ingestion"}
{"time":"2025-07-20T15:15:05.989072464Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run (trigger: cron[month='*', day='*', day_of_week='*', hour='*', minute='*'], next run at: 2025-07-20 15:16:00 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 Catalyst Center 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 View deviation types
  2. Click on the Name of a deviation type, to view deviations for a particular type Discovered new device
  3. Click on the Name of a an individual deviation, to view the details Discovered SW4

View Active Deviations​

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

Apply Deviations​

  1. Select the deviations that you'd like to apply, and then click Apply: apply deviations
  2. Click Apply X Deviations to apply the deviations to the NetBox database: confirm apply deviations
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 Catalyst Center Data in NetBox​

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

  1. Start by clicking on Devices in the main navigation menu devices
  2. Select an individual device to view the details device sw1

Additional Resources​

Support​

Email support@netboxlabs.com for support.

Related Topics
DiscoveryNetBox