Skip to content

Tutorial ManagerClientDatabase

sqall01 edited this page Mar 1, 2019 · 14 revisions

Tutorial - AlertR Manger Client Database

In this document a tutorial for the version 0.501 is given.

Table of Contents



This tutorial describes the basic configuration of the AlertR Manger Client Database. It can be used as foundation to develop an own AlertR system setup. This tutorial assumes you have set up the AlertR Server according to the provided Server Tutorial.

The client is described as the following by the installation:

sqall@towel:~$ python -l

AlertR Manger Client Database



1: MySQLdb (pip packet: MySQL-python) (lowest version: 1.2.3)

This client stores the state of the alert system in a database for external usage. It uses a MySQL db to store all information about the alert system and events that occur (for example a client that disconnected from the alert system). External components, such as a website, can use the information in the database for their purposes. In the case of a website, it can process the data and show a visualization to the user. In order to let external components interact with the alert system, the manager client contains a local UNIX socket server which can be contacted.


In order to install the AlertR Manger Client Database, we first have to fulfill all prerequisites. On a Debian/Ubuntu Linux you can install everything with the following commands:

root@towel:/home/sqall# apt-get install python-pip libmysqlclient-dev

root@towel:/home/sqall# pip install MySQL-python

IMPORTANT NOTE: On newer Debian like machines the package libmysqlclient-dev is replaced with default-libmysqlclient-dev. If you cannot install the former one, just install the latter.

It is always a good idea to have an own user for a daemon. Therefore, we create a user that runs the AlertR Manger Client Database called alertr:

root@towel:/home/sqall# adduser --disabled-password alertr
Adding user `alertr' ...
Adding new group `alertr' (1002) ...
Adding new user `alertr' (1002) with group `alertr' ...
Creating home directory `/home/alertr' ...
Copying files from `/etc/skel' ...
Changing the user information for alertr
Enter the new value, or press ENTER for the default
	Full Name []:
	Room Number []:
	Work Phone []:
	Home Phone []:
	Other []:
Is the information correct? [Y/n] y

To switch into this user in the terminal you can use the following command:

root@towel:/home/sqall# su alertr

Please note that this is only possible as root user. If you are trying this command as another user you will get a password prompt for the user alertr, which does not have a password.

Afterwards, you can use the installation script provided by AlertR to install the client.

alertr@towel:~$ wget

alertr@towel:~$ mkdir managerClientDatabase

alertr@towel:~$ python -i managerClientDatabase -t ./managerClientDatabase/


The AlertR Manger Client Database uses a MySQL server to store its data. This data can be used by other applications, such as a website, to show the current state of the AlertR system. In order to get the AlertR client to work, we have to install and set up a MySQL server first. In this tutorial, we install the MySQL server on the same host as the AlertR client. With the following command we can install the database on a Debian-like system.

root@towel:/home/sqall# apt-get install mysql-server

The installation asks to set a password for the database "root" user. In this tutorial, we assume you have set the password to "root_password".

Next we set up an own database user and database for the AlertR client:

root@towel:/home/sqall# mysql -u root -proot_password

mysql> CREATE DATABASE alertr_db_mgr DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_unicode_ci;
mysql> CREATE USER 'alertr_db_mgr'@'localhost' IDENTIFIED BY 'secret_password';
mysql> GRANT ALL ON alertr_db_mgr.* TO 'alertr_db_mgr'@'localhost';

This sets up the database user "alertr_db_mgr" with the password "secret_password" and grants it full access to the newly created database "alertr_db_mgr". Please make sure that only this AlertR instance uses the created database "alertr_db_mgr" on this MySQL server. Otherwise the instances will corrupt each others data.


The following describes the configuration of the AlertR Manager Client Database. It shows a basic configuration that can be used as a template for own installations.


For security reasons, the AlertR system enforces a TLS connection. During the installation of the AlertR server, you created a certificate file with the name alertr_server.crt. This file is needed by the client in order to verify the connection. Please copy it to the host you are installing this client on. This tutorial assumes that you have stored the certificate file in the following location: /home/alertr/managerClientDatabase/config/alertr_server.crt.

User Credentials

The client has to authenticate itself before it can work with the server. Therefore, we need to set up user credentials on the AlertR server for this client. We execute the following command with the script of the server which is located in the installation directory of the server (see Users Management for further information):

