Explore the latest product updates and best practices at our hybrid Checkmk Conference #12 from June 16-18, 2026 – Register here
back to website

Werk #19759: Test agent connection: token-based agent download and registration on remote-site hosts

Component Setup
Title Test agent connection: token-based agent download and registration on remote-site hosts
Date Apr 28, 2026
Level Trivial Change
Class Bug Fix
Compatibility Compatible - no manual interaction needed
Checkmk versions & editions
2.6.0b1
Not yet released 		Checkmk Community, Checkmk Pro, Checkmk Ultimate, Checkmk Cloud, Checkmk Ultimate MT
2.5.0p2
Not yet released 		Checkmk Community, Checkmk Pro, Checkmk Ultimate, Checkmk Cloud, Checkmk Ultimate MT

The "Test agent connection" panel on the Setup → Hosts → Add/Edit host page lets the user generate a one-time token (OTT) that is embedded in the suggested copy&paste commands for downloading and registering the agent.

For hosts that are monitored by a remote site in a distributed setup these commands failed with 401 Unauthorized:

  • The token endpoints (domain-types/agent_download_token/collections/all and domain-types/agent_registration_token/collections/all) always run on the central site GUI and write the token into the central site's per-site token store.
  • The generated curl / cmk-agent-ctl register commands point at the remote site (because the host is monitored there).
  • The token store is per site and intentionally not replicated, so the remote site rejected the token.

Both endpoints now accept an optional site_id field. When set to a remote site, the central GUI forwards the token creation to that site via the existing distributed-setup automation channel (site secret), so that the token is stored on the same site that will redeem it during agent download or registration.

The host setup slide-in passes the host's monitoring site_id automatically. Hosts on the central site are unaffected.

To the list of all Werks