Update to version 2.0.0

As before updating any production software, you should check that your backups are up to date before updating Checkmk.

Does this affect you? Yes.

What do you need to do? If you create your backups automatically via the WATO > Backups module, check there whether the last backup jobs have run through without errors.

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

The DokuWiki is no longer part of the Checkmk software.

Does this affect you? This affects you if you have previously used the wiki, for example, to provide information in the form of notes or via the sidebar snapin WIKI in Checkmk.

What do you need to do?

An important note beforehand: The DokuWiki data stored in Checkmk will not be deleted when updating to Checkmk 2.0.0. Only the software itself will be removed from the corresponding directories. You can therefore still move your DokuWiki data to version 2.0.0 at any time after the update.

If you have previously used the DokuWiki supplied and wish to continue using the information, we recommend installing DokuWiki separately. You will find instructions on how to do this on the dokuwiki.org project pages.

Since all articles and other texts and structures in DokuWiki consist only of text files and directories, moving them to another server is actually extremely simple. To do this, simply copy the contents of the ~/var/dokuwiki/data folder from your Checkmk site to the directory of the same name in your new DokuWiki installation.

If you have been accessing the information in DokuWiki primarily via the Notes icon in your Service and Host views, you should also edit the URL in the Notes URL for Hosts and Notes URL for Services rules after moving DokuWiki. If you have created a Custom Icon for this purpose instead, change the URL accordingly in Global Settings > Custom icons and actions.

In Checkmk version 2.0.0, some obsolete Linux distribution versions will no longer be supported.

Does this affect you? This affects you if your Checkmk server has any of the following versions installed that are still supported in 1.6.0:

What do you need to do? Before updating Checkmk, first update the Linux distribution. Make sure that the target version of the Linux distribution is supported by Checkmk 1.6.0 and that 2.0.0.

You can find out which Linux distribution versions Checkmk supports in the installation article and on the download page after you have selected the Checkmk version and your Linux distribution.

If it is now necessary to upgrade Linux before updating Checkmk, we recommend the following procedure:

When reinstalling Checkmk, follow the detailed installation instructions for your respective distribution.

In order to use the feature to forecast graphs in Checkmk 1.6.0, the installation of additional software (among others Prophet from Facebook) is necessary. As of 2.0.0, Checkmk has a completely stand-alone implementation of this prediction function, without the need to install additional software packages.

Does this affect you? If you have been using the forecast graphs introduced in Checkmk 1.6.0, it is highly recommended that you remove the Python and Prophet installed for it from your sites.

What do you need to do? The script you used to install Prophet and its dependencies will also remove these packages for you. To do this, simply call it with the -u option. In distributed monitoring, you will need to repeat this step on each site where you have installed Prophet.

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.

Does this affect you? 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.

What do you need to do? 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. Scripts and check plug-ins written in Python 2 and check plug-ins that follow the old Check API deserve special attention. We will go into both topics in more detail in the following two chapters.

Most of Checkmk is written in the Python programming language — for over 10 years in Python 2. With version 2.0.0 we have now taken the big step and ported Checkmk to Python 3. This step was costly, but necessary to be able to develop Checkmk efficiently and safely.

Up to and including version 1.6.0, Checkmk comes with Python 2.7 and all necessary third-party modules. Instead of Python 2.7, Checkmk 2.0.0 will be shipped with Python 3.8 and all necessary third party modules.

Does this affect you? This Python version change is relevant for you if you use local files (scripts or plug-ins) written in Python 2.

What do you need to do? In scripts, change the 'Shebang' and adapt the code from Python 2 to 3:

In a script that is called directly from a cronjob or the core, e.g. a notification script, you have often used the following shebang in the past:

This means that you have used the Python 2.7 delivered in version 1.6.0. Since this no longer exists, the Python version of the operating system is used without changing this line. Which one this is depends on your operating system and can be queried by you with the following command.

We recommend changing the shebang to:

This will allow you to go back to using the Python that comes with Checkmk 2.0.0.

After that, you may need to make some adjustments in your scripts to change your code from Python 2 to Python 3. You will learn how to do this in the following chapter on the new Check API.

Checkmk 2.0.0 introduces a new Check API that restructures the check plug-ins to standardize and simplify their handling.

However, as there are a large number of checks that were programmed according to the old check API valid up until version 1.6.0, the old Check API will continue to be supported for a transitional period.

Does this affect you? The new API 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 and have downloaded them, for instance, from the Checkmk Exchange. The affected files can be found in your site’s local files.

What do you have to do? We have tried to make the change to the new Check API as easy and comfortable as possible for you:

After updating to version 2.0.0 Checkmk tries to migrate all local plug-ins from the ~/local/share/check_mk/checks and ~/local/share/check_mk/inventory directories automatically to the new Check-API. This 'automigration' happens at runtime; the plug-in files are not changed. You can find out how to view the results after the update in the chapter Check automigration to the new Check API.

Although the chances are good that the automigration of your check plug-ins will work smoothly, the changeover to Python 3 may require some adjustments. Due to the introduction of the new Check API and the change of the code base to Python 3, there are two good reasons to revise your self-written check plug-ins. We provide detailed information on the necessary steps for this in the Blogpost on the migration of check plug-ins.

Last but not least, the new check API scores with improved documentation. There is an introductory article on Programming your own check plug-ins with the new check API, and you can access the always up-to-date plug-in API reference documentation in Checkmk 2.0.0 via the Checkmk interface — in the new Help menu in the navigation bar.

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.

Does this affect you? If you have installed MKPs, it is urgently recommended to check them, especially before such a large update. This will prevent incompatible packages from interfering with the update, or of having duplicate or at least very similar services following the update.

