CML2NetBox

A command-line interface for synchronizing Cisco Modeling Labs (CML) topologies and device types with NetBox.

Description

CML2NetBox is a tool that helps bridge the gap between Cisco Modeling Labs (CML) and NetBox, a leading open source IP Address Management (IPAM) and Data Center Infrastructure Management (DCIM) solution. This tool allows you to synchronize lab topologies and device types between these two systems.

Features

• Sync CML device types with NetBox device types
• Sync CML lab topologies with NetBox
• Command-line interface for easy automation and scripting

Installation

From Source

Note: A bash script, setup.sh, is included in the project that will create the Python venv and install cml2netbox in development mode. It is provided for convenience.

1. Clone the repository:

git clone https://github.com/hpreston/cml2netbox
cd cml2netbox

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install the package in development mode:

pip install -e .

Usage

Important Details

Here are some specifics about how objects are created in NetBox that are important to understand before using the tool.

• A NetBox Manufacture of CML is created and used for all device types
• A NetBox Device Role of CML Node is created and used for devices
• A NetBox Site will be created for the CML Lab Name/Title, all deviecs will be added to this site
• If NetBox does NOT have a matching Device Type for the CML Node Definition of a device being synchronized, cml2netbox will try to add it on demand.
• IP addresses are created based on the Day 0 config assigned to nodes, not what is operationally configured.

  IP address creation is supported for the following node types:

  • IOL, IOLL2, IOSv, CSR1000v, Cat8000v, NX-OS 9000, ASAv, Alpine, Alpine based VMs and containers

  Supporting other node types is possible and may come in the future

• IP addresses are created in the "Global VRF" in NetBox.
  • If the Global VRF does NOT allow duplicate IP addresses, an error will be raised and the sync will fail

Configuration

CML2NetBox requires configuration for both CML and NetBox servers. You can provide configuration in three ways (in priority order):

1. Command line options (highest priority)
2. Environment variables
3. .env file in the current directory (lowest priority)

Required Configuration

• CML2_URL: The HTTPS address for the CML server (e.g., https://10.1.20.10)
• CML2_USER: The user account to connect to CML with
• CML2_PASS: The password to connect to CML with
• CML2_VERIFY_SSL: Whether to verify the SSL cert (default: True)
• NETBOX_URL: The NetBox server address
• NETBOX_API_TOKEN: The NetBox API token (must have READ/WRITE permissions)
• NETBOX_VERIFY_SSL: Whether to verify the SSL cert (default: True)
• LAB_NAME: The CML Lab/Topology to sync into NetBox
• LAB_ID: Only required if multiple CML labs share a name, this is the Lab ID (UUID) for the CML topology.

Note: All CML2_* environment variables can also be set as VIRL2_* variants for backward compatibility.

Configuration Examples

Using environment variables:

export CML2_URL=https://cml.example.com
export CML2_USER=admin
export CML2_PASS=password123
export NETBOX_URL=https://netbox.example.com  
export NETBOX_API_TOKEN=your-token-here
export LAB_NAME="My CML Lab"

Using .env file:

# Copy .env.example to .env and edit
cp .env.example .env
# Edit .env with your values

Using command line options:

cml2netbox --cml2-url https://cml.example.com \
           --cml2-user admin \
           --cml2-pass password123 \
           --netbox-url https://netbox.example.com \
           --netbox-api-token your-token-here \
           sync lab "My CML Lab"

Commands

After installation, you can use the cml2netbox command:

Note: These examples assume that the configuration details are provided via ENVs or in a .env file.

# Show help
cml2netbox --help

# Show sync commands help
cml2netbox sync --help

# Sync lab topology 
cml2netbox sync lab

# Sync device types 
cml2netbox sync device-types

Logging and Output

cml2netbox generates a detailed log file for each job run. The log file will be stored in the working directory and named like 20250904-134758-cml2netbox.log, where the timestamp of the job run is the first part of the log name.

By default, the log level is set to INFO. If you'd like to enable DEBUG logging, run the command with the verbose flag.

cml2netbox --verbose sync lab

The command output of cml2netbox is simple and straightforward. For example:

cml2netbox sync lab   

🔄 Starting lab topology synchronization...
📡 CML Server: https://10.1.20.11
🗄️  NetBox Server: http://10.1.20.101
🧪 Lab Name: DEMO 01
Beginning lab synchronization now.
Adding 1 nodes from CML lab 'DEMO 01' to NetBox
Adding cables for 1 nodes from CML lab 'DEMO 01' to NetBox

Development

Setting up for development

1. Clone the repository and navigate to the directory
2. Create a virtual environment: python -m venv .venv
3. Activate the virtual environment: source .venv/bin/activate
4. Install in development mode with dev dependencies: pip install -e .[dev]

Running tests

pytest

Code formatting

black .

Type checking

mypy .

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

See the LICENSE file for details.