Zabbix Device Sync V2

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

The V2 Zabbix driver pulls host inventory from a Zabbix server using its JSON-RPC 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.

Platform	rConfig V8 Support	Auth supported	V2 Status
Zabbix	V8.2.0+	Username/password, or API token	Field tested

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 Zabbix 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 Zabbix 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:

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

Prerequisites

Zabbix:

A reachable Zabbix server with the JSON-RPC API enabled at /api_jsonrpc.php
An API user (or API token) with read access on host.get, hostgroup.get, apiinfo.version
Network connectivity from rConfig to the Zabbix frontend
Hosts organized into host groups, and/or tagged with rconfig::device_profile = <slug> for Device Profile resolution

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 host 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.

Placeholder — V2 driver picker (Settings → Integrations → New V2 Integration) with Zabbix highlighted

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

Placeholder — Zabbix Setup tab with Connectivity and Authentication sections expanded

Connectivity

Field	Default	Notes
Base URL	required	Root of the Zabbix frontend, e.g. `https://zabbix.example.com`. No trailing slash needed.
API Path	`/api_jsonrpc.php`	Only override for non-standard deployments.
Timeout (Seconds)	`30`	HTTP request timeout. Range 1–120.
Retries	`2`	Number of HTTP retries on transient failures. Range 0–5.
Retry Sleep (ms)	`250`	Backoff between retries. Range 0–5000.
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, Zabbix host tags become canonical tags in rConfig and are attached on Apply.

Authentication — pick an Auth Mode and provide its credentials:

API Token mode — supply an API Token generated under Administration → API tokens in Zabbix. Tried first when both are populated.
Basic mode — supply Username + Password for a user with API access. The driver calls user.login to exchange these for a session token.

1.3 Test the connection

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

Placeholder — Setup tab after a successful Test Connection (green status pill)

The driver invokes apiinfo.version against the JSON-RPC endpoint and returns the Zabbix version. Common failures:

What you see	Most likely fix
Connection refused / timeout	Wrong Base URL or firewall in between rConfig and Zabbix.
`SSL` / `certificate` error	Self-signed cert — toggle Verify TLS Peer / Hostname off (lab only).
`400`/`200` with `Login name or password is incorrect`	Basic auth mode — wrong username/password.
`200` with `Not authorized` / token errors	API token revoked or scoped to a user without API permission.

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.

You now have a functional Zabbix integration instance — but no Device Profile has been chosen yet. Do not run a preview yet. Move to Step 2.

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 an upstream record’s tag value to that slug to pick the profile.

2.1 Open the Device Profiles page

Navigate to Inventory → Device Profiles.

Placeholder — Inventory → Device Profiles list

2.2 Create a Device Profile per host class

For each host 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 Zabbix tags will reference.
Vendor, Category, Template, Credential set — standard rConfig device classification.
SNMP group, Vector agent, default tags, default model / prompt patterns — optional.

2.3 Tag hosts on the Zabbix side

The Zabbix V2 driver looks for the profile slug on each host’s tag list (zabbix.schema.php → device_profile.source_profile_paths reads tags.* and inheritedTags.*). The driver matches exactly on a tag with key rconfig::device_profile (case-insensitive); the tag’s value becomes the profile slug.

Apply this tag in Zabbix via Configuration → Hosts → <host> → Tags:

rconfig::device_profile = cisco-ios-core

Inherited tags from host templates are also honoured, so you can apply the tag once at the template level and have every linked host inherit it.

Placeholder — Zabbix host with the rconfig::device_profile tag set

If you cannot tag every host, set a default profile on the Zabbix integration instance so untagged hosts inherit a sensible fallback.

Step 3 — Run an Extract Preview

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

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

Placeholder — Zabbix Extract Preview tab with summary cards and result table

Zabbix supports filters on:

groupids — Zabbix host group IDs (operators: equals, in)
hostids — specific host IDs (operators: equals, in)
status — monitored / unmonitored
maintenance_status — not in maintenance / in maintenance

Open a row’s Details hover to see the full raw payload — confirm host, the chosen interface IP (interfaces[0].ip or interfaces[0].dns) and any rconfig::device_profile tag 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.

Placeholder — Run Insights tab populated after a Zabbix Sync Preview

For Zabbix 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 host has no interface or its rconfig::device_profile tag doesn’t match an active profile.
reconcile.ambiguous — non-zero means more than one rConfig device matches the same Zabbix host.

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:

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

Placeholder — Run Insights tab after a Full Sync, with the apply stage card populated

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:

Placeholder — Debug Console modal mid-run for the Zabbix driver

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 Zabbix instance, choose Apply mode, and set the cron schedule.

A common production pattern:

Hourly Preview — drift detection only, no writes. Surfaces new Problem Devices fast.
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=zabbix --mode=preview

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

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

See the V2 Overview for the full option list.

Driver Reference

Zabbix fields the driver reads

Canonical field	Zabbix payload paths checked, in order
External ID	`hostid`
Hostname	`host` → `name`
Primary IP	`interfaces[0].ip` → `interfaces[0].dns`
Serial	`inventory.serialno_a` → `inventory.serialno_b`
Vendor	`inventory.vendor`
Model	`inventory.model`
Tags / Profile	`tags[]` and `inheritedTags[]` — `rconfig::device_profile` value

The driver prefers interfaces with useip = '1' (use IP, not DNS) when picking the primary IP.

Reconciliation policy

Strong match — by instance_link_external_id (Zabbix hostid) or by 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 Zabbix host disappears from the upstream (or moves into maintenance), rConfig disables the integration_device_links row but leaves the device intact.

Troubleshooting

Connection works, credentials fail. For API token mode, regenerate the token under Administration → API tokens and confirm the owning user has API access. For basic mode, confirm the user can log in to the Zabbix UI.
Extract returns zero hosts. Confirm hosts are monitored (status = 0) and not in maintenance (maintenance_status = 0) — the driver filters both out. Re-check group ID filters.
Canonicalize flags candidates as invalid. Most common cause: a host without any interface (interfaces array empty) or with no rconfig::device_profile tag and no instance default profile.
Profile resolution fails. Confirm the tag key is exactly rconfig::device_profile (case-insensitive match), and the value matches an active rConfig Device Profile slug. Inherited template tags also work.
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 Sync V2 Overview
Statseeker Device Sync V2 — the model V2 setup
Extract Preview Tab
Run Insights Tab
Problem Devices Tab
Logs Tab
Debug Console
Zabbix Device Sync (Legacy V1)
Scheduled Tasks