Configuration¶
Alyvix monitoring system within NetEye is not included in the NetEye Core, and is to be additionally installed as a Feature Module.
In order to start using Alyvix within NetEye, follow the procedure described in Additional NetEye Components.
After the Alyvix Feature Module has been installed, it is possible to configure an Alyvix node in NetEye to be able to monitor it from the web interface in just a few steps that you will find below.
Alyvix Service is available under its own product license. You can find out more on how to obtain Alyvix license in its official documentation.
User Roles¶
The actions that a NetEye user can perform on the Alyvix module are based on the user role, defined by the NetEye user permissions. The roles are assigned based on the user’s IcingaWeb2 permissions as follows:
Super Admin¶
The privilege of a Super Admin role is granted to users with the Unrestricted Access, Administrative Access or Full Module Access permission on the Alyvix module. Please note that, to be able to see the configured Alyvix nodes, the user needs to have permissions to see them in the Monitoring module.
Tenant Admin¶
The privilege of a Tenant Admin role is granted to users with the General Module Access and alyvix/tenant-admin permissions, together with an alyvix/tenant restriction. For example, consider the case of a NetEye environment with a tenantA tenant. If you would like to grant a set of users the tenantA Tenant Admin role for Alyvix, you should enable the Alyvix module for tenant tenantA and configure a role in the Access Control as follows:
Inherit the neteye_tenant_tenantA role
Enable the General Module Access for Alyvix
Enable the alyvix/tenant-admin permission for Alyvix
Enable the General Module Access for the Monitoring (possibly restricting the hosts visible by the user)
Tenant Viewer¶
The privilege of a Tenant Viewer role is granted to users with the General Module Access and alyvix/tenant-viewer permissions, together with an alyvix/tenant restriction. For example, consider the case of a NetEye environment with a tenantA tenant. If you would like to grant a set of users the tenantA Tenant Viewer role for Alyvix, you should enable the Alyvix module for tenant tenantA and configure a role in the Access Control as follows:
Inherit the neteye_tenant_tenantA role
Enable the General Module Access for Alyvix
Enable the alyvix/tenant-viewer permission for Alyvix
Enable the General Module Access for the Monitoring (possibly restricting the hosts visible by the user)
Note
In case you would like to grant Tenant Admin/Viewer access on more than one tenant to a set of users, please repeat the procedure above for all the implied tenants.
Nodes¶
Install an Alyvix Node¶
In order to start using Alyvix Service, first you have to install an Alyvix Node as recommended in the official Alyvix Service user guide.
Note
NetEye supports Alyvix Service version >= 2.5.0. Please make sure your Alyvix Node is up to date before proceeding with the installation.
As a part of the installation procedure, you will have to perform mandatory security configuration. Appropriate certificate, JWT and role mapping files you will need are provided in Alyvix Node Authentication.
After the installation has been completed, you can proceed to configuring the Alyvix Node in the Director Module.
Alyvix Network Architecture¶
Before you start configuring the Alyvix Node in NetEye, it is important that you decide on the type of your network architecture and the type of environment you would like to work in, i.e. single- or multi-tenant.
There are four types of Alyvix Nodes for you to choose from when configuring an Alyvix Node intended to run the service. Thus, it is important that you are familiar with the Architecture of Alyvix Nodes at the moment of carrying out Install an Alyvix Node step, so that you can already define which type of a Role Mappings is to be later applied at step Configure an Alyvix Node.
Note
In case you prefer to set up your infrustructure as a multi-tenant environment, you need to create one or multiple Tenants in addition to the Master Tenant, which serves as a default one. In order to do that, use the neteye tenant config create. For more information please see The neteye Command section.
For NetEye to be able to reach the Alyvix Service, port 443 is to be opened, while the Alyvix should reach NetEye through port 4222. For a deeper insight into the Network Architecture please refer to the diagrams in Architecture of Alyvix Nodes section.
Alyvix Node Authentication¶
NetEye and the Alyvix nodes need to communicate securely, thus HTTPS certificates must be installed and JWT authentication must be configured for each Alyvix node.
Certificates¶
Each Alyvix node needs to have HTTPS certificates installed to enable secure communication with NetEye.
We strongly recommend following the same procedure as for the installation of the certificates on NetEye itself. The HTTPS Configuration section explains the procedure in details.
Another, not recommended, way to install the certificates on the Alyvix nodes is to create the certificates via a script provided by NetEye. The script generates server certificates signed by the internal Root CA of NetEye, which will then be trusted only by your NetEye machines.
Warning
Installing the certificates via the NetEye script is not recommended and it is only intended as a temporary solution.
The script is located under /usr/share/neteye/scripts/security/generate_server_certs.sh
and it accepts the following positional parameters:
Distinguished name. Example /C=IT/ST=Bolzano/L=Bolzano/O=Global Security/OU=Neteye/CN=*.neteyelocal
Server DNS(s), separated by whitespaces, for which the certificate must be valid
IP(s), separated by whitespaces, for which the certificate must be valid
Filename with which the certificate will be saved on file system
[Optional] Output folder, which defines the location of the certificates (defaults to
./)
Example usage:
bash /usr/share/neteye/scripts/security/generate_server_certs.sh \
"/C=IT/ST=Bolzano/L=Bolzano/O=GlobalSecurity/OU=AlyvixNodes/CN=example03.lan" \
"example03.lan" 192.168.0.100 "example03" "/root/certs"
The generated certificates must be copied and renamed inside the Alyvix nodes according to the documentation. For the details on where to store the certificates on the Alyvix nodes, please consult the official Alyvix documentation.
JWT Authentication¶
When performing a request from NetEye to the Alyvix node, Alyvix needs a way to authenticate the request.
JSON Web Tokens (JWT) are used to authenticate the requests to the Alyvix nodes. JWT is an open industry standard defined in RFC 7519 that provides a compact and self-contained way for securely transmitting information between parties as a JSON object.
Every request to Alyvix will contain the JWT Authorization Header with the JWT
token retrieved from NetEye. The JWT is calculated using the RS512 algorithm
(see RFC 7518#section-3.3) and the
key pair, which is stored on the NetEye host under
/neteye/shared/icingaweb2/conf/modules/neteye/jwt-keys.
In order for Alyvix to verify the JWT token, copy the public key file
/neteye/shared/icingaweb2/conf/modules/neteye/jwt-keys/multipurpose-jwt.pub
inside each Alyvix node. For more information please refer to the
official Alyvix documentation.
Role Mappings¶
For Alyvix to correctly evaluate the permissions defined in the JWT and thus correctly authenticate the user of the JWT, the following mappings need to be copied inside each Alyvix node. For more information, please refer to the official Alyvix documentation. Please select the proper mapping based on the architecture of the Alyvix node to be configured.
Role mappings for Multitenant - Tenant Shared
{
"role": {
"admin" : [
[
"$.permissions[?(@ == '*')]"
]
],
"editor": [
[
"$.permissions[?(@ == 'module/alyvix/*')]"
],
[
"$.permissions[?(@ == 'module/alyvix/edit')]"
]
],
"viewer": [
[
"$.permissions[?(@ == 'module/alyvix')]"
]
]
},
"tenants": "$.restrictions.neteye_tenants"
}
Role mappings for Multitenant - Tenant Specific
Note
Please replace every occurrence of <tenant_name> in the mapping below
with the actual Tenant name before copying the mapping into the Alyvix nodes.
{
"role": {
"admin": [
[
"$.permissions[?(@ == '*')]"
],
[
"$.permissions[?(@ == 'module/alyvix/*')]",
"$.restrictions.neteye_tenants[?(@ == '<tenant_name>')]"
]
],
"editor": [
[
"$.permissions[?(@ == 'module/alyvix/edit')]",
"$.restrictions.neteye_tenants[?(@ == '<tenant_name>')]"
]
],
"viewer": [
[
"$.permissions[?(@ == 'module/alyvix')]",
"$.restrictions.neteye_tenants[?(@ == '<tenant_name>')]"
]
]
},
"tenants": "$.restrictions.neteye_tenants"
}
Role mappings for Single Tenant - Direct to Master and for Single Tenant - Via Satellite
{
"role": {
"admin": [
[
"$.permissions[?(@ == '*')]"
],
[
"$.permissions[?(@ == 'module/alyvix/*')]",
"$.restrictions.neteye_tenants[?(@ == 'master')]"
]
],
"editor": [
[
"$.permissions[?(@ == 'module/alyvix/edit')]",
"$.restrictions.neteye_tenants[?(@ == 'master')]"
]
],
"viewer": [
[
"$.permissions[?(@ == 'module/alyvix')]",
"$.restrictions.neteye_tenants[?(@ == 'master')]"
]
]
},
"tenants": "$.restrictions.neteye_tenants"
}
Configure an Alyvix Node¶
To begin monitoring an Alyvix node, the node must first be created in the Director Module as an Icinga Host, setting the Hostname and the Host address, see Fig. 232.
Moreover, select the preferred option in the Alyvix node field under the section. For more information regarding this setting, please refer to Architecture of Alyvix Nodes.
Fig. 232 Creation of a Host as an Alyvix node¶
Once all the settings have been configured, a deployment is needed. A newly created Node is to appear in the Nodes list, where you can manage its details, and in the Dashboard.
Visualize Nodes¶
The Alyvix node list can be visualized by visiting the page. The following fields are displayed for each node:
Name: The name of the Alyvix node set previously during the Host creation
- Tenant: The Tenant which the node belongs to. In case of a multitenant tenant-shared node, an icon
is displayed instead of the tenant names.
Sessions status: The list of sessions with the status. Possible status values are:
Disconnected (Alyvix service is not able to connect to a specific session)
Running (Alyvix service is connected to the session and the session is running)
Waiting (Alyvix service is connected to the session and is ready to run assigned test cases)
Stopped (Alyvix service is connected to the session and is not going to run test cases)
Health: The Host status monitored by NetEye. Next to the health status is a link that opens the host page in the monitoring module.
License: The status of the license can be: Disabled, Active, Expiring or Expired. See more on this in the License Tab.
Alyvix version: The version of Alyvix that is running on the node
Apart from the node details, a summary provides the following information:
Total nodes: The overall number of nodes
License alerts: The number of licenses that are not in the Active status
Health alerts: The number of nodes with the host status DOWN or UNREACHABLE
For an easier lookup of the relevant information related to the nodes and their execution, it is possible to search the table, by using the search bar, and sort the various columns, clicking their name.
Fig. 233 The Alyvix nodes page¶
Manage Node Details¶
From the nodes page, available at , it is possible to click a particular node in the list to visualize its details. The details panel, shown in Fig. 234, is then rendered on the right-hand side of the table, displaying the details of the node, grouped in three different tabs.
Sessions Tab¶
A session on an Alyvix node is defined by the following properties:
Name: The domain and the session username separated by a
\. E.g.WP\MyUsernameTestcase waiting period: Number of minutes before scheduling the next test case
Workflow waiting period: Number of minutes before restarting the workflow
Display dimensions
Width: the width of the screen resolution in pixels
Height: the height of the screen resolution in pixels
Zoom: the zoom percentage
Tenant: the Tenant to which the session refers. This setting is only applicable to Multitenant - Tenant Shared nodes, and it is only used for the collection of the performance metrics. Furthermore, this setting can be edited only by NetEye users with the Super Admin role. For more information regarding the roles and permissions on the Alyvix module, please refer to the User Roles section.
Note
Currently no validation is applied to the Tenant name value when it’s being modified and in order for the changes to take effect, the neteye alyvix-node setup command should be used.
Password: the password used by the session in conjunction with the username
The Sessions tab, shown in Fig. 234, contains:
The New session button, which allows a user to create a new session
A counter, that reports how many licensed sessions have been consumed out of the available ones
The sessions table, in which each row represents a separate session defined on the node. Each session on the node can be edited or deleted by selecting the preferrable action in the More options menu for a particular session. When editing a session a user can:
Modify the sessions properties in the Settings tab. Please note that the Name cannot be changed
Manage the session workflow in the Workflow tab
A change in the session workflow status can also be applied to multiple sessions, by selecting the corresponding rows in the tab and applying the desired action.
Fig. 234 The session list of a node¶
Fig. 235 Session workflow¶
Fig. 236 Control multiple sessions workflow¶
License Tab¶
The Alyvix license should be activated individually for each node. The License tab contains the following details about the license of a particular node:
Status: the status of the license: Disabled, Active, Expiring or Expired
Subscription plan: the subscription plan currently in use
Expiration date: the expiration date of the license
Remaining days: days left before license expiration
Licensed sessions: the number of sessions available with the subscription plan currently in use
A new session can only be started with the license being in an Active or Expiring status.
Disabled license status is usually displayed for new users that have not activated their license yet. This can be done in the License tab. Download the request key in order to obtain a new activation key for the selected node. Once the request key has been downloaded, please contact your Alyvix provider in order to obtain the activation key file, which can then be uploaded directly in the node’s License tab.
One month prior to the end of the licensing period the license status is changed to Expiring. The licensing period is defined by the contract with the Alyvix Service provider and cannot be controlled from NetEye. In the case of an Expiring license please contact your Alyvix provider in order to extend your license and be able to seamlessly use Alyvix Module.
You can alternatively contact Alyvix team at info@alyvix.com for more information.
General Settings Tab¶
The General Settings tab reports the private key for the selected node and the retention period, in hours, for the successful test cases, failed test cases and for the service logs. Moreover, a toggle enables the capture of annotated screenshots also for successful test case runs. You can also edit settings in the General tab.
Time periods Tab¶
The Time periods tab reports the list of all time periods currently stored on the Alyvix Node.
In case a time period is not synced with its definition in the Director, one of the following two statuses will be reported:
Modified (The time period is present in the Director, but its definition does not match the one of the Alyvix Node)
Deleted (The time period was deleted from the Director but the associated Test Cases are still run based on it)
Furthermore, the Sync with NetEye button allows allows you to update the time periods present on the Alyvix Node based on their definition in the Director.
Note
In case of deleted time periods, a replacement time period should be specified, using the associated dropdown. If you choose to apply the default replacement Any (default), after the sync the Test Cases associated with it will be executed at all times.
Fig. 237 The time periods stored on the Alyvix Node¶
Test Cases¶
Manage Test Cases¶
The Alyvix test cases list can be visualized by visiting the page. The table displayed in the page provides a user with an overview of the test cases scheduled on all Alyvix nodes, useful to centralize, in a single view, the information coming from different nodes.
For each test case, the following data about its execution are displayed:
Name: The name of the test cases
Node: The name of the node on which the test case is scheduled
File: The name of the file associated with the test case
Arguments: The arguments used by the test case during its execution
For an easier lookup of the relevant information related to the test cases and their execution, it is possible to search the table, by using the search bar, and sort the various columns, clicking their name.
Fig. 238 The Alyvix test cases page¶
Moreover, a dedicated option of the More options menu allows a user to delete, after confirmation, a selected test case.
Furthermore, when visualizing the test cases, it is possible to add a test case by clicking the Create button. A side panel will open with the possibility to schedule a test case on one of the available nodes.
Manage Test Cases details¶
You can view the details of a particular test case by clicking it in the test cases list. The details panel for a selected test case will appear on the right, with details being grouped into Sessions and General tabs.
Sessions Tab¶
This tab reports all sessions a test case is scheduled for. Each session can be identified by its name and the status of a test case in the session, either enabled or disabled. The status can be simply changed by using the associated checkbox.
On the other hand, a session’s workflow and settings can be modified by clicking the arrow button for a particular session item.
Fig. 239 The session details of a test case¶
General Tab¶
General test case details include:
Name: The name of a test case
Node: The node a test case is scheduled for
File: The file containing the test case definition, selectable among the files available on the node
Arguments: The arguments used by a test case during its execution
Time Period: Specifies during which time of the day and during which days the test case must be executed. You can select Time Periods that were previously configured as described here. By default the Test Case will be executed at all times.
When visualizing the general details of a test case, it is possible to update the file, arguments and the Time Period.
Note
In case the node has some time periods out of sync with respect to the corresponding definition in the Director, before updating a Test Case it will be necessary to sync the time periods definitions with the Alyvix Node, as mentioned in the Time periods Tab section.
Fig. 240 The general details of a test case¶
Reports Tab¶
A test case is executed periodically by Alyvix. Each execution is called test case run. The Reports tab is the place where the runs of a test case are shown. Runs are ordered by date and time of execution, the most recent being added at the top of the list.
Each run is described by the following data:
Result icon: the result represented by a green icon for successfully run test cases, red icon for failed ones
Timestamp: the date and time when the test case was run
Session: the session in which the test was executed
Screenshot icon: an icon is displayed if the run has an associated screenshot of the execution
You can filter test cases to view only failed runs with a toggle on top of the list.
Clicking on a specific run will open the Report view, which shows the following details:
Node name: the name of the node where the test case was executed
Username: the username of the RDP session used by the test case
Date: the execution date
Time: the execution time
Duration: the time, in seconds, taken by the test case execution
Transactions list: a list of the transactions composing the test case. For each transaction, its execution status and duration are reported.
By selecting a transaction, you can consult the transaction parameters and understand how it performed. In particular, the following details are displayed:
Screenshots: if available, the screenshot taken by the Alyvix Robot (possibly with annotations and the transaction definition).
Transaction parameters: reporting the transaction performance and its specification.
Dashboard¶
The Alyvix Dashboard is the default view of the Alyvix module which provides summary of metrics for currently configured Alyvix nodes, including the status of all existing sessions and test cases assigned to them.
The Dashboard allows you to quickly monitor the overall status of the Alyvix installation, obtaining useful information, such as the number of currently configured nodes, the number of Test Cases that are currently present on the nodes and available sessions with a summary of their statuses. Here you can also find useful links to official documentation and support.
Moreover, the Dashboard provides even more specific information about the Alyvix installation components that require attention, such as expired licenses, unreachable nodes, failing Test Cases or outdated Time Periods. This allows you to take immediate actions to keep your Alyvix installation always in a healthy state.
Fig. 241 The Alyvix Dashboard¶
Put Test Case in Production¶
This section explains how to put an Alyvix test case in production.
Prerequisites¶
In order to be able to put a test case in production, the Alyvix Node should be installed as described in section Install an Alyvix Node, and then configured in the Director Module. You should also follow the Alyvix Node Authentication guide to configure secure communication with NetEye.
A new test case file should be created using Alyvix built-in tools.
To run a test case with an Alyvix Service, the Node must have a valid license. You can download the license request key and then upload the obtained license activation key directly from NetEye, as described in the License Tab section.
Note
The interval between obtaining the license request key and activating the license in NetEye may take some time. Thus, make sure your license is activated before you start working with sessions and test cases.
After the Alyvix Node setup process including all the above has been completed, you can proceed with creating your first Alyvix session.
Step 1. Create Alyvix Sessions¶
A test case should be run within a session. To add it, switch to the nodes list, select the Alyvix node and click the New Session button in the Sessions Tab.
Step 2. (Optional) Create a Time Period¶
If you want to execute your Test Case every day, without any time limitations, you can safely skip this step.
If instead you want to run the Test Case only during a certain time of the day or on certain days of the week (or even on certain dates), you should first create a Time Period which defines the exact hours and days when the Test Case must be executed.
To create the Time Period navigate to and define the Name and Display Name of the Time Period. If you cannot access the Icinga Director module, please ask your NetEye administrator to create such Time Period.
Note
Please do not use the Include period and Exclude period functionalities because Alyvix does not support them and will not allow you to use such Time Period.
Once the Time Period is created, use the Ranges tab to define in which days and/or hours you want the Alyvix Test Case to be run.
Note
If you modify an existing Time Period which is already associated with an Alyvix Test Case, you should synchronize the changes with Alyvix in the Node’s Time Periods tab. Click the Sync with NetEye button to sync all time periods definitions with the Alyvix Node, as described in the Time periods Tab section.
Step 3. Create Alyvix Test Cases¶
Once you have added a session on the Alyvix node, switch to the test cases list and click Create.
Select the node to run a test case on
Specify its definition by choosing the file previously created on the Alyvix Node as stated in Prerequisites.
Step 4. Run Test Cases¶
At this point, the test case you created is not running in its session. To enable its execution, click the arrow button in correspondence with the session previously defined to open the session workflow controls.
Enable the session if needed
Enable the test case in the session using the associated toggle
Start the session by enabling its workflow
Step 5. Check Test Case Results¶
Once the test case has been executed, switch to the Reports Tab to visualize its runs.
Click a specific run to open the Report view, which shows the details and all its transactions
Select a transaction to consult its parameters and understand how it performed.
Visualize Alyvix Performance Metrics¶
As a user, I want to be able to collect, explore and understand data on the Test Cases performance metrics sent by an Alyvix Session to an InfluxDB, so that I can analyze the test case performance based on the collected metrics data.
Prerequisites¶
In order to be able to collect the performance metrics generated by your Alyvix node in NetEye,
the neteye-alyvix module must be enabled for the NetEye Tenants to which the metrics belong to.
To enable the module for an already existing Tenant, please refer to the neteye tenant config modify. section.
To create a Tenant and directly enable the module for it, please refer to the neteye tenant config create section.
Step 1. Put a Test Case in Production¶
First of all, ensure Alyvix is set to generate the metrics that you would like to collect, putting a Test Case in production.
Step 2. Configure the Alyvix Node¶
After having configured a Test Case to generate metrics, the connection between the Alyvix node and NetEye must be configured. The configuration procedure depends on the architecture of the Alyvix node. The node can belong to one of the following types:
Please make sure to follow the steps related to the architecture of your Alyvix node.
Multitenant - Tenant Specific or Single Tenant - Via Satellite
On the Alyvix node, upload the certificate and key to be used to send the metrics to NetEye. To do this, upload to the Alyvix node the certificate that can be found on the chosen Satellite in the
/neteye/shared/nats-server/conf/certs/<tenant>-alyvix_metrics.crt.pemfile, with the corresponding key in the/neteye/shared/nats-server/conf/certs/private/<tenant>-alyvix_metrics.key.pemfile.On the Alyvix node upload the CA certificate of the NetEye node chosen as target of the Alyvix metrics. This can be found under the
/root/security/ca/root-ca.crtfile of that NetEye node.Configure on the Alyvix node, the NATS profile, as explained in the official Alyvix Service documentation. Specify, where needed:
The hostname of the NetEye Satellite chosen as target of the Alyvix metrics. This can be retrieved by running, on the chosen NetEye Satellite, the . /usr/share/neteye/scripts/rpm-functions.sh && get_neteye_hostname command.
The NATS default port 4222 as the connection port
The path to the previously uploaded certificate, key and CA
The NATS subject as alyvix.metrics
Connect the configured NATS profile, as explained in the official Alyvix Service documentation, to an existing Alyvix session for which you would like to collect the metrics.
Multitenant - Tenant Shared
Configure a Tenant for each session by entering the Tenant name in the Sessions Tab. Furthermore use the neteye alyvix-node setup to automatically configure the NATS channels for the direct communication to the NetEye Master.
Single Tenant - Direct to Master
Use the neteye alyvix-node setup command to automatically configure the NATS channels for the direct communication to the NetEye Master. Please note that in this case the Tenant related to all the sessions on the Alyvix node will be the Master Tenant.
Step 3. Configure the retention of your metrics¶
By default, the retention of the collected Test Cases performance metrics is of 365 days. If you would like to specify a different retention for a specific Tenant, please refer to the tenant configuration.
Step 4. Enjoy your metrics¶
On the NetEye Master, metrics generated during the run of Alyvix Session, for which NATS - InfluxDB connection was configured, are stored in the <tenant>-alyvix InfluxDB database. You can now consult them directly in InfluxDB or explore the data arranged in easy to read and meaningful dashboards via the The ITOA Module.
Make sure that you choose the correct Grafana Organization associated to the Tenant to which the performance metrics belong to.
