Checkmk Device Sync V2

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

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

Platform	rConfig V8 Support	Auth supported	V2 Status
Checkmk	V8.2.0+	Automation user + automation secret	Field tested

Field tested in customer environments

The Checkmk V2 driver is field tested in live customer environments for the V8.2.0 release. The schema declares this status in checkmk.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 Checkmk 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 Checkmk 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 — Checkmk 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 Checkmk hosts.
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

Checkmk:

• A reachable Checkmk site with the REST API enabled at /<site>/check_mk/api/1.0/
• An automation user with read access to host configurations. Automation users are created in Setup → Users and have an automation secret instead of a password
• Network connectivity from rConfig to the Checkmk site
• Hosts placed into folders / sites you want to scope to (optional), and labelled 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 Checkmk card carries a Field tested badge — click it to open the Setup tab.

1.2 Fill in the schema-driven Setup tab

The form is rendered from checkmk.schema.php and is laid out in two sections.

Connectivity

Field	Default	Notes
Base URL	required	Root of the Checkmk site, e.g. https://checkmk.example.com. The site name is part of the API path.
API Path Prefix	/check_mk/api/1.0	Override only if your Checkmk site exposes the API on a non-standard prefix.
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, non-control tags / labels extracted from Checkmk are created in rConfig and attached on Apply.

Authentication

• Username — the Checkmk automation user name (e.g. automation).
• Automation Secret — the secret paired with the automation user, taken from Setup → Users → <automation user>. Stored as a secret.

The driver sends both as Authorization: Bearer <username> <automation_secret> per the Checkmk REST API contract.

1.3 Test the connection

Click Test Connection in the action bar. The driver hits the GET /version endpoint, which returns the Checkmk site’s version metadata.

Common failures:

What you see	Most likely fix
Connection refused / timeout	Wrong Base URL (missing site name, wrong port) or firewall in between rConfig and Checkmk.
SSL / certificate error	Self-signed cert — toggle Verify TLS Peer / Hostname off (lab only).
401 / 403 from /version	Automation user disabled, automation secret regenerated, or the user lacks REST API access.
404 from /version	Wrong API Path Prefix — the site may use a non-standard mount point.

1.4 Save

Click Save. Move to Step 2 before running a preview.

Step 2 — Set Up Device Profiles (Inventory)

Device Profiles live outside the integration. The Checkmk V2 driver matches the upstream record’s extensions.attributes.labels.rconfig value to the Device Profile slug.

2.1 Open the Device Profiles page

Navigate to Inventory → Device Profiles.

2.2 Create a Device Profile per host class

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

• Name — human-readable.
• Slug — the value Checkmk’s rconfig label will reference (with the device_profile-- prefix).
• Vendor, Category, Template, Credential set — standard rConfig device classification.
• SNMP group, Vector agent, default tags, default model / prompt patterns — optional.

2.3 Label hosts on the Checkmk side

The Checkmk V2 driver looks for a host label with key rconfig whose value carries the device_profile--<slug> prefix. Open Setup → Hosts → <host> → Properties, expand Custom attributes / Labels and add:

rconfig : device_profile--cisco-ios-core

The driver strips the device_profile-- prefix and uses cisco-ios-core as the rConfig Device Profile slug.

If you cannot label every host, set a default profile on the Checkmk integration instance so unlabelled hosts inherit a sensible fallback.

Profile mode is required by default

The Checkmk schema declares device_profile.default_mode = required. If a host has no rconfig label and the instance has no default profile, the candidate will land in Problem Devices as profile_unresolved. Set a default profile on the instance up-front to avoid this.

Step 3 — Run an Extract Preview

Click Extract Preview in the action bar (amber download icon).

Checkmk supports filters on:

• folder (operator: equals) — Checkmk folder path, e.g. /main/datacenter-1.
• site (operator: equals) — Checkmk site name when running in distributed monitoring.

Open a row’s Details hover to see the full raw payload — confirm extensions.attributes.host_name, the chosen IP field (extensions.attributes.ipaddress or extensions.attributes.ipv4address) and the rconfig label 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 Checkmk 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 ipaddress/ipv4address set, or the rconfig label is missing / doesn’t resolve.
• reconcile.ambiguous — non-zero means more than one rConfig device matches the same Checkmk 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:

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.

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

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

Step 7 — Schedule the Sync

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

CLI Reference

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

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

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

Driver Reference

Checkmk fields the driver reads

Canonical field	Checkmk payload paths checked, in order
External ID	id → extensions.attributes.host_name
Hostname	extensions.attributes.host_name → id → title
Primary IP	extensions.attributes.ipaddress → extensions.attributes.ipv4address
Serial	extensions.attributes.serial
Vendor	extensions.attributes.vendor
Model	extensions.attributes.model
Tags	extensions.attributes.tags → extensions.attributes.labels
Profile slug	extensions.attributes.labels.rconfig (value with device_profile-- prefix stripped)

Reconciliation policy

• Strong match — by instance_link_external_id (Checkmk host id) 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 Checkmk host disappears from the upstream, rConfig disables the integration_device_links row but leaves the device intact.

Troubleshooting

• Connection works, credentials fail. Confirm the user is the automation user (not a regular Checkmk user) and that the automation secret in rConfig matches the current value in Checkmk. Regenerating the secret in Checkmk invalidates rConfig’s stored copy.
• Extract returns zero hosts. Re-check the folder / site filter and confirm the automation user has read access to the target folder (Checkmk per-folder permissions can hide hosts from the API).
• Canonicalize flags candidates as invalid. Most common: a host with no IP attribute populated, or an rconfig label missing the required device_profile-- prefix.
• Profile resolution fails. Confirm the host label key is exactly rconfig and the value starts with device_profile--<slug>. The schema requires the prefix — bare slugs are not parsed.
• 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
• Infrahub Device Sync V2
• Scheduled Tasks