What do you need to do? 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 via the WATO module 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.

As in every Checkmk version, there are changes to the software in the current version 2.0.0 that may have repercussions on your Checkmk installation. A so-called incompatible change may require you to make manual adjustments so that existing functions continue to run as usual and/or new functions can be used.

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

What do you need to do? After you have performed the update, the Checkmk interface will show you the number and content of the incompatible changes and ask you to check and take note of them. So you will definitely be confronted with this issue — but only after you have performed the update.

It is therefore a good idea to get an overview of the incompatible changes before the update. Open the list of Werks. (The software development of Checkmk is organized in so-called Werks). Filter the list of Werks by Checkmk 2.0 and by compatibility, i.e. check the checkbox Only show incompatible. In the description of a Werk you will find hints on what to do, if necessary, to make the change compatible.

The frustrating news: The Werk list of a version is very, very long — even if it only contains the incompatible changes. The comforting news: You can see from the number of changes how much effort we put into improving Checkmk for you.

In the following we describe best practices which 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 different procedures, to perform the update: All in one, successive with disabled configuration changes and completely during the operation. You have to create backups in each case.

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

Carry out the update procedure as described in the article on updates and upgrades.

The not to be overlooked innovation in the Checkmk version 2.0.0 is the completely-redesigned user interface (GUI) that presents itself after you have logged in:

The following overview is intended for the version switchers in a hurry and shows where the most important of the well-known GUI elements from version 1.6.0 are located in version 2.0.0:

In the Beginner’s guide you will find a detailed introduction to the most important elements of the new GUI.

In Checkmk 2.0.0 the principle of the auxiliary processes has changed a lot. Up to Checkmk 1.6.0 the Checkmk helpers were responsible for performing checks. The Checkmk helper processes remained permanent and thus provided a significant improvement in performance because the time-consuming creation of new processes could be dispensed with.

In Checkmk 2.0.0, these auxiliary processes perform their tasks in an even more specialized and targeted way. Instead of fetching the information and subsequently evaluating it, as in 1.6.0, one part of the auxiliary processes is only responsible for fetching the information. These processes are called Checkmk fetchers. The other part, on the other hand, takes care of evaluating the information passed by the fetchers. We call these processes Checkmk checkers.

Does this affect you? In short, yes — if you are using the Checkmk Enterprise Editions in which the above processes are available. Every administrator of the Checkmk 2.0.0 Enterprise Editions should deal with this point in the Global settings.

What do you need to do? You need to go to Setup > General > Global settings and adjust the values for Maximum concurrent Checkmk fetchers and Maximum concurrent Checkmk checkers.

For the checkers, it can be clearly said that the value should in no case be greater than your server can process in parallel. As a rule, this number corresponds to the number of processor cores in your Checkmk server. However, this would be the absolute maximum, and exceeding it makes no sense.

In the case of the fetchers, however, the available working memory of the server is the limiting factor. The number of Maximum concurrent Check_MK checks from Checkmk 1.6.0 is taken as the initial value here. To find a good setting for this, we recommend activating the Core statistics snapin of the sidebar. This shows you the percentage utilization of the fetchers and checkers. If the fetchers here are regularly close to 100%, you should increase their number in order to obtain a high-performance system. We recommend setting the fetchers so that their load is at 80% a few minutes after restarting a site.

Detailed information can be found here.

You can check if all local plug-ins from the directories ~/local/share/check_mk/checks and ~/local/share/check_mk/inventory can be automatically migrated to the new Check API.

Does this affect you? This check is useful if you have checks in your local files that were programmed conforming to the old Check API that was valid up to version 1.6.0.

What do you need to do? As a site user, run the following command:

The message above shows that a plug-in could not be migrated automatically. All of the listed plug-ins will need to be migrated manually by you. There are a number of reasons why an automigration cannot be performed, and you can read about these in the mentioned Werk #10601. You can find out how to carry out manual migration in the Blogpost on the migration of check plug-ins.

Checkmk 2.0.0 brings with it a whole series of new check plug-ins. If you do not use the automatic update of the service configuration via the periodic service discovery, you will have to search for services on a number of hosts.

If your hosts are organized accordingly (e.g. in folders), you can usually use the Bulk discovery function for this. You can find this under Setup > Hosts > Hosts and then in the menu Hosts > Discover services.

Below we list some components with the most new features.

Python 3 is much stricter than its predecessor version — also with regard to the requirements for correct syntax. In the beta phase of Checkmk 2.0.0, we repeatedly encountered plug-ins in which even small errors could hinder a successful update. If the error 'inconsistent use of tabs' occurs during the update or the subsequent start of the site, we recommend removing the affected plug-in with the following command.

The synchronization of configuration files between sites in distributed monitoring has changed in version 2.0.0. In version 1.6.0 all configuration files are synchronized between the central site and the remote sites; in version 2.0.0 this happens incrementally, so that only those files that have changed will be synchronized.

To enable the updating of all sites utilizing the distributed monitoring to version 2.0.0 during operation, the synchronization will also work for a transitional period in a mixed environment, as the incremental synchronization is performed only if both instances are running on version 2.0.0. Otherwise the old method will be used. Please read absolutely the hints regarding the Update during operation.

This compatibility mode will be removed for the next Checkmk version (currently planned as 2.1.0). We recommend that all sites using distributed monitoring be updated to version 2.0.0 as soon as possible.

The Web-API (also called the HTTP-API) will no longer be supported in the next but one Checkmk version (currently planned as 2.2.0). The Web-API will be replaced by the new REST-API introduced in 2.0.0.