NetBox Device Sync

NetBox Device Sync: Network Infrastructure Resource Synchronization with rConfig V8

NetBox Device Sync enables automated synchronization of network device inventory from NetBox infrastructure resource modeling platform into rConfig V8. This integration extracts device information from NetBox, transforms it using tag-based mappings, and imports devices through a staging process for administrator review before production deployment.

Platform	rConfig V8 Support	Platform Version Tested
NetBox	✓ Verified	3.5+, 4.0.8+

How It Works

The NetBox Device Sync follows an ETL (Extract, Transform, Load) pattern with a review stage:

1. Extract: Connect to NetBox API and retrieve device inventory based on configured tags
2. Transform & Map: Parse NetBox device data and apply rConfig-specific tag mappings
3. Load to Staging: Import transformed devices into staging table for review
4. Review & Approve: Administrator validates staged devices and resolves any issues
5. Deploy: Import approved devices into main rConfig device inventory
6. Schedule: Automated sync jobs keep inventory synchronized with NetBox

This idempotent process prevents duplicate device creation and maintains consistency across synchronizations. Staging tables are cleared after successful deployment to production.

Prerequisites

Before configuring NetBox Device Sync, ensure you have:

NetBox requirements:

• NetBox 3.5 or later (4.0.8+ recommended)
• Administrator access to NetBox
• API token with read permissions for devices, tags, and related objects
• Devices tagged for filtering and mapping
• Network connectivity between NetBox and rConfig servers

rConfig requirements:

• rConfig V8 Professional
• Administrator access to rConfig
• Credential sets configured for device authentication
• Device templates, vendors, categories, and tags created

NetBox device tagging:

All devices to be synchronized must have the following rConfig-specific tags applied in NetBox:

