Add Custom Icons to Hosts and Services in WATO

Dies ist die alte Dokumentation.
Sie können die neue Dokumentation hier finden, die im Laufe der Zeit die Artikel hier nach und nach ersetzt.
Dieser Artikel wird nicht mehr gepflegt und ist unter Umständen nicht mehr gültig - der neue Artikel hierzu ist jedoch noch nicht fertig!

1. Motivation

It is possible to add one single icon_image to hosts and services since a long time in classic Nagios and also in Multisite. But in many situations this is not enough. You often want to add multiple icons and also more than a simple image. In some cases you want to add an image with a link to the management web interface of a network defice and also an image with a link to the command line interface which lets your client open a command line client which connects to this device.

Multisite icon painter To face this requirement and the different requirements Multisite provides a plugin based API in the icon painter of host and service rows within Multisite. So if you open a view in multisite which shows host or service information and see the icon painter, this is the place you can extend.

2. How to create an icon plugin

The icon plugins are stored in the directory /share/check_mk/web/plugins/icons. In OMD the path for custom icon plugins is local/share/check_mk/web/plugins/icons relative to the sites home directory. All files within those directories named *.py are read and used by Multisite. If you are using OMD, please note that you don't name your files or You would override the default icon plugins shipped with Checkmk - in most cases you don't want that.

An icon plugin is a python function which gets four parameters and returns one string of rendered HTML code or None. Those plugin functions must be registered to multisite by adding them to the multisite_icons list.

To describe the API, we take a look at a simple icon plugin which can be used as skeleton for starting developing your own icon plugin:

def paint_my_own_icon(what, row, tags, custom_vars):
    what:        The type of the current object
                 string "host" or "service"
    row:         The livestatus row for the current object.
                 A dictionary of host attributes
    tags:        List of cmk tags for this object
    custom_vars: Dict of objects custom variables
    return repr(row)

This is one simple icon function which only outputs the contents of the current row as text. You can use this data to investigate which information are available and thus can be used for rendering future icons.

To make a plugin available in Multisite, it needs to be registered. To do this you need to add a dictionary to the multisite_icons list. The order of the multisite icons controls in the list controls the order in the GUI.

The dictionary must at least contain the paint attribute with the paint function as value. There are several other optional attributes as shown in this example:

    # List of host/service columns to be used in this icon
    'columns':         [ 'icon_image' ],
    # List of columns to be used in this icon when rendering as host
    'host_columns':    [],
    # List of columns to be used in this icon when rendering as service
    'service_columns': [],
    # The paint function as mentioned above
    'paint':           paint_icon_image,

With the *columns attributes you can define which information the icon plugin needs from livestatus to paint itselfs. All columns are prefixed with the object type host_ or service_ when communicating wiht livestatus. The service_columns are only fetched when dealing with service objects.

3. Example: Add Icon and Link to Website for all HTTP-Checks

# encoding: utf-8

def paint_http_icon(what, row, tags, custom_vars):
    if what == 'service' and row['service_description'].startswith('HTTP '):
        url = 'http://%s/' % row['host_address']
        return u'<a href="%s" title="Webinterface">' \
	       '<img class=icon src="images/icon_www.png"/></a>' % (url)

    'paint':           paint_http_icon,
    'host_columns':    [ 'address' ],
    'service_columns': [ 'host_address' ],