Installing the Checkmk Agent on Windows and Linux Hosts

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

ItemDetail
Newest release seen2.5.0p20, published 16 November 2026 (2.5.0p19 came out on 11 November)
LicenceFree, 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
PortsTCP 6556 on the host (pull mode); TCP 8000 on the Checkmk server for registration (Agent Receiver)
Windows binariesC:\Program Files (x86)\checkmk\service\ (agent and cmk-agent-ctl.exe)
Windows user configC:\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

FeatureCheckmk Community (free)Commercial editions
Stock MSI/DEB/RPM packagesYes, under Setup > AgentsYes
TLS-encrypted, compressed pull modeYes, after registrationYes
Agent Bakery (per-host packages built from GUI rules)NoYes
Automatic agent updatesNo, use your own deployment toolYes
Push mode and auto-registrationNoCheckmk 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/24

Step 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.rpm

The 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 port

If 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_registration

On Windows, in an elevated PowerShell:

& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" register --hostname mynewhost --server mycmkserver --site mysite --user agent_registration

Leave 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 run check_mk_agent.exe showconfig to see the merged configuration files.
  • Controller. cmk-agent-ctl dump should return agent data. “Connection refused (os error 111)” on Linux usually means the socket is not running; systemctl restart check-mk-agent.socket fixes it.
  • Registration errors. Add -vv to the register command to see which URL and port it tries.
  • Network. From the site user, echo | nc <host-ip> 6556 should print 16 on 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.

Contact our team

Our team handles software installation, setup and related IT tasks. We work with licensed software, deliver high-quality results and meet agreed deadlines.

  • Free initial consultation and basic setup.
  • Specialist visit on site, support by email or phone, or remote setup.
  • Remote training, plus participation in conferences and briefings.

Tell us about your company and leave a work email, and we will reply by email.