Checkmk
Our AI policyAI

1. Introduction

CEE There are cases where a Checkmk site cannot reach the host, for example when firewall configuration blocks incoming traffic from a network. With Checkmk Ultimate, the Checkmk Relay can be deployed to collect monitoring data and send it to the monitoring site.

1.1. Differences from distributed monitoring

There are notable differences compared to distributed monitoring:

  • The communication direction: The Relay always sends data to the monitoring site.

  • The place of data processing: The Relay neither processes, nor stores data, it just collects monitoring data and passes it on. Active checks are an exception, as their results are determined by the Relay itself and then sent to the Checkmk site.

Using the Relay in combination with distributed monitoring is currently limited to the central site. This also means that there is currently no practical use for it in environments using Checkmk Ultimate with Multi-Tenancy as intended.

1.2. Scope of functionality

The current state of the Relay encompasses functionality as follows:

The prioritizing of special agent additions is dependent on user benefit and the effort needed. A list of the special agents that are included in the Relay is available at GitHub. Special agents deployed via MKP to the Checkmk site are not synced to the Relay.

2. Setup

2.1. Technical requirements

Supported operating systems

The Checkmk Relay is provided as a container for the x86-64 platform. The following operating systems are currently supported:

  • Ubuntu Linux 24.04

  • Red Hat Enterprise Linux 8.10+, 9.7+, and 10

  • Windows Server 2022 and 2025

On Windows, the Checkmk Relay runs on the Windows Subsystem for Linux version 2 (WSL2). To prepare the necessary environment for this, an Ubuntu distribution is set up in WSL during the installation process.

If you run Windows in a virtual machine, this system must enable nested virtualization in order for the Relay to work as expected.

Podman and connection to Docker Hub

For the installation we provide a script that requires the Podman package provided by your distribution to be installed. The required container image is downloaded directly from Docker Hub during installation and with every update. Make sure your target system can connect to Docker Hub.

The installation wizard on Linux systems includes a step for explicitly installing Podman. When installing on Windows, the MSI installer we provide also handles the installation of Podman within the WSL environment.

We chose Podman because its tight integration with systemd facilitates automatic updates of the Relay container. Deploying on container runtimes other than Podman, running on distributions other than those listed, updating via methods other than direct access to hub.docker.com, using Podman packages other than those provided by the distribution, or using multiple Relays on a single Linux host may work for experienced users—​however, Checkmk does not provide support for such environments.

You can run the installation script on distributions other than those listed above. On unsupported distributions, the script will ask if you still wish to proceed. It will then check whether compatible versions of Podman and systemd are available.

Windows: Connection to GitHub and to cloud-images.ubuntu.com

An additional requirement under Windows is that a connection to GitHub must be possible at installation time. This connection is needed in order to download and install the latest version of WSL2.

In the course of the installation, a Linux system is additionally downloaded from cloud-images.ubuntu.com for the WSL environment.

Hardware requirements

In the standard configuration (13 fetchers), you should expect RAM requirements of about one gigabyte and CPU core utilization of less than 20 % on current hardware. With these resources, we were able to monitor more than 50 SNMP devices without any problems. If the number of devices to be monitored is significantly higher, the number of fetchers may need to be increased. As the number of devices increases, resource requirements scale almost linearly with the number of devices being monitored.

For each Relay registered on a site, the number of fetchers can be customized via Setup > Hosts > Relays by clicking the edit icon (Edit icon).

2.2. Configuring and installing a Relay

To set up a Relay, navigate to Setup > Hosts > Relays. There, click Add Relay configuration to launch the setup wizard for configuring a new Relay. First, choose between Linux and Windows to get the appropriate instructions for your target system.

In the Quick Setup for a new Relay, this step displays the curl command to download the installation script.
In the first step, the download link for the installation script is provided

Follow the wizard’s instructions.

Linux
Windows
Linux

In the wizard for Linux systems, installing Podman is a separate step that you perform individually on the target system.

Afterward, you can run the provided installation script as described in the wizard. When you run the script, the container with the Relay is downloaded and set up, the update service is installed, and the Relay is connected to the Checkmk site—​all in a single action.

On Linux, no separate log file is created for the installation. If needed, you can redirect the output of the installation script to a file.

Windows
Tip

To register the Relay with your Checkmk site, the wizard will prompt you to complete the installation using a one-time token. This token is valid for one hour after it is generated. If one hour is not sufficient, you can also complete the registration using the username and password of a user who has sufficient permissions to register the Relay.

In the Checkmk site to which you just added the Relay, you must now activate pending changes to complete its registration.

Notes on reinstallation

You can replace a Relay that has already been installed and registered on a system with another Relay. Begin by uninstalling the existing Relay (including the deletion of the Relay in your Checkmk site). Next, follow the installation assistant in the Checkmk web interface again and assign a new name to the new Relay.

Hosts that were already being monitored by the previous Relay must then be explicitly assigned to the newly registered Relay—​even if the Relay is running on the same machine as before.

2.3. Updates of the installation

A Checkmk Relay deployed using the provided installation script automatically keeps itself up to date. As soon as it detects that the version of the associated Checkmk site has changed, it downloads the appropriate container image from Docker Hub and restarts without requiring manual intervention. Depending on your network speed, this process can take up to 10 minutes.

If you encounter issues with incomplete updates, please refer to our troubleshooting guidelines.

2.4. Monitoring the Relay

If you want to monitor the container in which you are running the Relay, you can add it to your monitoring using the mk_podman agent plug-in.

3. Monitoring with the Relay

3.1. Linking hosts to the Relay

Once you have set up the Relay, you can now start assigning hosts to it. When adding a host, tick Monitored on Relay in the Basic settings section and select the Relay that can contact the host you are currently adding. Note that hosts assigned to a Relay cannot be monitored using the Checkmk agent. Therefore, when creating hosts, in the Monitoring agents box, select one of the options for the Checkmk agent / API integrations setting that include no Checkmk agent.

You can then configure the desired type of monitoring for the assigned hosts using the rules provided for this purpose. You can choose between special agents, SNMP monitoring and, since Checkmk version 2.5.0p18, also a number of active checks.

Once the required rules have been configured, the Relay begins to retrieve the relevant data from the hosts and make it available to the monitoring system.

3.2. Monitoring the states of hosts with active checks

Since version 2.5.0p18 of Checkmk, the Relay allows you to run active checks on hosts that are accessible via the Relay but not directly from your Checkmk site. This is particularly useful for hosts that cannot be monitored using the Checkmk agent or for which a specific check interval is required.

The following active checks are available for Relay-monitored hosts:

  • Check hosts with ping (ICMP echo request) / check_icmp to check IP reachability and latency

  • Check certificates / check_cert to check certificates

  • Check HTTP web service / check_httpv2 to check the availability of web services

If necessary, you can customize the maximum number of concurrently running helpers for active checks for a specific Relay. The setting for this is called Maximum concurrent active-check helpers and is set to the value 5 by default. You can find this setting via Setup > Hosts > Relays by clicking the edit icon (Edit icon).

To use active checks for Relay-monitored hosts, first configure the desired active checks. Then use the rule under Setup > Hosts > Host monitoring rules > Host check command to derive the state of a host from the previously configured service.

3.3. Configuration updates

Each Relay regularly contacts its assigned Checkmk site for configuration updates. Once an updated configuration has been received, it immediately carries out the checks for newly added services. A service discovery for special agents should be completed quickly; however, it may take longer with slow SNMP devices. Generally, the delay caused by the Relay is marginal and, in most cases, amounts to just a few seconds.

4. Troubleshooting

Reminder: This component of Checkmk is a work in progress! Although it is already quite stable, you may encounter the occasional bug.

If you encounter technical issues, it may be helpful to examine the behavior and status of the Relay and the container in which it is running. On Windows, start by switching to the WSL environment:

PS C:\Users\hhirsch> wsl.exe -d Ubuntu-Checkmk-Relay
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

On Linux systems the above WSL switch is not necessary.

All commands shown below can be executed directly on Linux systems, and on Windows systems after switching to the WSL environment.

4.1. Checking the Relay’s operating status

You can use systemctl at any time to check whether the Relay is active and view details about its operating status:

