This guide is for admins who already run a Checkmk site and now need hosts reporting into it. In short: in the free Community edition you install the stock agent package yourself (MSI on Windows, DEB or RPM on Linux), create the host in Setup, then run cmk-agent-ctl register on the host so the data travels over TLS instead of plain text. After that, run a service discovery and activate the changes.
We checked every command and path on 17 November 2026 against the official Checkmk User Guide (Windows agent, Linux agent and system requirements pages) and the Checkmk download archive. Not tested yet: we have not run 2.5.0p20 in our own lab, so register one test host before rolling the agent out.
Checkmk agent facts at a glance
| Item | Detail |
|---|---|
| Newest release seen | 2.5.0p20, published 16 November 2026 (2.5.0p19 came out on 11 November) |
| Licence | Free, open source (GPL-2.0) in Checkmk Community; the agent installer itself shows the GNU GPL |
| Windows support (2.5.0) | 64-bit releases 2016, 2019, 2022 and 2025; other editions, such as Windows Embedded, are not officially supported |
| Linux support (2.5.0) | Any distribution with Bash 4.2 or newer plus systemd 219+ or xinetd; the Agent Controller needs systemd |
| Ports | TCP 6556 on the host (pull mode); TCP 8000 on the Checkmk server for registration (Agent Receiver) |
| Windows binaries | C:\Program Files (x86)\checkmk\service\ (agent and cmk-agent-ctl.exe) |
| Windows user config | C:\ProgramData\checkmk\agent\check_mk.user.yml |
The server side is described on our Checkmk Community (formerly Raw Edition) page; this article only covers the agent.
Community vs commercial: what changes for agents
| Feature | Checkmk Community (free) | Commercial editions |
|---|---|---|
| Stock MSI/DEB/RPM packages | Yes, under Setup > Agents | Yes |
| TLS-encrypted, compressed pull mode | Yes, after registration | Yes |
| Agent Bakery (per-host packages built from GUI rules) | No | Yes |
| Automatic agent updates | No, use your own deployment tool | Yes |
| Push mode and auto-registration | No | Checkmk Ultimate only |
For a small team this means one extra job: you need your own way to push the package and rerun it on updates, whether that is GPO, a configuration management tool or a plain script. Our sysadmin automation tools hub lists options.
Step 1: create the host in Setup
A host must exist in the Checkmk configuration before it can be registered. Go to Setup > Hosts > Add host, enter the exact host name you will use on the command line, and save. For registration the documentation recommends the built-in automation user agent_registration, which can only register agents. Randomise its automation secret, save the user, and keep the secret in your password manager.
If you only need to bring up a first host or two, the GUI also offers a guided slideout that shows ready-made download, install and register commands with a one-time token.
Step 2: install the agent on Windows
In Community the MSI is under Setup > Agents > Windows, in the Packaged Agents box (check_mk_agent.msi). You can also fetch it straight from the site:
Invoke-WebRequest -Uri "http://mycmkserver/mysite/check_mk/agents/windows/check_mk_agent.msi" -OutFile "check_mk_agent.msi"For a single server, double-click the MSI, accept the GPL and choose Clean installation (the other options matter only when replacing an agent older than 1.6.0). For many servers, install silently:
msiexec /i check_mk_agent.msi /qn WIXUI_CLEANINSTALL=The agent starts as a Windows service under LocalSystem right away and the installer adds an inbound Windows Firewall rule for cmk-agent-ctl.exe on port 6556. Until you register it, that port hands out unencrypted agent data to anyone who asks, so restrict it straight away. On Windows the agent can drop requests from other addresses with an only_from line in check_mk.user.yml:
global:
only_from: 127.0.0.1/32 192.168.42.0/24Step 3: install the agent on Linux
Pick the package for the distribution: DEB for Debian and Ubuntu, RPM for RHEL-based systems, SLES, Fedora and openSUSE. Packages marked all or noarch install anywhere but carry the Agent Controller only for x86_64; ARM64 systems need the aarch64/arm64 package. Agent files can be fetched over HTTP from the site without logging in, because they contain no secrets:
wget http://mycmkserver/mysite/check_mk/agents/check-mk-agent_2.5.0p20-1_all.deb
dpkg -i check-mk-agent_2.5.0p20-1_all.deb
# RPM-based systems, download and install in one step:
rpm -U http://mycmkserver/mysite/check_mk/agents/check-mk-agent-2.5.0p20-1.noarch.rpmThe same dpkg -i or rpm -U command updates the agent later. The DEB install creates a cmk-agent user, deploys systemd units such as check-mk-agent.socket and cmk-agent-ctl-daemon.service, and prints a warning that the controller is in insecure mode until you register. Before registering, confirm the prerequisites:
systemctl --version # needs systemd 219 or newer
cmk-agent-ctl --version # should print the agent version
ss -tulpn | grep 6556 # cmk-agent-ctl should own the portIf systemd, xinetd or inetd owns port 6556 instead, or cmk-agent-ctl fails with “Exec format error” (for example on 32-bit x86), the host can only run the agent in legacy mode without TLS. Unlike Windows, the Linux Agent Controller ignores IP allow-lists, so use iptables or nftables to limit port 6556 to the Checkmk server.
Step 4: register the agent for TLS
Registration builds the trust between host and site. On Linux, as root:
cmk-agent-ctl register --hostname mynewhost --server mycmkserver --site mysite --user agent_registrationOn Windows, in an elevated PowerShell:
& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" register --hostname mynewhost --server mycmkserver --site mysite --user agent_registrationLeave out --password and the tool asks for the secret interactively, which keeps it out of shell history. If you script it on Windows, wrap the password in double quotes: single quotes become part of the value and registration fails. The tool then shows the site certificate and asks you to confirm with Y. --trust-cert skips that prompt for automation, but then you should verify the certificate another way, for example by checking C:\ProgramData\checkmk\agent\registered_connections.json.
Check the result with cmk-agent-ctl status; it should show one connection of type pull-agent. A host can have only one trust relationship per site, so registering the same machine again under another name replaces the first connection.
Step 5: discover services and troubleshoot
Back in the GUI, run the connection test on the host, then service discovery, accept the services and activate the pending changes. If something fails, work outwards from the host:
- Agent output. On Linux run
check_mk_agent | less; on Windows runcheck_mk_agent.exe showconfigto see the merged configuration files. - Controller.
cmk-agent-ctl dumpshould return agent data. “Connection refused (os error 111)” on Linux usually means the socket is not running;systemctl restart check-mk-agent.socketfixes it. - Registration errors. Add
-vvto the register command to see which URL and port it tries. - Network. From the site user,
echo | nc <host-ip> 6556should print16on a registered host. Full plain-text output means the connection is still unencrypted.
Limitations
- Version order. Keep agents at or below the server version. Newer servers read older agents, but a newer agent can produce output the server cannot parse, and those services go UNKNOWN.
- Old Windows. Releases outside the 2016–2025 list are not officially supported. The documentation mentions legacy agents at your own risk, without TLS or compression, and the 2.5.0 requirements note says output from the old 1.6.0-era Windows agent is no longer guaranteed to be compatible.
- No central rollout in Community. No Agent Bakery and no automatic updates, so every upgrade is a package redeploy plus, on Windows, a quick check that the service and firewall rule are still in place.
- Windows-only shops. If you only need event log, ping and web page checks for one Windows server, PA Server Monitor Free runs on Windows itself with no Linux server, but its free edition stops at one server or ten monitors.
FAQ
What port does the Checkmk agent use?
In pull mode the Agent Controller listens on TCP 6556 on the monitored host. Registration talks to the Agent Receiver on the Checkmk server, port 8000 by default; strict outbound firewalls should also allow 80 or 443 to the site.
What does “agent controller not registered” or “insecure mode” mean?
The agent is installed but has no trust relationship with the site yet, so it serves plain-text data on 6556. Run cmk-agent-ctl register as shown above, then check cmk-agent-ctl status.
Does the Checkmk agent support Windows Server 2012?
Not officially in 2.5.0, whose requirements list only 64-bit Windows 2016, 2019, 2022 and 2025. Older systems can only use a legacy agent at your own risk.
How do I restart the Checkmk agent on Linux?
The documented fix for a stopped agent socket is systemctl restart check-mk-agent.socket. The controller runs as cmk-agent-ctl-daemon.service.
How do I uninstall the Checkmk agent?
On Windows use Settings > Apps or msiexec /x check_mk_agent.msi /qn. On Debian or Ubuntu run dpkg --purge check-mk-agent; on RPM systems use rpm -e with the package name from rpm -qa | grep check-mk.
Is there an Agent Bakery in the free edition?
No. The Agent Bakery and automatic agent updates belong to the commercial editions; Community users install the stock packages and configure the agent through its files.
Last updated: 17 November 2026 · AdminHub Plus editorial team. Licence, version and platform details are checked against each developer's official documentation.