Setting Up Checkmk Synthetic Monitoring (Robotmk) Step by Step

Checkmk’s synthetic monitoring¹ runs a real Robot Framework Browser test against your site on a schedule and reports pass/fail straight into Checkmk

• not just “is the port open,” an actual headless-browser page load with whatever assertions you write. It’s exclusive to Checkmk’s commercial editions (not the free Raw edition), but within those, the first three tests are free of charge with no time limit. This is the full setup path, end to end, including the defaults that need changing before it’ll work and the one error message it throws that isn’t self-explanatory.

If you need a Rocky Linux host that can actually run Playwright/Chromium first, see the companion post² - this one assumes that part is done and focuses on the Checkmk side.

What you need

#

• Checkmk 2.5+ on a commercial edition (Robotmk is bundled, not a separate package)
• A dedicated Linux host to run the test - 4+ CPU cores, 8GB RAM is the documented minimum. I’m using robotmk01.example.org throughout below; substitute your own host.
• Outbound internet access from that host, at least for the first RCC environment build (it downloads Python/Node/browser packages)

Register the test host as a normal Checkmk host first

#

Robotmk rides on the regular Checkmk agent - get that working before touching anything synthetic-monitoring specific. Install the agent package built for your site and register it³:

sudo dnf install -y /path/to/check-mk-agent-<version>.rpm
sudo cmk-agent-ctl register \
  --hostname robotmk01.example.org \
  --server monitoring.example.org \
  --site mysite \
  --user automation \
  --password '<automation-secret>' \
  --trust-cert

Add the host in Setup, run a discovery, confirm the normal checks (CPU, memory, filesystem) come back green before moving on.

Package the test as a Managed Robot

#

This is the part with no REST API - it’s a GUI-only workflow under Setup → Synthetic monitoring → Managed Robots. A “Managed Robot” is a .tar.gz (or .zip) archive containing your test suite, stored server-side and distributed to hosts by the bakery.

The archive needs at minimum:

conda.yaml   # RCC environment: dependencies + the rccPostInstall hook
robot.yaml   # RCC manifest (path to conda.yaml); its own tasks: are unused
tests.robot  # the actual Robot Framework suite

See the companion post for the exact conda.yaml/rccPostInstall content if you’re testing a browser-based page.

In the Add robot form:

• Name / Description: whatever identifies this test
• Robot package: upload the archive
• Plan settings → Application name: a label, shows up in the service name
• Relative path to test suite file or folder: tests.robot
• Execution configuration → Limit per attempt: the 60-second default is too short if the environment needs to download a browser on first run - bump it to at least 5 minutes
• Automated environment setup: RCC, Relative path to robot.yaml: robot.yaml, Environment dependency handling: Download (internet connection)

Saving creates version 1 of the robot. Re-uploading the archive later (to fix a bug in the test itself) bumps the version number - the bakery rule below always deploys whatever the current version is.

The bakery rule: Robotmk scheduler (Linux)

#

Under Setup → Agents → Agent rules → Robotmk scheduler (Linux), add a rule and scope its Conditions to just the test host (explicit host condition) - this shouldn’t apply fleet-wide.

• Deploy Robotmk scheduler and agent plug-in
• Base directory of Robot Framework projects: e.g. /var/robot - doesn’t need to exist, the scheduler takes ownership of it
• Parallel running sequences of plans → Sequence execution interval: must be longer than the sum of all plan runtime limits in that sequence (limit-per-attempt × (1 + re-executions)) - Checkmk validates this and refuses to save otherwise. If your plan’s limit is 5 minutes, set the interval to something like 15.
• Sequence of plans → Add new plan: choose Managed Robot, pick the one you just created, leave it on “Use default managed plan settings” unless you specifically need to override something per-host
• RCC configuration → Allow agent deployment as root: leave this unchecked first - see the gotcha below before deciding
• Conda configuration: defaults are fine for a single dedicated host with direct internet access (no proxy)

NOTE: if your Checkmk agent is deployed running as root on this host (the default for most Linux agent installs), baking will fail with: Synthetic Monitoring is configured on Linux hosts with root agent deployment and RCC for the environment creation. This combination is not supported (werk #19460⁴). The underlying reason: RCC running as root can end up changing permissions on /opt the first time it runs, which on a Linux distro that also installs Checkmk itself under /opt/omd is exactly as bad as it sounds. The message itself names three ways out: switch the base agent to non-root deployment via Customize agent package (Linux), use Conda instead of RCC for the environment, or - if this host exists solely for synthetic monitoring, which is the common case - check Allow agent deployment as root in this same rule. For a dedicated test host, that third option is the simplest and is what the error message itself points to for exactly this situation.

Bake and deploy

#

Bake the agent package (Setup → Agents → Baking, or the /domain-types/agent/actions/bake/invoke endpoint of the Checkmk REST API⁵). Then get the new package onto the host. Two ways:

Signed auto-update⁶ (if you’ve set up an agent signing key and registered the updater):

sudo cmk-update-agent register -s monitoring.example.org -i mysite \
  -H robotmk01.example.org -U automation -P '<automation-secret>' -t
sudo cmk-update-agent -v

Manual reinstall (no signing key needed, works everywhere):

curl -o agent.rpm \
  "https://monitoring.example.org/mysite/check_mk/api/1.0/domain-types/agent/actions/download_by_host/invoke?os_type=linux_rpm&host_name=robotmk01.example.org" \
  -H "Authorization: Bearer automation <secret>"
sudo dnf install -y agent.rpm

Either way, the install restarts robotmk-scheduler-daemon, which triggers a fresh RCC environment build on that host.

Verify it actually ran

#

Don’t wait out the schedule while debugging - journalctl -u robotmk-scheduler-daemon shows environment build progress in real time, and the documented way to run the suite directly, bypassing the schedule entirely, is in the companion post.

Once it’s working, run a discovery and reload the core:

cmk -v -I robotmk01.example.org
cmk -R

Three new services should appear: RMK Scheduler Status, RMK <plan> Plan, and RMK <plan> Test: <test name>. Checkmk also ships a “Synthetic Monitoring” dashboard (Monitor menu) that summarizes test nodes, OK tests, and per-test runtime across every Robotmk-managed host at once.

Resources

#