Check_MK Packages

Introduction

Check_MK and the web GUI Multisite are extensible in many ways. You can write your own:

• Checks
• Manpages for checks
• Agents and agent plugins
• Extensions for Multisite (sidebar snapins, layouts, filters, sorters, painters)
• Templates for PNP4Nagios
• Documentation files

The new packaging mechanism of Check_MK supports you in distributing your extensions and using extensions from other people by allowing you to easily create, install, update and remove packages of extensions, which are portable between all installations of Check_MK - regardless of the installations paths choosen at setup.

Overview over the packager

The packager is called with the option -P or --package of check_mk. Without any further argument it prints a list of packaging commands:

root@linux# check_mk -P
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 /var/lib/check_mk/packages/.

Check_MK keeps track of which files belong to installed packages and which files are unpackaged. Uninstalled packages ("package files") are files with the extension .mkp. After a fresh installation of Check_MK all files are packaged and belong to the (only) packet check_mk. If you add you own files by simply copying them the various installation directories or created them there, new unpackaged files come into existence.

Creating packages

Creating own packages is most easily done by collecting all unpackaged files into a new package. The command find lists all unpackaged files:

root@linux# check_mk -P find
/usr/share/check_mk/checks/my_check
/usr/share/doc/check_mk/my_check

Adding the option -v gives a more verbose output:

root@linux# check_mk -vP find
Unpackaged files:
  Checks:
    my_check
  Documentation files:
    my_check

Creating a package foo containing these two files is as easy as using the command create foo:

root@linux# check_mk -vP create foo
Creating new package foo...
  Checks:
    my_check
  Documentation files:
    my_check
New package foo created with 2 files.
Please edit package details in /var/lib/check_mk/packages/foo

That way we have created an installed package. No more unpackaged files are lying around. The command list should show two packages now:

root@linux# check_mk -vP list
Name     Title                       Version Files
-------- --------------------------- ------- -----
check_mk Files shipped with Check_MK 1.1.5i3 356
foo      Title of foo                1.0     2

Before we create a package file we should provide a useful title and description and some other attributes. This is done be editing the package description file in /var/lib/check_mk/packages/foo:

{'author': 'Harri Hirsch (hirsch@example.com)',
 'description': 'The foo check makes sure that no bar is missed.',
 'download_url': 'http://example.com/foo/',
 'files': {'agents': [],
           'checkman': [],
           'checks': ['my_check'],
           'doc': ['my_check'],
           'pnp-templates': [],
           'web': []},
 'name': 'foo',
 'title': 'Check foo on bar',
 'version': '1.0',
 'version.min_required': '1.1.5i3',
 'version.packaged': '1.1.5i3'}

Now we are ready to create a package file. This is done with the command pack:

root@linux# check_mk -vP pack foo
Packing foo into foo-1.0.mkp...
  Checks:
    my_check
  Documentation files:
    my_check
Successfully created foo-1.0.mkp

Please note that the package foo and all of its files stay installed when packing a package.

Creating packages (quick)

Here once again how to create a package out of unpackaged existing files, this time the fast way:

root@linux# check_mk -P create bar
root@linux# vim /var/lib/check_mk/packages/bar
root@linux# check_mk -P pack bar

Examining packages

The commands show and list show you the details and packaged files of installed packages of package files:

root@linux# check_mk -P show foo
Name:                          foo
Version:                       1.0
Packaged on Check_MK Version:  1.1.5i3
Required Check_MK Version:     1.1.5i3
Title:                         Check foo on bar
Author:                        Harri Hirsch (hirsch@example.com)
Download-URL:                  http://example.com/foo/
Files:                         doc(1) checks(1)
Description:
  The foo check makes sure that no bar is missed.

And the list of contained files:

root@linux# check_mk -P list foo
/usr/share/check_mk/checks/my_check
/usr/share/doc/check_mk/my_check

The same works on the package file - this time with the option -v:

root@linux# check_mk -vP list foo-1.0.mkp
Files in package foo-1.0.mkp:
  Checks:
    my_check
  Documentation files:
    my_check

Installation, Update and Removal

The installation and update of a package is done with the command install. Simply add the name of the package file as an argument:

root@linux# check_mk -P install foo-1.0.mkp

Update

If a package with the name foo is already installed, an update mode will be selected - regardless of wether the new version number is greater, less or the same as the current one. In update mode first all new files are installed and then all files of the old version of the package that are not contained in the new one are deleted.

Conflicts

It is not allowed for two packages to share a file. You cannot install a package that contains a file which is already part of another package. The same holds for unpackaged files: The installation of a package will never overwrite existing files. You either have to delete or rename the corresponding files or refrain from installing the package.

Removal

An existing package is being removed with the command remove. Please note, that you do not specify the name of a package file here but just the package name:

root@linux# check_mk -P remove foo

All files of the package will be deleted from your file system.

Releasing files into freedom

The command release does much the same as remove but does not actually delete the packaged files from the filesystem. It just removes the package information file and thus renders the files of the package unpackaged:

root@linux# check_mk -P release foo

That way, release does quite the opposite of create.

Internal package structure

A Check_MK package is a gzipped compressed tar archive containing a text file with the name info and a list of uncompressed tar archives containing the files to be installed into the various installation directories. Thus you can manipulate a package with standard tools. But please understand that the internal structure of the packages is subject to change in future releases.