checkmk_agent

Ansible role to install the CheckMK RAW edition agent/client.

This is a complete rebuild of the previous install-check_mk-agent role, which I maintained for years. It was updated due to changes in CI/CD and naming conventions in Ansible Galaxy and CheckMK.

All tasks are tagged with checkmk-agent.

The following operating systems have been automatically tested:

• Debian 10 "Buster"
• Debian 11 "Bullseye"
• Debian 12 "Bookworm"
• Fedora 38
• Fedora 39
• Fedora 40
• Microsoft Windows Server 2019 / Windows 10
• Microsoft Windows Server 2022 / Windows 11
• Ubuntu 20.04 LTS "Focal Fossa"
• Ubuntu 22.04 LTS "Jammy Jellyfish"
• Ubuntu 24.04 LTS "Noble Numbat"

For better performance, certain sections are disabled by default in the Windows agent:

• services
• msexch
• dotnet_clrmemory
• wmi_webservices
• wmi_cpuload
• ps
• fileinfo
• logwatch
• openhardwaremonitor

Also, plugin execution settings have been adjusted:

• Timeout increased from 30 to 120 seconds
• Async enabled
• Cache_age set to 3600 (1 hour)

You can create your own "check_mk.user.yml.j2" file for further customization. To disable optimizations, set the checkmk_agent_win_config_optimize variable to false.

Similar changes were made to the default docker.cfg file, where all docker sections are activated. Revert to defaults by setting checkmk_agent_docker_complete to false.

Version Matrix

CheckMK Raw Edition Version	Role Version
2.3.0p13	1.1.1
2.3.0p12	1.1.0
2.3.0p11	1.0.99
2.3.0p10	1.0.98
2.3.0p9	1.0.97

Requirements

This role does not require other roles. It is compatible with CheckMK servers in general, and specifically with kso512.checkmk_server.

If you're connecting to a Windows host using Windows Remote Management (WinRM), you may need to install the pywinrm package:

pip install "pywinrm>=0.3.0"

On Unix-like systems, this role uses SSH instead of the default port 6556 for secure communication.

To create SSH authentication keys, use the "ssh-keygen" program following the instructions here.

Example command to create default keys without a passphrase:

ssh-keygen -C "cmkagent@$HOSTNAME" -f ./id_rsa -N "" -v

This creates two files: id_rsa (the private key) and id_rsa.pub (the public key).

The id_rsa file should be placed in the ~/.ssh directory of the CheckMK Agent user. Example:

cp ./id_rsa /opt/omd/sites/test/.ssh

The id_rsa.pub file can be shared with trusted hosts and needs to be added to your local "authorized_keys.j2" file. Example:

echo '# {{ ansible_managed }}' > /etc/ansible/local/authorized_keys.j2
cat ./id_rsa.pub >> /etc/ansible/local/authorized_keys.j2

Then set local/authorized_keys.j2 as checkmk_agent_authkey_src in your variables:

Finally, configure CheckMK to use these files instead of connecting to TCP port 6556.

Role Variables

Here are some main role variables (with defaults) you can customize:

Variable	Description	Default
checkmk_agent_user	CheckMK Agent user's login name	cmkagent
checkmk_agent_version	Version of CheckMK Agent to install	2.3.0p13
checkmk_agent_authkey_dest	Path for the "authorized_keys" file	"{{ checkmk_agent_ssh_path }}/authorized_keys"
checkmk_agent_docker_complete	Include all Docker modules	true
checkmk_agent_local_checks	List of checks to copy to the "local" folder	count_users, count_zombie_procs

For a complete list of variables and their descriptions, refer to the documentation.

Dependencies

No dependencies defined yet.

Example Playbook

Example using a local authorized_keys file:

- hosts: all
  roles:
     - { role: kso512.checkmk_agent, checkmk_agent_authkey_src="local/authorized_keys.j2" }

Example that purges the plugin folder before re-creating:

ansible-playbook site.yml -t checkmk-agent -e "checkmk_agent_plugin_purge=true"

License

Licensed under the GNU General Public License version 2.

Contributing

Feel free to open an issue or submit a merge request if you have suggestions or ideas.

Author Information

• @kso512
• @iamdevnull