Welcome to Alignak-App’s documentation!

Documentation content:

Introduction

About Alignak

Alignak is an open source monitoring framework written in Python under the terms of the GNU Affero General Public License . It is a fork of the Shinken project.

More information about Alignak is available in the Alignak documentation.

About Alignak-App

The Alignak-App is an open source Applet in system tray, written in Python. It is available under the terms of the GNU Affero General Public License .

This application is intended to be used within the Alignak project, it connects to the Alignak backend and allows you to be notified directly on your workstation. You will be able to view the states of the hosts and the services that you have defined in your installation.

Features

Alignak-App has many features:

  • Multi-platfom: Linux / Windows
  • Receive Alignak notifications inside application
  • Spy host: choose to monitor multiple hosts and receive their states
  • Search Hosts and Services, acknowledge problems, schedule downtimes and more
  • Many configurations
  • Links to your Alignak WebUI from the menus

Release cycle

“App” has no strict schedule for releasing.

Other features will come in the next versions and you can propose new features through project issues. Each feature is discussed in a separate issue.

Thanks

Thanks to ddurieux, mohierf and spea1 for their help and contribution.

Install Alignak-app

Requirements

Alignak Suite

You must have Alignak Suite installed before using this app :

Alignak-app need at least a functionnal and available alignak-backend to connect with it !

Windows Users

An installer is available in repository of Alignak-app on releases page. It is recommended that you use this installer to run Alignak-app on Windows.

You have nothing else to install if you are using the installer !

IMPORTANT: To keep it free, installer is not signed, so Windows Defender SmartScreen will warn you about that. Just click on “More Informations” and on “Execute anyway” to run installer.

IMPORTANT: This installer is currently only compatible with x64 architecture !

Linux Users

IMPORTANT Be sure to install this application with --user flags. Otherwise you may not be able to launch it !

You can install with pip:

pip3 install alignak_app --user

The required Python modules are automatically installed if not present on your system.

An installation for root will be available as soon as possible.

From Sources

External Libraries

You need to install Python modules that are listed in requirements.txt file with pip:

pyqt5<5.10
configparser
future
alignak_backend_client
python-gettext

Note: if you proceed to an end-user installation with pip, the required modules are automatically installed.

Installation

To install from source, clone repos and install with pip

git clone https://github.com/Alignak-monitoring-contrib/alignak-app
cd alignak-app
# If you're under Windows, use "pip" instead "pip3"
pip3 install . --user

Under Windows

If you’ve installed Alignak-app with pip under Windows, you must link install directory with your Program Files folder. Otherwise, App won’t start.

Open a command Windows console as admin and type the following line:

mklink /J "%ProgramFiles%\Alignak-app" c:\Users\<USERNAME>\AppData\Roaming\Python\alignak_app

Replace <USERNAME> by your username.

Be sure also that you’ve install Python3 on your device.

Alignak-app Main Folder

During installation, Alignak-app creates a root folder that contains all the files application need to run.

On Linux

The ROOT folder of the application should be under:

/home/$USER/.local/alignak_app/

On Windows

  1. If you install from Pip or with Sources:

The ROOT folder of the application should be under:

C:\Users\user\AppData\Roaming\Python\alignak_app\
  1. If you use Installer (see Install Alignak-app):

The ROOT folder will be located under:

C:\Program Files\Alignak-app\

This is to facilitate access to the configuration and respect Windows conventions.

Alignak-app Workdir

This folder is defined by the app_workdir.ini file located in the main application folder cited above.

The goal of this file is to define a directory where Alignak-app can write/read without problems to get settings and create log files. So make sure that you have the right to write and read.

You must set an absolute path for this settings.

Then only put/copy the settings.cfg in the folder you have defined.

Note: If you have not set this option, application use the same directory than cited above. If you have no rights, application will crash.

Configuration Parameters

Before running application, you must configure it.

You will find a file named settings.cfg located in the “ROOT” folder cited above. Otherwise, Alignak-app proposes to define your server Alignak and its port via the window login.

This file contains Sections who are introduced by a [section_name] header. Then, it contains name = value entries. All parameters are also explained in file. For the boolean parameters, you can use the following values: on/off, true/false or 1/0.

The most significant Section is [Backend]. You need set your backend url, ports and credentials.

[ToKnow]” Without connection on Backend of Alignak, App won’t start ! “

Settings file

Here is the full settings.cfg file. This file contains comments for each setting.

[Alignak]
; Backend authentication
; ------------------------------------------------------------------------------------------
; Credentials for your backend.
; 1/ Recommended: leave "username" and "password" empty. App will display a login Window.
; 2/ Recommended: set your token in "username" option and leave "password" empty.
; 3/ Not recommended: set your "username" and your "password".
; Read the alignak-app docs for more details on token and authentication,
; Or visit http://alignak-backend.readthedocs.io/en/latest/api.html#get-the-token
; The default values are empty.
username =
password =

