RANCID Import Tool

RANCID Import Tool: Automated Device Migration to rConfig V8

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

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

Why Migrate from RANCID?

While RANCID excels at configuration backup, rConfig V8 provides a comprehensive network configuration management platform with:

Modern interface: Web GUI and API replacing command-line and email-based workflows

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 RANCID Import Tool makes this transition seamless with automated device onboarding and credential migration.

How It Works

The import process follows three steps:

Create device type mappings: Define how RANCID device types translate to rConfig templates, vendors, and categories
Load devices from RANCID: Parse RANCID router.db files, extract credentials from .cloginrc, and generate import-ready JSON
Import devices to rConfig: Bulk import devices with validated configurations and immediate backup scheduling

File Locations

The import tool uses the following file locations:

Mappings file: storage/app/rconfig/rancid_mappings.json
Temporary files: storage/app/rconfig/tempdir/
Import JSON files: storage/app/rconfig/tempdir/rconfig_import_YYYY-MM-DD_HH-mm-ss.json
Failure logs: storage/app/rconfig/tempdir/rancid_import_failures_[group]_YYYY-MM-DD_HH-mm-ss.txt

These directories are created automatically if they don’t exist.

Prerequisites

Before importing devices, ensure you have:

Access to RANCID installation with router.db files
Read access to .cloginrc for credential extraction (optional but recommended)
Administrator access to rConfig V8
Device templates configured in rConfig matching your RANCID device types
At least one credential set created in rConfig (required for devices without .cloginrc credentials)
SSH/command-line access to the rConfig server

Step 1: Create Device Type Mappings

Command

php /var/www/html/rconfig8/current/artisan rconfig:rancid-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:rancid-device-mappings --add

You’ll be prompted to provide:

RANCID device type: The device type from your RANCID router.db (e.g., cisco, juniper, foundry)

rConfig device type: The internal device type name (e.g., cisco_ios)

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: Multi-select tags for device classification (use Space to select, Enter to confirm)

Prompts: Device enable and main prompts (use {device_name} as placeholder)

Common RANCID Device Types

cisco: Cisco IOS devices (routers, switches)
juniper: Juniper JunOS devices
foundry: Foundry/Brocade devices
hp: HP ProCurve switches
extreme: Extreme Networks devices
arista: Arista Networks devices
force10: Force10/Dell devices

View Existing Mappings

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

Output displays all configured mappings:

=== CISCO ===
rConfig Type: cisco_ios
Template ID: 1
Vendor ID: 1
Category ID: 2
Prompts:
  - device_enable_prompt: {device_name}>
  - device_main_prompt: {device_name}#
Tags: 5, 8

Edit or Delete Mappings

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

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

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 RANCID

Command

php /var/www/html/rconfig8/current/artisan rconfig:rancid-load-devices

Options

--rancid-base=/path - Specify RANCID base directory (auto-detected if not provided)
--group=groupname - Import only a specific RANCID group
--info - Display command help and usage information

RANCID Directory Structure

RANCID uses the following structure:

Debian/Ubuntu:

/usr/local/rancid/
├── .cloginrc              # Credentials file
├── etc/rancid.conf        # RANCID configuration
└── var/                   # Device data
    ├── group1/
    │   ├── router.db      # Device list
    │   └── configs/       # Configuration files
    └── group2/
        ├── router.db
        └── configs/

RHEL/Rocky/CentOS:

/var/lib/rancid/
├── .cloginrc
├── group1/                # Groups directly under base
│   ├── router.db
│   └── configs/
└── group2/
    ├── router.db
    └── configs/

The tool automatically detects both structures.

RANCID Base Directory Auto-Detection

If --rancid-base is not specified, the tool checks:

/usr/local/rancid
/var/lib/rancid
/var/rancid
/opt/rancid

If none are found, you’ll be prompted to enter the path manually.

RANCID router.db File Format

hostname:device_type:status

RANCID 3.0+ also supports:

hostname;device_type;status

Examples:

# Devices marked as "up" (will be imported)
router1.example.com:cisco:up
switch1.example.com:hp:up
fw1.example.com:juniper:up

# Devices marked as "down" (will be skipped)
router2.example.com:cisco:down

