Migration Guide

Guide for migrating from the legacy Python implementation to the new Rust implementation.

Overview

This guide covers the migration from the original Python-based OPNsense Config Faker to the new Rust implementation. The Rust version provides significant performance improvements, better error handling, and enhanced reliability.

Key Differences

Performance Improvements

Metric	Python Implementation	Rust Implementation	Improvement
Generation Speed	100ms per 100 VLANs	10ms per 100 VLANs	10x faster
Memory Usage	50MB for 1000 VLANs	5MB for 1000 VLANs	10x less memory
Startup Time	2-3 seconds	50-100ms	20-30x faster
Binary Size	N/A (script)	5-10MB	Self-contained

API Changes

Command Line Interface

Python (Legacy):

python generate_csv.py --count 100 --output vlans.csv
python generate_xml.py --count 100 --output vlans.xml

Rust (New):

cargo run --release -- generate vlan --count 100 --output vlans.csv
cargo run --release -- generate vlan --count 100 --output vlans.xml

Configuration Generation

Python (Legacy):

from opnsense_config_generator import VlanGenerator

generator = VlanGenerator()
vlans = generator.generate_vlans(count=100, base_id=1)

Rust (New):

#![allow(unused)]
fn main() {
use opnsense_config_faker::generators::generate_vlan_config;

let vlans = generate_vlan_config(100, 1, "192.168.0.0/24".parse().unwrap())?;
}

Migration Steps

1. Install Rust Implementation

# Clone the repository
git clone https://github.com/EvilBit-Labs/OPNsense-config-faker.git
cd OPNsense-config-faker

# Build the release binary
cargo build --release

# The binary will be available at target/release/opnsense-config-faker

2. Update Scripts and Automation

Shell Scripts

Before (Python):

#!/bin/bash
python generate_csv.py --count 100 --output vlans.csv
python generate_xml.py --count 100 --output vlans.xml

After (Rust):

#!/bin/bash
cargo run --release -- generate vlan --count 100 --format csv --output vlans.csv
cargo run --release -- generate vlan --count 100 --format xml --output vlans.xml

CI/CD Pipelines

Before (Python):

  - name: Generate test data
    run: |
      python generate_csv.py --count 1000 --output test-data.csv
      python generate_xml.py --count 1000 --output test-config.xml

After (Rust):

  - name: Generate test data
    run: |
      cargo run --release -- generate vlan --count 1000 --format csv --output test-data.csv
      cargo run --release -- generate vlan --count 1000 --format xml --output test-config.xml

3. Update Configuration Files

Configuration Parameters

Python (Legacy):

config = {
    'vlan_count': 100,
    'base_id': 1,
    'base_network': '192.168.0.0/24',
    'output_format': 'xml',
    'output_file': 'vlans.xml'
}

Rust (New):

cargo run --release -- generate vlan \
  --count 100 \
  --base-id 1 \
  --base-network 192.168.0.0/24 \
  --format xml \
  --output vlans.xml

4. Update Integration Code

Python Integration

Before (Legacy):

import subprocess

# Generate CSV data
result = subprocess.run([
    'python', 'generate_csv.py',
    '--count', '100',
    '--output', 'vlans.csv'
], capture_output=True, text=True)

After (Rust):

import subprocess

# Generate CSV data
result = subprocess.run([
    'cargo', 'run', '--release', '--',
    'generate', 'vlan',
    '--count', '100',
    '--output', 'vlans.csv'
], capture_output=True, text=True)

Node.js Integration

Before (Legacy):

const {
    spawn
} = require('child_process');

const python = spawn('python', ['generate_csv.py', '--count', '100', '--output', 'vlans.csv']);

After (Rust):

const {
    spawn
} = require('child_process');

const rust = spawn('cargo', ['run', '--release', '--', 'generate', 'vlan', '--count', '100', '--output', 'vlans.csv']);

5. Update Documentation

README Updates

Before (Legacy):

## Usage

Generate VLAN configurations:

```bash
python generate_csv.py --count 100 --output vlans.csv
python generate_xml.py --count 100 --output vlans.xml
```

After (Rust):

## Usage

Generate VLAN configurations:

```bash
cargo run --release -- generate vlan --count 100 --output vlans.csv
cargo run --release -- generate vlan --count 100 --output vlans.xml
```

Feature Mapping

Python Features → Rust Features

