Add Custom Icons to Hosts and Services in WATO


This article is obsolete and may be not valid anymore!

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 builtin.py or wato.py. You would override the default icon plugins shipped with Check_MK - 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:

check_mk/web/plugins/icons/my-own-icon.py
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:

multisite_icons.append({
    # 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

check_mk/web/plugins/icons/http.py
#!/usr/bin/python
# 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)

multisite_icons.append({
    'paint':           paint_http_icon,
    'host_columns':    [ 'address' ],
    'service_columns': [ 'host_address' ],
})