Oxidized Import Tool

Oxidized Import Tool: Automated Device Migration to rConfig V8

The Oxidized Import Tool enables seamless migration of network devices from Oxidized to rConfig V8. This command-line utility automates the process of mapping device types, parsing Oxidized host files, and importing devices with proper templates, credentials, and configurations—eliminating manual data entry and ensuring consistency across your device inventory.

Tip

Available in rConfig V8. This tool significantly reduces migration time by automating device type mapping and bulk imports.

Why Migrate from Oxidized?

While Oxidized excels at configuration collection, rConfig V8 provides a comprehensive network configuration management platform with:

Advanced scheduling: Flexible task scheduling with cron-based timing and dependency management

Template engine: Configuration snippet deployment across device groups with variable substitution

Compliance auditing: Policy-based configuration validation with automated remediation workflows

Rich reporting: Detailed analytics, change tracking, and configuration comparison tools

Role-based access: Granular permission controls for team collaboration and audit compliance

The Oxidized Import Tool makes this transition seamless with automated device onboarding.

How It Works

The import process follows three steps:

1. Create device type mappings: Define how Oxidized device types translate to rConfig templates, vendors, and categories
2. Load devices from Oxidized: Parse the Oxidized hosts file and generate import-ready JSON
3. Import devices to rConfig: Bulk import devices with validated configurations and immediate backup scheduling

Prerequisites

Before importing devices, ensure you have:

• Oxidized hosts file (router.db or equivalent)
• Administrator access to rConfig V8
• Device templates configured in rConfig matching your Oxidized device types
• Connection profiles or credential sets created in rConfig
• SSH/command-line access to the rConfig server

Step 1: Create Device Type Mappings

Command

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings

Options

• --list - Display all existing device type mappings
• --add - Create a new device type mapping interactively
• --edit=TYPE - Modify an existing mapping for specified device type
• --delete=TYPE - Remove a device type mapping
• --info - Display command help and usage information

Create New Mapping

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --add

You’ll be prompted to provide:

Oxidized device type: The device type from your Oxidized configuration (e.g., ios, asa, nxos)

rConfig template: The device template ID to use for this device type

Vendor: The vendor ID associated with this device type

Category: The category ID for organizing devices

Tags: Optional comma-separated tag IDs for device classification

View Existing Mappings

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --list

Output displays all configured mappings:

Oxidized Type | Template ID | Vendor ID | Category ID | Tags
------------- | ----------- | --------- | ----------- | ----
ios           | 1           | 1         | 2           | 5,8
asa           | 3           | 1         | 3           | 6
nxos          | 5           | 1         | 2           | 5,9

Edit or Delete Mappings

# Edit existing mapping
php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --edit=ios

# Delete mapping
php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --delete=ios

Caution

Accurate mappings are critical for successful imports. Verify template, vendor, and category IDs exist in rConfig before creating mappings.

Step 2: Load Devices from Oxidized

Command

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-load-devices /path/to/oxidized/router.db

Oxidized Hosts File Format

The Oxidized hosts file uses the following format:

hostname:device_type[:username:password[:enable_password]]

Examples:

# Basic format (credentials from connection profile)
router1.example.com:ios
switch2.example.com:nxos

# With embedded credentials
router3.example.com:ios:admin:SecurePass123
firewall1.example.com:asa:admin:SecurePass123:EnablePass456

# Mixed configurations
core-sw-01.example.com:nxos:netadmin:Password1
edge-rtr-05.example.com:ios

What Happens During Loading

1. File validation: Verifies hosts file exists and is readable
2. Device parsing: Extracts hostname, device type, and optional credentials
3. Mapping application: Applies device type mappings to each device
4. Connectivity validation: Optionally tests device reachability
5. JSON generation: Creates rconfig_import.json in the same directory as hosts file
6. Error logging: Records validation issues for troubleshooting

Output File

The generated rconfig_import.json contains:

{
  "devices": [
    {
      "hostname": "router1.example.com",
      "device_type": "ios",
      "template_id": 1,
      "vendor_id": 1,
      "category_id": 2,
      "tags": [5, 8],
      "username": "admin",
      "password": "SecurePass123",
      "enable_password": null
    }
  ]
}

Note

If no credentials are provided in the hosts file, devices will use the default connection profile or credential set configured in rConfig.

Step 3: Import Devices to rConfig

Command

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-import-devices /path/to/rconfig_import.json

Options

• --group=ID - Assign all imported devices to specified device group (default: 1)
• --dry-run - Preview import without modifying database
• --skip-existing - Skip devices that already exist in rConfig
• --info - Display command help and usage information

Import Process Flow

1. JSON validation: Verifies file structure and required fields
2. Duplicate detection: Checks for existing devices by hostname
3. Device creation: Creates device records with mapped configurations
4. Relationship linking: Associates tags, vendors, categories, and groups
5. Credential assignment: Applies credentials or connection profiles
6. Initial backup: Schedules immediate configuration retrieval
7. Summary report: Displays import statistics and any errors

Dry Run Mode

Test the import without making changes:

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-import-devices \
  --dry-run \
  /path/to/rconfig_import.json

Output preview:

Dry Run Mode - No changes will be made

