1. Introduction
In the commercial editions of Checkmk
you can configure agent packages so that they can be executed on the host by an unprivileged user, i.e. not by
root
.
This feature is initially fully usable for Linux agents, that have been installed as DEB or RPM packages.
The prerequisite for unprivileged execution is that the agent package has been installed within a single directory. The option to select an installation directory is available for Linux, as well as for Solaris and AIX.
The two related rules define Installation paths for agent files (Linux, UNIX) and Run agent as non-root user (Linux) have been discontinued. It is planned to remove both in Checkmk version 2.5.0.
![]() |
The functionality presented here is a technical preview, i.e. a preview of a new feature that will be subject to development and expansion until further notice. During this phase, it is possible that functionality will not only be added, but also modified in such a way that existing configurations will become obsolete and you will have to recreate them. We ask for your understanding in this matter. |
2. Configuring the agent packages
The agent packages are configured in the Agent Bakery, which you open via Setup > Agents > Windows, Linux, Solaris, AIX. Click the Agent rules button. Under Agent rules > Linux/UNIX agent options you will find the rule Customize agent package (Linux).
2.1. Specifying the installation directory
With Directory for Checkmk agent you can specify the installation directory:

All agent package files are installed in this directory instead of in directories such as /etc/
, /usr/lib/
or /var/lib/
.
For security reasons, do not select any directory in a user’s home directory.
For Solaris and AIX you are now finished. For Linux, you can also specify unprivileged execution.
2.2. Configuring unprivileged execution
Two basic options are available for the Linux agent after selecting Customize user:

The default values Run agent as root, set agent controller user, and cmk-agent
as user specify exactly the behavior that is the default behavior of the Checkmk agent for Linux, even without configuring this rule,
so that the Agent Controller will be executed under cmk-agent
, and the agent script under root
.
What is new, however, is the option of specifying a different user as cmk-agent
.
The second option is Run agent as non-root, set agent user. This specifies that, in addition to the Agent Controller, the agent script will also be executed under the specified user — i.e. both are unprivileged.
You can also assign numeric IDs to the user (UID) and group (GID). Note the conventions of your Linux distribution and any existing limitations of the file systems used.
The last option determines whether the user selected in this rule should be created if it does not already exist.
3. Configuring unprivileged execution on the host
If you have configured agent packages for unprivileged execution, additional configuration may be required on the Linux host on which the package is installed.
For security reasons, an agent configured for unprivileged execution offers a slightly smaller range of functions than an agent executed with root permissions. In order to make the missing functionality available, you as the administrator must find methods that are both effective and compatible with the security guidelines of your organization and the conventions of the Linux distribution used.
![]() |
Note that this chapter provides no single best solution for either the configuration supplied with the agent packages or the configuration carried out on the host. All possible and sensible solutions must be based on the distributions used, the operational guidelines in your organization, and maintainability. |
3.1. Configuration of sudo
We have added a wrapper function for the agent script, which prefixes commands that generally require high-level privileges with sudo
.
This affects in Checkmk 2.4.0 mdadm
(for reading the status of various software RAIDs and encrypted drives), as well as mailq
(for reading the email queue of the postfix MTA).
Example configurations for sudo
can be found in the installation directory of the agent in the subfolder default/package/agent/checkmk_agent_sudoers_template
.
You can transfer the required lines to your /etc/sudoers
or copy the entire file to /etc/sudoers.d
(not recommended).
Adjust the entries accordingly.
For example, in some cases no superuser permissions are required to read the email queue and the user ID under which the MTA is executed can be used.
3.2. Agent plug-ins
For the execution of agent plug-ins we recommend ensuring access to the required information via file permissions and group assignments. The following list shows possible methods:
Add the user under whose ID the agent script is executed to a group that can read required data in monitoring.
Change the access rights or group assignment of device files (e.g. via
udev
rules) so that the unprivileged user can access them.If necessary, execute plug-ins using a cronjob and redirect their output to a spool file.
If these measures do not achieve the desired result, you can also use the Plug-ins, local checks and MRPE for non-root users rule to specify the executing users for specific directories individually.
This rule creates an agent configuration which is automatically installed, and another configuration for sudo
, which you must deploy (as described above).
![]() |
You are welcome to send us any customizations you have made to agent plug-ins delivered with Checkmk. This can be done via a pull request, a support ticket or notes in the Checkmk Forum. We will gradually add best practices for plug-in developers to the article on developing agent-based check plug-ins. |
3.3. Automatic agent updates
![]() |
The current implementation of the Agent Updater as an agent plug-in is not compatible with unprivileged execution. We are working on necessary changes to the architecture. In the meantime, use other software deployment solutions. |
4. Legacy deployment
Unprivileged execution is also possible without an Agent Controller or if the installation cannot be carried out via a DEB or RPM package.
4.1. Installation without a package manager
When using the TGZ packages provided in .tar.gz
format, you must ensure that permissions are granted correctly after the installation.
Use a sample installation that you have carried out under Linux with package management as a guide.
![]() |
We will gradually add further information to this section. |
4.2. Call without an Agent Controller
If the Agent Controller cannot or should not be used, both the unencrypted call via (x)inetd
or the encrypted call via Secure Shell are possible.
Minor modifications are required compared to the call with root permissions.
Xinetd
The configuration file for xinetd
is provided in the installation directory under default/package/config/xinetd-service-template.cfg
, and will be activated if the Agent Controller is deactivated or incompatible. This file already contains the unprivileged user defined by the agent rule.
If you are using a different Internet super-server (e.g. the OpenBSD inetd
), create the configuration according to its documentation.
Examples are shown in the Monitoring Linux in legacy mode article.
Secure Shell
The call via SSH also corresponds to the procedure described in the Monitoring Linux in legacy mode article.
Only the path to the configuration file .ssh/authorized_keys
and the user name used must be adapted to the unprivileged user you are using.