Checkmk
Deutsch
master1.6.0latest (2.1.0)
to checkmk.com

1. Introduction

Checkmk has a very modular structure, and those with a knowledge of Python programming can extend it in many places. Among other things it is possible to extend Checkmk with the following elements:

  • Own checks and agent plug-ins, including input masks for the configuration environment.

  • Own plug-ins for the Checkmk HW/SW inventory

  • Extensions for the GUI (views, dashboards, columns, icons, etc.).

  • Definitions of graphs or Perf-o-Meters

  • Notification and alert handler scripts (also in shell or other scripting languages).

All of these these extensions can be implemented by placing additional files in the ~/local directory within the Checkmk site. To manage these extensions, to roll them out in distributed environments and also share them with other users, Checkmk provides its own package format the Checkmk extension package — in short MKP.

An MKP can include any desired set of extensions — for example, a set of check plug-ins including associated manual pages, threshold configuration environments and associated metric definitions. It can furthermore contain settings for distribution via the Agent Bakery. An MKP has a name, a version number and can be installed or removed with a simple action.

1.1. The Checkmk Exchange

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.

1.2. Tools for MKPs

There are two tools for managing MKPs:

  • The command line command mkp.

  • The Setup menu item Extension Packages (CEE Checkmk Enterprise Editions only)

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".

2. Managing extension packages via the Setup Menu

CEE The facility to manage MKPs via the GUI exists exclusively in the Enterprise Editions of Checkmk. In the Setup menu you enter the administration of MKPs via Setup > Maintenance > Extension packages. Here you can install, modify or create MKPs:

mkp manager sidebar

2.1. Installing an MKP

An MKP that you have downloaded from the Exchange, for example, can be uploaded and installed into Checkmk using the Upload package button. For this you need to have the file to be located on the computer where your web browser is running. The file extension for the package must be .mkp.

mkp manager upload

During the installation, the files will be installed in a folder hierarchy under ~/local/. In addition, a package description file is placed in ~/var/check_mk/packages/. After uploading, the package will appear in the list of installed MKPs:

mkp manager list

Now you only need an activation of changes and all functions from the package are anchored in the system and ready for use.

2.2. Package deinstallation

You can delete an installed package using the corresponding icon icon delete in the list of packages. With a deletion, the package itself is deleted along with its installed files and the extension is thus completely removed — the opposite of an installation.

2.3. MKPs in distributed environments

For distributed monitoring it is sufficient to install the packages on the central site. Each time you connect to a remote site, you can determine if the customizations should be transferred to that site. All you have to do is to activate the Replicate extensions option. After that, the MKPs and all other changes under the ~/local directory will be replicated to remote sites at the next synchronisation.

mkp distr wato

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

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

2.4. Installing Feature Packs

Besides plug-ins Checkmk also supports Feature Packs. These extensions provide new functionalities, which will actually be included in the next stable version of Checkmk. Such functionalities can be, for example, enhancements of existing checks or special agents. They are included in the actual Checkmk version and only need to be activated — or deactivated again.

There are currently no Feature Packs planned for Checkmk 2.0.0.

3. MKPs for developers

If you are programming or modifying your own plug-ins for Checkmk, please see the articles on the existing programming interfaces and the file system structure, the integration into the Agent Bakery and the guidelines for check plug-ins.

3.1. Unpacking packages

The icon release mkp 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 oppositeof 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.

3.2. Creating packages

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:

mkps unpackaged
List of Unpackaged files and the Create package button.

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

mkps create

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. 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 download 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 icon edit to change the version number, save the modified package and re-download it if necessary.

4. MKPs on the command line

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

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

Available commands are:
   create NAME      ...  Collect unpackaged files into a new package NAME
   pack NAME        ...  Create package file from an 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 in installed package
   list PACK.mkp    ...  List files in 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 a package from file PACK.mkp
   remove NAME      ...  Uninstall a package with the NAME

   -v  enables verbose output

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

4.1. Installing an MKP

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 a command:

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

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

OMD[mysite]:~$ mkp list
mypackage

For details on the contents of an individual package, use mkp show:

OMD[mysite]:~$ mkp show myPackage
Package file: /omd/sites/mysite/var/check_mk/packages/myPackage
Name: myPackage
Version: 1.0
Packaged on Checkmk Version: 2.0.0p23
Required Checkmk version: 2.0.0
Valid until Checkmk version: 2.1.999
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

4.2. Deinstalling or unpacking packages

Deinstalling a package is done with mkp remove. This command deletes the package description as well as all of its included files!

OMD[mysite]:~$ mkp remove mypackage

And you can release a package with mkp release. The extension files will be preserved and only the package description will be deleted:

OMD[mysite]:~$ mkp release mypackage

4.3. Creating packages

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:

OMD[mysite]:~$ mkp find
/omd/sites/mysite/local/lib/check_mk/base/plugins/agent_based/mycheck
/omd/sites/mysite/local/lib/check_mk/base/plugins/agent_based/mycheck_manpage

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:

OMD[mysite]:~$ mkp create mypackage

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

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

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:

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