Checkmk Monitoring Integration

What Is Checkmk?

Checkmk is a third-party infrastructure and application monitoring platform. The KW Group platform ships with a Checkmk Raw 2.3 container and a sync bridge that pulls Checkmk hosts and problem-service alerts into the RMM device list, so a single agent / device record shows both:

• Local RMM data (CPU, memory, disk, scripts, remote control), and
• Deep Checkmk service-level checks (HTTP, ping, database, app-level probes, etc.).

The Checkmk Container

A Checkmk Raw Edition container runs alongside the platform services:

The first time the container starts it initialises the cmk site and prints the generated cmkadmin password to the logs. The current live password is recorded in /opt/passwords.md §9 (this file is chmod 600 — do not commit).

Public Web UI (Recommended Access)

The Checkmk web UI is exposed publicly as a path prefix on the main portal host:

• URL: https://portal.kwgroup.org.uk/checkmk/
• Login: Checkmk's own cmkadmin user (not the portal login).
• Auth model: no portal auth wraps the path. The Checkmk login page is the gate.

This is a Traefik path-rewrite proxy: requests to /checkmk/... are stripped of the /checkmk prefix and forwarded to the Checkmk container on port 5000 under /cmk/check_mk/.... The router config lives in /opt/data/traefik/dynamic/checkmk.yml and is picked up live by Traefik's file provider.

Heads-up. /checkmk is a discoverable path prefix. The cmkadmin password in /opt/passwords.md is current as of the last rotation; rotate it from the Checkmk UI (User profile → Change password) if you change who's allowed to see it.

Configuring the Sync (admin → /admin/checkmk)

Once the Checkmk site is running, connect the platform to it:

1. In Checkmk: Setup → Users → Users → create an automation user (e.g. automation) and copy its secret.
2. In the platform: Admin → Checkmk (/admin/checkmk).
3. On the Config tab, fill in:
   • Site URL — base URL of your Checkmk site. Use http://host.docker.internal:5000 if the Checkmk container is on the same host as the platform services.
   • Site name — cmk (default).
   • API username — automation (default).
   • API secret — the automation user's secret.
   • Sync interval (minutes) — default 5.
   • Active — on.
4. Click Save, then click Sync now to run an immediate sync.

What the Sync Pulls

The sync service (checkmk-service, port 3017) calls the Checkmk REST API 1.0 in three batches:

1. Hosts collection — every host in Checkmk is upserted as a checkmk_hosts row.
2. Livestatus columns — host state (UP / DOWN / UNREACHABLE / PENDING) and per-state service counters (OK / WARN / CRIT / UNKNOWN).
3. Problem services — every service in a non-OK state on a Checkmk host is bridged as an RmmAlert with severity CRITICAL / WARNING / INFO and a [Checkmk · service] message prefix. Alerts are deduplicated against the OPEN status, so a previously-bridged-and-resolved alert can re-fire.

Each sync writes a checkmk_sync_runs row showing hosts added / updated, alerts created, devices mapped, and (on failure) the error text.

Mapping Hosts to RMM Devices

The sync tries to map each Checkmk host to an existing RMM device by exact hostname match (case-sensitive; trailing dots trimmed). Mapped hosts show their Checkmk state on the RMM device page and vice versa.

If the auto-match misses, open the host on the Hosts tab and click Map to RMM device to do it manually.

Troubleshooting

• Sync shows FAILED — open the Sync runs tab and read the error. The most common causes are 401 (rotated automation secret) or network to port 5000.
• Host not mapping — rmm_devices.hostname must match checkmk_hosts.hostname exactly. The /admin/rmm device editor shows the hostname; /admin/checkmk → Hosts shows the Checkmk hostname. Case matters; trim any trailing dots.
• Duplicate alerts — alerts are deduped by message contains service + OPEN status. If a previous alert was resolved, the bridge will re-raise the alert on the next sync.
• /checkmk returns 404 — Traefik dynamic config not loaded. Check /opt/data/traefik/dynamic/checkmk.yml exists and is valid YAML. The file provider polls the dir and reloads within seconds on edit.

API Access (for external automation)

Checkmk's REST API 1.0 is reachable through the public proxy at https://portal.kwgroup.org.uk/cmk/check_mk/api/1.0/... once authenticated. Authenticate with the automation user via HTTP Basic — the same automation / secret pair configured above. Example: ping the Checkmk version.

# Authenticated. Replace <secret> with the automation user's secret.
curl -u automation:<secret> \
  https://portal.kwgroup.org.uk/cmk/check_mk/api/1.0/version

{
  "site": "cmk",
  "group": "",
  "rest_api": { "revision": "0" },
  "versions": {
    "checkmk": "2.3.0p46.cre",
    "python": "3.12.9 ..."
  },
  "edition": "cre"
}

The full Checkmk API is documented at docs.checkmk.com. Common external automations:

• Add a host: POST /cmk/check_mk/api/1.0/folder_config/{folder}/hosts/{name}.
• Bulk-acknowledge problems: POST /cmk/check_mk/api/1.0/domain-types/acknowledge/collections/all.
• Get all services of a host: GET /cmk/check_mk/api/1.0/objects/host_config/{name}/collections/services.

The same endpoints work over the platform's host-side listener (http://localhost:5000/cmk/check_mk/api/1.0/...) when running automation from a job on the platform host itself.