Introduction

Alignak is a monitoring framework. It is used to check your IT (or over) and to keep you informed about problems and performance degradation (mail, SMS, XMPP…). It can be used from small environments to very large (multi-datacenter, fail-over, load-balancing).

WARNING: Alignak is still under development but is yet stable enough! The first release is however very close.

During this tutorial, we’ll install Alignak and its satellites, who are written mainly in Python. Despite Alignak team is trying to make it an easy to set-up monitoring solution, Alignak and its satellites require a minimum knowledge with Linux and being resourceful.

This tutorial comes in addition to the demo tutorial provided by the Alignak team: Alignak Demo.

Almost all of Alignak’s repositories have stable versions available via pip. But I’ll try to provide each repository URL each time you install a new software.

Prerequisites

Note: This tutorial was run on an Ubuntu 16.04 LTS server. Other Linux distributions are also compatible.

Mandatory Requirements

First of all, like all installation, you need to have a server up-to-date:

sudo apt-get update && sudo apt-get upgrade

Then some tools are needed and obviously Python. Main satellites of Alignak are only compatible with Python 2.7 ! So if you have Python 3 installed, be sure python command is linked to Python 2.7.

Alignak base

Note: You have to know that all Alignak components need a root account (or sudo privileges) to get installed.

Alignak need also an alignak user. Don’t create it yet, we’ll create after with a script.

Many components will be installed with pip, only the Alignak framework is installed with Git. If you want to install from the repository also, it is recommended to use only the develop branch. Alignak team makes sure that the develop branch of all the repositories is always a stable version.

Note: Alignak framework is enough to check the monitored system and get information about the detected problems thanks to the notifications. But we need more than this… what about a friendly user interface, logs retention, performance data…?

Web services

The Web Services module exposes Web services to get information from Alignak (logs, daemons status), notify external commands to Alignak or push checks results to Alignak. This module is also used by the Alignak Web UI to interact with the monitored systems thanks to commands.

Configure Alignak

As you will see, most of the configuration will be located in /usr/local/etc. Inside this folder, you’ll find the alignak, alignak-backend and alignak-webui folders.

Alignak packages and modules will install there configuration files inside /usr/local/etc/alignak (like alignak-notification for example). With this system alignak developers want the configuration of Alignak and its satellites to be centralized maximum.

Note: All alignak configuration files are widely commented and detailed for each options ! Read carefully before making any changes.

As you can see some files in alignak folder are missing alignak user / group and the same for the log folder.

To solve that, run the following commands:

cd ~/repos/alignak
sudo ./dev/set_permissions.sh

Now your installation is OK and ready to get adapated to your needs!

We’ll begin with the Backend and WebUI folder which are the more simple to set-up.

Configure Alignak Backend

You will find 2 files in the alignak-backend folder:

uwsgi.ini

settings.json

Right now, edit the following file:

sudo vi /usr/local/etc/alignak-backend/uwsgi.ini

In this file you can see that backend is listening by default on 0.0.0.0:5000. You can change IP and Port but don’t forget after to report this change to the other files (alignak backend modules configuration files)!

The JSON file contains some other configuration parameters essentially for the Backend data, Mongo or Timeseries databases.

Configure Alignak WebUI

In alignak-webui folder, you’ll find 3 files:

uwsgi.ini

settings.cfg

logging.json

Open the uwsgi.ini file. You will see that this file looks much like the backend one. WebUI is listening on 0.0.0.0:5001 by default. Personnaly I prefer to use port 80, so:

http-socket = 0.0.0.0:80

Then open the main WebUI configuration file: settings.cfg. If you’ve modified IP and port of your WebUI, report your change here:

The alignak.cfg file is the configuration file you’ll import in the backend of Alignak. It mainly defines the files that will be imported or not in the backend. Currently you don’t need to modify something in this file, unless you do not use the default directories.

The alignak.backend-run.cfg is a sample file like the one above. This file is intended to be used when you want to run Alignak with the configuration you stored in the backend.

The alignak.ini file is only used by the scripts provided in the dev forlder of the repository. It is not used by Alignak so do not care about them;)

