Updates and Upgrades

When updating to major versions, you should always update directly to the next version and not just skip any. For example, if you want to update from 1.6.0 to 2.1.0, update to 2.0.0 first. The reason is simple: there are sometimes simply so many changes between two major versions that skipping them can cause problems. This recommendation is enforced by omd update by a block and issues a warning message if necessary. Nevertheless, you can perform such updates by enforcing the operation with the -f option:

Attention: Sites updated in this way are no longer supported by us!

The omd update command also allows updating to a lower version. After such an update in the reverse direction, however, many adjustments are necessary to make configuration and runtime environment compatible again — especially, but not only, when updating to a lower major version. Therefore, we advise against this procedure — and can no longer provide support when updating to a lower version.

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. Local files can cause problems when updating, as they may no longer match the new Checkmk version.

Since it is not possible for Checkmk to intercept and handle local customizations and any third-party extension during an update, you should check your Checkmk site before an update to see if and which local files you are using.

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

In a fresh installation of Checkmk, you will currently only see a file called README.TXT listed. Anything beyond that should be at the top of your troubleshooting list in case you have problems updating.

The Checkmk extension packages (MKPs) can be used to extend your monitoring system quite easily and conveniently. On the one hand, it happens that such MKPs are no longer maintained and may then no longer be compatible with new versions of Checkmk. On the other hand, we keep adding new plug-ins and functional extensions to Checkmk, which is why MKPs sometimes become obsolete. Their functionality is simply ensured by Checkmk itself.

If you have installed MKPs, it is urgently recommended to check them. This will prevent incompatible packages from interfering with the update, or of having duplicate or at least very similar services following the update.

To do this, check your installed MKPs against our Catalog of Check plug-ins and remove packages which are now provided natively by Checkmk. You can also take this opportunity to remove MKPs that may have only been installed for a test run. You can find a list in the Setup menu under Maintenance > Extension packages. On the command line, with the following commands you can display installed extensions as well as any unpackaged files:

Should you not be able to assign all packages via the check of the installed MKPs and the comparison with our catalog, we recommend the dry run of the update described below in order to identify incompatibilities and then remove these from your production monitoring before the update.

Check the output of these commands for extensions and files that are no longer needed or that you cannot even allocate. To check their impact on the update, you can make copies of these extensions and files and remove them from your Checkmk site, at least temporarily.

As described in the introduction, the first step with an update is the installation of the desired new version of Checkmk. This is achieved in exactly the same way as with the initial installation — it will however proceed somewhat more quickly since most of the dependent packages have already been installed. In the following example we are installing the package for Ubuntu 20.04 (Focal Fossa):

Note: When installing a local package via apt install, you have to state the pull path to the .deb file.

A list of your installed Checkmk versions can be displayed at any time with the omd versions command:

One of these listed versions is marked with (default). This default version will be used automatically when creating new sites, as long as no other version is specified with omd -V myversion create mysite. The current default version can be queried with omd version, and it can be altered with omd setversion:

The default version plays no role when managing existing sites. The omd command always starts with the version appropriate to the site for which the command is called.

A listing of the current sites and the versions they use is provided by the omd sites command:

Once the desired new version has been installed, the site can be updated. No root-permissions are required for this. The best way to do this is as a site user:

Ensure that the site has been stopped:

The update — in effect switching to a different version — can now simply be performed with the omd update command:

If more than one target version is available, a selection list will open:

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

When updating from a Raw Edition to the Checkmk Enterprise Standard Edition you will be reminded of this fact:

An important part of an update is the refreshing of the originally provided configuration files. Here changes that had possibly been made to these files by the user will not simply be discarded, rather they will be merged. This functions very much like version control systems which attempt to amalgamate changes made to a single file simultaneously by multiple developers.

Occasionally — when the changes affect the same location in the file — that won’t function, and a conflict occurs. How you can solve such conflicts will be explained later below.

The update provides a listing of all modified files and directories (shortened in the following example):

Once everything has been successfully processed, the site is switched to the new version:

… and can then be started:

Software development of course consists of changes. Because we are always actively working to keep Checkmk modern, sometimes cutting dead weight and making changes that turn out to be incompatible is unavoidable. That means that when updating it may possibly be necessary to adapt your configuration, or you should at least check it.

A typical example of such a situation is with new check plug-ins which replace existing plug-ins. If you use one of the affected plug-ins, a fresh service discovery will be required on the affected host.

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

Even more practical however is the built-in search function in the release notes. After you have logged in to the site, you will find the link highlighted in red in the Help menu:

Checkmk keeps track of incompatible changes that occurred during the update from the original to the current version and asks you to check and then acknowledge them:

You can call up each 'Werk' individually, view it, confirm it with a mouse click — and thus successively reduce the number of open incompatible changes. In addition, you can use the Filter button to show the filter bar and thus have access to the complete history of changes.

Are you curious about what exactly is happening ‘under the hood’ of an update? Or have data conflicts appeared when omd update is running? If so, here is some further reading.

Three actions take place during omd update:

Would you like to automate Checkmk’s software updates? You may at first have difficulties with the interactive responses from omd update. There is a simple solution for this scenario: the command has options that have been especially conceived for use in scripts:

Possible values for --conflict= are:

Below is an example of the complete command for an automated update to version 2.1.0p1.cee of mysite:

Through the && before omd start a restarting of the site will be prevented if the omd update is aborted by an error. Replace the && with a semicolon (;) if a start should definitely be attempted even in such a situation.

If you are certain that only a single Checkmk site is running on the server, the name to be used in a shell script can simply be trapped in a variable:

This enables the above line to be independent of the site’s name. For example, a small shell script could look like this:

You can also upgrade the Free Edition appliance to a full version of one of the Enterprise Editions without data loss. For this you must also upgrade the firmware of the appliance!

An upgrade of the Checkmk Raw Edition to one of the Enterprise Editions is also possible. Here as well, the procedure is the same as before: install the desired package, and upgrade the sites with omd update.

Since a number of modules and features of the Enterprise Editions are not available in the Raw Edition, following a changeover there are a couple of points to be aware of. The key point is that when creating new sites of Raw Edition or Enterprise Editions different default settings are set.

Since the Raw Edition only supports Nagios as its core, this is preinstalled in sites created by the Raw Edition. This is retained when an upgrade to the Checkmk Enterprise Standard Edition is made. That means that after an upgrade, processing will initially continue with a Nagios core. A migration to the CMC is performed with omd config, and this procedure will be described in its own article.

The Enterprise Editions support an alternative format for saving historic performance data, one which requires significantly less hard drive-I/O. This is preinstalled in new Enterprise Editions sites. Raw Edition sites will not be changed over automatically by an upgrade. How the migration can be performed is described in its own chapter in the article covering Performance data and graphing.

The Raw Edition has no notification spooler. Thus following the changeover to one of the Enterprise Editions it is not active at first. How to activate it can be learned here.

The uninstallation of no longer required Checkmk versions is performed using the operating system’s package manager. To do this, enter the installed package’s name – NOT the file name of the original RPM/DEB file. Important: Only delete Checkmk versions that are no longer being used by any site!

Checkmk sites that are no longer required can simply be removed with omd rm (thereby deleting all data as well!):

Here is how to identify which Checkmk packages are being used in RPM-based systems:

The deletion is performed with rpm -e:

Use the below to identify which packets are installed:

The uninstallation is performed with dpkg --purge: