Check_MK's extension packages (MKPs)

Last updated: December 28. 2017


1. Introduction

Check_MK has a fundamentally modular structure and many of its components can be extended by those with a bit of Python programming experience. Possibilities for enhancing Check_MK include:

  • Own checks and agent plug-ins, including data entry masks for WATO
  • Own plug-ins for Check_MK Inventory
  • Extensions for the GUI (Views, Dashboards, Columns, Icons, ...)
  • Definition of graphs or Perf-O-Meters
  • Alarm and alert handler scripts (also in Shell or other Script languages)

All of these enhancements are effected by saving your own data in the ~/local folder in a Check_MK instance. In order to manage these extensions effectively, to roll them out from distributed environments, and also to enable these to communicate with other users, Check_MK provides its own package format: the Check_MK extensions package - the MKP.

An MKP can collect any number of extensions - e.g., a set of check plug-ins including handbook pages, WATO masks and metric definitions. The MKP has a name, a version, and can be installed or likewise subsequently deinstalled with a simple action.

1.1. The Check_MK exchange

Users can submit user packages for the community to share on the <Check_MK Exchange site. From here free extensions can be downloaded for your use. Please be aware that packages in the exchange have been voluntarily submitted by other users and are therefore provided without any kind of guarantee. It is possible that these have not been correctly programmed and can cause problems with your Check_MK version. MKPs can naturally also contain errors that can lead to all sorts of problems and even to data loss. It is strongly-recommended to first trial all externally-provided packages on a test system.

1.2. Tools for MKPs

The are two tools for managing MKPs:

  • The command line command mkp
  • The [icon_mkps.png] Extension Packages (only ) WATO module

We will now look at both of these procedures. They are compatible, so that sometimes one, or sometimes the other can be used without getting "mixed up".

2. Managing extension packages using WATO

From version 1.2.8 WATO has offered the new Extension Packages module, with which MKPs can be managed and also be modified or created. This module can be accessed, as usual, via the WATO element in the sidebar:

2.1. Installing an MKP

An MKP, for example, that you have downloaded from the Exchange, can be uploaded and installed by using the Upload Package button. You will also need the data on the computer on which your web browser is running. The data set name must have the .mkp extension.

During the installation the data sets will be installed in the correct locations under ~/local/. In addition, a package description file will be saved in ~/var/check_mk/packages/. Following the upload the package will appear in the list of installed MKPs:

Finally, you require only an Activate Changes, with which all of the package's functions will be anchored in the system and ready for use:

2.2. Deinstalling packages or releasing their files

Using the appropriate symbol in the package list you can either delete a package or release its files. With a deletion the package with its installed files and extensions will be removed - the opposite of an installation so to speak. A release on the other hand leaves the package's data under ~/local/ quasi free and removes only the package description - the result being that the files are unpackaged and the extension remains active. This is the opposite to creating a package.

2.3. Creating packages

Creating your own MKP is very simple (not considering the small matter of the extension first having to be coded, naturally). The starting point is that your own data sets have been saved to the appropriate folders under ~/local/. For own check plug-ins the correct folder is, for example, ~/local/share/check_mk/checks. These data sets at first belong to no package and thus will be listed under Unpackaged Files:

Via the symbol you can access the dialogue for creating a new package:

Alongside the obvious entries it is important that you select at least one data set to be packed. With the creation a package description will be saved under ~/var/check_mk/packages/, this description defining the general information and also the list of included data sets.

This package - intended for another system or for uploading to the exchange, for example - will be seen in the package list with the symbol as an MKP data set for downloading.

Note that subsequent changes to the packaged data sets do not require the package to be created anew. A simple download of the MKP file is sufficient. On the other hand, following a change it naturally can't hurt to give the package a new version number.

3. MKP on the command line

All of the actions described above can be executed on the command line. The mkp command (an abreviation of cmk -P) serves this function:

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. Installing an MKP

A package installation is executed with mkp install. Naturally the MKP data must first be loaded to the monitoring server (e.g. with scp). Lastly, the installation is started with the command:

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

The installed packages can be listed with mkp list:

OMD[mysite]:~$ mkp list
mypackage

The details of an individual package can be seen 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.2.8
Required Check_MK Version:     1.2.6
Title:                         My own check plugin that checks my stuff
Author:                        Alfred E. Neumann
Download-URL:                  http://www.example.com
Files:                         checkman(1) checks(1)
Description:
  This package contains a check plugin that checks my stuff

3.2. Deinstalling packages or releasing their files

Deinstalling a package is executed with mkp remove. This command deletes the package description as well as all of its data sets!

OMD[mysite]:~$ mkp remove mypackage

Release a package with mkp release. With this the extension's data sets are retained, and only the package description is deleted:

OMD[mysite]:~$ mkp release mypackage

3.3. Creating packages

Creating MKPs on the command line is analogous to creation in the WATO module, but perhaps not so conveniently. Firstly, create your extensions in the appropriate folders under ~/local/. All unpackaged data sets can be found 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

With the mkp create command - include the desired name for the new package - you now create a new package which (at first) contains all of these data sets:

OMD[mysite]:~$ mkp create mypackage

The characteristics of the package can now be edited with a text editor. The data is stored in var/check_mk/packages/mypackage:

var/check_mk/packages/mypackage
{'author': u'Alfred E. Neumann',
 'description': u'This package contains a check plugin that checks my stuff',
 '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 that checks my stuff',
 'version': '1.0',
 'version.min_required': '1.2.6',
 'version.packaged': '1.2.8'}

Edit this data as desired. Adhere to correct Python-Syntax. Texts that contain non-Ascii-characters (e.g umlauts) must be prefixed with a lower case u.

Under the files entry you can remove data sets that are not to be packaged. In version.min_required enter the minimum version of Check_MK required to be able to run the plug-in.

Lastly, the .MKP file is created 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 a distributed monitoring it is sufficient when the packet has been installed on the master. For each connection to a slave site it can be specified whether the customisation should be passed to that site. The Extensions option must only be activated to make this possible. Subsequently during a synchronisation the MKPs and all other changes within the ~/local directory will be carried over.

Should a carryover not be desired, simply deactivate the option for any specific, or all sites.

Important: The customisation will only be carried over if the Replication method has been set to Slave: push configuration to this site.