Werk #19234: Unix agents: single-directory deployment is now the default
| Component | Checks & agents | ||
| Title | Unix agents: single-directory deployment is now the default | ||
| Date | Nov 5, 2026 | ||
| Level | Major Change | ||
| Class | New Feature | ||
| Compatibility | Incompatible - Manual interaction might be required | ||
| Checkmk versions & editions |
|
Checkmk 3.0 installs the Unix agent under a single directory,
/opt/checkmk/agent/default, with the subfolders package and runtime.
Previously, the agent installed files across /usr/lib/check_mk_agent,
/var/lib/check_mk_agent, /etc/check_mk and /usr/bin. This is known as the
classic file deployment, and Checkmk 3.1 removes it.
This affects all baked Unix agent packages - DEB, RPM, Solaris PKG and TGZ - the vanilla package, and the prebuilt DEB and RPM packages from the download page. Windows is not affected.
Werk #17900 introduced the single-directory deployment as an option. This werk makes it the default.
Existing sites retain their deployment configuration
Upgrading a site to Checkmk 3.0 does not change the layout of the agents that are already installed. The upgrade creates an unconditional rule Use classic file deployment in the main folder. This preserves the classic layout for newly baked packages, unless a Customize agent package rule takes precedence.
The upgrade creates that rule in every case, including in a site whose hosts all use Customize agent package already. There it has no effect, because Customize agent package takes precedence.
A newly created Checkmk 3.0 site gets no such rule, so the packages it bakes use the single-directory deployment.
This covers baked packages. The prebuilt packages from the download page always use the single-directory deployment, see below.
Switching hosts to the single-directory deployment
As soon as the rule Use classic file deployment no longer matches a host, the agent package you bake for that host uses the single-directory deployment. You can do this in three ways:
- narrow the conditions of the rule, for the hosts you choose,
- delete the rule, for all hosts at once,
- add a Customize agent package rule for the hosts, which also lets you choose the directory.
Bake the agents afterwards. On installation, the DEB, RPM and Solaris packages relocate the files that the running agent has written: the agent controller's registration, the agent updater's state, the spool directory and the logs. Nothing is lost, and the host does not have to register again.
The migration moves these files, it does not copy them. Installing a classic package again afterwards does not bring them back: such a host starts with an empty runtime directory, and you have to register it again.
TGZ packages require manual migration
TGZ packages ship no installation scripts, so nothing is relocated for you. This concerns every TGZ package, and AIX in particular, for which Checkmk offers no other package format.
For hosts using TGZ packages, move the contents of the old variable directory -
by default /var/lib/check_mk_agent - to /opt/checkmk/agent/default/runtime
before you unpack the new package, and preserve ownership, permissions and
symbolic links. Without this step, the agent controller loses its registration
and the agent updater loses its state, and you have to register the agent
again.
Hosts without an agent bakery
The prebuilt DEB and RPM packages from the download page now install under
/opt/checkmk/agent/default as well, and they migrate an existing installation
the same way the baked packages do. Only the agent bakery can keep a host on
the classic file deployment, so without a bakery your hosts switch with the
first Checkmk 3.0 agent package that you install.
Rulesets that now apply to classic hosts only
Installation paths for agent files (Linux, UNIX) and Run agent as non-root user (Linux) are deprecated, and Checkmk 3.1 removes them. They no longer determine where a single-directory package installs its files.
The values of Installation paths for agent files (Linux, UNIX) are still read, however. Keep those rules until every host has installed its new agent package: the migration takes the old variable directory from them, and on a host with a custom path it finds nothing to migrate without them.
The ruleset Run agent as non-root user (Linux) has no effect on any host that uses the single-directory deployment. Without a Customize agent package rule, such a host runs the agent as root, even if a Run agent as non-root user rule matches it. Before you switch such hosts, add a Customize agent package rule and configure the user through its Customize user option. This already changed earlier in Checkmk 3.0 for hosts using Customize agent package.
Solaris and AIX
The ruleset is now called Customize agent package (Linux, Solaris, AIX). Werk #22164 had marked Solaris and AIX as experimental; that designation has been removed.
The Solaris PKG package migrates its runtime directory on installation, like the Linux packages do. AIX ships as a TGZ package, which has no installation scripts, so an AIX host needs the manual migration described above.