# RANCID 3.0+ format
router3.example.com;cisco;up

Credential Extraction from .cloginrc

The tool automatically parses .cloginrc to extract credentials:

.cloginrc format:

# Username for specific devices
add user router1.example.com admin
add user 192.168.1.* netadmin

# Password (and optional enable password)
add password router1.example.com myPassword myEnablePassword
add password *.example.com defaultPass defaultEnable

# Glob patterns are supported
add user *.core.* coreuser
add password *.core.* corepass

Credential matching:

Tool checks .cloginrc for patterns matching each device’s hostname/IP
If found: credentials embedded in JSON (device_cred_id = 0)
If not found: uses default credential set selected by user

Default Credential Selection

If devices don’t have credentials in .cloginrc, you’ll be prompted:

Select a default credential to use for devices without specific credentials in .cloginrc:

Which credential would you like to use as default?
  ID #1: Production SSH Credentials
  ID #2: Lab Credentials

What Happens During Loading

RANCID directory detection: Locates RANCID base directory
Group discovery: Finds all groups with router.db files
Group selection: User selects specific group or all groups
Prerequisite checks: Validates mappings and credential sets exist
router.db parsing: Reads device lists from each group
Status filtering: Skips devices not marked as “up”
Device type validation: Checks mapping exists for each device type
DNS resolution: Resolves hostnames to IP addresses
Config file verification: Ensures config file exists
Config analysis: Extracts model/version information from config files
Credential extraction: Parses .cloginrc for device credentials
JSON generation: Creates timestamped import file per group
Failure logging: Records validation issues per group

Output Files

The generated files include:

Success file: storage/app/rconfig/tempdir/rconfig_import_2025-01-25_14-30-45.json

Failures file: storage/app/rconfig/tempdir/rancid_import_failures_networking_2025-01-25_14-30-45.txt

Example JSON output:

[
  {
    "device_name": "router1.example.com",
    "device_ip": "192.168.1.1",
    "device_model": "7206VXR",
    "template_id": 1,
    "vendor_id": 1,
    "device_category_id": 2,
    "prompts": {
      "device_enable_prompt": "router1.example.com>",
      "device_main_prompt": "router1.example.com#"
    },
    "tags": [5, 8],
    "rancid_group": "networking",
    "device_cred_id": 0,
    "device_username": "admin",
    "device_password": "myPassword",
    "device_enable_password": "myEnablePassword",
    "connection_type": "ssh",
    "port": 22
  },
  {
    "device_name": "switch1.example.com",
    "device_ip": "192.168.1.2",
    "device_model": "3750",
    "template_id": 1,
    "vendor_id": 1,
    "device_category_id": 2,
    "prompts": {
      "device_enable_prompt": "switch1.example.com>",
      "device_main_prompt": "switch1.example.com#"
    },
    "tags": [5, 8],
    "rancid_group": "networking",
    "device_cred_id": 1,
    "connection_type": "ssh",
    "port": 22
  }
]

Credential Assignment Logic

device_cred_id = 0: Device uses embedded credentials from .cloginrc (username/password in JSON)
device_cred_id > 0: Device uses the specified credential set ID from rConfig

NOTE: The {device_name} placeholder in prompts is automatically replaced with the actual device hostname during the loading process.

Step 3: Import Devices to rConfig

Command

php /var/www/html/rconfig8/current/artisan rconfig:rancid-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
--info - Display command help and usage information

Interactive Import Options

When run without a file path, the command offers:

What would you like to do?
  Show information about this command
  Import devices from a JSON file
  Import from the latest available JSON file
  Select from all available import files
  Exit

Latest file mode: Automatically finds and uses the most recent JSON file

Select file mode: Displays all available import files with filename, date, size, and device count

Import Process Flow

JSON validation: Verifies file structure and required fields
Device validation: Checks each device for required fields and valid IDs
Transaction-based import: All valid devices imported in a single database transaction
Device creation: Creates device records with mapped configurations
Relationship linking: Associates tags, vendors, categories, and templates
Duplicate handling: Automatically skips devices that already exist
Summary report: Displays import statistics

Device Relationships Created

For each imported device:

