Checkmk
DeutschEspañolFrançaisItaliano日本語
Cloud (SaaS) master2.4.02.3.02.2.02.1.02.0.01.6.0
Our AI policyAI

1. Introduction

In the other articles on the programming of extensions, you will have already learned how to develop extensions even with just a basic knowledge of Python. And you will surely have already downloaded and installed extensions as MKP from the Checkmk Exchange. In this article, you will learn everything you need to know about customizing Checkmk extension packages or creating them from extensions you have developed yourself.

1.1. The working environment

To create and customize MKPs, use a separate site for testing, and once the tests have been satisfactory, copy the MKPs to the production site for deployment. This will primarily save you from two potential problems that arise when modified files are not packaged into MKPs in a timely manner:

  • During a Checkmk update, locally modified files are overwritten by the latest version of the MKP (this is exactly what happened to the author of this sentence).

  • In a distributed monitoring with central setup, you will be puzzled because plug-ins behave differently on remote sites than on the central site, since the remote sites continue to receive the most recently packaged version.

In addition, the risk of accidentally overwriting something that already exists is much lower if a site is used primarily to test in-house developments and does not use any production-grade extensions from other sources.

1.2. Tools for MKPs

There are two tools for managing MKPs:

  • The mkp command

  • In the commercial editions, you also have the Setup menu item Maintenance > Extension Packages

Both methods are compatible, and changes made using one method are immediately visible in the other. However: additional options are available on the command line, which will be further expanded in the future. It can also be used in scripts.

For development work, we therefore recommend using the command line.

2. The workflow

In this chapter, we will show you how to modify an existing package by following these steps: disassemble, modify, rearrange, and repackage. Our example uses the sample MKP Hello world! available in the Checkmk Exchange. If you would prefer to build your own MKP from files you have created yourself, simply skip the first steps and go directly to search for unpackaged files.

2.1. Disassembling an MKP

For a package to be disassembled, it must first have the status Enabled (active on this site). This can be checked using the following command:

OMD[mysite]:~$ mkp list
Name        Version Title        Author             Req. Version Until Version Files State
----------- ------- ------------ ------------------ ------------ ------------- ----- -----------------------------
hello_world 0.2.5   Hello world! Mattias Schlenker  2.3.0b1      2.5.99        8     Enabled (active on this site)
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

If the package is not active, activate it:

OMD[mysite]:~$ mkp enable hello_world
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

If a package is incompatible with your Checkmk version but you still want to activate it—specifically to update it to the newer Checkmk version—use the additional parameter --force-install.

You can then disassemble the package with the following command:

OMD[mysite]:~$ mkp release hello_world
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

In the Setup of the commercial editions, an icon representing a block (icon release mkp) is also available.

2.2. Making modifications

Now you can modify existing files or add new ones. If your work is not based on an existing MKP but 'starts from scratch', so to speak, you will first need to create a directory structure and populate it, for example, as described in the articles on programming agent-based check plug-ins, special agents, or SNMP plug-ins.

2.3. Finding unpackaged files

Once your development work has reached a stage you are satisfied with, prepare to repackage it. The first step is to get an overview of which unpackaged files are located in the site directory. With this information, you can decide whether to delete files or to first package earlier experiments.

The command used for this is mkp find:

OMD[mysite]:~$ mkp find
File                                                  Package Version Part                                         Mode
----------------------------------------------------- ------- ------- -------------------------------------------- ----------
hello_world/rulesets/ruleset_hello_world.py                           Additional Checkmk plug-ins by third parties -rw-------
hello_world/agent_based/hello_world.py                                Additional Checkmk plug-ins by third parties -rw-------
hello_world/rulesets/ruleset_hello_world_bakery.py                    Additional Checkmk plug-ins by third parties -rw-------
hello_world/graphing/helloworld_perfometer_graphing.py                Additional Checkmk plug-ins by third parties -rw-------
hello_world/checkman/hello_world                                      Additional Checkmk plug-ins by third parties -rw-------
windows/plugins/hello_world.cmd                                       Agents                                       -rwx------
plugins/hello_world                                                   Agents                                       -rwx------
python3/cmk/base/cee/plugins/bakery/hello_world.py                    Libraries                                    -rw-------
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

The list displayed is for informational purposes only. In the commercial editions, you can use the List unpackaged files button on the Extension packages page. On the page that appears, you can easily delete files you no longer need.

2.4. Creating the package configuration

Use the mkp template command to create a template for a package configuration. You must specify the package name as an additional parameter. Since this command writes to standard output, you must either redirect the output or simply copy it from the terminal:

OMD[mysite]:~$ mkp template hello_world > ~/tmp/hello_world.info
OMD[mysite]:~$ cat ~/tmp/hello_world.info
{'author': 'Add your name here',
 'description': 'Please add a description here',
 'download_url': 'https://example.com/hello_world/',
 'files': {'agents': ['plugins/hello_world', 'windows/plugins/hello_world.cmd'],
           'cmk_addons_plugins': ['hello_world/agent_based/hello_world.py',
                                  'hello_world/checkman/hello_world',
                                  'hello_world/graphing/helloworld_perfometer_graphing.py',
                                  'hello_world/rulesets/ruleset_hello_world.py',
                                  'hello_world/rulesets/ruleset_hello_world_bakery.py'],
           'lib': ['python3/cmk/base/cee/plugins/bakery/hello_world.py']},
 'name': 'hello_world',
 'title': 'Title of hello_world',
 'version': '1.0.0',
 'version.min_required': '2.5.0p4',
 'version.packaged': 'cmk-mkp-tool 3.0.0',
 'version.usable_until': None}
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