user@host:~$ systemctl status checkmk_relay
● checkmk_relay.service - Checkmk Relay Container
     Loaded: loaded (/etc/containers/systemd/checkmk_relay.container; generated)
     Active: active (running) since Mon 2026-10-19 10:13:58 UTC; 1min 55s ago
   Main PID: 21434 (conmon)
      Tasks: 27 (limit: 11791)
     Memory: 573.0M (peak: 573.4M)
        CPU: 5.589s
     CGroup: /system.slice/checkmk_relay.service
             ├─libpod-payload-f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6
             │ ├─21446 python3 /opt/check-mk-relay/bin/cmk-relay daemon
             │ ├─21497 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21498 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21499 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21500 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21501 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21502 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21503 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21504 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21505 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21506 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21507 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21508 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21509 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─21510 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             │ ├─21511 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             │ ├─21512 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             │ ├─21513 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             │ ├─21514 /opt/check-mk-relay/lib/cmc/checkhelper
             │ ├─21515 /opt/check-mk-relay/lib/cmc/checkhelper
             │ ├─21516 /opt/check-mk-relay/lib/cmc/checkhelper
             │ ├─21517 /opt/check-mk-relay/lib/cmc/checkhelper
             │ └─21518 /opt/check-mk-relay/lib/cmc/checkhelper
             └─runtime
               └─21434 /usr/bin/conmon --api-version 1 -c f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6 -u f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6 -r /usr/bin/runc -b /var/lib/containers/storage/overlay-containers/f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6/userdata -p /run/containers/storage/overlay-containers/f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6/userdata/pidfile -n checkmk_relay-container --exit-dir /run/libpod/exits --full-attach -l journald --log-level warning --syslog --runtime-arg --log-format=json --runtime-arg --log --runtime-arg=/run/containers/storage/overlay-containers/f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6/userdata/oci-log --conmon-pidfile /run/containers/storage/overlay-containers/f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6/userdata/conmon.pid --exit-command /usr/bin/podman --exit-command-arg --root --exit-command-arg /var/lib/containers/storage --exit-command-arg --runroot --exit-command-arg /run/containers/storage --exit-command-arg --log-level --exit-command-arg warning --exit-command-arg --cgroup-manager --exit-command-arg systemd --exit-command-arg --tmpdir --exit-command-arg /run/libpod --exit-command-arg --network-config-dir --exit-command-arg "" --exit-command-arg --network-backend --exit-command-arg netavark --exit-command-arg --volumepath --exit-command-arg /var/lib/containers/storage/volumes --exit-command-arg --db-backend --exit-command-arg sqlite --exit-command-arg --transient-store=false --exit-command-arg --runtime --exit-command-arg runc --exit-command-arg --events-backend --exit-command-arg journald --exit-command-arg container --exit-command-arg cleanup --exit-command-arg --rm --exit-command-arg f3ff62713b3a6b12b338d3deba1aad69e38794ee59258ab6e45c174f376464f6
user@host:~$ sudo podman container list
CONTAINER ID  IMAGE                                 COMMAND               CREATED         STATUS         PORTS       NAMES
f3ff62713b3a  localhost/checkmk_relay:checkmk_sync  sh -c cmk-relay d...  10 minutes ago  Up 10 minutes              checkmk_relay-container
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

4.2. Verifying the version of the Relay

The version of the Relay container image must exactly match the version of the Checkmk site to which it is assigned. You can verify the Relay version using the podman images command. Run this command as root or with sudo prefixed to ensure that the output includes all relevant images:

root@linux# podman images
REPOSITORY                        TAG           IMAGE ID      CREATED       SIZE
docker.io/checkmk/check-mk-relay  2.5.0b1       423f9b67558b  5 months ago  428 MB
localhost/checkmk_relay           checkmk_sync  72c27637aa5a  5 months ago  428 MB
docker.io/checkmk/check-mk-relay  2.5.0b2       72c27637aa5a  5 months ago  428 MB
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

4.3. Restarting the container

As mentioned earlier, Podman is tightly integrated with systemd. Therefore, restarting containers is simply a matter of restarting systemd units.

root@linux# systemctl restart checkmk_relay
root@linux# systemctl status checkmk_relay
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

4.4. Status of the update service

When deploying using the included installation script, the Checkmk Relay sets up a service that automatically updates the container image to the same version as the associated site and then restarts the container.

To check the status of the update service for the Checkmk Relay, run the following command:

user@host:~$ systemctl status checkmk_relay-update-manager
○ checkmk_relay-update-manager.service - Checkmk Relay Update Manager
     Loaded: loaded (/etc/systemd/system/checkmk_relay-update-manager.service; static)
     Active: inactive (dead)
TriggeredBy: ● checkmk_relay-update-manager.path
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

The service has been loaded here, but no update has been performed yet. As the update itself will only start once the relevant trigger file has been modified, the service displays the (misleading) status inactive (dead) in the output shown above.

If you notice that the Relay is in an error state because an update could not be performed, you can resolve this issue manually. First, reset the error status of the update service:

root@linux# systemctl reset-failed checkmk_relay-update-manager.service checkmk_relay-update-manager.path
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

After that, you can restart the update service:

