NetBox Device Sync V2

NetBox Device Sync V2: End-to-End Setup in rConfig V8.2.0

The V2 NetBox driver pulls device inventory from a NetBox server using its REST API and feeds it through the unified V2 pipeline. This guide follows the same model as the Statseeker V2 setup — only the Setup tab fields and upstream-side conventions are different.

Marketing overview on rconfig.com

See the NetBox integration page on rconfig.com for the platform-specific overview, or browse all rConfig integrations.

Platform	rConfig V8 Support	Auth supported	V2 Status
NetBox	V8.2.0+	API token	Field tested

Field tested in customer environments

The NetBox V2 driver is field tested in live customer environments for the V8.2.0 release. The schema declares this status in netbox.schema.php → verified.status. Please report any issues to rConfig support.

Interactive demo

Mental Model: End Goal First

The point of setting up a V2 integration is to land in a steady state where rConfig’s device inventory is continuously reconciled against NetBox on a schedule, with no operator in the loop. That end state looks like this:

A Scheduled Task of type Integration V2 Job runs the NetBox instance in Apply mode on a cron, e.g. nightly. It runs the same six-stage pipeline you’ll run interactively in this guide, writes any create and update decisions to rConfig, leaves any conflicts or ambiguous matches in Problem Devices for review, and notifies you on completion.

To get there, you walk a one-time setup and a sanity-check loop:

1. Create the integration instance — NetBox connectivity and auth in the Setup tab. Validate with Test Connection.
2. Set up the Device Profiles the synced devices will inherit from. This happens under Inventory → Device Profiles, not in the integration itself.
3. Run an Extract Preview to confirm filters return the right NetBox devices.
4. Run a Sync Preview to walk the full pipeline (canonicalize → reconcile → decide) without writing.
5. Run a Full Sync (Apply) once the preview’s decisions look right.
6. Schedule the integration to run on a cron from the rConfig scheduler.

Prerequisites

NetBox:

• A reachable NetBox server (3.x or later) with the REST API enabled
• An API token for a service user with read access to /dcim/devices/ and /status/
• Network connectivity from rConfig to NetBox
• A custom field of type Text named rconfig_device_profile added to the dcim | device content type — this is the field the V2 driver reads to resolve the Device Profile slug
• Optional: tags and sites for upstream filtering

rConfig V8.2.0+:

• Administrator access
• A clear answer to: which Device Profile (vendor, category, template, credential set, optional SNMP group / Vector agent) every synced device should adopt by default

Step 1 — Create the Integration Instance (Setup Tab)

1.1 Open the V2 driver picker

Navigate to Settings → Integrations, then click New V2 Integration. The driver picker shows every V2 driver in two groups: drivers you’ve already configured and drivers you haven’t.

Each card carries the driver’s verification badge — Field tested for NetBox — plus a link to its docs page. Click the NetBox card.

1.2 Fill in the schema-driven Setup tab

The driver picker drops you straight into the instance Detail page on the Setup tab. The form is rendered from netbox.schema.php and is laid out in two sections.

Connectivity

Field	Default	Notes
Base URL	required	Root of the NetBox server, e.g. https://netbox.example.com. No trailing slash needed.
Timeout (Seconds)	30	HTTP request timeout. Range 1–120.
Verify TLS Peer	on	Leave on for production. Disable only for self-signed labs.
Verify TLS Hostname	on	Leave on for production. Disable only for hostname mismatches in labs.
Import Source Tags	off	When on, NetBox tag slugs become canonical tags in rConfig and are attached on Apply.

Authentication

• API Token (required). Generated under Admin → Users → API tokens in NetBox. Stored as a secret. The driver sends it as Authorization: Token <api_token>.

1.3 Test the connection

Click Test Connection in the action bar at the top of the page.

The driver hits the lightweight GET /status/ endpoint, then a separate credential validation call to GET /dcim/devices/?limit=1. Common failures:

What you see	Most likely fix
Connection refused / timeout	Wrong Base URL or firewall in between rConfig and NetBox.
SSL / certificate error	Self-signed cert — toggle Verify TLS Peer / Hostname off (lab only).
/status/ works but /dcim/devices/ 401/403	Token revoked, expired, or scoped to a user without dcim.view_device.
404 from /status/	Old NetBox version (pre-3.x) — upgrade NetBox or open a support ticket.

1.4 Save

Click Save. The runtime config is written to integration_instances.runtime_config and the auth material is stored via secrets_ref. The save indicator in the action bar flips to Saved once persisted.

Step 2 — Set Up Device Profiles (Inventory)

Device Profiles live outside the integration. They are the rConfig-side definition of what a synced device should look like — vendor, category, device template, credential set, optional SNMP group and Vector agent. Each profile has a slug; the V2 driver matches the upstream record’s custom_fields.rconfig_device_profile value to that slug to pick the profile.

2.1 Open the Device Profiles page

Navigate to Inventory → Device Profiles.

2.2 Create a Device Profile per device class

For each device class you want to sync, click New Device Profile and fill in:

• Name — human-readable.
• Slug — the value NetBox’s rconfig_device_profile custom field will reference.
• Vendor, Category, Template, Credential set — standard rConfig device classification.
• SNMP group, Vector agent, default tags, default model / prompt patterns — optional.

2.3 Populate the custom field on the NetBox side

The NetBox V2 driver reads the profile slug from custom_fields.rconfig_device_profile (netbox.schema.php → device_profile.source_profile_paths). Tags and sites are not used for profile resolution — the custom field is authoritative.

In NetBox:

1. Navigate to Customization → Custom Fields → + Add.
2. Object types: dcim | device.
3. Type: Text.
4. Name: rconfig_device_profile (must match exactly).
5. Save.
6. Open each device, set the rconfig_device_profile custom field to the matching rConfig Device Profile slug (e.g. cisco-ios-core).

