Technical

Shinken services and you (writing your own service)

    • 8 December 2014
    • 4min read
featured 4

Introduction

Shinken is a monitoring service based on Nagios written in python. The cool stuff here is that it’s written in python, but also that you are able to use many, if not all, Nagios plugins.

“But Maarten, why is it so great that it’s written in python ?”.

Simple, you can actually pip install this entire monitoring system.

pip install shinken

After installing it, we just have to run the init command

shinken --init

Shinken itself comes with an update and install tool (much like apt-get) that lets you search and install plugins, modules and add-ons. It’s easy in use and easy to operate. Let’s get to it, then.

This guide will assume you’re working on an Ubuntu system and running Shinken 2.0.3.

Once you’ve installed Shinken, searching and installing is as easy as:

$ shinken search webui
$ shinken install webui

But let’s face it, this is not why we’re here. Let’s get started with the real stuff: installing a non default service.

Installing a custom service

So, to install your very own service, you’ll need to do 3 things: – define a command block – define a service block – activate this service in the desired host block

1. writing a command

While it’s possible to write your own plugin, for this command we’re going to use an existing plugin. In this case, we’re going to check if a certain web service is running with the check_http plugin.

You can get this plugin by installing the Nagios plugins trough apt-get install nagios-plugins

Let’s take a closer look at the check_http plugin before we move on.

check_http -H 192.168.111.111 -p 80

Check_http will send an http request to a given host and port returning a critical state if the http status is not in the expected range. You define the host you want to test using the -H parameter, while specifying the port is done with -p.

It’s important that we understand how this plugin works, so we have a good overview on how to define our command.

Now, we can approach the creation of a command block in 2 different ways. Defining macro arguments or defining host arguments.
The difference is easily explained: Macro arguments are used when the arguments used for your plugin command are always the same, while host arguments depend on the host you’re using the service for. Don’t worry, we’ll go over both ways of doing it.

Before continuing it’s useful to know that we’ll be defining our macro parameters in the service block (handled further below). While the host parameters are handled in the hosts block (also handled further below). Using one way does not exclude the other, so you are able to mix and mash as much as you like.

1.1. Using macro parameters. (MACRO WAY)

Create a file in your favorite text editor on the following location `/etc/shinken/commands/check_http_service.cfg`

define command {
   command_name   check_http_service
   command_line   $NAGIOSPLUGINSDIR$/check_http -H $ARG1$ -p $ARG2$
}

You can see we named our command `check_http_service`, you can name it as you like, but it’s important to note that you’ll be needing this name later on.

Also note that we’ve named our parameters ‘ARG1’ and ‘ARG2’ enclosed in ‘$’ signs. It does matter that you use this naming convention for macro parameters. The convention being ‘ARGn’ where n is the n-th argument.

1.2. Using host parameters (HOST WAY)

Create a file in your favorite text editor on the following location `/etc/shinken/commands/check_http_service.cfg`

define command {
    command_name check_http_service
    command_line $NAGIOSPLUGINSDIR$/check_http -H $_HOSTCHECK_HTTP_URI$ -p $_HOSTCHECK_HTTP_PORT$
}

Similar like the macro way, you define your parameters enclosed in ‘$’ signs, but here you are free to choose your parameter names as long as it’s prefixed by ‘_HOST’.

Now that we’ve defined our command, we’re ready to pour it into a service.

2. Writing a service

As mentioned before, we’ll be defining our parameters within the service block for the macro way. So here you’ll see a distinct change between the two ways.

2.1. Defining a service (MACRO WAY)

Create a file in your favorite text editor on the following location `/etc/shinken/services/check_http_service.cfg`

define service{
   service_description           My_Pretty_Web_Instance_Name
   use            generic-service
   register       0
   host_name      my_web_instance_service
   check_command  check_http_instance!192.168.111.111!80
}

There are a few things to note here.

  • Service description: This is the string that will be shown on your Shinken monitor to show the service. Basically, it’s your frontend service name.
  • Host name: Here you define your service name that you will use to activate the service in the hosts block (discussed further below).
  • check_command: Here you can see we’ve defined some parameters. Each new parameter is prepended with a “!” and corresponds with its respective $ARGn$ (where n is the n-th parameter… you get the picture… but to be very clear, this means that “192.168.111.111” is $ARG1$ and “80” is $ARG2$)

2.2. Defining a service (HOST WAY)

Create a file in your favorite text editor on the following location `/etc/shinken/services/check_http_service.cfg`

define service{
   service_description           My_Pretty_Web_Instance_Name
   use            generic-service
   register       0
   host_name      my_web_instance_service
   check_command  check_http_instance
}

Defining a service with host parameters looks very similar to that of using macro parameters, because, well… it is. You can see we’ve left out the hard coded parameters for the simple reason that we’re going to define them in the service blocks.

3. Enabling the service

3.1 Activating your service (MACRO WAY)

Create a file in your favorite text editor on the following location `/etc/shinken/hosts/my_hosts.cfg`

You’ll want your host block to look something like this:

define host{
   use my_web_instance_service
   host_name my_web_host
   address 192.168.111.123
}

Note: here you define all services you want running on this host delimited by a ‘,’ and no space. We want to use our shiny service, so we’ve added ‘my_web_instance_service’

3.2 Activating your service (HOST WAY)

Create a file in your favorite text editor on the following location `/etc/shinken/hosts/my_hosts.cfg`

You’ll want your host block to look something like this:

define host{
   use my_web_instance_service
   host_name my_web_host
   address 192.168.111.123

   _CHECK_HTTP_URI 192.168.111.111
   _CHECK_HTTP_PORT  80
}

Different from the macro way, you can see we’ve added two parameters here. As mentioned in the beginning of this post, you’ll want to do this if your input parameters for a service are different depending on which host you want to run it on.

It’s important to note that these parameters don’t have “_HOST” prepended, as defined in the command block. So it’s good to remember when defining other parameters

Well that’s about it, now you’ve got your very own service running.

The experienced Shinken users will have already noticed that the check_http feature comes with it’s very own pack (which is installable through the shinken install tool). A pack is a dedicated folder that houses all files related to a single service type (in this case http checks) and comes with an array of commands and services, which you can use as-is or are editable if you’re not 100% satisfied with how they work. But explaining packs in detail will have to wait for another blog post. Happy monitoring!

More in Technical