Found 45 devices to import
- 42 new devices
- 3 existing devices (will skip)

Device Preview:
[1] router1.example.com (ios) → Template: Cisco IOS, Vendor: Cisco
[2] switch2.example.com (nxos) → Template: Cisco NXOS, Vendor: Cisco
[3] firewall1.example.com (asa) → Template: Cisco ASA, Vendor: Cisco
...

Run without --dry-run to perform import

Production Import

Execute the actual import:

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-import-devices \
  --group=5 \
  --skip-existing \
  /path/to/rconfig_import.json

Import results:

Importing devices...

✓ Created: router1.example.com
✓ Created: switch2.example.com
⊘ Skipped: firewall1.example.com (already exists)
✓ Created: core-sw-01.example.com

Import Summary:
- Total devices: 45
- Successfully imported: 42
- Skipped (existing): 3
- Failed: 0

Initial backup tasks scheduled for all imported devices.

Complete Workflow Example

# Step 1: Create device type mappings
php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --add

# Step 2: Load devices from Oxidized hosts file
php /var/www/html/rconfig8/current/artisan rconfig:oxidized-load-devices \
  /opt/oxidized/router.db

# Step 3: Preview import (dry run)
php /var/www/html/rconfig8/current/artisan rconfig:oxidized-import-devices \
  --dry-run \
  /opt/oxidized/rconfig_import.json

# Step 4: Execute production import
php /var/www/html/rconfig8/current/artisan rconfig:oxidized-import-devices \
  --group=1 \
  --skip-existing \
  /opt/oxidized/rconfig_import.json

Troubleshooting

Device type mapping not found

Symptoms:

• Error during device loading: “No mapping found for device type ‘xyz’”

Resolution:

Create missing mapping:

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --add

List existing mappings to verify:

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --list

Invalid template/vendor/category ID

Symptoms:

• Import fails with “Template ID X does not exist”
• Database constraint violation errors

Resolution:

Verify IDs exist in rConfig:

• Navigate to Settings > Templates (or Vendors/Categories)
• Note the correct ID numbers
• Update mapping with correct IDs:

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-device-mappings --edit=ios

Hosts file parsing errors

Symptoms:

• Device loading fails with “Invalid hosts file format”
• Some devices missing from JSON output

Resolution:

Verify hosts file format:

# Check for blank lines or malformed entries
cat /opt/oxidized/router.db | grep -v '^#' | grep -v '^$'

# Valid format examples:
# hostname:device_type
# hostname:device_type:username:password
# hostname:device_type:username:password:enable_password

Remove or fix any lines that don’t match the expected format.

Duplicate devices

Symptoms:

• Import fails with “Device already exists”
• Duplicate hostname errors

Resolution:

Use --skip-existing flag:

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-import-devices \
  --skip-existing \
  /path/to/rconfig_import.json

Or manually remove duplicates from JSON before import.

Connection credential errors

Symptoms:

• Devices imported but cannot connect
• Authentication failures during initial backup

Resolution:

For devices with embedded credentials: Verify credentials in JSON file are correct

For devices without credentials: Ensure default connection profile is configured:

• Navigate to Settings > Connection Profiles
• Set default profile with valid credentials

Assign specific credential sets after import:

• Navigate to Devices
• Bulk edit imported devices
• Assign appropriate credential set

JSON validation errors

Symptoms:

• Import command fails with “Invalid JSON structure”
• Parse errors when reading import file

Resolution:

Validate JSON syntax:

# Check JSON is valid
python -m json.tool /path/to/rconfig_import.json

# Or use jq
jq . /path/to/rconfig_import.json

If errors found, regenerate JSON:

php /var/www/html/rconfig8/current/artisan rconfig:oxidized-load-devices \
  /opt/oxidized/router.db

Best Practices

Start with dry run: Always use --dry-run first to preview changes and catch errors before production import.

Create mappings first: Configure all device type mappings before loading the hosts file to avoid import failures.

Pre-create credential sets: Set up connection profiles and credential sets in rConfig before importing devices.

Backup regularly: Keep copies of your JSON import files for audit trails and potential rollbacks.

Import in batches: For large deployments (500+ devices), consider splitting hosts file into smaller batches for easier troubleshooting.

Verify mappings: Double-check that template, vendor, and category IDs are correct—typos cause import failures.

Test connectivity: After import, test a sample of devices to ensure they can connect and retrieve configurations.

Review logs: Check import logs for warnings or errors that need attention.

Post-Import Tasks

After successful import:

1. Verify device inventory: Navigate to Devices and confirm all devices imported correctly
2. Review credentials: Check that devices have appropriate credential assignments
3. Test connectivity: Use device debug command to verify connection to sample devices
4. Monitor initial backups: Check scheduled tasks to ensure configuration retrieval completes
5. Organize devices: Create device groups and apply bulk settings as needed
6. Configure schedules: Set up automated backup schedules for device groups
7. Enable compliance: Apply compliance policies to imported devices

Related Documentation

• Device Management - Understanding device configuration in rConfig
• Device Templates - Configuring device templates
• Connection Profiles - Setting up connection credentials
• Scheduled Tasks - Automating configuration backups
• Device Groups - Organizing devices for management