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.

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, auth and (optionally) host filters 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.

%%{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

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
• Every host you want to sync carries the host label rconfig: device_profile--<slug>, where <slug> is an rConfig Device Profile slug. It must be a label, not a host tag or custom attribute.
• Optional: hosts organised into folders, or labelled / tagged, so you can limit the sync with filters

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 Platform → Integrations. Scroll to the Device Sync section and click + Add Driver under V2 Drivers.

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.

1.5 Limit which hosts are imported (Filters)

By default every host the automation user can see is imported. The Filters card at the bottom of the Setup tab narrows that down. It has three filter groups, and each one is optional.

Filter group	What you enter	A host matches when
Folders	Folder paths, e.g. /testlab-infra-systeme/nw-devices. Use / for Main.	It is in any listed folder. With Include subfolders on (default), child folders count too.
Labels	key:value pairs, e.g. env:prod, or a bare key to match any value.	It has any (or all, your choice) of the listed labels.
Host attributes & tags	key:value pairs from the host’s attributes, e.g. tag_test:ja, or a bare key.	It has any (or all) of the listed attributes.

Type a value and press Enter or comma to add it as a pill. When a group holds two or more values, buttons appear to choose Any of these or All of these.

When two or more groups have values, Combine filter groups decides how they work together:

• AND, must match every group: the host must pass every group you filled in.
• OR, can match any group: the host only needs to pass one of them.

The Result line under the card spells out the rule in plain English, for example:

Result: Import hosts that are in folder /testlab-infra-systeme (including subfolders) AND have the label env:prod.

Things to know:

• Find the values in the host’s raw data. Run an Extract Preview and open a row’s Details. Folders come from extensions.folder, labels from extensions.attributes.labels and host attributes from extensions.attributes.
• Host tags are attributes. Checkmk stores a host tag as tag_<group>: <tag id>, so filter on tag_agent:cmk-agent or tag_criticality:prod in Host attributes & tags.
• Only values set on the host itself are checked. Labels and tags inherited from a folder, tag defaults, and labels found by service discovery are not part of the host’s configuration data, so they never match.
• Matching ignores case. env:Prod matches env:prod. Folder paths ignore case and trailing slashes.
• Filtering happens in rConfig. The Checkmk host API cannot filter by folder, label or attribute, so rConfig fetches the host list and drops non-matching hosts before canonicalize. Hosts that are filtered out are counted in the run metric extract.client_filtered_out.

Click Save after changing filters. They apply to Extract Preview, Sync Preview, Full Sync and scheduled runs.

Step 2: Set Up Device Profiles (Inventory)

Device Profiles live outside the integration. The Checkmk V2 driver reads the host label rconfig (extensions.attributes.labels.rconfig in the raw payload), strips the device_profile-- prefix, and looks up a Device Profile with exactly that slug.

Only the label is read. A host tag, a custom host attribute, or an rconfig::device_profile:: tag does not set the profile on Checkmk hosts.

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. Not used for matching.
• Slug: the identifier the Checkmk label points at. Enter it without the device_profile-- prefix, e.g. cisco-ios-core. The slug cannot be changed after the profile is created.
• Vendor, Category, Template, Credential set: standard rConfig device classification.
• SNMP group, Vector agent, default tags, default model / prompt patterns: optional.

In the Device Profiles list the slug is the smaller grey line under the profile name. That is the value to use, not the name:

Device Profiles list shows	Checkmk label value
Cisco Core / cisco-ios-core	device_profile--cisco-ios-core
test2 / test	device_profile--test

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, find the Labels field 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. Activate the change in Checkmk, then confirm the label is in the host’s raw data. The Extract Preview Details for a correctly labelled host looks like this:

{
  "id": "testlab-switch-1",
  "extensions": {
    "folder": "/testlab-infra-systeme/nw-devices",
    "attributes": {
      "ipaddress": "10.28.253.5",
      "tag_test": "ja",
      "labels": {
        "rconfig": "device_profile--test"
      }
    }
  }
}

Set the label on the host, not on its folder. Labels inherited from a folder do not appear under extensions.attributes.labels, so the driver cannot see them.

A resolvable profile is required

The Checkmk schema declares device_profile.default_mode = required, and there is no instance-level fallback profile. A host with no rconfig label lands in Problem Devices under missing_required_tag (REJECTED_MISSING_REQUIRED_DEVICE_PROFILE_TAG). A label pointing at a slug that does not exist, or at an inactive or incomplete profile, lands under device_profile_unusable (REJECTED_DEVICE_PROFILE_UNUSABLE). Use filters to leave out hosts you do not want to label.

Step 3: Run an Extract Preview

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

Extract Preview applies the Setup tab filters, so the row count is the number of hosts that passed them.

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).
• extract.client_filtered_out: hosts Checkmk returned that your folder, label or attribute filters dropped.
• 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 Tasks and click New Task. Choose task type 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.labels (keys and values, excluding the rconfig label)
Profile slug	extensions.attributes.labels.rconfig only (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

Common gotchas

• Profile resolution requires the exact device_profile-- prefix on the rconfig label; a bare slug is not parsed.
• Regenerating the automation secret in Checkmk invalidates rConfig’s stored copy; update it on the integration instance immediately.
• Checkmk per-folder permissions can hide hosts from the API entirely, which looks identical to an empty extract from a filter mismatch.
• A host with no rconfig label lands in Problem Devices under missing_required_tag rather than syncing with a fallback.

• 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. Read the Result line in the Setup tab Filters card. An AND across groups, or All of these inside a group, is easy to over-tighten. Also 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.
• Device Profile slug [test] was not found. The label was read correctly, but no profile has that slug at the time of the run. Check, in order:
  1. Slug, not name. Open Inventory → Device Profiles and compare the grey slug line under the profile name with the text after device_profile--. The message suggests the right slug when a profile’s name or a differently-cased slug matches.
  2. Run again after fixing. Problem Devices shows the latest run. If you created the profile or fixed the label after that run, the rows stay until you run Sync Preview or Full Sync again.
  3. Label on the host. A label set on the folder, or typed as a host tag or custom attribute, is not read.
• 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