Python Feature	Rust Equivalent	Notes
`--count`	`--count`	Same parameter name
`--output`	`--output`	Same parameter name
`--base-id`	`--base-id`	Same parameter name
`--base-network`	`--base-network`	Same parameter name
`--format`	`--format`	Same parameter name
`--validate`	`--validate`	Enhanced validation
`--verbose`	`--verbose`	Enhanced logging

New Features in Rust

Feature	Description	Usage
`--memory-efficient`	Memory-efficient mode	`--memory-efficient`
`--parallel`	Parallel processing	`--parallel`
`--stream`	Streaming output	`--stream`
`--batch-size`	Batch processing	`--batch-size 100`
`--progress`	Progress indication	`--progress`
`--stats`	Generation statistics	`--stats`

Performance Comparison

Generation Speed

Python (Legacy):

time python generate_csv.py --count 1000 --output vlans.csv
# Real: 0m2.345s
# User: 0m2.123s
# Sys: 0m0.222s

Rust (New):

time cargo run --release -- generate vlan --count 1000 --output vlans.csv
# Real: 0m0.234s
# User: 0m0.123s
# Sys: 0m0.111s

Memory Usage

Python (Legacy):

python generate_csv.py --count 1000 --output vlans.csv
# Memory usage: ~50MB

Rust (New):

cargo run --release -- generate vlan --count 1000 --output vlans.csv
# Memory usage: ~5MB

Troubleshooting Migration

Common Issues

Command Not Found

Problem: cargo command not found.

Solution:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Verify installation
cargo --version

Build Failures

Problem: Build fails with dependency errors.

Solution:

# Update Rust toolchain
rustup update

# Clean build artifacts
cargo clean

# Rebuild
cargo build --release

Performance Issues

Problem: Slower than expected performance.

Solution:

# Use release build
cargo run --release -- generate vlan --count 1000

# Enable parallel processing
cargo run --release --features rayon -- generate vlan --count 1000 --parallel

# Use memory-efficient mode
cargo run --release -- generate vlan --count 1000 --memory-efficient

Validation Issues

Output Format Differences

Problem: Generated output differs from Python version.

Solution:

# Validate generated output
cargo run --release -- validate --input config.xml

# Compare with Python output
diff python-output.xml rust-output.xml

Schema Validation Errors

Problem: Generated XML doesn’t validate against OPNsense schema.

Solution:

# Use strict validation
cargo run --release -- generate vlan --count 100 --validate --strict --output config.xml

# Check XML structure
xmllint --noout config.xml

Rollback Plan

If Migration Fails

Keep Python Implementation: Maintain the Python version as backup
Gradual Migration: Migrate one component at a time
Validation: Compare outputs between Python and Rust versions
Testing: Thoroughly test Rust implementation before full migration

Rollback Steps

# Revert to Python implementation
python generate_csv.py --count 100 --output vlans.csv

# Or use both implementations
if command -v cargo &> /dev/null; then
    cargo run --release -- generate vlan --count 100 --output vlans.csv
else
    python generate_csv.py --count 100 --output vlans.csv
fi

Best Practices

Migration Strategy

Test First: Test Rust implementation with small datasets
Validate Output: Compare outputs between Python and Rust versions
Gradual Rollout: Migrate one use case at a time
Monitor Performance: Track performance improvements
Document Changes: Update all documentation and scripts

Quality Assurance

Output Validation: Ensure generated configurations are identical
Performance Testing: Verify performance improvements
Error Handling: Test error scenarios and recovery
Integration Testing: Test all integration points
User Acceptance: Get user feedback on new implementation

Maintenance

Keep Both Versions: Maintain Python version during transition
Update Documentation: Keep all documentation current
Train Users: Provide training on new implementation
Monitor Issues: Track and resolve any migration issues
Plan Deprecation: Plan for eventual Python version deprecation

Support

Getting Help

GitHub Issues: Report migration issues
Documentation: Check the User Guide for detailed usage
Examples: Review Examples for migration examples
Community: Join the discussion in GitHub discussions

Migration Support

Migration Guide: This document provides comprehensive migration guidance
Troubleshooting: Troubleshooting Guide for common issues
Performance: Performance Guide for optimization
API Reference: API Reference for detailed API documentation

This migration guide ensures a smooth transition from the Python implementation to the new Rust implementation while maintaining all functionality and improving performance.

Keyboard shortcuts

OPNsense Config Faker User Guide