Import devices from RANCID into rConfig V8 Core

The RANCID Import Tool migrates network devices from RANCID into rConfig V8 Core using the command line. After reading this page, you can map RANCID device types to rConfig templates, extract credentials from .cloginrc, generate an import file from router.db, and bulk import the devices with their vendors, categories, tags, and prompts.

Available in rConfig V8

The RANCID import commands ship with rConfig V8 Core. They reduce migration time by automating device type mapping, credential extraction, and bulk imports.

When to use this

Use this tool when you are moving an existing RANCID deployment to rConfig V8 Core and want to onboard devices in bulk rather than adding them by hand. It suits a one-time migration or a phased cut-over where RANCID and rConfig run in parallel while you validate connectivity. For a handful of devices, adding them through the UI is usually quicker.

Prerequisites

Before importing devices, ensure you have:

• Access to a RANCID installation with router.db files
• Read access to .cloginrc for credential extraction (optional but recommended)
• Administrator access to rConfig V8 Core
• Device templates configured in rConfig that match 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

How the import works

The import runs in three commands, each a distinct stage:

1. Create device type mappings: define how RANCID device types translate to rConfig templates, vendors, and categories.
2. Load devices from RANCID: parse router.db, extract credentials from .cloginrc, and generate an import-ready JSON file.
3. Import devices to rConfig: bulk import the devices with validated configurations.

File locations

The tool uses the following paths:

• 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 do not exist.

Step 1: Create device type mappings

Run the mappings command:

php /var/www/html/rconfig/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 the specified device type
• --delete=TYPE - Remove a device type mapping
• --info - Display command help and usage information

Create a new mapping

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

You are prompted to provide:

• RANCID device type: the device type from your RANCID router.db (for example cisco, juniper, foundry)
• rConfig device type: the internal device type name (for example 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 organising 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 the 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/rconfig/artisan rconfig:rancid-device-mappings --list

The 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/rconfig/artisan rconfig:rancid-device-mappings --edit=cisco

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

Verify IDs before mapping

Accurate mappings are critical for successful imports. Confirm that the template, vendor, and category IDs exist in rConfig before creating a mapping. Devices that reference a missing ID are sent to the failures log.

Step 2: Load devices from RANCID

Run the load command:

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

Options

• --rancid-base=/path - Specify the 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 one of two structures, both auto-detected by the tool.

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/

RANCID base directory auto-detection

If --rancid-base is not specified, the tool checks these paths in order:

1. /usr/local/rancid
2. /var/lib/rancid
3. /var/rancid
4. /opt/rancid

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

router.db file format

hostname:device_type:status

RANCID 3.0+ also supports a semicolon delimiter:

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 parses .cloginrc to extract credentials per device.

.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 works as follows:

• The tool checks .cloginrc for patterns matching each device’s hostname or IP.
• If a match is found, the credentials are embedded in the JSON (device_cred_id = 0).
• If no match is found, the device uses the default credential set you select.

Default credential selection

If devices have no credentials in .cloginrc, you are prompted to pick a default:

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

1. RANCID directory detection: locates the RANCID base directory
2. Group discovery: finds all groups with router.db files
3. Group selection: you select a specific group or all groups
4. Prerequisite checks: validates that mappings and credential sets exist
5. router.db parsing: reads device lists from each group
6. Status filtering: skips devices not marked as “up”
7. Device type validation: checks a mapping exists for each device type
8. DNS resolution: resolves hostnames to IP addresses
9. Config file verification: ensures a config file exists
10. Config analysis: extracts model and version information from config files
11. Credential extraction: parses .cloginrc for device credentials
12. JSON generation: creates a timestamped import file per group
13. Failure logging: records validation issues per group

Output files

The command generates two files per group.

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: the device uses embedded credentials from .cloginrc (username/password in the JSON).
• device_cred_id > 0: the device uses the specified credential set ID from rConfig.

Prompt placeholder substitution

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

Step 3: Import devices to rConfig

Run the import command, passing the generated JSON file:

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

Options

• --group=ID - Assign all imported devices to the specified device group (default: 1)
• --dry-run - Preview the import without modifying the database
• --info - Display command help and usage information

Interactive import options

When run without a file path, the command offers a menu:

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

1. JSON validation: verifies file structure and required fields
2. Device validation: checks each device for required fields and valid IDs
3. Transaction-based import: all valid devices are imported in a single database transaction
4. Device creation: creates device records with mapped configurations
5. Relationship linking: associates tags, vendors, categories, and templates
6. Duplicate handling: skips devices that already exist
7. Summary report: displays import statistics

Device relationships created

For each imported device, rConfig links:

• Tags: many-to-many relationship with the selected tags
• Vendor: single vendor
• Category: single category
• Template: single template

Validation rules

Required fields:

• device_name
• device_ip (must be a valid IP format)
• device_model
• template_id (must exist in the database)
• vendor_id (must exist in the database)
• device_category_id (must exist in the 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: the credential set must exist in the database.

Duplicate detection:

• No existing device with the same device_name
• No existing device with the same device_ip

Dry run mode

Test the import without making changes:

php /var/www/html/rconfig/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/rconfig/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)

Imports are transactional

All imports run inside a single database transaction. If any error occurs during the import, every change is rolled back automatically, so a failed run leaves no partial data behind.

Complete workflow example

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

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

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

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

# The command will:
# - Auto-detect the RANCID installation
# - Show available groups
# - Extract credentials from .cloginrc
# - Generate a 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/rconfig/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/rconfig/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/rconfig/artisan rconfig:rancid-import-devices
# Select: "Import from the latest available JSON file"

Troubleshooting

RANCID directory not found

Symptom: Could not find RANCID installation directory.

Specify the RANCID base directory explicitly:

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

No RANCID groups found

Symptom: No RANCID groups found in: /path/to/rancid/var.

Verify the directory structure and that 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

Symptom: No device credentials found in the system, and the import halts before processing devices.

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

Symptom: devices logged to the failures file with Unknown device type 'xyz'. No mapping found..

Create the missing mapping, then verify:

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

Invalid template, vendor, or category ID

Symptom: Template ID X does not exist or Vendor ID X not found.

Verify the IDs exist in rConfig:

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

php /var/www/html/rconfig/artisan rconfig:rancid-device-mappings --edit=cisco

DNS resolution failures

Symptom: devices logged to the failures file with Could not resolve hostname to IP address.

Verify DNS is working on the rConfig server:

nslookup router1.example.com
host router1.example.com

Then resolve by adding entries to /etc/hosts, configuring DNS servers in /etc/resolv.conf, or updating router.db to use IP addresses instead of hostnames.

Config file not found

Symptom: devices logged to the failures file with Config file not found in /path/configs.

Verify config files exist, and run RANCID to collect them if needed:

ls -la /usr/local/rancid/var/groupname/configs/
rancid-run groupname

.cloginrc parsing errors

Symptom: all devices use the default credential set despite .cloginrc existing.

Verify the file format and permissions so the web server user can read it:

ls -la /usr/local/rancid/.cloginrc
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

Symptom: many devices logged with Device status is not 'up'.

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

Symptom: devices logged with Invalid router.db format.

Verify the format and remove blank lines:

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

sed -i '/^$/d' router.db

Transaction rollback on import

Symptom: Import failed: [error message], and zero devices imported despite validation passing.

Check the application logs, then re-run with --dry-run to identify the issue:

tail -f storage/logs/laravel.log

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

Common gotchas

Avoid the usual import failures

• Create all device type mappings before loading devices. A device whose type has no mapping is sent to the failures log and skipped.
• Make .cloginrc readable by the web server user (chmod 644), or every device falls back to the default credential set.
• Always run --dry-run first to catch invalid template, vendor, or category IDs before they affect a production import.
• Duplicate devices (matching name or IP) are skipped silently, not updated. Check the summary report for the skipped count.

Post-import tasks

After a successful import:

1. Verify the device inventory: navigate to Devices and confirm all devices imported correctly.
2. Review credentials: check that devices have the appropriate credential assignments.
3. Test connectivity: use the device debug command to verify connections to sample devices.
4. Organise devices: create device groups matching your RANCID organisation.
5. Configure schedules: set up automated backup schedules for device groups.
6. Archive RANCID data: back up the RANCID directories for historical reference.

What’s next

• Manage devices in rConfig V8 Core - Review and edit the devices you just imported.
• Configure connection templates - Tune the templates and credentials used to reach each device.
• Schedule configuration backups - Automate backups for the imported device groups.