Werk #17900: Linux agent: single directory deployment
| Component | Agent bakery | ||||
| Title | Linux agent: single directory deployment | ||||
| Date | Apr 23, 2025 | ||||
| Level | Prominent Change | ||||
| Class | New Feature | ||||
| Compatibility | Compatible - no manual interaction needed | ||||
| Checkmk versions & editions |
|
It's now possible to deploy the Checkmk agent under a single directory on Linux systems.
What does this mean?
When installing a Checkmk agent on a Linux (or UNIX) host, its contents are distributed over
multiple folders, like /usr/lib/check_mk_agent, /var/lib/check_mk_agent,
/etc/check_mk, /usr/bin.
While this approach loosely follows the filesystem hierarchy standard for UNIX-like systems,
it also violates it in some details.
Since there is no real advantage in this approach, and it's sometimes hard to overview all
agent related files, we now offer to install the Checkmk agent under one single root directory
on Linux systems, which defaults to /opt/checkmk/agent/default.
New bakery ruleset Customize agent package (Linux)
You can deploy the agent files under a single directory by entering a path at the new agent bakery ruleset Customize agent package (Linux), under Installation directories: Directory for Checkmk agent.
This path defaults to /opt/checkmk/agent, and it's active as soon as you add a rule instance.
Please note that the agent installation will always create one additional default subfolder, so the final
agent installation directory is <installation_directory>/default.
Note: There is also an optional Customize user entry that can be used to enable the new non-root agent deployment, which is described in more detail in Werk #17901.
The ruleset Customize agent package (Linux) is also a replacement for the Installation paths for agent files (Linux, UNIX) ruleset. When configuring both rulesets, the new Customize agent package (Linux) ruleset will win, and the other one will be ignored. Though, when currently using the old ruleset, please keep it activated while updating to the new ruleset, since the agent package needs the custom installation paths to properly migrate runtime files on agent update.
After configuring Customize agent package (Linux) and baking agents, you can either install the resulting packages manually on target hosts, or letting them update on next automatic agent update.
We plan to make the single directory deployment the new standard. Hence, the ruleset Installation paths for agent files(Linux, UNIX) will be removed in a future Checkmk release, so we recommend to use the new approach of Customize agent package (Linux) instead.
Is this ruleset really Linux-only?
You can configure the Customize agent package ruleset as described above, bake agents,
and observe that all resulting UNIX-like packages come with the new single directory structure.
Hence, the answer is: Yes, the single directory depoyment is available for all baked agents for
UNIX-like systems. However, we declare the whole feature as Linux-only because only managed
packages (.rpm and .deb) come with the whole featureset. This includes the migration of
existing Checkmk agent installations and making shipped executables available under symlinks
at /usr/bin (since they are located under /opt/checkmk/agent/default/package/bin now and
are not directly available in $PATH).
Some technical details (FYI)
When choosing the single directory deployment, all contents of the Checkmk agent will be installed under
the folder <configured_directory>/default, which itself will contain two subfolders package and runtime.
package contains all static agent files resulting from the Agent Bakery configuration; runtime is there
for all files that get created while agent operation. This includes state files, logs, cache files, etc..
Internally, the agent finds its files with the help of some environment variables that exist equally for the
old multiple directory deployment, like MK_LIBDIR, MK_VARDIR, MK_BIN, MK_CONFDIR.
Additionally, there is now the new environment variable MK_INSTALLDIR that acts, when existant, as a switch
to activate the single directory deployment. When available, the agent will set all environment variables
by itself based on MK_INSTALLDIR, e.g., MK_LIBDIR=${MK_INSTALLDIR}/package.