Werk #19273: Register agent controller and agent updater in one command
| Component | Agent bakery | ||||
| Title | Register agent controller and agent updater in one command | ||||
| Date | Feb 11, 2026 | ||||
| Level | Prominent Change | ||||
| Class | New Feature | ||||
| Compatibility | Compatible - no manual interaction needed | ||||
| Checkmk versions & editions |
|
The agent controller and agent updater can now register together, eliminating the need to run cmk-agent-ctl register and cmk-update-agent register separately with mostly the same arguments.
A new Registration option in the Automatic agent updates bakery ruleset lets you configure how the agent updater registers alongside the agent controller. Alternatively, for a one-time combined registration without changing bakery configuration, use the new --automatic-updates flag:
cmk-agent-ctl register --automatic-updates -s <server> -i <site> -H <hostname> -U <user>
What's included
Automatic updater registration
The Automatic agent updates bakery ruleset has a new Registration option. When set to an automatic mode, the agent updater registers alongside the agent controller — regardless of how the controller registration is triggered:
- Manual registration (
cmk-agent-ctl register) - Manual registration with automatic host creation (
cmk-agent-ctl register-new) - Fully automatic registration via the Agent Controller auto-registration bakery ruleset (Checkmk Ultimate)
Two automatic modes are available:
- On first agent controller registration: Keep any previous agent updater registration info. If the agent controller registers with multiple sites, only the first site will be used for agent updates.
- On every agent controller registration: Overwrite any previous agent updater registration info. If the agent controller registers with multiple sites, only the last site will be used for agent updates.
New rules default to the first mode. To opt out, set the option to Register manually. In that case you can still trigger a combined registration explicitly with cmk-agent-ctl register --automatic-updates, or register the agent updater separately with cmk-update-agent register. Since the registration is handled manually by the user, any existing agent updater registration will be overwritten.
Note: Shipping the agent updater plugin via this ruleset is a prerequisite for agent updates in general. This applies equally when using cmk-agent-ctl register --automatic-updates manually.
Agent registration role
The builtin "Agent registration" user role is now authorized to also register for agent updates, so least-privilege setups work with the unified registration without additional configuration. If you need permissions on a finer granularity, or don't want to use the unified registration feature with a single user, please create a separate user role with a subset of the agent controller/agent updater registration permissions.
Further details
Agent updater still acting independently
The agent updater (cmk-update-agent) is still the owner of the agent updater registration. To do the agent updater registration, cmk-agent-ctl calls cmk-update-agent as a subprocess and passes all relevant arguments. The password is passed securely via a temporary file — it never appears in process arguments.
Agent updater running under agent controller user
As a consquence, cmk-update-agent then runs under the Agent Controller User. We have devoted a separate Werk to this topic. See Werk #19274 for details.
Agent updater resources
The agent updater resources - configuration, state, and log, still apply. This means that the values configured in the Automatic agent updates bakery ruleset are still active. Arguments passed by the agent controller take precedence over configured values. Configured HTTPS certificates are still active and considered.
Protocol auto-detection
The -p (protocol) argument for cmk-update-agent is now optional. If omitted, the agent updater tries https first and falls back to http. This also means the unified registration command doesn't need to guess the protocol.
Error handling
If the agent updater is not installed or you're connecting to a Checkmk Community Edition server, the registration completes successfully for the agent controller and logs a note about the skipped updater registration. Same goes for a failed agent updater registration, while the latter can also be traced in the cmk-update-agent.log.