Icinga2 scripts

Scripts to make administration of Icinga2 servers easier.

generate-nginx-vhosts-config.py

This script reads in nginx's site-enabled files, extracts the virtual hostnames, and generates an icinga configuration file to make icinga2 check not only whether the web server is up, but also whether all the hosted domains and subdomains are in a healthy state.

In order to be able to customize the generated configuration, it reads in a file config.yml which must be in the same directory as the script. In this file, the user can specify single virtual hosts, and override a given set of keys supported by the script.

Those are currently:

• hostname: (sub)domain extracted from the nginx configurations
• uri: default /, change this to check a "subdirectory" or specific index file
• expect: a semicolon-separated list of strings. The HTTP header status line is matched with them one by one, at least one of them needs to yield a match. Example: expect: "404"

More information on how those parameters are interpreted by check_http can be found in the man page.

Install

The script has a few runtime dependencies, for which Ubuntu, Debian and most likely all the other major distributions provide packages.

Ubuntu/Debian:

> sudo apt install python3-yaml python3-jinja2

To install these scripts, you will have to clone this repository to a location on your server, e.g., /srv or /opt.

Next, copy config.yml.template to config.yml and edit it to your needs. You probably don't want to make changes here before running generate-nginx-vhosts-config.py once and have icinga2 perform the checks, as the checks will tell you which entries you need to add to the config, and what status you can expect, given icinga2 finds the pages in their normal state.

The script will generate the file /etc/icinga2/conf.d/nginx-vhosts.conf, and you need to include that script in your /etc/icinga2/conf.d/hosts.conf. Place the following snippet below the line containing vars.http_vhosts["http"]:

  // autogenerated file
  include "nginx-vhosts.conf"

Finally, you need to have cron execute the script occassionally to update the icinga2 configuration. If you change vhosts very often or receive a lot of false positives, you should run this script e.g., every five minutes. For a private instance, an hourly execution should be appropriate.

Therefore:

> cd /etc/cron.hourly
> ln -s /srv/icinga2-scripts/generate-nginx-vhosts-config.py`

That's it. The script should be executed every hour.

Debugging and Testing

By calling export DEBUG=1, the script will no longer write to your system and won't reload icinga2 after performing changes. Instead, the configuration is written to stdout.

TODO

• support adding custom entries in the config file, e.g., to check multiple "subdirectories" on the same domain
• automatically alter icinga2 config to include the generated file