We use cookies to ensure that we give you the best experience on our website.  Visit our Privacy Policy to learn more. If you continue to use this site, we will assume that you are okay with it.

Your choices regarding cookies on this site.
Your preferences have been updated.
In order for the changes to take effect completely please clear your browser cookies and cache. Then reload the page.

Checkmk Conference #6 goes digital. Get your tickets here!

Checkmk extension packages (MKPs)

1. Introduction

Checkmk is very modular, and can be extended at many points with a little Python programming knowledge. Among other things, you can extend Checkmk with the following elements:

  • Own checks and agent plug-ins, including input masks for WATO
  • Own plug-ins for the Checkmk Inventory
  • Extensions for the GUI (views, dashboards, columns, icons, etc.)
  • Definitions of graphs or Perf-O-Meters
  • Notifications and notification handler scripts (also in shell or other scripting languages)

All of these extensions are implemented by storing your own files in the ~/local directory within a Checkmk instance. In order to manage these extensions sensibly, to roll them out in distributed environments, and also to exchange them with other users, Checkmk provides its own package format: the Checkmk Extension Package - MKP for short.

An MKP collects any number of extensions – for example, a set of check plug-ins including their manual pages, WATO masks and metric definitions. It has a name, a version, and can be installed or removed with a simple action.

1.1. The Checkmk Exchange

On the Checkmk Exchange, users can provide packages for the general public and exchange them with each other. From the Exchange you can download and use extensions for free. Please note that packages from the Exchange are provided by other users voluntarily and without any guarantee – they may be improperly-programmed and could cause problems with your Checkmk version. Of course MKPs can also contain general errors that can lead to all sorts of other errors or even data loss. In order to try out a new package it is therefore advisable to first install it on a test system.

1.2. Tools for MKPs

There are two tools for managing MKPs:

  • The command line command mkp
  • The Extension Packages WATO module (only )

We will now introduce both commands in more detail. They are compatible with each other, so that you can use the command line command and the WATO module without ‘messing up’.

2. Managing extension packages via WATO

In WATO you will find the Extension Packages module, with which you can manage MKPs, and even change them or create new ones. You can access the module as usual via the WATO element in the side bar:

2.1. Installing an MKP

An MKP – that you, for example, downloaded from the Exchange – can be uploaded and installed in Checkmk using the Upload Package button. For this you need the file to be on the computer on which your web browser also runs. The package’s name must have the .mkp file extension.

During installation the files are installed in the correct locations under ~/local/. A package description file is also stored in ~/var/check_mk/packages/. After uploading, the package will appear in the list of installed MKPs:

Now you only need to perform an Activate Changes, and all functions from the package will be anchored in the system and ready for use.

2.2. Uninstalling or releasing packages

Using the corresponding icons in the list of packages, you can either ‘delete’ installed packages , or ‘release’ them . When deleting, the package is deleted together with its installed files, and thus the extension is removed. So this is the opposite of an installion. On the other hand, the release function releases – so to speak – the files packaged under ~/local/, and only removes the package description. As a result the files are then unpackaged and the extensions are still active. This is the opposite of creating a package.

2.3. Creating packages

Creating your own MKP is very easy (apart from the minor detail that the extensions must of course have been programmed beforehand). The starting point is that you have created your own files in the corresponding directories under ~/local/. The right directory for your own check plugins is ~/local/share/check_mk/checks, for example. These files do not initially belong to any package and are therefore listed under Unpackaged Files:

The icon takes you to the dialogue for creating a new package:

In addition to the obvious information, it is important that you select at least one file to be packed. When the package is created, it is saved in ~/var/check_mk/packages/, which includes the list of files in addition to the general information.

You can download this package as an MKP file from the package list with the icon – for example, to transfer it to another system, or to upload it to the Exchange.

Note that if you later make changes to the packaged files, the package does not have to be recreated. A simple download of the MKP file is sufficient. On the other hand, of course it can’t hurt to give the package a new version number after a change.

3. MKPs on the command line

You can also perform all of the above actions on the command line. The command mkp (which is actually an abbreviation of cmk -P) is used for this:

OMD[mysite]:~$ mkp
Usage: check_mk [-v] -P|--package COMMAND [ARGS]

