Checkmk
DeutschEspañolFrançaisItaliano日本語
Cloud (SaaS)Cloud master2.4.02.3.02.2.02.1.02.0.01.6.0
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.

Using the Relay in combination with distributed monitoring is currently limited to the central site. This also means that there is typically 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:

Work on extending functionality towards running active checks is currently under way. 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. If compatible versions of Podman and Systemd are found, the script will prompt you to either abort or proceed with an unsupported installation.

Windows: Connection to GitHub

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.

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

If you install and register the Relay multiple times on the same system, your Checkmk site will treat each installation as a 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

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

Once you have set up the Relay, you can now start using it to monitor hosts via a special agent or SNMP. When adding a host, enable 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 with the Checkmk agent.

The Relay will not begin monitoring the assigned hosts until special agents or SNMP connections have been configured for those hosts.

Each Relay periodically contacts its assigned Checkmk site for configuration updates. After receiving an updated configuration, it immediately executes the special agents and other checks. A service discovery for special agents should be completed quickly, but it may take longer with slow SNMP devices. In general, the delay caused by the Relay is marginal and, in most cases, is in the range of 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 Thu 2026-03-19 07:44:27 UTC; 2h 41min ago
   Main PID: 2063 (conmon)
      Tasks: 21 (limit: 4646)
     Memory: 669.5M (peak: 686.2M)
        CPU: 1min 38.577s
     CGroup: /system.slice/checkmk_relay.service
             ├─libpod-payload-cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439
             │ ├─2067 python3 /opt/check-mk-relay/bin/cmk-relay daemon
             │ ├─2113 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2114 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2115 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2116 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2117 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2118 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2119 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2120 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2121 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2122 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2123 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2124 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2125 python3 /opt/check-mk-relay/bin/fetcher
             │ ├─2126 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             │ ├─2127 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             │ ├─2128 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             │ └─2129 python3 -m cmk.fetcher_helper.fetch_ad_hoc
             └─runtime
               └─2063 /usr/bin/conmon --api-version 1 -c cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439 -u cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439 -r /usr/bin/crun -b /var/lib/containers/storage/overlay-containers/cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439/userdata -p /run/containers/storage/overlay-containers/cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439/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/cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439/userdata/oci-log --conmon-pidfile /run/containers/storage/overlay-containers/cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439/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 crun --exit-command-arg --events-backend --exit-command-arg journald --exit-command-arg container --exit-command-arg cleanup --exit-command-arg --rm --exit-command-arg cd8f4482262c4812546c5cf25796548037a1cb0cacca4a23e239a6a6d1a5d439
user@host:~$ sudo podman container list
CONTAINER ID  IMAGE                                 COMMAND               CREATED         STATUS         PORTS  NAMES
6c5bf8861dc5  localhost/checkmk_relay:checkmk_sync  sh -c cmk-relay d...  49 minutes ago  Up 49 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. Since the update itself is only triggered when a file appears, the service displays the (misleading) status inactive (dead).

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 (/home/ubuntu/.config/systemd/user/checkmk_relay-update-manager.service; enabled; preset: enabled)
     Active: activating (start) since Tue 2026-01-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: /user.slice/user-1000.slice/user@1000.service/app.slice/checkmk_relay-update-manager.service
             ├─47108 /bin/bash /home/ubuntu/.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:

user@host:~$ journalctl -u checkmk_relay.service -f
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,944 - cmk.relay.processors.configuration - INFO - Extracting config update [context: {"type":"'ConfigUpdateTask'","id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'","serial":"56"}]
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,946 - cmk.relay.processors.configuration - INFO - Config update extracted [context: {"type":"'ConfigUpdateTask'","id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'","serial":"56"}]
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,947 - cmk.relay.processors.configuration - INFO - Updated 'latest' symlink to point to serial '56' [context: {"type":"'ConfigUpdateTask'","id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'","serial":"56"}]
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,947 - cmk.relay.processors.configuration - INFO - Successfully unpacked configuration [context: {"type":"'ConfigUpdateTask'","id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'","serial":"56"}]
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,948 - cmk.relay.processors.fetcherpool - INFO - Scaling fetcher pool adhoc to size: 4 [context: {"type":"'ApplyConfigTask'","id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'"}]
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,948 - cmk.relay.processors.fetcherpool - INFO - Scaling fetcher pool relay to size: 13 [context: {"type":"'ApplyConfigTask'","id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'"}]
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,948 - cmk.relay - INFO - Log level set: INFO [context: {"type":"'ApplyConfigTask'","id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'"}]
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,949 - cmk.relay.processors.site_client - INFO - Using serial '56'
Mar 14 11:01:30 relay checkmk_relay-container[2783]: 2026-03-14 11:01:30,949 - cmk.relay.processors.site_client - INFO - Submitting Result [context: {"id":"'ab63eee2-71ef-40db-92ae-d47606cf7917'"}]
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: Fri, 31 Jul 2026 08:09:33 GMT via commit 760fa229e
On this page