Tags: Many-to-many relationship with selected tags
Vendor: Many-to-many relationship (single vendor)
Category: Many-to-many relationship (single category)
Template: Many-to-many relationship (single template)

Validation Rules

Required fields:

device_name
device_ip (must be valid IP format)
device_model
template_id (must exist in database)
vendor_id (must exist in database)
device_category_id (must exist in database)
prompts (must contain device_enable_prompt and device_main_prompt)

Credential validation:

If device_cred_id = 0: device_username and device_password are required
If device_cred_id > 0: credential set must exist in database

Duplicate detection:

No existing device with same device_name
No existing device with same device_ip

Dry Run Mode

Test the import without making changes:

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

Output preview:

Running in dry-run mode - no database changes will be made

Validating devices ████████████████████ 100%

12 devices failed validation:
Device: router99.example.com
  - Template ID 99 not found

Continue with 188 valid devices? (yes/no)

Dry run completed. 188 devices would be imported.

Production Import

Execute the actual import:

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

Import results:

Found 200 devices in the import file

Validating devices ████████████████████ 100%

Importing devices ████████████████████ 100%

Import completed successfully!
Imported: 195 devices
Skipped: 5 devices (already exist)

NOTE: All imports use database transactions. If any error occurs during import, all changes are rolled back automatically.

Complete Workflow Example

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

# Add mappings for common RANCID types: cisco, juniper, hp, etc.

# Verify mappings
php /var/www/html/rconfig8/current/artisan rconfig:rancid-device-mappings --list

# Step 2: Load devices from RANCID
php /var/www/html/rconfig8/current/artisan rconfig:rancid-load-devices

# The command will:
# - Auto-detect RANCID installation
# - Show available groups
# - Extract credentials from .cloginrc
# - Generate timestamped JSON file

# Review failures log
cat storage/app/rconfig/tempdir/rancid_import_failures_networking_2025-01-25_14-30-45.txt

# Step 3: Preview import (dry run)
php /var/www/html/rconfig8/current/artisan rconfig:rancid-import-devices \
  --dry-run \
  storage/app/rconfig/tempdir/rconfig_import_2025-01-25_14-30-45.json

# Step 4: Execute production import
php /var/www/html/rconfig8/current/artisan rconfig:rancid-import-devices \
  --group=1 \
  storage/app/rconfig/tempdir/rconfig_import_2025-01-25_14-30-45.json

# Or use the latest file automatically
php /var/www/html/rconfig8/current/artisan rconfig:rancid-import-devices
# Select: "Import from the latest available JSON file"

Troubleshooting

RANCID directory not found

Symptoms:

Error: “Could not find RANCID installation directory”

Resolution:

Specify RANCID base directory explicitly:

php /var/www/html/rconfig8/current/artisan rconfig:rancid-load-devices \
  --rancid-base=/custom/path/to/rancid

No RANCID groups found

Symptoms:

Error: “No RANCID groups found in: /path/to/rancid/var”

Resolution:

Verify directory structure and router.db files exist:

# Check for groups
ls -la /usr/local/rancid/var/

