Checkmk
Deutsch
Cloud (SaaS) masterlatest (2.4.0)2.3.02.2.02.1.02.0.01.6.0
to checkmk.com

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.

Tip

The functionality presented here is a technical preview, i.e. a preview of a new feature that will be subject to development and expansion until further notice. During this phase, it is possible that functionality will not only be added, but also modified in such a way that existing configurations will become obsolete and you will have to recreate them. We ask for your understanding in this matter.

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.

1.3. Supported platforms

The Checkmk Relay is distributed as a container for the x86-64 platform. For installation, we provide an installation script that requires the distribution-supplied Podman package to be present. Currently, the installation script supports Ubuntu Linux 24.04 as well as Red Hat Enterprise Linux 8.10, 9.7 and 10.

We decided for Podman since its tight integration with Systemd facilitates automatic updates of the Relay container. Deployment on other container platforms than Podman, on other distributions than those mentioned, updating using other ways than directly accessing hub.docker.com, using other Podman packages than the distribution supplied ones or running multiple relays on a single Linux host might work for experienced users — however, Checkmk will not provide support for such environments.

The Relay on Windows

We are currently in progress testing the Relay on Windows. To be precise: on Windows Subsystem for Linux (aka WSL). So far, we had positive results with WSL2, with Systemd enabled, using the latest stable WSL2 (2.6.3 as of the time this text last being edited) and running Ubuntu 24.04 atop.

Windows Server 2025 enables all dependencies needed by just running:

PS C:\whatever> wsl.exe --install
PS C:\whatever> wsl.exe --update
PS C:\whatever> wsl.exe --install -d Ubuntu
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

For older Windows versions, you have to manually ensure that WSL2 is selected and Systemd is used as init system. We will create check and installation scripts during the months after Checkmk 2.5.0 release.

2. Setup

For easy download, installation and association, we provide an installation script. To retrieve the URL of the installation script, navigate to Setup > Hosts > Relays. There, click the Add Relay configuration button to start the assistant for configuring a new Relay.

Quicksetup for a new Relay showing the first step with a curl command to download the installation script
In the first step, you are presented with the download URL of the installation script

Follow the instructions the assistant provides. After some preparatory steps, you will be presented with the parameters to run the script. This will download and configure the container with the Relay, install the update service and associate the Relay with the Checkmk site in a single step.

Tip

The parameters offered for copy and pasting the command for installation and registration contain a one-time token. This is valid for one hour after generation. In case this one hour is not sufficient, you can authenticate with the user name and password of a user with sufficient privileges to register the Relay.

After installation, check the running state with the following commands:

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!

On the Checkmk site to which you just added the Relay, activate the changes to complete the registration of the Relay.

3. Monitoring via Relay

After configuring your Relay, you are now all set to use it to start monitoring hosts via special agents or SNMP. When adding a host, activate Monitored on Relay in the Basic settings box and select the Relay that can connect to the host you are adding. Keep in mind that monitoring hosts with the Checkmk agent is currently not possible if the hosts are assigned to a Relay.

The Relay will only start monitoring the hosts assigned to it once the special agents or SNMP connections for those hosts are configured.

Each Relay contacts its associated Checkmk site frequently for configuration updates and runs special agents and other checks immediately after pulling an updated configuration. A service discovery for special agents should complete quickly, though sluggish SNMP devices may take longer.

4. Updates

The Checkmk Relay keeps itself up to date automatically. Once it detects that the version of the associated Checkmk site has changed, it pulls the matching container image from Docker Hub and restarts without any manual intervention. Depending on your network speed, this process can take up to 10 minutes.

5. Troubleshooting

Remember, this component of Checkmk is work-in-progress! While generally quite stable, you might encounter bugs.

5.1. Check the version of the Relay

The version of the Relay container image must match the exact version of the Checkmk site it is connected to. You can check the version with the podman images command. Running this command as root or prefaced with sudo ensures that the list 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!

When deployed with the supplied installation script, the Checkmk Relay installs a service that automatically updates the container image to the same version as the associated site and restarts the container afterwards.

To check the state of the update manager for the Checkmk Relay, run:

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!

Here, the service is loaded, but no update has been performed yet. Since the update itself only is triggered when a file appears, it has the (misleading) state inactive (dead).

When manually restarting the service and checking the status immediately afterwards, you might encounter an output like this:

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 indicates that an update is running and the newest container is currently being downloaded.

5.2. Restart the container

As hinted above, Podman tightly integrates with Systemd. Thus, container restarts are simple restarts of 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!

5.3. Tail the container logs

In cases something is not running correctly or your support contact at Checkmk asks you for log lines, you will want to peek at the container logs. Use journalctl with the -f (as in follow) option to show ten log lines and print added log lines as well:

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!

5.4. Removing the relay

In case you do not need a relay anymore, the installation script provides an --uninstall switch that removes the Relay without further asking.

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!

Don’t forget to delete the connected Relay in your Checkmk site after purging the Relay.

Last modified: Sat, 25 Apr 2026 03:59:20 GMT via commit 4d8f6623c
On this page