cml2netbox 0.1.1
A command-line interface for synchronizing Cisco Modeling Labs (CML) topologies and device types with NetBox
License: MIT
Requires Python: >=3.8
Keywords: cisco, cml, netbox, ipam, dcim, network, automation

# 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:
```bash
git clone https://github.com/hpreston/cml2netbox
cd cml2netbox
```

2. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

3. Install the package in development mode:
```bash
pip install -e .
```

<!-- Not published to PyPi yet, hiding these instructions
### Using pip (when published)

```bash
pip install cml2netbox
``` -->

## 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:**
```bash
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:**
```bash
# Copy .env.example to .env and edit
cp .env.example .env
# Edit .env with your values
```

**Using command line options:**
```bash
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.

```bash
# 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. 

```shell
cml2netbox --verbose sync lab
```

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

```shell
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

```bash
pytest
```

### Code formatting

```bash
black .
```

### Type checking

```bash
mypy .
```

## Contributing

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

## License

See the LICENSE file for details.