Update to version 2.3.0

As with any update to production software, you should check that your backups are up to date before performing the update of Checkmk.

Does this affect you? Yes.

What will you need to do? If you create your backups automatically via Setup > Maintenance > Backups, check there that your backups are up to date and that the most recent backup jobs have completed without errors.

For more information, see the articles on Backups and on Backing up and restoring sites.

Checkmk 2.3.0 requires slightly higher system resources than 2.2.0. It is therefore advisable to find out before updating which free capacity the servers used for Checkmk still have.

Does this affect you? Yes, but the extent to which you are affected depends heavily on how you use Checkmk. Alone the updating of the Python interpreter from version 3.11 to 3.12 results in an increase in CPU load in the single-digit percentage range. Furthermore — depending on the proportion to the total number of checks — the more extensive checks in 2.3.0, especially in the cloud area, can result in further additional load, so that a total of 10-15 % (in extreme cases around 20 %) more CPU load can be expected.

What will you need to do? Make sure that there is sufficient free capacity available. As a rule of thumb: If the CPU load is below the number of processor cores x 0.8 and the CPU utilization is below 70 %, no problems should be expected. If one or both values are higher, create sufficient free capacity, for example by deactivating test sites on the same server or moving hosts to other sites.

Some obsolete distributions will no longer be supported under Checkmk version 2.3.0.

Does this affect you? This will affect you if any of the following Linux distributions — still supported in 2.2.0 — is installed on your Checkmk server:

What will you need to do? Before updating Checkmk, first perform a Linux distribution version upgrade. Make sure that the target version of the Linux distribution of Checkmk is 2.2.0 and that 2.3.0 is supported. You can find out which Linux distribution versions Checkmk supports in the update matrix for 2.3.0 and on the download page after you have selected the Checkmk version and your Linux distribution.

Shortly after the release of Ubuntu 24.04 LTS, we will provide Checkmk 2.2.0 and 2.3.0 packages for this distribution version. This will allow you to first update to the latest patch version of Checkmk 2.2.0, then update from Ubuntu 23.10 STS to 24.04 LTS and finally update to the latest patch version of Checkmk 2.3.0.

With Checkmk version 2.3.0 (and 2.2.0p21) on SUSE Linux Enterprise Server 15 Service Pack 3 and 4, the dependency on the PHP programming language runtime environment is raised from version 7 to version 8.

Does this affect you? Yes, as a user of SLES 15 SP3/SP4. The update is somewhat more complex, as package sources for the outdated version 7 must be deactivated and activated for the new version 8.

What will you need to do? If, in addition to Checkmk applications on your server that use the PHP programming language, make sure that they can handle PHP 8 without any problems. Then prepare the package sources for the update to 2.2.0p21 (or higher), which is mandatory for the installation of Checkmk 2.3.0, as described in Werk #16025.

Checkmk 2.3.0 uses new JavaScript features that are not available in older browsers. Which browsers are supported in which versions can be found in the Release notes.

Does this affect you? You will usually have automatic updates to the latest version enabled on desktop systems.

What will you need to do? Check the browser version you are using and install a more recent browser if necessary. If you are using Single Board Computers, Smart TVs or Digital Signage solutions to display dashboards and you have no control over the system browser, test that any required dashboards are displayed correctly before updating. If necessary, contact the hardware manufacturer for updates.

For the first time, Checkmk 2.3.0 provides OpenSSL in version 3.0 instead of the previous 1.1. This change affects almost all components that use Secure Socket Layer or Transport Level Security.

Does this affect you? As OpenSSL 3 is now widely used, hardly any surprises are to be expected. Problems can occur — especially with active checks — if connections are to be established to devices that expect old ciphers or attempt renegotiation. These are usually old network devices (switches, printers…​) that no longer receive updates. In some cases, services on older Linux distributions or Unix versions are affected, which are still supplied with updates.

What will you need to do If possible, try to find out in advance which devices are likely to have problems. Good indicators for this are age and how long ago updates were installed. Test these devices with Checkmk 2.3.0. If problems occur, you have two options:

With Checkmk 2.3.0, Checkmk MSP has changed its foundation from Checkmk Enterprise to Checkmk Cloud. This not only means that Checkmk MSP receives the extended range of functions of Checkmk Cloud, but also that the license management is aligned with that of Checkmk Cloud.