alertr@towel:/home/alertr/server# python -a -u user_database -p password_database -t manager -i managerClientDatabase

Please make sure that the AlertR Server is not running while adding a user.
Otherwise it can lead to an inconsistent state and a corrupted database.
Are you sure to continue?
(y/n): y

Configuration File

Every AlertR installation has a template configuration file with detailed comments that describe the functionality of each option. To use it as a draft, you can just copy the template file and modify your new configuration file.

alertr@towel:~/managerClientDatabase/config$ cp config.xml.template config.xml

The configuration file itself is split into the following parts:

  • General
  • SMTP
  • Update
  • Manager

In this tutorial, we are going through each of these parts separately and describe why we configured it like that.


The general section is used for options such as certificate file location. In our tutorial configuration, the section looks like this:


			level="INFO" />

			caFile="/home/sqall/managerClientDatabase/config/alertr_server.crt" />

			keyFile="/absolute/path/to/client.key" />

			password="password_database" />

			persistent="True" />


Section log is used to configure the log file setup. The file attribute sets the location for the log file. Please note that this has to be the absolute path to the location. Make sure it exists and is writable by the user that starts the AlertR client. Otherwise the client will not start. For example, the directory /var/log is usually only writable by the "root" user and users of the group "syslog". If you want the client log file in this directory, please create a sub-directory for the AlertR client log file and set the correct permissions on it. The level attribute sets the log level. Possible values are DEBUG, INFO, WARNING, ERROR, CRITICAL.

Section server is used to configure the server connection setup. The host and port attribute sets the address and port of the AlertR server. The port was previously configured in the server configuration file. The address can either be a name that can be resolved by the DNS system or an IP address. The caFile attribute sets the location of the certificate file that is used to authenticate the server (see Certificate). Please make sure that the location is an absolute path to the file.

Section client is used to configure the client connection setup. The certificateRequired attribute determines if the client needs a certificate to connect to the server or not. The certFile and keyFile are used to determine the client certificate and key file. Since this tutorial is not using client certificates, we do not have to set sane values here.

Section credentials is used to configure the login credentials of this client. The credentials were configured in a previous step of this Tutorial and must be the same as in this configuration file.

Section connection is used to configure the connection to the server. The persistent attribute is used to configure if the connection to the server has to be persistent. This means that if the client disconnects, a sensorAlert is created by the server.


The smtp section is used for options that configure the used SMTP server. In our tutorial configuration, the section looks like this:


			toAddr="" />

			port="25" />


Section general is used to configure the basic options of the eMail notification. The eMail notification is used if problems on the AlertR client occur that can not be solved (like connection problems). The activated attribute determines if the eMail notification is activated or not. If it is deactivated, the rest of the options in the whole smtp section are ignored. The fromAddr attribute sets the used eMail address from which the eMail notification is sent. The toAddr attribute determines the eMail address the notification is sent to.

Section server is used to configure the SMTP server that is used to send the eMail notification. The host attribute sets the address and the port attribute sets the port of the used SMTP server. At the moment, only "" is allowed as address and port 25. This means you have to set up a local SMTP server in order to send eMail notifications. Personally, I would suggest to set up a local Postfix SMTP server that can forward eMails like in this Tutorial. Please note that the local SMTP server has to accept eMails from localhost without any authentication since it is not supported by AlertR yet.


The update section is used for options such as update checking. In our tutorial configuration, the section looks like this:


			interval="86400" />

			caFile="/etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem" />


Section general is used to configure the update checking setup. The activated attribute defines if the update checking should be activated. If it is activated, the AlertR instance will check regularly the Internet repository if a new version is available. The interval gives the seconds the AlertR instance waits before checking for updates.

Section server is used to configure the remote update repository. Normally, the default configuration can be used here (which is this repository). The host attribute gives the remote server location of the repository. The port attribute gives the port on which the repository is reachable (AlertR uses HTTPS for it). The location attribute sets the location on the remote repository. The caFile attribute gives the local location of the certificate that is used to verify the HTTPS connection. The default value is the location on Debain/Ubuntu distributions of the current certificate that is used by Github.


