Checkmk Connector

Overview

This connector integrates with Checkmk to retrieve hosts and hardware/software inventory data
for synchronizing Configuration Items into the Xurrent CMDB.

Prerequisites

To use this connector, you need:

• A Checkmk 2.4+ server with the REST API enabled
• A Checkmk user with read access to hosts and HW/SW inventory
• Site access for every site whose hosts you plan to sync

Authentication

Uses your Username and Password to authenticate. Additionally, provide
your Domain (e.g. myserver.example.com) and Site name (e.g. mysite)
to locate your Checkmk instance.

Triggers

None — this connector is outbound only.

Actions

Get hosts

Retrieves hosts from Checkmk with optional filters for hostnames, site, field selection,
effective attributes, and links. Returns each host with its folder, attributes, and optional
members metadata.

Use case: Fetch the host inventory before retrieving detailed HW/SW inventory, or refresh
host metadata for CMDB tagging and grouping.

Input Parameters

Example Input

{
"effective_attributes": false,
"include_links": false,
"fields": "(value(id,title,extensions))",
"hostnames": ["web-server-01"],
"site": "mysite"
}

Output

Host fields

Host extensions fields

Host attributes fields

Example Output

{
"domain_type": "host_config",
"id": "host_config",
"title": "All hosts",
"extensions": {},
"hosts": [
  {
    "id": "monitoring-container",
    "title": "monitoring-container",
    "domain_type": "host_config",
    "extensions": {
      "folder": "/",
      "attributes": {
        "ipaddress": "127.0.0.1",
        "meta_data": { "created_at": "2026-02-19T07:18:24Z" }
      }
    }
  },
  {
    "id": "web-server-01",
    "title": "Web Server 01",
    "domain_type": "host_config",
    "extensions": {
      "folder": "/production",
      "attributes": {
        "ipaddress": "10.0.1.5",
        "meta_data": { "created_at": "2026-03-01T12:00:00Z" }
      }
    }
  }
]
}

Error Handling

Best Practices

• Use the fields filter — e.g. (value(id,title,extensions~folder,extensions~attributes)) —
  to drop members and links from the wire when only host identity + attributes are needed.
• Combine hostnames with site to narrow queries on multi-site Checkmk deployments.
• Call Get hosts before Get host inventory timestamps so you have the canonical host
  list to diff timestamps against.

Get host inventory timestamps

Retrieves the mk_inventory_last Unix timestamp for every host in one lightweight call.
Returns 0 for hosts that have never been inventoried.

Use case: Drive incremental inventory syncs — compare each host's mk_inventory_last
against the watermark stored from the previous sync, and pass only the changed subset to
Get host inventory.

Input Parameters

None.

Example Input

{}

Output

Host fields

Example Output

{
"domain_type": "host",
"id": "host",
"hosts": [
  { "name": "cmk", "mk_inventory_last": 0 },
  { "name": "mysite", "mk_inventory_last": 1776179669 }
]
}

Error Handling

Best Practices

• Call this before Get host inventory to filter the host_names input down to only hosts
  whose mk_inventory_last changed since the previous sync.
• Persist each host's mk_inventory_last as the watermark for the next run.
• Skip hosts where mk_inventory_last = 0 if your sync only cares about inventoried hosts.

Get host inventory

Retrieves detailed hardware, software, and networking inventory for a batch of hosts.
The action paginates internally — it emits one page per batch and drains the full
host_names list across successive iterations.

Use case: Fetch device inventory (manufacturer, model, serial, CPU, memory, OS,
applications, network interfaces) for CMDB synchronization.

Input Parameters

Example Input

{
"host_names": ["host1", "host2"],
"batch_size": 50
}

Output

Host fields

Inventory fields

The inventory object mirrors Checkmk's HW/SW inventory tree with snake-cased keys.
Each node carries attributes (with a pairs object of scalar facts), optional nodes
(child sub-trees), and optional table (rows of tabular data such as interfaces).

Example Output

{
"has_next_page": false,
"hosts": [
  {
    "hostname": "host1",
    "inventory": {
      "attributes": {},
      "table": {},
      "nodes": {
        "hardware": {
          "attributes": {},
          "table": {},
          "nodes": {
            "system": {
              "attributes": {
                "pairs": { "manufacturer": "Amazon EC2", "model": "m5a.2xlarge" }
              },
              "nodes": {},
              "table": {}
            },
            "cpu": {
              "attributes": { "pairs": { "cores": 4 } },
              "nodes": {},
              "table": {}
            },
            "memory": {
              "attributes": { "pairs": { "total_ram_usable": 33688150016 } },
              "nodes": {},
              "table": {}
            }
          }
        },
        "software": {
          "attributes": {},
          "table": {},
          "nodes": {
            "os": {
              "attributes": {
                "pairs": { "name": "Microsoft Windows Server 2019 Datacenter" }
              },
              "nodes": {},
              "table": {}
            }
          }
        },
        "networking": {
          "attributes": {
            "pairs": { "hostname": "host1", "total_interfaces": 2 }
          },
          "table": {},
          "nodes": {
            "interfaces": {
              "attributes": {},
              "nodes": {},
              "table": {
                "key_columns": ["index"],
                "rows": [
                  {
                    "index": 1,
                    "description": "eth0",
                    "alias": "Primary",
                    "speed": 10000000000,
                    "oper_status": 1,
                    "phys_address": "00:11:22:33:44:55",
                    "port_type": 6,
                    "available": true
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
]
}

Error Handling

Best Practices

• Keep batch_size at its documented maximum (50) to minimize round-trips.
• Feed host_names from the diffed output of Get host inventory timestamps — do not
  re-fetch inventory for hosts whose mk_inventory_last is unchanged.
• Let the action drain its internal pagination across iterations rather than slicing
  host_names manually at the caller.

Rate Limiting

Best Practices

• Run Get host inventory timestamps first, diff mk_inventory_last against your stored
  watermark, then pass only the changed subset as host_names to Get host inventory.
  This avoids re-fetching heavy inventory trees for unchanged hosts.
• Keep batch_size on Get host inventory at its maximum (50).
• Use the fields filter on Get hosts — e.g.
  (value(id,title,extensions~folder,extensions~attributes)) — to drop members and links
  from the wire when only hosts plus attributes are needed.
• Narrow Get hosts with site when your Checkmk is multi-site.
• Persist each host's mk_inventory_last in Xurrent as the watermark for the next run.

Common Use Cases

• Initial CMDB import → Get hosts → Get host inventory for all hostnames.
• Incremental sync → Get host inventory timestamps → diff against stored watermark →
  Get host inventory with the changed subset.
• Host list refresh for tagging and grouping → Get hosts with a fields filter.
• Troubleshoot a single host → Get hosts with hostnames=[name] →
  Get host inventory with host_names=[name].

References

• Checkmk REST API documentation: https://docs.checkmk.com/latest/en/rest_api.html
• Endpoints used by this connector:
• GET /api/1.0/domain-types/host_config/collections/all — Get hosts
• POST /api/1.0/domain-types/host/collections/all — Get host inventory timestamps (livestatus-backed host columns)
• GET /host_inv_api.py — Get host inventory (HW/SW inventory over Web API)