Tag Name	Required	Description	Example
rconfig::template::{id}	Yes	Device template ID	rconfig::template::1
rconfig::credentialset::{id}	Yes	Credential set ID	rconfig::credentialset::5
rconfig::vendor::{id}	Yes	Vendor ID	rconfig::vendor::2
rconfig::category::{id}	Yes	Category ID	rconfig::category::3
rconfig::tag::{id}	No	Tag ID (comma-separated for multiple)	rconfig::tag::7,8,9
rconfig::model::{string}	No	Device model string	rconfig::model::Catalyst 9300
rconfig::prompt::{string}	No	Command prompt regex	rconfig::prompt::[>#]
rconfig::enable_prompt::{string}	No	Enable prompt regex	rconfig::enable_prompt::[>#]

Note

NetBox tags require explicit IDs (not names) for templates, credential sets, vendors, and categories. Ensure you use the correct ID numbers from rConfig.

Configure NetBox

Step 1: Create API Token

Create a NetBox API token with read permissions:

1. Navigate to Admin > API Tokens in NetBox
2. Click Add to create new token
3. Configure token settings:
   • User: Select your user account
   • Allowed IPs: Leave blank for any IP, or restrict to rConfig server IP
   • Write enabled: Leave unchecked (read-only access sufficient)
   • Description: rConfig Device Sync
4. Click Create
5. Copy the token immediately (you won’t be able to view it again)

Step 2: Tag Devices for Sync

Apply rConfig-specific tags to NetBox devices:

1. Navigate to Devices > Devices
2. Select a device to edit
3. Scroll to Tags section
4. Add required rConfig tags with IDs:

Example tagging:

rconfig::template::1
rconfig::credentialset::5
rconfig::vendor::2
rconfig::category::3
rconfig::tag::7,10,15
rconfig::model::Catalyst 9300
rconfig::prompt::[>#]
rconfig::enable_prompt::[>#]

5. Save the device
6. Repeat for all devices to be synchronized

Tip

Use NetBox bulk edit feature to apply tags to multiple devices simultaneously. Create custom fields or config contexts for easier rConfig tag management.

Step 3: Create Filter Tags (Optional)

Create NetBox tags to filter which devices to sync:

1. Navigate to Organization > Tags
2. Create tags such as:
   • sync-to-rconfig
   • production-network
   • managed-devices
3. Apply filter tags to devices you want to sync

Configure rConfig V8

Step 1: Access Integration Settings

Navigate to Settings > Integrations in rConfig and click Configure on the NetBox integration.

Step 2: Configure Connection Settings

Complete the NetBox integration form:

Integration Name:

• Descriptive name for this integration (e.g., “Production NetBox”)

NetBox Base URL:

• Full URL to NetBox server (e.g., https://netbox.example.com)

NetBox API Token:

• API token created in NetBox with read permissions

SSL Verification:

• SSL Verify Host: Uncheck if using self-signed certificates

Caution

Only disable SSL verification for internal networks with self-signed certificates. Always use proper SSL certificates in production environments.

Step 3: Configure Tag Filters

Select which NetBox devices to synchronize using tags:

Tag Filter Configuration:

• Enter tag name in the input field
• Click Add tag to include in filter
• Add multiple tags as needed

Example filter tags:

• sync-to-rconfig
• production-network
• managed-devices

Caution

NetBox API applies multiple tags using AND condition. Devices must have ALL specified filter tags to be extracted. If you want to extract devices with ANY of the tags, run the sync process multiple times with different tag configurations.

Step 4: Save and Test Connection

Click Save to store the configuration.

Test Connection:

1. Click Test Connection button
2. Verify successful connection to NetBox API
3. Review connection status message

Test Credentials:

1. Click Test Credentials button
2. Successful test confirms API token is valid
3. Verify API permissions are correct

Extract Devices from NetBox

Step 1: Access Extract Tab

Click Next on the configuration screen or navigate to the Extract List tab.

Step 2: Run Extraction

Click Run extract from NetBox to retrieve devices.

The extraction process:

1. Connects to NetBox API
2. Retrieves devices based on configured tag filters
3. Extracts device properties and tags
4. Displays results in extract list table

Step 3: Review Extracted Devices

Review the extracted device list:

• View in NetBox: Opens device directly in NetBox interface
• Delete: Remove device from extract list (will re-import on next automated run)
• Expand row: View detailed device information from NetBox

Transform and Map Devices

Step 1: Run Transformation

Click Run Transform & Mapping to process extracted devices.

The transformation process:

1. Parses rConfig-specific tags from NetBox devices
2. Extracts IDs from tag values (e.g., rconfig::template::1 → template ID 1)
3. Maps tag values to rConfig templates, vendors, categories
4. Validates required tags are present
5. Checks that referenced rConfig resources exist
6. Flags any devices with validation errors

Step 2: Review Transformation Results

After transformation, the extract list updates:

• Expandable rows: Show mapped rConfig properties for each device
• Status indicators: Show whether device is ready for import
• Validation messages: Display any errors preventing import

Common validation errors:

• Missing required tags
• Invalid template, vendor, or category IDs
• Credential set not found
• Tag ID format incorrect (missing :: delimiter or ID number)
• Duplicate hostnames

Step 3: Check Logs

Click Status & Logs tab to view detailed transformation logs:

• Successful transformations
• Validation errors with device names
• Tag parsing issues
• Resource not found errors

Load to Staging Table

Step 1: Load Devices

Click Load to Device Staging Table to import transformed devices.

The loading process:

1. Validates all devices in extract list
2. Imports valid devices to staging table
3. Skips devices with validation errors
4. Maintains staging table for review

Step 2: Review Staged Devices

The staging table displays:

• All devices ready for import
• Expandable rows showing complete rConfig property mappings
• Final validation status
• Device details as they will appear in rConfig

Staging table actions:

• Run assessment: Execute full ETL process up to staging (no deployment)
• Run full deployment: Complete ETL process and import to production devices
• Manual review: Examine individual devices before deployment

Deploy to Production

Option 1: Manual Deployment

Review staged devices and click Run full deployment when ready.

The deployment process:

1. Validates staged devices one final time
2. Creates devices in main rConfig device inventory
3. Links devices to templates, vendors, categories, tags
4. Assigns credential sets
5. Schedules immediate configuration backups
6. Clears staging table
7. Logs deployment results

Option 2: Automated Assessment

Click Run assessment to test the full process without deploying:

• Executes extract, transform, and load to staging
• Does not deploy to production devices
• Useful for validating configuration before automated runs
• Staging table remains populated for review

Verify Imported Devices

View Devices in rConfig

Navigate to Devices to view newly imported devices.

Integration indicator: Imported devices display an integration icon next to the hostname, showing the device source.

Device details: Click a device to view full details. Integration-sourced devices include:

• View in NetBox button linking to NetBox device
• Integration device ID stored for API reference
• Source integration name in device metadata

Schedule Automated Sync

Step 1: Create Scheduled Task

Navigate to Scheduled Tasks and click Add Task.

Step 2: Configure Task

Task Type: Select Integration Job from dropdown

Task Name: Descriptive name (e.g., “Daily NetBox Sync”)

Task Description: Optional description of sync purpose

Step 3: Select Integration

Choose the NetBox integration configured in previous steps.

Step 4: Set Schedule

Configure sync frequency:

• Daily: Run at specific time each day
• Weekly: Run on specific day and time
• Monthly: Run on specific date and time
• Cron expression: Custom schedule using cron syntax

Example schedules:

• Daily at 2:00 AM: 0 2 * * *
• Every 6 hours: 0 */6 * * *
• Monday through Friday at 1:00 AM: 0 1 * * 1-5

Step 5: Review and Save

Review task settings and click Save.

The scheduled task will:

• Run full ETL process automatically
• Extract devices from NetBox
• Transform and map using configured tags
• Load to staging table
• Deploy valid devices to production
• Log all activities

CLI Commands

Main Integration Command

php /var/www/html/rconfig8/current/artisan rconfig:integration-netbox

Running without options displays available commands:

Available options:

Option	Shortcut	Description
--connection	-c	Test connection to NetBox API
--usertest	-u	Test API token credentials
--extract	-e	Extract devices from NetBox
--transform	-t	Transform and map devices
--mapping	-m	Run mapping process
--load	-l	Load devices to staging table
--assessment	-a	Run full process without deployment
--deployment	-d	Run full process and deploy to production

Example command sequences:

# Test connection
php artisan rconfig:integration-netbox --connection

# Full assessment (no deployment)
php artisan rconfig:integration-netbox --assessment

# Production deployment
php artisan rconfig:integration-netbox --deployment

Single Device Sync Command

Synchronize an individual NetBox device through the complete ETL workflow with verbose debugging output:

php /var/www/html/rconfig8/current/artisan rconfig:integration-netbox-single-device {device_id} [options]

Parameters:

• {device_id}: NetBox device ID to synchronize (required)

Options:

• -d, --deployment: Deploy device to production after staging
• -a, --assessment: Run assessment only (load to staging without deployment)
• -v, --verbose: Display verbose output

Use cases:

Troubleshoot individual device:

# Process single device with verbose output
php artisan rconfig:integration-netbox-single-device 59919 -v

Test device mapping:

# Extract, transform, and stage single device
php artisan rconfig:integration-netbox-single-device 59919 --assessment

Quick device import:

# Import single device directly to production
php artisan rconfig:integration-netbox-single-device 59919 --deployment

Workflow:

1. Extracts specified NetBox device using device ID
2. Transforms device data using rConfig tag mappings
3. Validates required tags and referenced resources
4. Loads to staging table for review
5. Deploys to production (if -d flag used)
6. Outputs detailed process information and any errors

Tip

Use single device sync to test tag mappings and troubleshoot transformation issues before running bulk synchronization operations. NetBox device IDs can be found in the device URL or API response.

Example output:

$ php artisan rconfig:integration-netbox-single-device 59919 -d

Processing NetBox Device ID: 59919
✓ Extracting device from NetBox
✓ Device found: core-router-01.example.com
✓ Transforming device data
✓ Parsing tags: template::1, vendor::2, category::3
✓ Validating required tags
✓ Loading to staging table
✓ Deploying to production devices
✓ Device created: core-router-01.example.com
✓ Scheduling initial configuration backup

Single device sync completed successfully.

Troubleshooting

Connection test fails

Check NetBox URL: Verify base URL is correct and accessible from rConfig server

Verify SSL settings: Disable SSL verification for self-signed certificates

Test network connectivity: Ensure firewall allows traffic between rConfig and NetBox

Check NetBox API status: Verify NetBox API is enabled and responding

Credential test fails

Verify API token: Confirm token was copied correctly without extra spaces

Check token permissions: Ensure token has read access to devices and tags

Review token status: Confirm token is not expired or revoked in NetBox

Test token manually: Use curl to test API access with the token

No devices extracted

Verify tag filters: Check that filter tags match NetBox device tags exactly

Review AND condition: Remember multiple tags use AND logic—devices need ALL filter tags

Check device status: Confirm devices are active in NetBox

Validate tag syntax: Verify tag names are spelled correctly (case-sensitive)

Transformation errors

Missing required tags: Add all required rConfig tags to NetBox devices

Invalid ID format: Ensure tags use correct format with :: delimiters (e.g., rconfig::template::1)

Wrong ID numbers: Verify template, vendor, category IDs exist in rConfig

Tag parsing issues: Check for extra spaces or special characters in tag values

Devices fail to deploy

Duplicate hostnames: Check for existing devices with same hostname in rConfig

Invalid IDs: Verify all ID numbers in tags correspond to existing rConfig resources

Credential set errors: Confirm credential set ID exists and is accessible

Database constraints: Review Laravel logs for database errors

Single device sync fails

Invalid device ID: Verify ID exists in NetBox and is a valid integer

Device not accessible: Ensure API token can access the specific device

Missing tags: Check device has all required rConfig tags in NetBox

Use verbose flag: Run with -v option to see detailed error information

Tag filter issues

Too restrictive: Multiple filter tags use AND logic, making extraction too narrow

No matching devices: Verify at least some devices have ALL specified filter tags

Case sensitivity: Ensure filter tag names match NetBox tags exactly

Solution: Run multiple sync processes with different single-tag filters if OR logic needed

Scheduled sync not running

Verify task enabled: Check scheduled task is active

Review cron schedule: Ensure cron expression is valid

Check task logs: View scheduled task execution history

Verify queue workers: Ensure Horizon/queue workers are running

Best Practices

Use ID-based tagging: Always use numeric IDs in NetBox tags for templates, credentials, vendors, and categories.

Document ID mappings: Maintain a reference document mapping rConfig IDs to resource names for easy tagging.

Start with test group: Create a small set of test devices in NetBox with proper tags before full-scale sync.

Single filter tags: Use one filter tag per sync configuration to avoid overly restrictive AND conditions.

Test single devices: Use single device sync command to validate mappings before bulk operations.

Leverage custom fields: Consider using NetBox custom fields to store rConfig IDs for easier management.

Consistent tag format: Establish and enforce tag naming standards across NetBox inventory.

Regular monitoring: Check sync logs regularly for errors or validation issues.

Staged review: Use assessment mode to preview imports before deploying to production.

Schedule wisely: Run automated syncs during low-activity periods to minimize impact.

Backup before bulk imports: Create rConfig backup before first large-scale deployment.

Related Documentation

• Device Sync Overview - Understanding device synchronization concepts
• Zabbix Sync Setup - Configure Zabbix integration
• Nautobot Sync Setup - Configure Nautobot integration
• Device Management - Managing devices in rConfig
• Scheduled Tasks - Automating sync operations