Available commands are:
   create NAME      ...  Collect unpackaged files into new package NAME
   pack NAME        ...  Create package file from installed package
   release NAME     ...  Drop installed package NAME, release packaged files
   find             ...  Find and display unpackaged files
   list             ...  List all installed packages
   list NAME        ...  List files of installed package
   list PACK.mkp    ...  List files of uninstalled package file
   show NAME        ...  Show information about installed package
   show PACK.mkp    ...  Show information about uninstalled package file
   install PACK.mkp ...  Install or update package from file PACK.mkp
   remove NAME      ...  Uninstall package NAME

   -v  enables verbose output

Package files are located in /omd/sites/mysite/var/check_mk/packages/.

3.1. Installation of an MKP

A package is installed with mkp install. To do this, you must of course first transfer the MKP file to the monitoring server (e.g., with scp). The installation is then performed with one command:

OMD[mysite]:~$ mkp install /tmp/mypackage-1.0.mkp

You can get a list of the installed packages with mkp list:

OMD[mysite]:~$ mkp list
mypackage

You can find out the details of a single package with mkp show:

OMD[mysite]:~$ mkp show myPackage
Package file:                  /omd/sites/mysite/var/check_mk/packages/myPackage
Name:                          myPackage
Version:                       1.0
Packaged on Check_MK Version:  1.6.0
Required Check_MK Version:     1.6.0
Title:                         My own check plugin
Author:                        myName
Download-URL:                  http://www.example.com
Files:                         checkman(1) checks(1)
Description:
  This package contains a cool check plugin

3.2. Uninstall or release packages

A package is uninstalled with tt>mkp remove. This command deletes both the package description and all of the files it contains!

OMD[mysite]:~$ mkp remove mypackage

You can release a package with mkp release. The extension files are retained and only the package description is deleted:

OMD[mysite]:~$ mkp release mypackage

3.3. Creating a package

The creation of MKPs on the command line is analogous to the WATO module, only maybe not quite as convenient. First create your extensions in the appropriate directories under ~/local/. You can find all unpackaged files with mkp find:

OMD[mysite]:~$ mkp find
/omd/sites/mysite/local/share/check_mk/checks/mycheck
/omd/sites/mysite/local/share/check_mk/checkman/mycheck

Now use the mkp create command to create a new package that – for the time being – contains all of these files. Enter the desired name for the new package:

OMD[mysite]:~$ mkp create mypackage

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

var/check_mk/packages/mypackage
{'author': u'myName',
 'description': u'This package contains a check plugin',
 'download_url': 'http://www.example.com',
 'files': {'agents': [],
           'checkman': ['mycheck'],
           'checks': ['mycheck'],
           'doc': [],
           'inventory': [],
           'notifications': [],
           'pnp-templates': [],
           'web': []},
 'name': 'myPackage',
 'title': u'My own check plugin',
 'version': '1.0',
 'version.min_required': '1.6.0',
 'version.packaged': '1.6.0'}

Edit this file as you wish. Pay attention to correct Python syntax. Texts that contain non-ascii characters (e.g., umlauts) must be marked with a lower-case u.

Under the files entry you can remove files that should not be packaged. Enter the minimum version of Checkmk required to use the package under version.min_required.

You can then create an MKP file with mkp pack:

OMD[mysite]:~$ mkp pack mypackage
OMD[mysite]:~$ ll *.mkp
-rw-rw-r-- 1 mysite mysite 495 Dez 22 13:36 mypackage-1.0.mkp

4. MKPs in distributed environments

With distributed monitoring it is sufficient to install the packages on the Master. For each connected slave site you can then determine whether any alterations should be transferred to the site. All you have to do is activate the Extensions option. After that, the MKPs and all other changes in the ~/local directory will be transferred during a synchronization.

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

Important: The alterations are only transferred if the Enable replication option is set to Push configuration to this site.

5. Installing Feature Packs

From version 1.6.0p9 there are Feature Packs in Checkmk. These extensions provide functionalities that should actually only be included in the next stable version. Such functionalities can be, for example, extensions of existing checks, or Special Agents. These are included in the respective version and only have to be activated – or deactivated again. To activate such an optional MKP in the  Checkmk Enterprise Editions, in the Extension Packages module click on the plug to the left of the package:

To install a package in the  Checkmk Raw Edition you can use the command line as usual. You can find the MKPs under ~share/check_mk/optional_packages/. For example, to install the azure_ad package, execute the following command:

OMD[mysite]:~$ mkp install ~/share/check_mk/optional_packages/azure_ad-1.0.mkp