root@linux# systemctl restart checkmk_relay-update-manager.path
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

Finally, check to make sure the status of the update service is okay after the restart.

user@host:~$ systemctl status checkmk_relay-update-manager.path checkmk_relay-update-manager.service --no-pager
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

If you manually restart the service and check its status immediately afterward, you may see output similar to the following:

user@host:~$ systemctl status checkmk_relay-update-manager
● checkmk_relay-update-manager.service - Checkmk Relay Update Manager
     Loaded: loaded (/etc/systemd/system/checkmk_relay-update-manager.service; static)
     Active: activating (start) since Tue 2026-10-20 17:47:38 CET; 46s ago
TriggeredBy: ● checkmk_relay-update-manager.path
   Main PID: 47108 (checkmk_relay-u)
      Tasks: 12 (limit: 9484)
     Memory: 772.8M (peak: 780.0M)
        CPU: 15.249s
     CGroup: /system.slice/checkmk_relay-update-manager.service
             ├─47108 /bin/bash /usr/local/bin/checkmk_relay-update-manager.sh
             └─47110 podman pull docker.io/checkmk/check-mk-relay:2.5.0p3
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

Here, the running podman pull process shows that an update is currently in progress and that the latest container is being downloaded.

4.5. Checking log files

If something is not working properly or your support contact at Checkmk asks you for log entries, check the container logs. Use journalctl with the -f option (like follow) to display ten log lines and immediately output any new lines as they arrive:

root@linux# journalctl -u checkmk_relay.service -f
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,711 - cmk.relay.processors.configuration - INFO - Adding task for processing new configuration [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","serial":"4","type":"'ConfigUpdateTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,711 - cmk.relay.processors.configuration - INFO - Processing configuration update task [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","serial":"4","type":"'ConfigUpdateTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,711 - cmk.relay.processors.configuration - INFO - Extracting config update [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","serial":"4","type":"'ConfigUpdateTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,715 - cmk.relay.processors.configuration - INFO - Config update extracted [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","serial":"4","type":"'ConfigUpdateTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,717 - cmk.relay.processors.configuration - INFO - Updated 'latest' symlink to point to serial '4' [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","serial":"4","type":"'ConfigUpdateTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,717 - cmk.relay.processors.configuration - INFO - Successfully unpacked configuration [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","serial":"4","type":"'ConfigUpdateTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,717 - cmk.relay.processors.subprocess_pool - INFO - Scaling pool fetcher to size: 13 [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","type":"'ApplyConfigTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,717 - cmk.relay.processors.subprocess_pool - INFO - Scaling pool adhoc-fetcher to size: 4 [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","type":"'ApplyConfigTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,718 - cmk.relay.processors.subprocess_pool - INFO - Scaling pool checkhelper to size: 5 [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","type":"'ApplyConfigTask'"}]
Oct 19 10:13:31 relayhost checkmk_relay-container[8525]: 2026-10-19 10:13:31,718 - cmk.relay - INFO - Log level set: INFO [context: {"id":"'c19550be-3d65-416a-857e-2fc95da94038'","type":"'ApplyConfigTask'"}]
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

4.6. Troubleshooting on Windows

You can find hints for resolving specific issues with running the Relay on Windows in the Checkmk Knowledge Base.

5. Removing the Relay

If the Relay is no longer required, you can uninstall it.

Linux
Windows
Linux

To uninstall, run the installation script with the --uninstall option, which will remove the Relay without further prompting.

root@linux# bash install_relay.sh --uninstall
=== Checkmk Relay Installer ===
[2026-03-14 11:52:55] [INFO] Checking prerequisites for uninstall...
[2026-03-14 11:52:55] [INFO] Uninstalling Checkmk Relay...
[2026-03-14 11:52:55] [INFO] Stopping services...
[2026-03-14 11:53:06] [INFO] Disabling services...
[2026-03-14 11:53:07] [INFO] Removing installed files...
[2026-03-14 11:53:07] [INFO] Removing data directories...
[2026-03-14 11:53:07] [INFO] Reloading Systemd daemon...
[2026-03-14 11:53:07] [INFO] Removing Podman volumes...
relay
[2026-03-14 11:53:07] [INFO] Relay uninstalled.

--------------------------------------------------------
The Checkmk Relay has been removed.
--------------------------------------------------------
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!
Windows

Don’t forget to delete the associated Relay in your Checkmk site after you have removed the Relay.


Last modified: Thu, 12 Nov 2026 11:38:58 GMT via commit ca992376b
On this page