If you cannot tag every device immediately, set a default profile on the NetBox integration instance so untagged devices inherit a sensible fallback.

Hardcoded extraction filter

The NetBox driver only extracts devices where status = active. Planned, staged, decommissioning and inventory-only devices will not appear in Extract Preview or sync runs.

Step 3 — Run an Extract Preview

Return to Settings → Integrations → V2 → NetBox and click Extract Preview in the action bar (amber download icon).

Extract Preview hits NetBox exactly the way a real sync would, but stops the moment the records come back — no canonicalize, no reconcile, no writes.

NetBox supports filters on:

• tag (operators: equals, in)
• site (operators: equals, in)
• status (operators: equals, in)

Open a row’s Details hover to see the full raw payload — confirm name, the chosen IP field (primary_ip4.address or primary_ip.address) and the custom_fields.rconfig_device_profile value used for profile resolution are all present.

For the full anatomy of this tab, see the Extract Preview Tab reference.

Step 4 — Run a Sync Preview

Click Preview Sync in the action bar (sky icon). Sync Preview runs the complete pipeline through decide and stops without writing.

Switch to the Run Insights tab to inspect the result.

For NetBox the most-watched stage metrics are:

• extract.items_extracted — should match the Extract Preview count (within filter scope).
• canonicalize.invalid — non-zero usually means a device has no primary_ip4/primary_ip set, or the rconfig_device_profile custom field is empty / doesn’t resolve.
• reconcile.ambiguous — non-zero means more than one rConfig device matches the same NetBox device.

If Open Problems is greater than zero, switch to the Problem Devices tab and triage the rows.

For the full anatomy of these tabs, see the Run Insights Tab reference and Problem Devices Tab reference.

Step 5 — Run a Full Sync (Apply)

When the Sync Preview decisions look correct and Open Problems is at an acceptable level, click Full Sync in the action bar (indigo icon).

Full Sync re-runs the full pipeline and finishes by executing the apply stage:

1. Creates new devices for each decision = create.
2. Updates existing devices for each decision = update.
3. Assigns the resolved Device Profile to each affected device.
4. Syncs canonical tags onto the device when Import Source Tags was on at Setup.
5. Updates integration_device_links (first_seen, last_seen).
6. Schedules an initial configuration backup for newly created devices.

Re-check Problem Devices after Apply — Apply does not auto-resolve ambiguous_match or conflict rows; those still need a human.

Step 6 — The Debug Console

For any of the runs above, you can swap the action-bar button for the Open Debug Console button (shimmer icon). The Debug Console runs the same Artisan command synchronously and streams its native stdout/stderr into a modal:

For the full anatomy of the dialog, see the Debug Console reference.

Step 7 — Schedule the Sync

Once a manual Full Sync completes cleanly, schedule it. Navigate to Scheduled Tasks → Add Task → Integration V2 Job, pick the NetBox instance, choose Apply mode, and set the cron schedule.

A common production pattern:

• Hourly Preview — drift detection only, no writes.
• Nightly Apply — commits real changes during the maintenance window.

CLI Reference

# Sync Preview (does not write)
php /var/www/html/rconfig8/current/artisan rconfig:integration-v2-run --driver=netbox --mode=preview

# Full Sync (Apply) by explicit instance ID, with debug output
php artisan rconfig:integration-v2-run 16 --mode=apply --debug

# Queue an async run
php artisan rconfig:integration-v2-run 16 --mode=apply --queue

Driver Reference

NetBox fields the driver reads

Canonical field	NetBox payload paths checked, in order
External ID	id
Hostname	name
Primary IP	primary_ip4.address → primary_ip.address
Serial	serial
Vendor	device_type.manufacturer.name
Model	device_type.model
Tags	tags[*].slug
Profile slug	custom_fields.rconfig_device_profile (only path)

NetBox returns full inline objects in its standard serializer, so unlike Nautobot the driver does not perform per-record hydration — runs are typically faster.

Reconciliation policy

• Strong match — by instance_link_external_id (NetBox id).
• Medium match — hostname and primary IP both unique in rConfig.
• No automatic medium-match auto-relink, no cross-family matching.

Missing upstream policy

The default mode is disable_link_only — when a previously-synced NetBox device disappears from the upstream (or transitions out of active status), rConfig disables the integration_device_links row but leaves the device intact.

Troubleshooting

• Connection works, credentials fail. /status/ is anonymous on most NetBox installs, so a successful Test Connection only confirms reachability. The credential validation call to /dcim/devices/?limit=1 is what fails — check token validity and the user’s dcim.view_device permission.
• Extract returns zero devices. Confirm devices are in status = active — staged / planned / decommissioning are filtered out by the driver. Re-check tag / site filters and the API user’s object permissions.
• Canonicalize flags candidates as invalid. Most common: primary_ip4 not assigned, or custom_fields.rconfig_device_profile empty / pointing at a Device Profile that doesn’t exist.
• Profile resolution fails. Confirm the custom field is named exactly rconfig_device_profile (lowercase, underscore), is attached to the dcim | device content type, and its value matches an active rConfig Device Profile slug.
• Reconciliation produces ambiguous matches. Two rConfig devices share the same hostname or primary IP. Resolve in Problem Devices by picking the correct target, or de-duplicate the device list.

Related Documentation

• Device Sync V2 Overview
• Statseeker Device Sync V2 — the model V2 setup
• Extract Preview Tab
• Run Insights Tab
• Problem Devices Tab
• Logs Tab
• Debug Console
• Nautobot Device Sync V2
• Scheduled Tasks