Checkmk extension packages (MKPs)

On the Checkmk Exchange, programmers of plug-ins can provide packages for other Checkmk users and exchange these amongst themselves. From the Exchange you can download and use extensions for free. Please note that packages from the Exchange are shared voluntarily by other users and are without any warranty. Improperly programmed plug-ins can lead to increased CPU/system loads and memory requirements. In addition, it is possible that an MKP was developed for older versions of CMK and thus may not be fully compatible (from version 1.6.0 to 2.0.0 Checkmk changed from Python 2 to Python 3). In extreme cases there can be a risk of data or service loss. We therefore strongly recommend that before using third-party MKPs in a production environment, they should first be installed on a test site.

There are two tools for managing MKPs:

We will now introduce both management tools in more detail. They are compatible with each other so that you can use the command line command and Extension Packages without "messing anything up".

An MKP that you have downloaded from the Exchange, for example, can be uploaded to Checkmk by clicking the Upload package button and will then be made available for installation. To do this, the file must be present on the machine that is also running your web browser. The file extension of the package must be .mkp.

Following an installation, the extension package will initially be available. It is located under All packages (enabled or disabled):

Only with a click on the plug icon will an available package also be activated. During activation, the files are installed in a folder hierarchy under ~/local/. The package description file is also placed in ~/var/check_mk/packages/. After activation, the package will also appear in the list of enabled and active MKPs — Enabled (active on this site):

Now perform an activation of changes, after which all functions from the package will be anchored in the system and ready for use.

The complete deletion of a package is also done in two stages. With the button you first deactivate a package in the list of active packages. In this step the installed files are removed, but the MKP is still kept — this step only reverses the activation.

Using the icon in the list of all packages, you can again delete installed and unused packages. When deleting, the package is deleted and with it the extension is completely removed — i.e. the opposite of adding a package.

In the case of a distributed setup, it is sufficient to make the packages available on the central site. For each remote site associated with the central site, you can then separately determine whether the customizations should be propagated to that remote site. All you have to do is activate the Replicate extensions option. After that, the MKPs and all other changes below the ~/local directory will also be transferred during synchronization.

If a transfer is not desired, simply turn off the option for this or all sites.

Important: The customizations for the distributed setup will only be transferred if the Enable replication option is set to Push configuration to this site.

A special case is the attempted activation of a package that does not match the Checkmk version used. Such a package that is enabled, but whose activation fails because of an incompatible Checkmk version, will end up in the Enabled (inactive on this site) list.

But why install packages that do not match the Checkmk version you are using? There are two good reasons:

From the version numbers shown in the above screenshot, you can see that it is a Checkmk 2.1.0 central site that provides packages for remote sites that have already been upgraded to 2.2.0.

The unpack icon unpacks the packaged files under ~/local/ and only removes the package description. As a result, the files will be unpackaged and the extensions will remain active. This is the opposite of creating a package from previously unpackaged files.

In practice, you will most likely need to unpackage when you want to customize an extension and later repackage it with any changes. For example, you can use our Hello world! example, which does nothing useful, but can serve as a template to help you get started with your first custom package.

Creating your own MKP is very easy once the programming work has been completed. The starting point is that you have created your own files in the appropriate directories under ~/local/. For example, for custom, agent-based check plug-ins, the correct directory is ~/local/lib/check_mk/base/plugins/agent_based. These files do not initially belong to any package and are therefore listed under Unpackaged files:

The Create package button will open the dialog for creating a new package:

Besides the obvious information, it is important that you select at least one file to be packed. When creating a package, a description is added under ~/var/check_mk/packages/, which, in addition to the general information, also contains the list of the included files. The highest supported Checkmk version is of course difficult to predict without a crystal ball. As a rule of thumb it can be assumed that something that was programmed for 2.0.0 without using old APIs will also run with 2.1.0 and 2.2.0. Therefore the highest Checkmk version is used to identify older packages, which require more intensive testing and possibly customization.

You can now use this package — e.g. to transfer it to another system or upload it to the Exchange — or, with the icon in the package list, to download it as an MKP file.

When making changes to packaged files, the package does not need to be rebuilt. Click to change the version number, save the modified package and re-download it if necessary.

The installation of a package is accomplished with the mkp install command. For this, first you must of course load the MKP file onto the Checkmk server (e.g. with scp). After that the installation is performed with the following command:

You can list the installed packages with the mkp list command:

Uninstalling a package is done in two stages. First, the package is disabled with mkp disable. This deletes installed files, but still keeps the package — for example for a later reactivation. The specification of the version number is only required in the event that the name alone is not unique:

In the package list you will now see this package has the Disabled state when you again call mkp list:

A subsequent mkp remove command will then irrevocably delete the package:

A special situation is the installation of a package that does not match the Checkmk version in use:

A package which has been enabled, but whose activation fails due to an incompatible Checkmk version, will be identified with the Enabled (inactive on this site) state.

Above we explained the reasons for installing incompatible packages — i.e. for updates and distributed environments. Similarly, as in setup, use mkp enable packagename version to enable a package, or mkp disable packagename version to disable an existing enabled package.

You can unpack an existing and active package (State: Enabled (active on this site)) with the mkp release command. The extension files will be retained and only the download package and its description will be deleted:

The procedure for creating MKPs on the command line is analogous to that using the Setup menu. First you create your extensions in the appropriate directories within ~/local/. You then list all unpackaged files with mkp find:

Now create a package configuration with the mkp create command, which (for now) contains all of these files. Specify the desired name of the new package:

You now edit the properties of the package with a text editor. The file for this is located in ~/var/check_mk/packages/mypackage:

Edit this file according to your needs. Make sure you use the correct Python syntax. Unicode strings — i.e. texts containing non-ASCII characters, such as umlauts — must be prefixed with a lower-case u.

At the entry files you can remove files which should not be be packaged. Under version.min_required you enter the minimum version of Checkmk that is required to use the package.

Afterwards you can create a MKP file using mkp pack: