OP5 Monitor ["OP5 Monitor"]
["Technical Reference"]

# Custom plugins

## Overview

OP5 Monitor has an open architecture. You can extend the standard functionality by adding custom plugins from the Naemon community or developed by your own organisation.

The sections below explain how to create and install custom plugins. ITRS does not provide any support for custom plugins.

### Macros

Custom plugins in OP5 Monitor rely on the use of Naemon macros. For more information, see Macros in Manage commands.

## Create a custom plugin

The following procedure explains how to write a simple shell script to run as a plugin. You can use it as a basis for creating more complex custom plugins of your own.

To create a custom plugin:

1. Log on to the OP5 Monitor server, using SSH.
2. Add your custom plugin to directory `/opt/plugins/custom` and make it executable. In the following example, we are adding a new file called `check_local_helloworld`:

    cd /opt/plugins/custom
    touch check_local_helloworld
    chmod 755 check_local_helloworld

3. You can now edit your plugin file to add some checking logic. In the following example, we add code to print a value:

    #!/bin/sh
    echo 'WARNING: Hello, world!'
    exit 1

4. You can now execute the file to test it:

    $ ./check_local_helloworld
    WARNING: Hello, world!
    $ echo $?
    1

Success: You have created your custom plugin. The next step is to install it in OP5 Monitor.

## Install custom plugins on a standard OP5 Monitor server

You install a custom plugin by creating a new command for it and adding the command to a service configuration.

To install a custom plugin:

1. In the OP5 Monitor interface, click Manage > Configure > Commands.
2. Enter the details of the new command. For the plugin created in Create a custom plugin, the parameters are as follows:

    command_name: check_local_helloworld
    command_line: $USER1$/custom/check_local_helloworld

For guidance on creating commands, see Create and update commands in Manage commands.

3. Add the command to a service configuration. For guidance, see Configure a service in Manage hosts and services. You can now see it in the service list views:

## Install custom plugins on a Slim Poller

### Custom Docker image

Creating a custom Docker image on top of the image provided for the OP5 Monitor Slim Poller is the recommended way to install custom plugins on the Slim Poller. It is a flexible approach which enables plugin dependencies to be installed as well.

To create a custom Docker image, you need to define a new Dockerfile. This new image must be based on the `naemon-core` image. After you define the base image in the Dockerfile, you can install the plugin and dependencies as required.

The example Dockerfile below installs plugin `check_puppetdb`.

    FROM op5com/slim-poller_naemon-core:8.3.0

    # Run as root while installing
    USER root

    ARG PLUGIN_PATH=/opt/plugins/custom

    WORKDIR /tmp

    # Make sure the custom plugins path exists
    RUN mkdir -p $PLUGIN_PATH

    # Install dependencies
    RUN yum install -y ruby rubygems rubygem-json

    # install git
    RUN yum install -y git

    # Checkout the sourcecode from git
    RUN git clone https://github.com/xorpaul/check_puppetdb.git
    RUN cp ./check_puppetdb/check_puppetdb.rb $PLUGIN_PATH

    #clean up
    RUN rm -rf ./check_puppetdb/

    # Change back to correct monitor user
    USER $MON_UID

You can find more information on Dockerfiles at docs.docker.com.

### Build image

After you define your new custom Docker image, build the image using the following command:

    docker build -f <path/to/dockerfile>

Depending on how you deploy the Slim Poller, you might need to upload or push the image to your environment, or you can upload it to hub.docker.com.

### Change deployment files

After you make the new image available in your environment, change your deployment files to use this new image instead of the `naemon-core` image. For more information on Slim Poller deployment files, see Scale up your monitoring environment in Scale up your monitoring environment.

### Updates

After each new release of the Slim Poller, you must rebuild your custom image to ensure you have the newest changes. You can use the following commands to do this manually.

    docker pull op5com/slim-poller_naemon-core
    docker build . --no-cache

## Example custom plugin

The following example creates a plugin to print the OP5 Monitor storage path:

    #!/bin/bash
    # Create a function to print the storage path
    storagepath() {
      grep ^storagepath /etc/op5-backup/main.conf |tail -1 |sed 's/^[^"]*"//g' | sed 's/"$//g'
    }

    # Put the storage path in an environmental variable
    STORAGEPATH=`storagepath`
    # Test if the storagepath exists and is a directory
    if [[ ! -d "$STORAGEPATH" ]]; then
      # Print a warning message for the web gui
      echo "op5-backup is not properly configured for local operation"
      # Exit with status Warning (exit code 1)
      exit 1
    fi

    # If the script reaches this point then the test passed
    # Print an OK message
    echo $STORAGEPATH exists
    # Exit with status OK
    exit 0

For more information on custom plugins, see Naemon - Plugin API documentation.

Was this topic helpful?
Your thoughts...
How can we improve this topic?
It did not answer my question(s)
Confusing
Missing screenshot or graphics
Missing technical details
Information is out of date
Your thoughts...
Thank you for your feedback!