Device Sync integrationNautobot

Field tested

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

The V2 Nautobot driver pulls device inventory from a Nautobot 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 Nautobot integration page on rconfig.com for the platform-specific overview, or browse all rConfig integrations.

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

Field tested in customer environments

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

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 Nautobot 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 Nautobot 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: Nautobot 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 Nautobot 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.

%%{init: {'themeVariables': {'fontSize': '60px'}}}%%
flowchart LR
    A[Create instance<br/>Setup tab] --> B[Test Connection]
    B --> C[Device Profiles<br/>Inventory]
    C --> D[Extract Preview]
    D --> E[Sync Preview]
    E --> F[Full Sync · Apply]
    F --> G[Scheduled Task<br/>recurring sync]

  classDef step font-size:60px,stroke-width:2px;
  class A,B,C,D,E,F,G step;

Prerequisites

Nautobot:

• A reachable Nautobot server with the REST API enabled
• An API token for a service user with read access to /dcim/devices/, /extras/tags/ and /ipam/ip-addresses/
• Network connectivity from rConfig to Nautobot
• 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 Platform → Integrations. Scroll to the Device Sync section and click + Add Driver under V2 Drivers. The picker shows every V2 driver split into Configured Drivers and Not Configured Yet.

V2 driver picker. Shown with Zabbix highlighted. Pick Nautobot from the same list.

Each card carries the driver’s verification badge (Field tested for Nautobot), plus a link to its docs page. Click the Nautobot 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 nautobot.schema.php and is laid out in two sections.

Connectivity

Field	Default	Notes
Base URL	required	Root of the Nautobot server, e.g. https://nautobot.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, Nautobot tag slugs become canonical tags in rConfig and are attached on Apply.
Prefer NAT (Outside) IPv4	off	When on, devices are managed on their primary IPv4’s NAT (outside) address if Nautobot has one. See Devices behind NAT.

Authentication

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

Devices behind NAT

From V8.4.1, the Nautobot driver can manage a device on its NAT address instead of its primary IPv4. Use this when the primary IPv4 in Nautobot is a remote-site address rConfig can’t reach, but the same IP has a NAT (outside) address that is reachable from your network.

Turn on Prefer NAT (Outside) IPv4 and save. On each run the driver fetches the primary IPv4’s record from /ipam/ip-addresses/{id}/, reads its NAT (outside) addresses (nat_outside_list), and uses that IPv4 as the device IP in rConfig. If there are several, the lowest one is used so the choice doesn’t change between runs. Devices with no NAT (outside) address keep their primary IPv4, and so does any device whose lookup fails.

In Nautobot, set the NAT relationship on the outside address: edit the reachable IP and set its NAT (Inside) field to the device’s primary IPv4.

rConfig doesn’t test which address is reachable. It uses the NAT address whenever Nautobot has one. Because the setting is part of the integration, every sync applies it again, so a re-sync never puts the primary IPv4 back.

Caution

Devices that are already synced switch to their NAT address on the next Apply. Run Sync Preview after turning the setting on and check the IP changes before you apply them.

1.3 Test the connection

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

Setup tab after a successful Test Connection (green status pill). Shown with the Zabbix driver. The Nautobot screen is the same.

The driver hits 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 Nautobot.
SSL / certificate error	Self-signed cert: toggle Verify TLS Peer / Hostname off (lab only).
401 / 403	Token revoked, expired, or scoped to a user without dcim.view_device permission.
404	API not reachable at the expected path: check Nautobot reverse proxy / sub-path config.

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 (e.g. Cisco IOS Core Routers, Arista Edge Switches), click New Device Profile and fill in:

• Name: human-readable.
• Slug: the value Nautobot’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 Nautobot side

The Nautobot V2 driver reads the profile slug only from custom_fields.rconfig_device_profile (nautobot.schema.php → device_profile.source_profile_paths). Tags and groups are not used for profile resolution in this driver: the custom field is authoritative.

