/
Troubleshooting the Checkmk Relay on Windows (WSL2)

Troubleshooting the Checkmk Relay on Windows (WSL2)

This article helps you detect and resolve issues that are specific to running the Checkmk Relay on Windows. Because the Relay on Windows runs inside a Linux environment provided by WSL2 (Windows Subsystem for Linux 2), most "the Relay isn't working" problems on Windows are actually problems in one of the layers below it.

LAST TESTED ON CHECKMK 2.5.0P10

Table of Contents

How the Relay runs on Windows

On Windows the Relay does not run natively. The MSI installer sets up a dedicated WSL2 Linux environment and runs the existing Linux Relay inside it.

The stack looks like this:

Windows Server (host)
└── WSL2
    └── Ubuntu-Checkmk-Relay        (dedicated Ubuntu 24.04 distro, fixed name)
        └── systemd

 

Two mechanisms ensure the Relay keeps running even across reboots:

  • A scheduled task in Windows named StartCheckmkRelayAtLogon starts the WSL distro after a reboot (no user login required) and restarts it if it is terminated.

  • On the Ubuntu distro inside of WSL, systemd keeps checkmk_relay.service running with Restart=always.

 

Key locations and names you will use throughout this article:

Item

Value

Item

Value

WSL distro name

Ubuntu-Checkmk-Relay (fixed and reserved — do not rename)

Relay service (inside distro)

checkmk_relay.service

Windows scheduled task

StartCheckmkRelayAtLogon

Install directory

C:\Program Files\checkmk\relay\

Log directory

C:\ProgramData\checkmk\relay\logs\

Run diagnostics from an elevated session

All commands below require an Administrator PowerShell or Command Prompt. The Relay scripts and most WSL operations fail silently or with permission errors otherwise.

 

 

Quick health check

Run these in an elevated PowerShell, top to bottom. The first command that returns an unexpected result tells you which layer to investigate.

# 1. Is WSL2 present and which kernel? # WSL version must be >=2.1 wsl --version # 2. Default version + last kernel update # Must show "Default Version: 2" wsl --status # 3. Is the Relay service active? # Must show "active" wsl -d Ubuntu-Checkmk-Relay -- systemctl is-active checkmk_relay.service  # 4. Is the Relay container running? # Must show the running "checkmk_relay-container" container wsl -d Ubuntu-Checkmk-Relay -- podman ps # 5. Will the Relay survive a reboot? # Must show the scheduled task "StartCheckmkRelayAtLogon" in the state "running" Get-ScheduledTask -TaskName StartCheckmkRelayAtLogon

 

 

Connectivity and registration

These are not strictly WSL problems, but they surface the same way ("Relay not registered / not monitoring") and are worth ruling out once the stack below them is healthy.

Symptom

Likely cause

What to check / do

Symptom

Likely cause

What to check / do

Install fails right after pulling the image; log shows an auth error

Registration token expired, tokens are valid for 1 hour

Generate a fresh one-time token in the wizard and re-run the install promptly

Install fails with a connection error

Target server unreachable from the host

Verify TARGET_SERVER / site name; test reachability from the Windows host to the Checkmk site

Install fails; log contains HTTP 400

Duplicate relay name already registered

Use a unique relay name, or remove the existing registration on the site first

Service runs but the site stops showing data

mTLS / proxy / firewall between host and site

Confirm outbound connectivity from the host; check any proxy configuration

 

Re-running the installer does not re-attach an old registration

Reinstalling registers a new Relay, and monitored hosts must be re-assigned to it. Use a deliberate, unique relay name.

 

 

Installation issue: Windows / WSL platform

These problems usually appear during installation, before the Relay distro is ever created.


Symptom: MSI aborts immediately, no files installed

By design the installer runs a launch condition that fails before copying any files if WSL2 is not available. C:\Program Files\checkmk\relay\ will not exist.

 

Detect

# error or "not recognized" = WSL not installed wsl --version wsl --status

 

 

Common WSL platform errors and what they mean

The error codes below are shown in the console when the WSL installation fails. 

Error code

Meaning

Fix

Error code

Meaning

Fix

0x8007019e

The Windows Subsystem for Linux optional component is not enabled

Enable WSL (see below) and reboot

0x80370102 / 0x80070003

Virtualization / Virtual Machine Platform not available

Enable virtualization in BIOS/UEFI and the Virtual Machine Platform feature

0x1bc

The WSL2 kernel needs updating

Install the standalone WSL release (see fix below); wsl --update --web-download


Fix: enable and update WSL2 and install the standalone WSL release (≥ 2.1.0)

Use the standalone WSL release, not the in-box Windows feature

The Relay requires WSL tool version 2.1.0 or newer. The in-box WSL (the Windows optional component) ships an outdated kernel that the Relay cannot run on, and it has not been updated meaningfully since Windows 21H2. Simply enabling the Windows feature is not sufficient. The supported WSL builds are published at Microsoft WSL Github.

 

# 1. Install or update to the STANDALONE WSL release (>= 2.1.0 required). # Do NOT rely on the in-box Windows feature: it ships an outdated kernel # the Relay cannot run on. On Windows Server (no Microsoft Store), pull # the package directly from GitHub with --web-download. Newly installing # WSL 2 requires a reboot. wsl --install --web-download --no-distribution; Restart-Computer -Confirm wsl --update --web-download # 2. Verify the WSL tool version is 2.1.0 or newer. # If this errors with "unrecognized option", you are STILL on the in-box # version -> install the MSI manually from # https://github.com/microsoft/WSL/releases wsl --version # 3. Set the default version wsl --set-default-version 2

 

For running WSL2 your system needs to have virtualization enabled. If Windows runs on a VM, the VM must support nested virtualization. This is usually disabled by default and must be enabled at the hypervisor/cloud level, not inside Windows.

 

After WSL2 is working, re-run the installer using the supported steps in Setup → Hosts → Relays → Add Relay (Windows tab).

 

Symptom: WSL commands hang and never return

The WSL service can wedge. Restart it, then re-check:

wsl --shutdown # If still unresponsive: taskkill /f /im wslservice.exe wsl --list --verbose

 

 

Installation issue: The Relay distro (Ubuntu-Checkmk-Relay)

Symptom: distro is missing

wsl --list --verbose

If Ubuntu-Checkmk-Relay is not listed, the WSL setup stage did not complete. Re-run the installation from the supported wizard steps. Do not try to import an arbitrary Ubuntu distro manually  the name Ubuntu-Checkmk-Relay is reserved and the Relay tooling looks for it specifically.


Symptom: distro is listed but state is Stopped

A stopped distro means the Relay is not running. This is normal immediately after boot for a few moments while the scheduled task starts it, but it should not persist.


Detect

wsl --list --verbose # should be Ready Get-ScheduledTask -TaskName StartCheckmkRelayAtLogon

 

Fix: start it manually to confirm it can run, then check persistence

# forces the distro to start wsl -d Ubuntu-Checkmk-Relay -- true # should now show Running wsl --list --verbose

If it starts manually but keeps stopping on its own, the keepalive scheduled task is the problem, see below.

 

 

Installation issue: Container runtime (Podman)

Symptom: the relay image was not pulled

Detect

wsl -d Ubuntu-Checkmk-Relay -- podman images wsl -d Ubuntu-Checkmk-Relay -- podman ps -a

If no relay image is present, the install step that pulls the image failed. Almost always a network/connectivity problem to the image source on Docker Hub.  Check the log in C:\ProgramData\checkmk\relay\logs\

 

 

The Relay service

Symptom: distro, systemd, and Podman are healthy, but the Relay is not working


Detect

wsl -d Ubuntu-Checkmk-Relay -- systemctl status checkmk_relay.service wsl -d Ubuntu-Checkmk-Relay -- journalctl -u checkmk_relay.service --no-pager -n 100

 

Interpret

  • active (running)
    The service is up; if monitoring still isn't working, move to connectivity/registration).

  • activating / restart loop
    systemd is restarting it repeatedly (Restart=always). The journal output shows why. The most common causes are an expired token or an unreachable target server at first start, see "Connectivity and registration".

  • inactive / failed
    Read the journal lines for the failure reason.



Runtime issue: Reboot survival and keepalive

Symptom: the Relay does not come back automatically after a Windows reboot

The Relay is expected to come back automatically after a Windows reboot, with no user login.

Detect

# State should be Ready Get-ScheduledTask -TaskName StartCheckmkRelayAtLogon # LastRunTime / LastTaskResult Get-ScheduledTaskInfo -TaskName StartCheckmkRelayAtLogon # distro should be Running wsl --list --verbose

 

Symptoms and fixes

  • Scheduled task missing
    The installation did not complete, or the task was removed by a policy/cleanup tool. Reinstall the Relay.

  • Task present but state Disabled: re-enable it:

    Enable-ScheduledTask -TaskName StartCheckmkRelayAtLogon

 

Logs

The installer and uninstaller write timestamped transcripts to a well-known Windows location:

C:\ProgramData\checkmk\relay\logs\     install-*.log     uninstall-*.log

  • A successful install leaves an install-*.log containing a success marker.

  • A failed install leaves an install-*.log capturing the failure cause (e.g. the HTTP error code or connection-error detail).

  • Logs are preserved across uninstall and reinstall, and entries are appended rather than overwritten, so the history of attempts stays intact.

 

For the runtime side, the authoritative logs live inside the distro

wsl -d Ubuntu-Checkmk-Relay -- journalctl -u checkmk_relay.service --no-pager -n 200

 

 

Reinstalling the Relay

Repair (msiexec /f) and reinstall-over-existing are intentionally disabled; reinstalling over an existing install is rejected (exit code 1638).

To get a clean install:

  1. Uninstall via the MSI (msiexec /x CheckmkRelayInstaller.msi /quiet) or Programs and Features. This removes the distro, the install directory, and the StartCheckmkRelayAtLogon scheduled task, while preserving the logs under C:\ProgramData\checkmk\relay\logs\.

  2. Confirm a clean state:

    # Ubuntu-Checkmk-Relay should be absent wsl --list --verbose # should error: task not found Get-ScheduledTask -TaskName StartCheckmkRelayAtLogon

     

  3. Generate a fresh registration token and run the installation again from Setup → Hosts → Relays → Add Relay (Windows tab).

Reinstalling creates a new Relay registration. Monitored hosts must be re-assigned to the newly registered Relay.

 

Related articles