Does this affect you? This only affects users of Checkmk MSP, other forms of distributed monitoring are not affected.

What will you need to do? Updating a Checkmk MSP to 2.3.0 follows the general procedure in distributed environments with distributed setup. However, it must be ensured that the central site can still transfer the license information under Checkmk 2.2.0 to remote sites already updated on Checkmk 2.3.0.

As the necessary changes are only implemented in Checkmk 2.2.0p17 (Werk #16193), you must therefore update the central site to at least this version. This ensures the transfer of the license information. The remote sites can then be updated to 2.3.0 and finally the central site.

Irrespective of the minimum requirement for 2.2.0p17 mentioned here, we recommend that you first update all involved sites to the latest available patch version of 2.2.0 and only then start the update to 2.3.0.

Checkmk 2.3.0 no longer creates SHA1 signatures for agent packages. The verification of SHA256 signatures was introduced with Checkmk 2.2.0p8. In order for agent updates to version 2.3.0 to take place automatically, the agents must first be updated to version 2.2.0p8 or higher.

Does this affect you? This affects you if you perform automatic agent updates but occasionally skip patch versions of the agent. It also affects you if your deployment uses prepared operating system images that include the Checkmk Agent Updater and rely on automatic installation/update.

What will you need to do? Make sure that all agents that are to be updated automatically have been updated to at least version 2.2.0p8. In particular, verify prepared operating system images and update the existing agent to version 2.2.0p8 or higher. And if you are currently working on agent updates, you can already add the certificate provided by the agent bakery now, if this is required later.

Some plug-ins that were marked as deprecated have been removed and may require manual installation if needed: Werk #16359

The official support for the Checkmk agent under Windows Server 2008 and Windows 7 by Checkmk GmbH already ended with the release of Checkmk 2.2.0. Nevertheless, operation under Windows Server 2008 R2 and Windows 7 was still possible without restrictions. With 2.3.0, restrictions must be accepted: The previous option of supplying a Python 3.4 runtime environment for Windows agents via the agent bakery rule is no longer available in 2.3.0.

Does this affect you? Hopefully not: The discontinuation only affects you if you use agent plug-ins written in Python on Windows Server 2008 R2 or Windows 7 (both end-of-life already in 2020). Current Python versions run on all newer Windows versions. On all even older Windows versions — such as Windows Server 2008 R1 or Windows Vista — the agent could no longer be used in version 2.2.0.

What will you need to do? If you want to continue monitoring these Windows systems, you must provide the runtime environment for agent plug-ins that require Python yourself: Install Python 3.4 manually on affected systems. For these systems, usually set Setup > Agents > Windows, Linux, Solaris, AIX > Agent rules > Windows modules > Install Python runtime environment the setting Install Python runtime environment > Installation to Never install Python with the agent. Note that we cannot guarantee support for such old Windows systems and we no longer test new agent versions in patch releases.

mod_auth_mellon is a software module for Apache that provides services for authentication via the Secure Assertion Markup Language (SAML). The connection to SAML authentication services was possible in Checkmk 2.2.0 in two ways: At Apache level with mod_auth_mellon (the only supported option until version 2.1.0) or in the commercial editions of Checkmk the built-in SAML authentication. With version 2.3.0 mod_auth_mellon` is no longer delivered with the Checkmk software.

Does this affect you? This affects you if you use SAML authentication with mod_auth_mellon.

What will you need to do? Users of the commercial editions should switch SAML authentication to the solution integrated in Checkmk before updating to 2.3.0.

If you are using Checkmk Raw, you can already install mod_auth_mellon system-wide before the update according to the instructions on the project page. Then change the line for loading the module in the configuration file ~/etc/apache/conf.d/auth.conf to the system-wide installation path. The installation directory may vary depending on the distribution used:

Restart your site after making the change. Finally, test — still under 2.2.0 — whether SAML authentication continues to work. If this is the case, no difficulties are to be expected after the update.

Checkmk 2.3.0 updates Python from 3.11 to 3.12. This update affects modules installed to a Checkmk site. In many cases, post-installed modules are incompatible with Python 3.12. In the worst case, obsolete modules overwrite the functionality of the modules supplied by Checkmk.

Does this affect you? This will only affect you when you have explicitly-installed Python modules for special agents or agent-based check plug-ins that you have written yourself or obtained from the Exchange. If you are unsure, carry out the check described in the following section.

What will you need to do? First find out whether Python modules are installed in the site, and if so — identify them. To do this, search for the dist-info and egg-info directories:

Make a note of the installed modules and then uninstall them:

You can find out how to deal with uninstalled Python modules after the update below.

The Prometheus special agent offered kube-state-metrics as data source, whose checks are no longer supported. These have since been replaced by improved counterparts in the Kubernetes agent (see Werk #14572). In addition, in the Prometheus and Alertmanager rules, the specification of IP address/host name, port and path prefix has been replaced by a single input field Custom URL (see Werk #14573).

In both cases, the old method continued to work in 2.2.0. To use it in 2.3.0, however, you must have changed your configuration to the new method.

Local files allow you to customize and extend the functionality provided by Checkmk. These files are located in the local part of the site directory structure, i.e. in ~/local and can be located in extension packages or simply 'lying around'. Local files can cause problems during an update if they no longer match the new Checkmk version.

Does this affect you? Since it is not possible for Checkmk to fully ensure the compatibility of local adaptations during an update, you should check your Checkmk site before an update to see whether local files are used, which ones they are and how they are organized.

What will you need to do?

In Checkmk 2.3.0 some internal programming interfaces (APIs) have been rebuilt. Some previously ad-hoc defined APIs have been replaced by well-specified ones. In addition, the Check API already marked as deprecated in 2.0.0 has been permanently removed.

Does this affect you? The topic of APIs affects you if you have extended the checks delivered with Checkmk with your own, self-written checks and/or if you use plug-ins from other sources.

What will you need to do? Check the functionality of extensions you have written yourself and those from third-party providers. Since the new APIs can be used parallel to the old ones during Checkmk 2.3.0 and changes to the existing APIs could be small, most extensions will continue to be usable without modifications. If changes are necessary, we recommend migrating to the new APIs, which will be available from Checkmk 2.4.0 and completely replace the old APIs.

Deprecated endpoints or parameters of the Checkmk REST API are marked in the API documentation with the icon.

Does this affect you? This may affect you if you use the Checkmk REST API in your own scripts, for example.

What will you need to do? Open the REST API documentation with Help > Developer Resources > REST API documentation. Search for Deprecated in the browser on the page, check whether you are using deprecated elements in your scripts and replace them before updating. In the REST API documentation, you will usually find instructions on how to replace the functions that no longer exist in the new version.

As in every Checkmk version, there are also changes to the software in the current 2.3.0 version which may have repercussions on your Checkmk installation — at Checkmk these are organized and documented in what we refer to as our Checkmk Werks. A so-called incompatible change requires that you make manual modifications in order to allow existing functions to continue to run as usual and/or to be able to use new functions.

Does this affect you? In general, there will be incompatible changes that will also affect your Checkmk installation, it is however impossible to make a general statement. In this article we have collected those issues that apply to all or most Checkmk installations. In any case there may be additional changes that are relevant to you, for example in checks that you use in your installation.

What will you need to do? Following every update — including patch releases — Checkmk will show you the number and content of incompatible changes and ask you to check and take note of them. Before performing the update is the right time to check for any changes from version 2.2.0 that may have an impact on the update. Since Checkmk 2.3.0, such Werks are no longer carried over, but are deleted during the update after approving a confirmation dialog (Werk #15292).

It is also a good idea to get an overview of the incompatible changes in version 2.3.0 before the update: Open the list of Werks on the Checkmk website. In the description of a Werk, you will find information on what you may need to do to make the change compatible.

After you have carried out the update, the number and content of the incompatible changes will be displayed in the Checkmk interface and you will be asked to check and take note of them. Links help you to check so that you can find out with just a few clicks whether you are using an affected component. If it is certain that a Werk has no impact or you have made the required changes, confirm it with Acknowledge.

In this section we describe the best practices that we follow even when updating large Checkmk environments. These are certainly not mandatory in every environment, but they can make the process of updating easier for you.

There are two different procedures for performing an update of all sites included in a distributed monitoring:

In particular, if you want to update while the system is running, you should read the notes in the general article on Updates and Upgrades.

Nothing fundamental has changed with the actual update of the software in Checkmk 2.3.0, i.e. you install the new version, perform the update of the Checkmk site, rectify any possible conflicts and check and confirm the incompatible changes.

Perform the update procedure as described in the article on Updates and Upgrades.

The Checkmk user interface (GUI), which was completely redesigned with version 2.0.0, has not been changed fundamentally in version 2.3.0. The general procedures, which you are already familiar with from versions 2.0.0 and 2.2.0, can also be used as they are in 2.3.0. However, menus, menu items, icons, and other details have been modified to make new features available — and to improve existing ones.

We will present these changes in this User Guide’s articles — and in the Beginner’s Guide you will find a detailed introduction, including the most important elements of the user interface.

As with every major version, Checkmk 2.3.0 introduces a whole new set of check plug-ins. If you do not use the 'discovery check', i.e. the automatic update of the service configuration via the periodic service discovery, you will have to search for services on quite a number of hosts.

If your hosts are organized accordingly (e.g. in folders), you can generally use the Bulk discovery function for this. This function can be found under Setup > Hosts > Hosts and then in the Hosts > Run bulk service discovery menu.

The behavior of the command line parameter --trust-cert of the cmk-update-agent command has been changed. Previously, the entire certificate chain was checked and the highest self-signed certificate found in the hierarchy was trusted; this is usually the root or an intermediate certificate. From Checkmk 2.3.0, only the server certificate is imported and trusted.

Does this affect you? This only affects you if you rely on --trust-cert when registering hosts for automatic agent updates and do not provide a certificate via the Agent Bakery. In this case, from Checkmk 2.3.0 hosts already lose the trust position when the server certificate expires, hosts registered with Checkmk 2.2.0 only when the root or intermediate certificates expire.

What will you need to do? We recommend providing the correct certificates via the agent bakery promptly following the update to 2.3.0 and updating all agents to ensure consistent behavior for all hosts that use the Agent Updater.

Does this affect you? This will only apply to you if you have explicitly installed Python modules for special agents or agent-based check plug-ins that you have written yourself or obtained from the Exchange and have removed these in the course of preparing for the update.

What will you need to do? First find out whether the previously uninstalled modules have already been delivered with the new Checkmk version, for example:

If the module has already been found, mark it as not required in your notes. Install the latest version of any modules that are not included:

Then test the check plug-ins or special agents that rely on Python modules installed in the site.

Up to Checkmk 2.2.0, the Windows agent relied on the additional Windows: State and Performance of Network Interfaces plug-in to correctly transmit the status of network interfaces. Without the plug-in, the status was always up. As of Checkmk 2.3.0, the agent can transmit the correct status on its own (Werk #15839).

Does this affect you? Depending on the extent to which you have distributed the plug-in and whether you have deactivated the monitoring of the status of network interfaces for hosts without a plug-in, this may affect you. Hosts that have not previously used a plug-in and whose network interfaces were included in the monitoring will change many interfaces from up to down, resulting in the CRIT status and triggering notifications.

What will you need to do? Check whether the status determined for the affected network interfaces is the desired one. Then carry out the service discovery again for the affected hosts. Take the opportunity to first implement the recommendations of the blog article Network monitoring with Checkmk: 3 rules to rule them all, at least for your Windows hosts. For Windows, the above-mentioned settings have to be made in the Network interfaces on Windows rule.

With Checkmk Cloud and Checkmk MSP with distributed setup, license information is sometimes not synchronized to remote sites during the update.

Does this affect you? If you need a complete overview of your license usage immediately after the update, you may be affected. Check the license status and initiate synchronization manually if necessary.

What will you need to do? Under Setup > General > Distributed Monitoring, take a look at the overview of remote sites and search for sites marked with License state: trial. To force an immediate synchronization for these sites, check the license under Setup > Licensing or save the license settings. If this step is forgotten, the license data is usually synchronized in the background within seven days of the update.

Checkmk 2.3.0 contains a new active check for HTTP connections and certificates, which is significantly better performing, more robust and easier to configure than the previous Check HTTP service. In addition, it is now possible to monitor several things at once with a single rule, for example HTTP response code, response time and certificate validity.

The new Check HTTP web service can be found in the Networking box under Setup > Services > HTTP, TCP, Email, …​. In the medium term, this will completely replace the old Check HTTP service, which you can find on the same page. For this reason, we recommend that you no longer use the previous check (internal: check_http) when creating new hosts and gradually migrate existing hosts to the new check (internal: check_httpv2).

A migration script will be provided later in the lifecycle of Checkmk 2.3.0. However, a fully automated migration tends to be difficult, because with many hosts rules from two checks have to be merged in order to benefit from the improved efficiency.

Further information can be found in the two Werks #15514 and #15515.

The legacy Check HTTP service contained basic functionality for checking certificates and the new Check HTTP web service mentioned in the previous section improves it even further. However, both have a few things in common: First of all, these are only applicable when a certificate is used at an HTTPS endpoint, and they also lack the option of a detailed examination of the certificates, for example for contained Certificate Subject Alternative Names or the issuing authority.

We have implemented the resulting user requests with the new Check certificates (internal: check_cert). All settings for the new check can also be found under Setup > Services > HTTP, TCP, Email, …​ in the Networking. box.

Further information can be found in the Werk #15516.

After Checkmk version 2.3.0 only the well-specified APIs for programming check plug-ins, special agents, graphing, etc. will be supported. The changes concern the directory structure, recognition of plug-ins (Discovery instead of Registry) and of course the functions and objects of the APIs themselves. An overview of the biggest changes can be found at Werk #16259.

As the previous APIs are no longer supported from Checkmk 2.4.0, all plug-ins that use the older APIs must be migrated to the new APIs before the update to 2.4.0.

A new agent plug-in is available for monitoring Microsoft SQL Server with Checkmk 2.3.0. You can find it under Setup > Agents > Windows, Linux, Solaris, AIX > Agent rules > Microsoft SQL Server (Linux, Windows). This one is implemented in Rust and in the longer term will replace the previous one written in VBScript. The new plug-in runs under Linux and Windows on the x86/64 platform. It also offers increased flexibility through local and remote monitoring under Windows and remote monitoring under Linux. Of course, you can monitor an MS SQL database running locally under Linux using the TCP/IP interface.

The configurability has been significantly improved, so now you can choose which sections are to be checked and add your own SQL statements. Furthermore, you can monitor databases on different hosts using a single plug-in. To keep this clear, the piggyback mechanism can be used to assign databases to other hosts. All configuration is done via a YAML file. The stable options are available via Agent Bakery rules. Other settings, which we reserve the right to modify, can be configured using a text editor. Details can be found in the Werk #15842.

With the introduction of the new agent plug-in, the deprecation of the old agent plug-in Microsoft SQL Server (Windows) starts. In Checkmk 2.3.0 you will only receive information about the use of an obsolete rule set. From 2.4.0 it will no longer be possible to create new rules and with 2.5.0 the old plug-in will probably be removed from Checkmk. Further information can be found at Werk #15844.

The term management board stands for separate plug-in cards or extended BIOS functionality (Baseboard Management Controller/BMC, Management Engine/ME, Lights Out Management/LOM) for monitoring and managing the hardware in addition to the installed operating system.

Up to Checkmk 2.3.0, management boards can be configured in two ways: As a property of a host or as a separate host. As the configurability as a property of a host is very limited, in the future this option will no longer be available. Support for Redfish compatible management boards will be added and improved during the lifecycle of Checkmk 2.3.0, initially as an optional MKP (Werk #16589). We explain additional background information and alternatives in the blog article Monitoring management boards.

Up to Checkmk 2.2.0, every automation user could be logged in with a user name and password passed via the GET parameter. This option will be reduced from Checkmk 2.3.0 and eventually removed completely (Werk #16223). In the medium term, you must therefore switch your scripts to authentication via HTTP headers.

First, 2.3.0 makes the option of logging in via the GET parameter configurable. However, the global setting Enable automation user authentication via HTTP parameters will initially use enabled as the default. In Checkmk 2.4.0, the default will then change to disabled. Finally, the option of logging in via the GET parameter will be completely removed under Checkmk 2.5.0.

Checkmk 2.3.0 will be the last version to support ntopng in versions 5.x and 6.x (Werk #16483). With Checkmk 2.4.0, support for ntopng 5.x will be discontinued and only ntopng 6.x will be supported. Therefore, update your ntopng installations to 6.x during the lifecycle of Checkmk 2.3.0.