Folder arbiter: this folder contains all main configuration files. Here you will define your hosts, your services, your check commands, as well as the configuration of the modules.

Folder certs: it is used to store your certificates if you are using SSL connection between the Alignak daemons.

Folder daemons: contains the daemon ini files, which allow to define the folders, the pid, the port,…

Configure daemons

First we will configure the daemons. Into the arbiter/daemons folder, you can find one .cfg file for each Alignak daemon.

You must at least add the modules of the Backend and the other modules that you’ve installed. Here is sample examples for each daemons:

Arbiter

# Address of the daemon
address127.0.0.1# Add the modules you have installed.
modulesbackend_arbiter

Broker

# Address of the daemon
address127.0.0.1# Add the modules you have installed.
modulesbackend_broker, logs

Poller

# Address of the daemon
address127.0.0.1# If you install booster modules, add them here !

Reactionner

# Address of the daemon
address127.0.0.1# There is currently no modules available for this daemon.

Receiver

# Address of the daemon
address127.0.0.1# If you install web-services, nsca or external-commands, add them here !

Scheduler

# Address of the daemon
address127.0.0.1# Add the modules you have installed.
modulesbackend_scheduler

For each file, you can also set timeout, data_timeout, max_check_attempts and check_interval and other settings, like spare or ssl. For the moment, do not care about this…

Configure modules

Now that you have linked your modules to the daemons, you must configure them in arbiter/modules/ folder.

The configuration in this folder is almost the same. Be sure to update the api_url if your backend is not on 127.0.0.1 by default. Here is an example

# Change address according to your backend configuration
api_urlhttp://127.0.0.1:5000# Use your token instead of username and password
# token xxxxxxxxxxxxx-xxxxxxx-xxxx-xxxxxxxxxxxx
# For the first import, you can let password by default
# It is recommended to change it afterwards
usernameadminpasswordadmin

Other configurations

We have already seen what is inside daemons and modules folder. But if you’ve installed other alignak components, like notifications, you will find them in the packs folder.

Inside notifications, you’ll have notification-ways.cfg file which defines the way users will be notified. You must add your choosen notification-ways in your contacts if you want to receive notifications.

You can see in this file that you have commands. They are defined in the commands.cfg file next to it.

Finally, inside the resource.d folder, you have notifications.cfg file where you can add your SMTP settings.

Note: this pack requires an SMTP server for the mail notifications to be sent out. If none is available you will get WARNING logs and the notifications will not be sent out, but alignak will run anyway.

use: tell to alignak which template this host will use, located in arbiter/templates folder.

contact_groups: tell with which contact groups this host is related. If a user is not in this group, he will not be related to this host for the notifications.

host_name: the name of host

address: the adress of host (IP or FQDN). Be sure your server can join your DNS to resolve FQDN !

Currently, localhost has no service defined, we will add one.

If you’ve install some checks, they are normally located in one of the following folders: /usr/lib/nagios/plugins/ (for Nagios-plugins), /usr/local/libexec/monitoring-plugins/ (for Monitoring plugins) and /usr/local/var/libexec/alignak/ (for alignak-checks).

For the following example, we will use the alignak-checks-snmp and the command check_snmp_storage.pl. If you have not installed this plugins, you can do it now:

That’s all ! If we try to sum-up, we have an host which uses a template, and which has a service which uses a template and this last has a command. A service must always have an associated host and a check command!

You have noticed that there are variables (macros) in these configuration files. They are usually defined in other configuration files, such as templates. For the $SNMPCOMMUNITYREAD$, you can find her in arbiter/packs/resource.d/snmp.cfg file.

Each variable must follow the following syntax: $MY_VARIABLE$ !

Start Alignak

Now we are ready to start our alignak server. We’ll use screen tool we have installed at the beginning of the tutorial. To make things easier we’ll create scripts for that.

Return to your home folder or in a folder you’re sure and make an alignak_cmds folder. Don’t create it in the alignak repos folder or install folders of alignak ! Otherwise, it will be erased during updates !

cd ~;
mkdir alignak_cmds; cd alignak_cmds/

Start/Stop backend

First we have to start the backend. Be sure your mongod is running before !