In Nautobot:

1. Navigate to Extensibility → Custom Fields → + Add.
2. Content 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 Nautobot integration instance so untagged devices inherit a sensible fallback.

Step 3: Run an Extract Preview

Switch to the Extract Preview tab (amber download icon in the action bar).

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

Extract Preview tab with summary cards and result table. Shown with the Zabbix driver. The Nautobot screen is the same.

Nautobot supports filters on:

• tag (operators: equals, in, contains_all, contains_any)
• 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.

On-the-fly hydration

The Nautobot driver hydrates tag and IP-address references when the upstream returns IDs instead of inline objects (calls to /extras/tags/{id}/ and /ipam/ip-addresses/{id}/). Hydration adds extra round-trips for large inventories: give the run a little more wall-clock budget than you would for NetBox.

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.

Run Insights tab populated after a Sync Preview. Shown with the Zabbix driver. The Nautobot screen is the same.

For Nautobot 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 Nautobot 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.

Run Insights tab after a Full Sync, with the apply stage card populated. Shown with the Zabbix driver. The Nautobot screen is the same.

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:

Debug Console modal mid-run. Shown with the Zabbix driver. The Nautobot screen is the same.

Debug Console modal after a run completes. Shown with the Zabbix driver. The Nautobot screen is the same.

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 Tasks and click New Task. Choose task type Integration V2 Job, pick the Nautobot 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=nautobot --mode=preview

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

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

Driver Reference

Nautobot fields the driver reads

Canonical field	Nautobot payload paths checked, in order
External ID	id
Hostname	name
Primary IP	NAT (outside) IPv4, only with Prefer NAT (Outside) IPv4 on → 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 (declared schema path)

If the upstream returns tag IDs instead of objects, the driver fetches each tag via /extras/tags/{id}/. Same for IP addresses via /ipam/ip-addresses/{id}/.

Fallback profile resolution paths

If the rconfig_device_profile custom field is empty, the driver also checks a cf_rconfig_device_profile field and a rconfig::device_profile::<slug> tag as fallbacks before giving up. The custom field is still the primary, documented mechanism above; treat the fallbacks as a safety net, not the intended workflow.

Reconciliation policy

• Strong match: by instance_link_external_id (Nautobot id) or an exact global serial match.
• 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 Nautobot device disappears from the upstream, rConfig disables the integration_device_links row but leaves the device intact.

Troubleshooting

Common gotchas

• The rconfig_device_profile custom field must be attached to the dcim | device content type and named exactly right (lowercase, underscore) or profile resolution silently fails.
• API tokens scoped to a single object permission group can pass the connection test but fail when the driver reads tags or IP addresses; grant broad read access.
• A device with no primary_ip4/primary_ip assigned is flagged invalid at canonicalize and will not sync.
• Full Sync does not auto-resolve ambiguous or conflicting matches; always check Problem Devices after Apply.

• Connection works, credentials fail. Confirm the API token is active in Nautobot and the owning user has dcim.view_device permission. Tokens scoped to a single object permission group can pass /dcim/devices/?limit=1 but fail when reading tags or IPs: give the user broad read access.
• Extract returns zero devices. Re-check tag / site / status filters and the API user’s object permissions. Nautobot will silently filter records the user cannot see.
• Canonicalize flags candidates as invalid. Most common: primary_ip4 not assigned on the device, 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.
• Device imported with an IP rConfig can’t reach. If the primary IPv4 is a remote-site address and Nautobot records a reachable NAT address for it, turn on Prefer NAT (Outside) IPv4. If the device still gets the primary IP, check that the NAT address’s NAT (Inside) field points at the primary IPv4 and that the API token can read IP addresses.
• Slow runs. Hydration of tag and IP IDs is the usual cause. Ensure your Nautobot API serializer is returning inline objects where possible, or accept the extra wall-clock for large inventories.

Related Documentation

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