The manager section configures special options of this client. In our tutorial configuration, the section looks like this:


			description="Towel Database Manager" />

			password="secret_password" />

			unixSocketFile="/home/sqall/managerClientDatabase/config/localsocket" />

			eventsLifeSpan="10" />


The context has four main sections: general, storage, server and options. The following describes the settings of each section.

Section general is used to configure the basic manager settings. The description attribute gives the description of this manager client.

Section storage sets the database settings. The method attribute sets the database that is used. Currently, only mysql is allowed. The server and port attributes set the address and the port used by the MySQL server. The database attribute sets the database that should be used by the AlertR client. The username and password attributes set the credentials that are used to connect to the MySQL server. The database and credentials are configured in the Setup Part of this tutorial.

Section server sets up a local socket server that can be used by external applications to talk back to the AlertR system. The activated attribute sets if the server is activated or not. The unixSocketFile attribute sets the location of the local socket file.

Section options configures some settings that are used for the behavior of the client. The sensorAlertLifeSpan attribute sets the number of days a sensorAlert is kept in the database before it is removed. Analogously, the eventsLifeSpan attribute sets the number of days a event is kept in the database. An event is anything that is received by the manager client (a sensorAlert, a stateChange of a sensor, etc.).


If you want the AlertR client to start automatically after a reboot of the host, you have to set it up. In this tutorial, I will give two examples on how to set up the autostart of the AlertR client depending on your system using systemd or just init.d.


An init.d script is provided by the AlertR installation. The only thing you have to do is to copy and configure it correctly. The following command copies it to the correct location, sets the permissions correctly and installs it:

root@towel:/home/alertr/managerClientDatabase/init.d_example# cp /etc/init.d/

root@towel:/etc/init.d# chown root:root
root@towel:/etc/init.d# chmod 755

root@towel:/etc/init.d# update-rc.d defaults
 Adding system startup for /etc/init.d/ ...
   /etc/rc0.d/ -> ../init.d/
   /etc/rc1.d/ -> ../init.d/
   /etc/rc6.d/ -> ../init.d/
   /etc/rc2.d/ -> ../init.d/
   /etc/rc3.d/ -> ../init.d/
   /etc/rc4.d/ -> ../init.d/
   /etc/rc5.d/ -> ../init.d/

Next we have to configure the init.d script correctly. The following changes have to be made to the script:

# change USER to the user which runs the alertRclient
# change DAEMON to the path to run the alertRclient

In order to work correctly, the AlertR client has to be executable. With the following, we change the permissions of the AlertR client:

alertr@towel:~/managerClientDatabase$ chmod 755

To start the client as daemon, we can now execute:

root@towel:/home/alertr/managerClientDatabase# /etc/init.d/ start

The log file of the client (it is created in the directory you have configured in the General Section) should now show the following:

08/12/2016 22:23:38 INFO: []: Starting local unix socket server instance.


If your system uses systemd for its autostart, you have to configure the AlertR client a bit different. Copying the template and setting permissions is still the same:

root@towel:/home/alertr/managerClientDatabase/init.d_example# cp /etc/init.d/

root@towel:/etc/init.d# chown root:root
root@towel:/etc/init.d# chmod 755

Configuring the init.d script correctly is also the same:

# change USER to the user which runs the alertRclient
# change DAEMON to the path to run the alertRclient

Now, systemd has to be configured. For this we copy the template service file to the correct location and install the service:

root@towel:/home/alertr/managerClientDatabase/init.d_example# cp alertRmanagerDatabase.service /etc/systemd/system/

root@towel:/home/alertr/managerClientDatabase# systemctl enable alertRmanagerDatabase.service

The AlertR client can be started with the following command:

root@towel:/home/alertr/managerClientDatabase# service status

The log file of the client (it is created in the directory you have configured in the General Section) should now show the following:

08/12/2016 22:23:38 INFO: []: Starting local unix socket server instance.


If you experience problems, please check the log file first. If it is not helpful, change the log level to DEBUG and check again. If no error can be seen, please start the AlertR client manually and check if an error occurs that is not printed into the log file. This can be done by just executing the AlertR client as the user that it normally runs with.

alertr@towel:~/managerClientDatabase$ ./

If you still have problems and do not know how to solve them, you can ask on the community page on reddit or you can use the Github Issues.

You can’t perform that action at this time.