Icinga Director

Icinga Director is the web-based configuration tool for Icinga2. Director provides a simple interface for configuring the various parts of your monitoring environment. Even if you would rather do all of the configuration from a terminal, I still recommend using Director for its self-service API which allows new nodes to register with no interaction required on the node (i.e. via a script).

Start by logging into your Icinga instance. If you followed the master installation guide you should have a tab labeled Icinga Director. Click on that, and you should see something similar to this:

Hosts

Let's start by looking at the hosts section. Clicking on the hosts button from the Director menu will present you with several options. Click on host templates, and then click add to define our first host template. Host templates are the building blocks of Icinga, they allow for your nodes to be structured however you see fit, and then to have monitoring checks automatically applied to them based on that structure.

I like to structure my host templates by operating system. For example, I have a template called Linux Server, which is designed to encompass all of the Linux servers in my environment. I then get more specific, creating templates based on distro. These templates are children of the Linux Server template, so they inherit whatever is applied to the parent, but then can have distro-specific checks applied to themselves.

Start by giving your template a name - I will use Linux Server here. Groups can be left empty for now, but you may want to add groups and apply them to templates later. The check command should be set to hostalive. Expand Icinga Agent and zone settings and set Icinga2 Agent, Establish connection, and Accepts config to Yes. Click store to save the template. Your template should look like this:

Service templates

Let's turn to services now. Return to the Director menu and select Services. The services menu is structured similar to hosts, and we will start with the service templates section. The idea behind service templates is very similar to host templates. Typically, a service template corresponds to a single monitoring command.

As an example, we'll create a service template for a monitoring command that checks the status of a web server. Give the template a name, set the check command to http, and finally expand Icinga Agent and zone settings and set Run on agent to no. We set this to no because we want Icinga to query the web server externally instead of from the web server itself.

Service sets

Service sets are simply groups of service templates. They can be structured however you see fit. Service sets can then be applied to hosts/host templates to have the checks be automatically applied.

Add a new service set and give it a name. Then click on the services tab and add all of the services you want to group into that set. Here is an example of a service set Linux Standard that has service checks that should be applied to all Linux servers.

To bring service sets and host templates together, return to your host templates, select Linux Server, select the services tab, and then select add service set and choose your desired set from the dropdown menu.

Render your config

When you have made all of the changes you need you will need to render the Director configuration. Return to the Director menu, select Config Deployment, and then select Render config.

Self Service API

In this last section we will look at what I think is the best feature of Director which is the self service API. To enroll a host template in the self service API, select the host template, select the agent tab, and select generate self service api key. That's it! The string of letters and numbers is the API key associated with this host template. Hosts can be enrolled with this API key and Icinga will automatically assign the host to this template. With proper structuring, you can have hosts be completely provisioned without touching Director. In the next article, we will use this to enroll a host in Icinga with a shell script.