If you would rather use the package configuration from a previously unpacked package, simply extract it from the original package:

OMD[mysite]:~$ tar -Ox info -f ~/var/check_mk/packages_local/hello_world-0.2.5.mkp \
    > ~/tmp/hello_world.info
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

Now customize the package configuration using your favorite editor. As with many other configuration files in Checkmk, this is a Python file. Therefore, make sure to use correct Python syntax.

Under the files key, you can remove files that should not be included in the package. Under version.min_required, enter the minimum version of Checkmk required to use the package. Under version.usable_until, you can specify the highest Checkmk version for which the package is usable. If you use only the stable public plug-in APIs, your package will cover the entire range from 2.3.0 to 3.0.99. The version number used (version key) must comply with the conventions of Semantic Versioning. For minor changes such as bug fixes, increment only the last digit.

If you are using a commercial edition, you will find the Create package button on the Setup > Maintenance > Extension packages page. This button takes you to a form where you can enter all of the parameters contained in the package configuration template—without having to worry about correct Python syntax.

2.5. Creating the package

Once you have finished editing the configuration file, build the package by running mkp package followed by the name of the configuration file:

OMD[mysite]:~$ mkp package ~/tmp/hello_world.info
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

This process not only generates the MKP, which you can then find in ~/var/check_mk/packages_local/ or download via the package manager in the commercial editions. The package is also activated immediately (meaning it has the status Enabled (active on this site)), which corresponds exactly to its behavior before packaging.

Note that when packaging on a production site with a central setup enabled, the new package will be automatically distributed directly to the remote sites. This fact should be another reason to use dedicated test sites.

3. Publishing on the Checkmk Exchange

If you would like to share your newly created MKP, you can upload it to the Checkmk Exchange. There are a few things to keep in mind before uploading:

  • Be aware that your extension uses programming interfaces licensed under GPL v2 and is therefore also subject to the GPL v2 license.

  • Checkmk performs a security check on the extension prior to publication to identify any potential risks. Packages that read from or write to directories outside a site directory, or that use APIs not provided by Checkmk, will be rejected.

  • When extending existing (possibly orphaned) packages, point out potential conflicts due to the use of the same directory structure. Users should be aware that they must disable the original package before installing your version.

4. The MKP package format

If you just want to take a look inside an MKP or extract individual files without installing the entire package, it is helpful to understand the package format. Looking inside a package is quite simple, because the MKP format is simply a .tar.gz file, which in turn contains .tar files and manifest files.

Examining the downloaded file hello_world-0.2.5.mkp reveals the first level of the structure:

user@host:~$ tar -tvf hello_world-0.2.5.mkp
-rw-r--r-- 0/0            1715 2025-03-07 16:19 info
-rw-r--r-- 0/0            1311 2025-03-07 16:19 info.json
-rw-r--r-- 0/0           10240 2025-03-07 16:19 agents.tar
-rw-r--r-- 0/0           20480 2025-03-07 16:19 cmk_addons_plugins.tar
-rw-r--r-- 0/0           10240 2025-03-07 16:19 lib.tar
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

Using a pipeline consisting of two tar commands, you will be able to view the contents of cmk_addons_plugins.tar:

user@host:~$ tar -Ox cmk_addons_plugins.tar -f hello_world-0.2.5.mkp | tar -tvf -
-rw------- mysite/mysite 3711 2025-03-07 10:59 hello_world/agent_based/hello_world.py
-rw------- mysite/mysite 1079 2025-03-07 10:59 hello_world/checkman/hello_world
-rw------- mysite/mysite 1179 2025-03-07 10:59 hello_world/graphing/helloworld_perfometer_graphing.py
-rw------- mysite/mysite 3373 2025-03-07 10:59 hello_world/rulesets/ruleset_hello_world.py
-rw------- mysite/mysite 2634 2025-03-07 10:59 hello_world/rulesets/ruleset_hello_world_bakery.py
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

And what about the two manifest files, info and info.json? You learned about the info file and its fields—which are in the Python dictionary format—earlier above. The JSON equivalent, info.json, contains exactly the same fields and values, but has been serialized in JSON format.

5. Command reference

Commands for management and for updates can be found in the article on managing MKPs.

5.1. Development

Subcommand Parameter Function

release

Package name

Resolves an active package.

find

none

Lists all files that do not belong to any package.

template

Name of the new package to be created

Creates a manifest file as the basis for a new package.

package

Path to the manifest file

Creates an MKP based on the contents of a manifest file.
Last modified: Mon, 06 Jul 2026 07:29:15 GMT via commit 19cbaec62
On this page