Tutorial ManagerClientConsole
(For version 1.000)
This tutorial describes the basic configuration of the AlertR Manager Client Console. 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:~$ ./alertRinstaller.py -l
[...]
AlertR Manager Client Console
-----------------------------
Instance:
managerClientConsole
Type:
manager
Version:
0.901-0
Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: urwid (pip packet: urwid) (lowest version: 2.1.0)
Description:
This client is a manager client for the AlertR system. It shows the current state of all sensors, the connected clients and if the currently active system profile.
[...]
In order to install the AlertR Manager Client Console, 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 python3-pip
root@towel:/home/sqall# pip3 install urwid requests
Afterwards, you can use the installation script provided by AlertR to install the client.
sqall@towel:~$ wget https://raw.githubusercontent.com/sqall01/alertR/master/alertRinstaller.py
sqall@towel:~$ mkdir managerClientConsole
sqall@towel:~$ chmod 755 alertRinstaller.py
sqall@towel:~$ ./alertRinstaller.py -i managerClientConsole -t ./managerClientConsole/
The following describes the configuration of the AlertR Manager Client Console. It shows a basic configuration that can be used as a template for own installations.
For security reasons, it is strongly recommended to use a TLS connection for your AlertR system. Hence, all tutorials will use TLS. However, for testing purposes AlertR gives you the option to disable TLS. If you do so, you have to disable it for the complete AlertR system.
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/alertClientDbus/config/alertr_server.crt.
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 manageUsers.py 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# ./manageUsers.py -a -u user_console -p password_console -t manager -i managerClientConsole
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
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.
sqall@towel:~/managerClientConsole/config$ cp config.xml.template config.xml
sqall@towel:~/managerClientConsole/config$ chmod 700 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:
<general>
<log
file="./logfile.log"
level="INFO" />
<server
host="localhost"
port="44556"
caFile="./config/alertr_server.crt" />
<client
certificateRequired="False"
certFile="/path/to/client.crt"
keyFile="/path/to/client.key" />
<credentials
username="user_console"
password="password_console" />
<connection
persistent="False" />
</general>
Section log is used to configure the log file setup. The file attribute sets the location for the log file. 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.
Section ssl is used to configure the TLS/SSL setup. The enabled attributes gives you the option to disable or enable it. This setting has to be the same for your complete AlertR setup. It is strongly recommended to enable TLS/SSL and only disable it in a testing environment. In this tutorial, we enable TLS/SSL. The caFile attribute in the server section sets the location of the certificate file that is used to authenticate the server (see Certificate). 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 Sensor Alert 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:
<smtp>
<general
activated="True"
fromAddr="managerClientConsole@alertr.de"
toAddr="myalarmaddress@example.org" />
<server
host="127.0.0.1"
port="25" />
</smtp>
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 "127.0.0.1" 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 to give the online repository for updates. In our tutorial configuration, the section looks like this:
<update>
<server
url="https://raw.githubusercontent.com/sqall01/alertR/master/" />
</update>
Section server is used to configure the remote update repository. Normally, the default configuration can be used here (which is this repository). The url attribute gives the remote server location of the repository. Only the https protocol is allowed here if you want to change it.
The manager section configures special options of this client. In our tutorial configuration, the section looks like this:
<manager>
<general
description="Console Manager Towel" />
<console
timeShowSensorAlert="3600"
maxCountShowSensorAlert="3"
maxCountShowSensorsPerPage="6"
maxCountShowAlertsPerPage="2"
maxCountShowManagersPerPage="4"
maxCountShowAlertLevelsPerPage="3" />
</manager>
The context has two main sections: general and console. 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 console is used to configure the graphical properties of the console. The timeShowSensorAlert attribute sets the time in seconds that received Sensor Alerts are displayed in a list before they are removed. The maxCountShowSensorAlert attribute sets the number of shown sensorAlerts in the list before the oldest is removed. The maxCountShowSensorsPerPage, maxCountShowAlertsPerPage, maxCountShowManagersPerPage, and maxCountShowAlertLevelsPerPage attributes sets the number of items (sensors, alerts, managers, and alertLevels) shown on a page.
Since this client is used directly by the user, it has no autostart options. Just start the client directly.
sqall@towel:~/managerClientConsole$ ./alertRclient.py
The output should look something like this:
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 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.