CML Migration Tool

A Python-based automation tool for migrating Cisco Modeling Lab (CML) environments from version 2.x to 2.9, handling lab extraction, configuration backup, and preparation for import into the new environment.

Overview

This tool addresses the lack of in-place upgrade options between CML 2.x and 2.9 by providing automated lab migration capabilities. It connects to your existing CML 2.x environment, extracts all labs with their configurations, and prepares them for import into CML 2.9.

Features

• 🔐 Secure authentication with CML API
• 📦 Automated lab discovery and extraction
• ⚙️ Configuration backup for all network nodes
• 🚀 Parallel processing with retry mechanisms
• 📊 Convergence monitoring and validation
• 📁 Organized output structure for easy migration
• 🔄 Graceful error handling and recovery

Prerequisites

• Python 3.7 or higher
• Access to CML 2.x environment
• Network connectivity to CML server
• Sufficient disk space for lab backups

Installation

1. Clone the repository:

git clone <repository-url>
cd cml-migration-tool

2. Install dependencies:

pip install -r requirements.txt

3. Configure environment variables:

cp .env.example .env
# Edit .env with your CML credentials and settings

Configuration

Environment Variables

Create a .env file in the project root:

# CML Server Configuration
CML_HOST=192.168.1.32
CML_PORT=443
CML_USERNAME=your_username
CML_PASSWORD=your_secure_password

# Migration Settings
OUTPUT_DIR=./Labs
MAX_RETRIES=3
CONVERGENCE_CHECK_INTERVAL=5
MAX_CONVERGENCE_WAIT=300

SSL Certificate Handling

For production environments, consider:

• Adding your CML server's CA certificate to the trust store
• Using proper SSL verification instead of verify=False
• Implementing certificate pinning for additional security

Usage

Basic Migration

Run the complete migration process:

python cml_migrator.py

Advanced Usage

from cml_migrator import CMLMigrator

# Initialize migrator
migrator = CMLMigrator(
    host='192.168.1.32',
    username='admin',
    password='secure_password'
)

# Authenticate
if migrator.authenticate():
    # Get all labs
    labs = migrator.get_labs()
    
    # Migrate specific lab
    migrator.migrate_lab('lab-uuid-here')

Output Structure

Labs/
├── Lab_Name_1.yaml          # Lab topology file
├── Lab_Name_2.yaml

Security Considerations

Credentials Management

• Never commit credentials to the repository
• Use environment variables or secure credential stores
• Rotate passwords regularly
• Use least-privilege access principles

Network Security

• Run from a secure, isolated network segment
• Use VPN or secure tunnels for remote access
• Monitor network traffic during migration
• Validate SSL certificates in production

Data Protection

• Encrypt sensitive configuration data at rest
• Secure backup storage locations
• Implement access controls on migration artifacts
• Consider data residency requirements

Migration Process

1. Authentication: Secure login to CML 2.x environment
2. Discovery: Enumerate all available labs
3. Lab Startup: Start labs if not already running
4. Convergence Wait: Monitor network convergence
5. Configuration Extract: Backup all node configurations
6. Lab Download: Export lab topology files
7. Cleanup: Stop labs and clean up resources

Troubleshooting

Common Issues

Authentication Failures

# Check credentials and network connectivity
curl -k https://192.168.1.32/api/v0/authok

SSL Certificate Errors

• Add CA certificate to system trust store
• Use proper certificate validation
• Check for certificate expiry

Convergence Timeout

• Increase MAX_CONVERGENCE_WAIT in configuration
• Check lab complexity and resource allocation
• Verify network connectivity between nodes

Logging

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Migration to CML 2.9

After running this tool:

1. Transfer the Labs/ directory to your CML 2.9 environment
2. Import lab YAML files through CML 2.9 interface
3. Verify node configurations and topology
4. Update any version-specific configurations
5. Test lab functionality in new environment

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement changes with proper testing
4. Submit a pull request with detailed description
5. Ensure all security checks pass

Cisco Compliance

This tool is designed to work with supported Cisco Modeling Lab APIs and follows Cisco best practices for:

• Network automation
• Configuration management
• API integration
• Security standards

License

MIT License

Support

For issues and questions:

• Check the troubleshooting section
• Review Cisco CML documentation
• Open an issue in this repository

Changelog

See CHANGELOG.md for version history and updates.

Note: This tool is designed for CML 2.x to 2.9 migration. Always test in a non-production environment first and ensure you have proper backups before migration.