; Alignak Url
; ------------------------------------------------------------------------------------------
; Url of alignak server.
; Default is http://127.0.0.1
url = http://127.0.0.1

; Backend url
; ------------------------------------------------------------------------------------------
; The url of your Backend.
; Default is %(alignak_url)s:5000
backend = %(url)s:5000

; Webui url
; ------------------------------------------------------------------------------------------
; The url of your Webui
; Default is %(alignak_url)s:80
webui = %(url)s:80

; Backend processes
; ------------------------------------------------------------------------------------------
; The number of processes for connection to backend
; -!- Windows users must leave this parameter at 1 -!-
; Default is 1
processes = 1

[Alignak-app]
; Requests interval
; ------------------------------------------------------------------------------------------
; Define interval of App requests. App make regular requests
; Default is 5. Increase this settings can improve speed of App
; Set this settings less than 5 is not recommended !
requests_interval = 5

; Notifications elapsed
; ------------------------------------------------------------------------------------------
; Sets in minutes the time elapsed since notifications were triggered.
; Default is 30
notification_elapsed = 30

; Notifications duration
; ------------------------------------------------------------------------------------------
; Define duration of temporary notifications
; Default is 30
notification_duration = 30

; Spy checks interval
; ------------------------------------------------------------------------------------------
; Define checks interval in seconds for spied hosts. One host check by interval.
; Default is 60
spy_interval = 60

; Locales
; ------------------------------------------------------------------------------------------
; Define language of App. Currently only "fr_FR", "en_US" are available.
; If empty, "en_US" will be used as default.
; Default is "en_US"
locale = en_US

; Update dock "Status"
; ------------------------------------------------------------------------------------------
; Define in seconds the refresh of dock alignak status
; Default is 15
update_status = 15

; Update dock "Buttons"
; ------------------------------------------------------------------------------------------
; Define in seconds the refresh time of dock buttons
; Default is 15
update_buttons = 15

; Update dock "Livestate"
; ------------------------------------------------------------------------------------------
; Define in seconds the refresh time of Dock livestate
; Default is 15
update_livestate = 15

; Update panel Dashboard
; ------------------------------------------------------------------------------------------
; Define in seconds the refresh time of panel Dashboard
; Default is 15
update_dashboard = 15

; Update panel Host
; ------------------------------------------------------------------------------------------
; Define in seconds the refresh time of panel Host view
; Default is 15
update_host = 15

; Update panel Service
; ------------------------------------------------------------------------------------------
; Define in seconds the refresh time of panel Service view
; Default is 15
update_service = 15

[Log]
; Log filename
; ------------------------------------------------------------------------------------------
; Define name of file where logs will be stored.
filename = alignakapp

; Log location
; ------------------------------------------------------------------------------------------
; Set this value to define another directory. Path must be absolute !
; Default is empty. Default values are:
; Linux:   ~/.local/alignak_app
; Windows: C:\ProgramData\Alignak-app
location =

; Application Debug Mode
; ------------------------------------------------------------------------------------------
; Activate Debug mode for Alignak-App to get more logs
; Set to 'yes' or 'true' to activate "debug" mode
; Set to 'no' or 'false' to deactivate "debug" mode
; Default is "no"
debug = no

[Folders]
; Root Application Path
; ------------------------------------------------------------------------------------------
; This is the config path of the application. Change this setting is not recommended !
path = /alignak_app

; Images Path
; ------------------------------------------------------------------------------------------
; Path of images. Must have a 'slash' before. This path is relative of the [path] value.
img = /images

Connection to Backend

Alignak-app have a login form by default, who let you to connect with the username and password define in backend.

You can also set connection information in settings file:

  • Recommended: leave empty “username” and “password”. Alignak-app will display a login Window.
  • Recommended: set your token in “username” field and leave “password” empty (See below).
  • Not recommended: set your “username” and your “password”. This method is less secure.

To obtain a token, open a python terminal and type the following commands:

import requests
backend_url = 'http://alignak.com:5000'
r = requests.post(
    backend_url + '/login',
     data={
        'username': 'admin',
        'password': 'admin'
     }
)
print(r.text)

Launch Alignak-App

On Linux

Once you have configured your application, just type the following in a terminal:

$HOME/.local/alignak_app/alignak-app start

Alignak-app will start, but will also create a command for later. Thereafter, you will only have to type the following command to launch your application:

alignak-app start

Here is the available commands:

alignak-app {start|stop|status|restart}

On Windows

With Installer

Just launch Alignak-app vX.x shorcut on your desktop or run the alignak-app.exe located in C:\Program Files\Alignak-app\.

From command line

If you install from sources or with pip, you just have to launch the alignak-app.py in bin folder:

python c:\Users\user\AppData\Roaming\Python\alignak_app\bin\alignak-app.py

Obviously, it requires to keep an open command prompt on Windows.

Solve Problems

If you’re having trouble getting started and running the app, here are some things to check:

  1. Be sure you have correctly set your configuration file (see above) and that you can join your backend.
  2. The application generates a log file in its root folder (see Alignak-app Main Folder). Search for ERROR messages.
  3. If you have installed Alignak-app with pip, be sure to add the flag –user (see Install Alignak-app).

Alignak-app Interface

System Tray

Once Alignak-app is started, you’ll have an icon in your task bar (in bottow right under Windows, top right under Ubuntu for example). When you click on this icon, you’ll have access to multiple menu like “dock”, “about” or configurations.

App Dock

When App is launched, a “dock” will also appear right of your screen. This “dock” will contains different buttons and some container who will receive different notifications.

Alignak part

This part of dock contains informations about your connection to backend and the states of Alignak daemons. If you’ve some connection problems or if backend is restart, you’ll see icons change.

You can also see each daemon state by clicking on button with Alignak icon.

Livestate part

In the livestate part, you’ll have many buttons who let you see: hosts, user configuration, problems view (available soon) and a button to reach your WebUI if available.

You’ll also see a resume of number of problems for hosts and services monitored in your backend.

Events part

This is one of the most interesting features of the application. You’ll receive many informations in this part like alignak notifications, acknowledge or modifications you do in App.

Events:

  • If you want to remove an event, simply double click on it.
  • Full events text can be see in tooltip when you keep mouse over.
  • Some events are temporary and remove themselves.
  • Some events can be drag and drop (see below)

Drag & Drop:

  • Events from a host or a service can be drag to in “Spy Hosts”. Then App will send you regular notifications about that host.
  • Events can also be move to host synthesis view (Panel), to display host instantly.

Spy part

This is where you can find the list of hosts that you spy on.

  • You can spy on as many hosts as you want.
  • To stop spying on a host, just double click on it, host will be removed from list.

App Panel

When you click on host button in dock, a new window will appear, called Hosts Synthesis View. This where you can see your monitored hosts and services.

At the top of this window, you will find a summary of the number of items for each state (OK, CRITICAL, DOWN…).

Start typing the name of a host in the search bar and App will propose to you different corresponding names. When you select a host, its information and the list of its services will be displayed.

You will then be able to perform various actions such as seeing the details of each of its services, acknowledging a problem or planning a downtime for an item (service or host).

You will also have access to the host’s history. It may take a while to be available. It depends on the number of hosts monitored in backend.

WebUI

App also have lot of buttons which bring you to WebUI. You’ve to set WebUI url in configuration file to make this buttons available.

Windows Setup

For releases, a setup is generated for Windows and is available for download. For the version under development, you have to do it yourself.

Requirements

Obviously, you must clone the Alignak-app repository, on the develop branch before. Like that you’ll have the last fixes. Normally, we try to have a branch develop as stable as possible.

Python and requirements

You have to install Python 3.5 in any case.

Then the requirements of Alignak-app . Otherwize, pyinstaller will not have the required .dll for compilation. All is available on Pypi:

# In repository folder
pip install -r requirements.txt --user

Once done, you’ll normally have your python modules installed in:

"%APPDATA%\Python\Python35\"

Then install pyinstaller.

Pyinstaller

The module pyinstaller is also available on Pypi. So just run the following command:

pip install pyinstaller --user

Normally, pyinstaller.exe command will be available under:

"%APPDATA%\Python\Python35\Scripts\"

And will be added to your PATH variable. If it is not the case, you can add this folder to your PATH without problem, you will definitely need it for other python libraries.

Inno Setup

Inno Setup is a free installer for Windows. It is very powerful and allows to create and customize installers quite easily.

To install Inno Setup, just download the last unicode version on Official download page.

Be sure to choose unicode version !

And simply run it with values as default.

Create Setup

To create your own setup, you’ll find scripts in bin\win folder of repository. There is also images, a redistribuable for Windows (needed for old versions of Windows) and 2 script files.

The first one is pyinstaller_app.bat.

Before running it, check the --paths arguments. Normally, you’ll have just to change the repository folder (line 13).

Be sure to put absolute paths !

The others are normally the sames on your device. If pyinstaller does not find the PyQt dll, check these paths.

Then run the .bat. This script will generate an alignak-app.exe in dist folder. Don’t move it !

After, simply open the Inno Setup file alignak-app-win-setup.iss. You can change ShortVersion if you want, but normally these digits are same as current develop. And then, compile the file with CTRL+F9 or from menu Build->Compile.

This will generate an installer inside the dist\setup folder.

Your installer is ready !

You can then uninstall the python libraries if necessary, your Setup will no longer use them. All the libraries you need are compressed into the executable.

Indices and tables