# Verify router.db exists
ls -la /usr/local/rancid/var/*/router.db

No credential sets exist

Symptoms:

Error: “No device credentials found in the system”
Import halts before processing devices

Resolution:

Create at least one credential set in rConfig:

Navigate to Settings > Credentials
Create a new credential set with valid SSH credentials
Re-run the load devices command

Device type mapping not found

Symptoms:

Devices logged to failures file with “Unknown device type ‘xyz’. No mapping found.”

Resolution:

Create missing mapping:

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

List existing mappings to verify:

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

Invalid template/vendor/category ID

Symptoms:

Import fails with “Template ID X does not exist”
Validation shows “Vendor ID X not found”

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:rancid-device-mappings --edit=cisco

DNS resolution failures

Symptoms:

Devices logged to failures file with “Could not resolve hostname to IP address”

Resolution:

Verify DNS is working on the rConfig server:

# Test DNS resolution
nslookup router1.example.com

# Or use host command
host router1.example.com

Options to resolve:

Add entries to /etc/hosts for devices
Configure proper DNS servers in /etc/resolv.conf
Update router.db to use IP addresses instead of hostnames

Config file not found

Symptoms:

Devices logged to failures file with “Config file not found in /path/configs”

Resolution:

Verify config files exist:

# Check configs directory
ls -la /usr/local/rancid/var/groupname/configs/

# Run RANCID to collect configs
rancid-run groupname

.cloginrc parsing errors

Symptoms:

All devices use default credential set despite .cloginrc existing

Resolution:

Verify .cloginrc format and permissions:

# Check file exists and is readable
ls -la /usr/local/rancid/.cloginrc

# Ensure proper permissions
chmod 644 /usr/local/rancid/.cloginrc

# Valid format:
# add user router1.example.com admin
# add password router1.example.com myPass myEnable

Devices marked as “down” being skipped

Symptoms:

Many devices logged with “Device status is not ‘up’”

Resolution:

This is intentional. Only devices marked as “up” in router.db are imported.

To include down devices, temporarily edit router.db:

# Backup first
cp router.db router.db.backup

# Change status to up
sed -i 's/:down$/:up/g' router.db

router.db format errors

Symptoms:

Devices logged with “Invalid router.db format”

Resolution:

Verify router.db format:

# Valid formats:
# hostname:device_type:status  (legacy)
# hostname;device_type;status  (RANCID 3.0+)

# Remove blank lines
sed -i '/^$/d' router.db

Duplicate devices

Symptoms:

Validation shows “Device with same name or IP already exists”

Resolution:

Duplicates are automatically skipped during import. To handle duplicates:

Check existing devices:

Navigate to Devices in rConfig
Search for the device name or IP
Delete the existing device if needed

Transaction rollback on import

Symptoms:

Import fails with “Import failed: [error message]”
Zero devices imported despite validation passing

Resolution:

Check application logs:

tail -f storage/logs/laravel.log

Re-run with dry-run to identify the issue:

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

Best Practices

Use interactive menus for first-time users: The guided menus provide helpful context and validation

Create mappings first: Configure all device type mappings before loading devices to avoid import failures

Ensure .cloginrc is readable: Set permissions so the web server user can read credentials:

chmod 644 /usr/local/rancid/.cloginrc

Test DNS resolution: Verify devices are resolvable from the rConfig server before starting import

Review router.db files: Check that devices are marked as “up” and device types are correct

Use dry-run mode: Always use --dry-run first to preview changes and catch errors

Import one group at a time: For initial testing, import a single RANCID group to validate the process

Review failures logs: Check the failures file to identify and fix issues

Backup rConfig database: Before importing large batches, backup your rConfig database

Verify mappings: Double-check that template, vendor, and category IDs are correct

Keep RANCID running: Run both systems in parallel initially to ensure successful migration

Post-Import Tasks

After successful import:

Verify device inventory: Navigate to Devices and confirm all devices imported correctly
Review credentials: Check that devices have appropriate credential assignments
Test connectivity: Use device debug command to verify connection to sample devices
Organize devices: Create device groups matching RANCID organization
Configure schedules: Set up automated backup schedules for device groups
Enable compliance: Apply compliance policies to imported devices
Archive RANCID data: Backup RANCID directories for historical reference

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

RANCID Import Tool

RANCID Import Tool: Automated Device Migration to rConfig V8

Why Migrate from RANCID?

How It Works

File Locations

Prerequisites

Step 1: Create Device Type Mappings

Command

Options

Create New Mapping

Common RANCID Device Types

View Existing Mappings

Edit or Delete Mappings

Step 2: Load Devices from RANCID

Command

Options

RANCID Directory Structure

RANCID Base Directory Auto-Detection

RANCID router.db File Format

Credential Extraction from .cloginrc

Default Credential Selection

What Happens During Loading

Output Files

Credential Assignment Logic

Step 3: Import Devices to rConfig

Command

Options

Interactive Import Options

Import Process Flow

Device Relationships Created

Validation Rules

Dry Run Mode

Production Import

Complete Workflow Example

Troubleshooting

RANCID directory not found

No RANCID groups found

No credential sets exist

Device type mapping not found

Invalid template/vendor/category ID

DNS resolution failures

Config file not found

.cloginrc parsing errors

Devices marked as “down” being skipped

router.db format errors

Duplicate devices

Transaction rollback on import

Best Practices

Post-Import Tasks

Related Documentation