Updates

The update path determines which packages you will need to download and, if applicable, whether an update of the Linux distribution is required before the Checkmk update, or whether it is possible after the Checkmk update.

Local files allow you to customize and extend the functionality provided by Checkmk. These files are located in the local part of the site’s directory structure, i.e., in ~/local. Local files can cause problems during an update, as they may no longer be compatible with the new Checkmk version.

Since Checkmk cannot detect and handle local customizations or third-party extensions during an update, you should check your Checkmk site before updating to see if you are using local files and, if so, which ones.

Get an overview of the local files in your Checkmk site by running the following command as a site user, (where the -L option ensures that symbolic links are also followed):

In a fresh Checkmk installation, the output should be empty. If files are found, compare the list with the output of mkp find. Ideally, local files are already fully bundled in MKPs.

If this is not the case, bundle related files into Checkmk extension packages (MKPs). Once combined into a package, an extension can be disabled or re-enabled as a whole.

When updating to a higher patch version within a major version, compatibility issues with MKPs are rarely a concern. However, incompatibilities can never be ruled out entirely. For example, some extension developers set the highest compatibility to a specific patch version of Checkmk if a REST API provider discontinues a version as of a certain date.

The likelihood of incompatibilities is greater when updating the major version. If you encounter incompatible extensions obtained from third parties (for example, from the Checkmk Exchange), check whether a newer version is available. If this is not the case—or if you developed the extension yourself—you will find all of the necessary information for adapting your extensions in the article Developing extensions for Checkmk.

We do not need to explain to you how important it is to create a backup immediately before an update, so that you do not lose too much of your monitoring history in the event of a failure. For detailed examples of backing up with omd backup, see the article on site administration with omd.

In addition to file-based backups, it is advisable to enable configuration versioning with Git in the Global settings. This ensures that there are no gaps in the monitoring data in the event that a rollback is necessary.

As described in the introduction, the first step in the update process is to install the desired new version of Checkmk. This is done exactly as in the initial installation—however it will likely run a bit faster because most of the required packages have already been installed. In the following example, a package for Ubuntu 24.04 (Noble Numbat) is installed:

If a major version update is planned and the site to be updated is not yet at the latest patch version, you must first also install the corresponding patch package:

You can view the list of installed Checkmk versions at any time using the omd versions command:

One of these versions is marked with (default). This default version is automatically used when creating new sites. When managing existing sites, the default version is irrelevant. The omd command always starts with the version that matches the site for which the command is called.

The omd sites command provides a list of the current sites and the versions they use:

Once the desired new version has been installed, you can update the site. No root privileges are required for this. It is best to perform the update as the site user:

Make sure that the site has been stopped:

Updating—which essentially means switching to a different version—is now done simply with the omd update command:

If there is more than one possible target version, you will be presented with the following options:

In the following dialog box, confirm the selected update to the new version:

If you perform a version update at the same time as an edition upgrade from Checkmk Community to one of the commercial editions, you will be reminded of this fact again as a precaution:

An important part of the update is updating the included configuration files. Any changes you may have made to these files are not simply discarded, but merged. This works very similarly to version control systems, which attempt to automatically merge simultaneous changes made by multiple developers to the same file.

Sometimes—if the changes affect the same part of the file—this does not work, and a conflict occurs. We show you how to resolve this below.

The update displays a list of all modified files and directories (abbreviated in the following example):

If the line highlighted in the output above, Completed verifying site configuration, appears, the site has been switched to the new version:

… and can be started:

While incompatible changes are less common in patch releases and usually require only minor adjustments, major updates more often result in new check plug-ins replacing existing ones. If you are using one of the affected plug-ins, a new service discovery will be necessary on the affected hosts following the update.

An overview of all changes in Checkmk, including a search function, can be found online in our Werks.

Even more convenient, however, is the search function built into Checkmk. After logging in to the site, you will find a red-highlighted link at the top of the Help menu showing the number of incompatible and unconfirmed changes:

Checkmk tracks the incompatible changes introduced by the update to the current version, and prompts you to review and then acknowledge them:

If you open this page via the red link in the Help menu, you will only see the 'Werks' (i.e., the changes) that require action and are therefore marked with Incompatible - TODO. You can open each Werk individually, view it, confirm it with a mouse click—and thus gradually reduce the number of open, incompatible changes. Additionally, the Help > About Checkmk > Change log (Werks) menu item gives you access to the complete history of changes in the current major version.

The technical rationale for this approach lies in the protocols used: The central site primarily accesses the data from the remote sites in read-only mode via Livestatus; in a central setup, it also accesses the data in write mode via a non-public HTTP API. In both cases, new versions introduce proper supersets of the protocols used. Thus, an older central site uses only a proper subset of the functionality of the newer remote sites. If the central site were to be updated first, it might use API calls or Livestatus requests on the remote sites that they do not yet understand.

The maximum version difference for a single major version, in turn, results from the fact that the removal of interfaces is accompanied by a grace period of exactly one version.

To facilitate phased updates, Checkmk allows you to store extension packages with the same name but in different versions—one compatible with the older central site and one compatible with the newer remote sites. The appropriate package is activated in each case. Details are described in the article on extension packages (MKPs).

When using viewer sites, viewer sites may only be updated after the sites whose data they display have been updated. If a viewer site displays only data from remote sites, it may be updated as soon as those remote sites have been updated. If, on the other hand, the viewer site also displays data from the central site, it must be updated last.

If the new version includes a change to a configuration file that you have since modified yourself, Checkmk will attempt to automatically merge both changes. This is done using the same methods that version control systems use.

The fewest problems occur when your changes and Checkmk’s changes are far enough apart (at least a few lines). In that case, the merge takes place automatically without your help.

If two changes conflict because they affect the same part of the file, Checkmk cannot and will not decide which of the two changes is more important. In this case, you, the user, will be prompted to resolve the conflict interactively:

You will now have the following options:

In addition to merging file contents, there are a number of other situations in which Checkmk will need you to make a decision. Some of these are very unusual situations, but they will still require proper handling. In these cases, Checkmk will always give you the option to keep your version or adopt the new default version. In addition, you always have the option to cancel or open a shell. Examples of such situations can include:

If an update fails, it is worth first checking any changes you have made to configuration files yourself. Furthermore, you should check whether a poorly programmed extension might be causing the problem and disable it if necessary. Of course, it’s simply possible that an error has crept into the update routine. In such a case, please report the issue via a support ticket (if you have a support contract) or on the Checkmk Forum.

The following options control the behavior of the pre-checks and should be used in preference to --force (short for -f):

The following options control the behavior during the first step of the configuration update, the file-based update:

The following options are passed to the cmk-update-config program and control the behavior during the second step of the configuration update, where format changes or conversions from lists to objects are performed.

An example of the complete command for an automatic update of the mysite site to version 2.5.0p8.community:

The && before omd start prevents the site from starting if omd update aborts with an error while updating the configuration. Replace the && with a semicolon (;) if you absolutely want to attempt a startup even in such a situation.