/
TLS compatibility issues in agent updater with Checkmk 2.3 on Windows

TLS compatibility issues in agent updater with Checkmk 2.3 on Windows

Owned by Matthew Hierholzer
May 23, 2025

In Checkmk 2.3, the Agent Updater on Windows may run into new TLS issues due to updates to Python and OpenSSL.

LAST TESTED ON CHECKMK 2.3.0P1

Table of Contents


Overview

When using the Agent Updater in Checkmk 2.3, especially on Windows hosts, you may encounter TLS-related issues that didn’t appear in earlier versions. This is due to significant changes in the underlying Python and OpenSSL versions shipped with the agent, including a stricter requirement in OpenSSL 3 for certificates to include a Subject Alternative Name (SAN). Certificates without SANs, which were previously tolerated, will now cause connection failures.


Why SAN Entries Matter

The Subject Alternative Name (SAN) is a required extension in modern TLS. It tells clients which domains, IPs, or hostnames the certificate is valid for. 

Without a SAN, OpenSSL 3 will reject the certificate, even if it’s otherwise valid.

Certificates issued without SANs might still work on older clients, but they are non-compliant with modern standards and will break on newer platforms like Checkmk 2.3 Windows agents.


What Changed?

With Checkmk 2.3, the Windows agent now includes:

  • Python 3.12

  • OpenSSL 3.0.11 (updated later to 3.0.13)

By contrast, previous versions (like Checkmk 2.2) shipped with:

  • Python 3.10

  • OpenSSL 1.1.1m

This update is important because OpenSSL 3 introduced stricter security requirements, which can impact how the Agent Updater interacts with your monitoring infrastructure.


The Problem: Missing SAN Entries

OpenSSL 3 has dropped support for several deprecated protocols and configurations, one of them being certificates without Subject Alternative Name (SAN) entries.

If your monitoring site uses certificates missing these SAN fields, the Agent Updater will likely fail to connect, resulting in TLS errors. This affects Windows hosts more readily, since they’re using the stricter OpenSSL 3, while Linux agents (still using Python 3.8 with OpenSSL 1.1.1) tolerate these certificates, for now.

Example Error Symptoms

  • TLS handshake errors

  • Certificate validation failures

  • Agent updater not being able to reach the monitoring site


Why Linux Isn’t Affected (Yet)

On Linux, Checkmk is still shipping the agent with Python 3.8 and OpenSSL 1.1.1, which are more lenient with deprecated certificate configurations. This means the issue may not show up unless those components are updated.

However, it’s likely this will change in future versions, so it’s a good idea to future-proof your configuration now.


Solution and Workaround

To resolve or avoid these issues:

  • Ensure your server certificates include SAN entries.

  • Review your TLS configurations to meet OpenSSL 3 requirements.

We recommend checking out this blog post for more detailed guidance: How to monitor servers with broken TLS in Checkmk


Summary

Agent VersionPythonOpenSSLAffected by missing SAN?
2.2 (Windows)3.101.1.1m❌ Not affected
2.3 (Windows)3.123.0.11+✅ Yes
2.x (Linux)3.81.1.1❌ Not affected (yet)


If you're experiencing issues with agent updates on Windows in Checkmk 2.3, checking your certificate configuration is a great place to start.