Werk #17901: Linux agent: non-root deployment
| Component | Agent bakery | ||||
| Title | Linux agent: non-root 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 operate the Checkmk agent under a custom agent user instead of root.
Before going into details, please note the scope of this change:
When running the agent as a non-root user, it may omit monitoring data, if permissions are not granted.
Currently the non-root mode is limited to the agent controller and agent script.
If agent plug-ins or other subprocesses of the main agent script (E.g., mk_logwatch.py monitoring an only-root-accessible file) require elevated privileges, it will remain a user's duty to provide these permissions and make the necessary adaptations.
Now, let's see what's in:
What does this mean?
You can now configure Linux agent packages to perform a non-root agent installation.
This means that, after installation, the agent script will run under a custom non-root user.
The main reason for this feature is the need to fulfill certain security requirements and policies that may deny the operation of system services under root.
While the Checkmk agent will run under the agent user, the installation itself still needs root access.
Also, automatic agent updates (if configured) still run under root.
All static files deployed with the agent package remain under the ownership of root, but the agent user
will get access to needed ressources via group ownership.
Note: To make use of the full featureset of the non-root agent deployment, some manual action is still required after installation. See The scope of the non-root agent deployment for details.
New bakery ruleset Customize agent package (Linux)
To configure a non-root agent deployment, go to the new bakery ruleset Customize agent package (Linux),
activate Customize user and choose Run agent as non-root, set agent user.
As you can see, it's a prerequisite to also activate the single-directory deployment (see Werk #17900)
at the same bakery ruleset.
Multiple options are available for the choice of the agent user. Please refer to the inline help of the ruleset for details.
Wasn't this possible before already?
Up to now, you could already configure the bakery ruleset Run agent as non-root user (Linux).
This also resulted in running the Checkmk agent service(s) under the configured user.
However, this ruleset did nothing more than letting systemd operate the Checkmk agent service under
the agent user instead of root. All parts of the agent that require root access didn't work with this setup.
In contrast to the simple agent user option, the new non-root agent deployment comes with mechanisms to
overcome the limitation of the agent user's permissions.
When configuring Run agent user as non-root user (Linux) and Customize agent package (Linux) in parallel, the latter ruleset will win and the former will be ignored.
We plan to make configuration via Customize agent package the new standard for non-root deployments.
Hence, the ruleset Run agent as non-root user can be considered as deprecated and will be removed
in a future Checkmk release, so we recommend to use the new approach.
The scope of the non-root agent deployment
As mentioned, the most obvious change of the non-root deployment is that the Checkmk agent will run under the configured agent user instead of root.
Additional to that, the whole agent installation will be transformed to a non-root deployment. This means that the agent user will have access to all ressources of the agent installation that are needed to operate the agent and all plug-ins that come with it.
The non-root deployment also comes with a sudo Mechanism that enables the agent user to call commands
and executables that need elevated rights. This means, when running the agent under a non-root user, certain
commands do get executed with sudo (without a password).
However, this is the point where some manual action from you is required after installation:
To enable the agent user to successfully call the commands with sudo, the user will need sufficient rights
in the suoders configuration. To facilitate this configuration, the non-root agent installation comes with
a sudoers template that can be found under /opt/checkmk/agent/default/package/agent/checkmk_agent_sudoers_template.
When copying to /etc/sudoers.d, the agent user will have sufficient sudo rights to call all commands modified
with sudo by us in the agent script.
Disclaimer: It's called template for a reason. Please challenge the template with your own security
requirements before copying it blindly, and modify it by your own accordingly!
You can also ignore the template and do the sudoers config for the agent user completely on your own.
This is where the current scope of the non-root agent deployment ends.
sudo gives us a powerful tool to grant the agent user permissions on a fine-grained level for selected
commands. But it's limited to shell scripts.
Also, we currently only added the usage of sudo to a selection of commands within the agent script.
Especially, we didn't touch agent plugins that may need sudo rights yet.
There are more powerful tools out there, like the setuid bit or Linux capabilities, but we currently refrained from including them in the non-root deployment because the consequences of using them can be underestimated too easily.
Is this really Linux-only?
We must have to say: Yes.
The non-root agent installation relies on installation scripts to install the services for the agent user,
create/find the agent user, and to grant needed permissions to the Checkmk agent's file structure.
These scripts are only called automatically on installation of the Linux .rpm or .deb package.
However, there's a good chance for them to run on other UNIX-like systems, though we didn't test them.
In the end, the service installation relies on systemd (or xinetd as a fallback), which again means a
limitation to Linux systems.
The mentioned sudo mechanism gets deployed to all UNIX-like systems equally.
Some technical details (FYI)
The implementation of the non-root agent deployment relies on the call of installation scripts that
are called by the package manager on installation or update of the Checkmk agent package. They can be
found at /opt/checkmk/agent/defaut/package/scripts after the agent installation.
manage_agent_user.sh gets called to create or check the configured agent user, and to grant the user
the needed permissions. To get access to needed files, the group ownership of these files is changed
to the agent user's group. The ownership of the whole runtime directory is changed to the agent user.
As mentioned above, the installation comes with a sudoers template under
/opt/checkmk/agent/default/package/agent/checkmk_agent_sudoers_template, that can be modified
and copied to /etc/sudoers.d (root access required).
The counterpart in the agent script itself is implemented by a simple environment variable ROOT_OR_SUDO,
which can be found not far from the beginning of the agent script.
Its value depends on the deployment mode: In normal root deployment, it's empty, while in non-root
deployment, it's set to "sudo --non-interactive".
By that, commands that need elevated permissions can be prefixed with $ROOT_OR_SUDO to enable the
usage under non-root deployment.