Edge Configuration Manager
The relayr Edge Configuration Manager enables managing the Gateway Agent components and their application configuration files with the use of the web user interface or REST API.
For example, Protocol Adapter's application configuration files contain settings related to measurements, alerts, configuration parameters and metadata reported by devices. The Configuration Manager allows you to add, edit and delete these settings.
To modify deployment configuration files, e.g. settings related to the Cloud connection, edit them manually in a text editor.
The Configuration Manager supports the following features:
Discovering and monitoring the started components using the health monitoring reports mechanism.
Restarting components after a configuration change.
Restoring a previous configuration in case of any errors.
Uploading and downloading configurations as
.json
files.Validating configurations.
Access control using custom authentication.
Displaying logs of components.
Once the Configuration Manager is installed, it becomes the primary way of configuring application configuration files. If you change the application settings manually in a text editor, the Configuration Manager ignores these changes and the settings are not updated.
For a step-by-step guide on how to install the Configuration Manager, see the Installation Guide.
Configuring the Configuration Manager
Before you access the Configuration Manager for the first time, you need to configure its settings and configure the admin
Administrator's account.
After the installation, no user account is configured, so you cannot log in to the application. To configure the Administrator's account, use the provided
gwa-config-mgr-configure
configuration script. The configuration script also enables configuring a number of settings of the Configuration Manager.
For a description of settings available in the configuration file, see the Configuration File section.
Configuration Script
The gwa-config-mgr-configure
configuration script facilitates configuring the following settings:
Private key and certificate required for secure SSL communication.
Custom path to the configuration file.
Custom path to the database.
Password to the
admin
Administrator's account, required to log into the application for the first time. See below for details.
If you are using the Configuration Manager for test purposes, you can still use the application without a signed SSL certificate. After the installation, the unique key and certificate are generated and inserted in the configuration file, so the Configuration Manager operates using those values.
After the installation, the script is located at the default location of binaries in the system (e.g. /usr/bin
).
Run the script with the configuration parameters you want to set (see table below for a list of parameters):
gwa-config-mgr-configure
Script Parameters:
Script Parameter | Description |
---|---|
-c | Path to the Configuration Manager's configuration file. By default, /etc/relayr/gwa-config-mgr-cpp/gwa-config-mgr-config.json . |
-d | Path to the Configuration Manager's database. By default, /var/cache/relayr/gwa-config-mgr-cpp/gwa-config-mgr-db.sqlite3 . |
-k | Private key file for SSL handling. |
-r | Certificate file for SSL handling. |
-h | Help that presents available script parameters. |
Here is an example that sets the paths to a key and a certificate for SSL handling:
gwa-config-mgr-configure -r cert.pem -k key.pem
The script automatically saves the provided values in the Configuration Manager's configuration file.
Configuring Administrator's Account
The Administrator's account is required to log in to to the Configuration Manager for the first time. After the installation, you need to configure a password for the admin
account, using the gwa-config-mgr-configure
script.
To configure the Administrator's account, follow these steps:
- Run the
gwa-config-mgr-configure
configuration script with or without its parameters:
gwa-config-mgr-configure
- Provide your password to the Administrator's account, when prompted:
Configure password for gwa-config-mgr administrator account:
new password [left blank - do not change]:
repeat password:
- Repeat your password.
You can now log into the Configuration Manager.
Configuration File
The deployment configuration file of the Configuration Manager is located at:
/etc/relayr/gwa-config-mgr-cpp/gwa-config-mgr-config.json
To change the settings, modify the file in a text editor. You can also edit some configuration settings using the configuration script.
The following configuration settings are available:
web_server
- configuration of the address for starting the Configuration Manager, database and authentication mode:
Configuration Option | Description | Default Value |
---|---|---|
host | Hostname or IP address for starting the HTTP server. | 127.0.0.1 |
port | TCP port number for starting the HTTP server. | 21080 |
database_path | Path to the database to store configurations of components. | /var/cache/relayr/gwa-config-mgr-cpp/gwa-config-mgr-db.sqlite3 |
use_ssl | Enables secure HTTP connection over TLS. If true or missing, private_key_path and certificate_path need to be provided. | true |
private_key_path | Path to the private key for SSL handling. | The unique key value is generated and inserted in the configuration file after the installation, which enables using the Configuration Manager for test purposes. |
certificate_path | Path to the SSL certificate for SSL handling. | The unique certificate value is generated and inserted in the configuration file after the installation, which enables using the Configuration Manager for test purposes. |
health_monitor.mqtt_connection
- settings for receiving health monitoring reports, enabling the detecting and monitoring of the installed Gateway Agent components:
Configuration Option | Description | Default Value |
---|---|---|
host | Hostname or IP address of the MQTT broker. | 127.0.0.1 |
port | Port number for connecting to the MQTT broker. | 1883 |
keepalive | Keepalive time interval of the MQTT connection, given in seconds. | 5 |
When you edit the configuration file, restart the Configuration Manager to apply your changes:
systemctl restart gwa-config-mgr-cpp
For an example of the Configuration Manager configuration file, see here.
Accessing the Configuration Manager
After the installation, no user account is created. To log in for the first time, you must first configure the
admin
Administrator's account, using the configuration script. See here for details.
After logging in as an Administrator, you can create other accounts. See the Managing Users Accounts section for details.
To access the Configuration Manager, provide the IP address and the port number to start the HTTP server. The address for running the Configuration Manager is configured in the host
and port
settings in the web_server
section of the the Configuration Manager configuration file.
On the opened login page, provide your user name and password. Then, press Enter or click Login.
The home page of the Configuration Manager opens, showing a list of detected components.
List of Detected Components
When you log in, the Configuration Manager automatically detects and lists the installed components, based on the received health monitoring reports.
For more information on health monitoring, see the Edge Platform Monitoring documentation.
The list shows the following information on each component:
- Component - Component name.
- Version - Component version.
- Config - Location of the application configuration file. For components which have a deployment configuration file only (e.g. Task Executor), this column is empty.
- Status - Component status. Possible values are:
Status | Description |
---|---|
Started | Component operates with no errors. |
Restarting | Component is being restarted. The Configuration Manager is waiting for the component's health report after the restart. |
Error | Component did not restart because of an invalid configuration or a problem in the system, or the component did not send a health report at a specified time interval. |
Off | Component has been stopped. |
Not configured | Component is started, but not operational. For example, the Cloud Adapter has this status before you configure MQTT credentials to a device or a device group. |
- Configure - Click this button to view and change the component's configuration. See the sections below for more information.
- See logs - Click this button to display the component's logs. See the Viewing Logs section for more information.
The Configure button is only available for components which have an application configuration file, e.g. for Protocol Adapters.
The List of detected components is always accessible under the Home tab in the left navigation menu.
Configuring Access Credentials to the relayr Cloud
The Configuration Manager enables configuring the MQTT credentials, which authorize access to a device or a device group defined in the relayr Cloud.
The obtained credentials are then automatically entered in the
username
,password
andcredentials_type
fields in the Cloud Adapter's application configuration file.
To configure your access credentials, follow these steps:
Log in to the Configuration Manager.
On the List of detected components, click Configure for the relayr Cloud Adapter component.
- Type your login and password to the relayr Cloud.
Click Login or press Enter.
Select a device or a device group to which you want to configure access.
Use the Search functionality to find devices or device groups in the list. Type in the search phrase and click Search or press Enter to view results. You can search by device or group name. The search is case-insensitive and it accepts wildcards (*).
- Click the Save Changes button at the bottom of the page. This button becomes active only after you select a device or a device group.
The Configuration Manager enters the access credentials in the Cloud Adapter's application configuration file and restarts the Cloud Adapter.
The Gateway Agent is now able to exchange information about a selected device or a device group with the relayr Cloud.
Viewing the Configured Credentials
To view the Cloud Adapter's application configuration file, click Download Json Config to download the file.
Example of configured credentials:
{
"cloud_connection": {
"username": "f3cc6bab-b39e-4f5a-934a-23h935d8b27a",
"password": "dw3Bf5gdxgaqBmQhkrg9wk8vZ",
"credentials_type": "device"
}
}
Configuring Protocol Adapters
The sections below explain how to modify the Protocol Adapters' configuration files, using the Configuration Manager's user interface.
Quickstart
To change the configuration settings of a component, follow these steps:
- On the List of detected components, click Configure next to the Protocol Adapter you want to edit. The configuration form opens.
Modify the configuration settings. See sections below for more information on available actions:
Click Save & Reload at the top of the page.
The Configuration Manager saves the changes and restarts the component. It validates the new configuration file. If it is correct, the updated configuration is loaded. The date and time of when you last saved the configuration show.
If the Configuration Manager detects some errors, it displays a list of errors and does not reload the configuration.
If any mandatory fields are missing, they are are also marked in red in the configuration form, as shown below.
Editing a Configuration Setting
To edit a configuration setting, follow these steps:
- Navigate to the configuration section you want to edit by clicking its row.
- Edit the configuration settings directly in the fields.
To display detailed information on a configuration setting, hover the cursor over its value field.
Some of the settings or configuration sections are optional. For example, while configuring a measurement, configure the Complex section only if you want to configure a complex measurement. For a regular measurement, leave this section empty.
When you change values in some fields, additional settings may become available for them. For example, there are different sets of settings in the Modbus object configuration, depending on the value selected in the
type
field, as shown below.
- Click Save & Reload at the top of the page.
The configuration is now updated.
Adding a New Configuration Section
The Add New... buttons allow you to add new, empty configuration sections to the configuration form. For example, for Protocol Adapters, you can add:
measurements
alerts
configuration parameters
metadata
devices
To add a new configuration section, follow these steps:
- Navigate to the configuration section you want to edit by clicking its row.
- Click the Add New... button at the end of the expanded section. For example, to add a new alert, click Add New Alert.
A new configuration section appears, ready to be configured. A green line at the bottom indicates the added configuration section.
The added configuration section is empty. You cannot save the configuration until you provide values in all the mandatory fields.
- Provide values in at least the mandatory fields (marked with asterisks).
- Click Save & Reload at the top of the page.
A new alert is now configured.
Cloning a Configuration Section
To add a new configuration section with settings copied from an already configured section, use the clone button. For Protocol Adapters, you can clone:
measurements
alerts
configuration parameters
metadata
devices
Example: To clone metadata, follow these steps:
- Expand the metadata section by clicking its row.
- Click Clone above the metadata you want to copy.
The metadata is cloned. A green line at the bottom indicates the cloned configuration section.
The copied metadata has the same settings as the original one.
Settings that must be unique, e.g. ID, are not cloned.
- Provide a unique ID of your cloned metadata. You can also modify any other settings.
- Click Save & Reload at the top of the page.
The new metadata is now configured.
Deleting a Configuration Section
To delete a configuration section, follow these steps:
- Navigate to the section you want to delete by clicking its row.
- Click Delete above the section.
- Confirm your decision when a warning message appears.
- Click Save & Reload at the top of the page.
The configuration section is now deleted.
Resetting a Configuration Section
To clear configuration settings in, click Reset at the top of the configuration section. For Protocol Adapters, you can reset the device Connection section.
As a result, the connection fields are cleared.
You can now provide new connection settings.
Editing the Rule Engine Manifest File
The Configuration Manager allows you to view and edit a rule manifest file of the Rule Engine. This file contains a set of rules that are executed by the Rule Engine and defines triggers of the rule execution.
To view the rule manifest file, click Configure in the Rule Engine's row in the list of detected components.
A list of rules appears.
Rules highlighted in pink and labelled as blacklisted
are disabled. It means they are included in the rule blacklist file.
To enable a blacklisted rule, edit the rule blacklist file file in a text editor. You cannot do it using the Configuration Manager's user interface.
To view details of a rule, click its row in the list. This displays the rule details included in the rule manifest file and the rule source code, as shown below.
Here, you can edit the rule properties, e.g. change the rule_log_severity
or set the max_exec_time
. See below for an example how to edit the rule triggers.
Not all the rule settings are editable in the Configuration Manager. For example, you cannot change the
file
value. To modify such settings, open the rule manifest file in a text editor.
Editing the Rule Triggers
In the Triggers section of the rule details, you can view and edit triggers of the rule execution.
In the Configuration Manager, you can edit the
on-tick
triggers only. To edit theon-publish
,on-pmq
, andon-config-change
triggers, open the file in a text editor.
In the on-tick
section, you can edit, remove or add new Cron expressions to schedule a rule execution.
When you edit or add a new Cron expression, you can either type it directly in the field in the table or use a form that appears below.
Each section of the form represents a field of the Cron expression: seconds, minutes, hours, days of the month, months, days of the week.
When you select a value in the form, it automatically modifies the Cron expression in the table.
To combine different values in a field using the form, click the button and provide an additional value. In the example below, values 2 and 12 are combined in the minutes field.
The Configuration Manager verifies if you have provided a valid Cron expression. If not, it displays an error in the triggers list.
For more information on scheduling rules with the
on-tick
triggers, see the Cron Expressions section.
To apply your changes, click Save & Reload at the top of the page.
The Rule Engine is restarted with the updated rule manifest file.
Downloading a Configuration File
The Configuration Manager enables exporting configurations and saving them as .json
files. To do so, follow these steps:
- On the List of detected components, click Configure next to the configuration you want to open.
- Click Download Json Config at the top of the page.
The Configuration Manager downloads and saves the .json
configuration file in your default download location.
Uploading a Configuration File
You can import saved configuration files to the Configuration Manager and use them as component configurations. To do so, follow these steps:
- On the List of detected components, click Configure next to the configuration you want to open.
- Click Choose File at the top of the page and select a file you want to import.
You can only import configurations saved as
.json
files.
- Click Load File.
The Configuration Manager imports the file and overrides the previous configuration.
If the selected file does not contain a valid configuration, the Configuration Manager displays an error message is displayed and does not load the file.
Example: A configuration file is invalid if it is not a
.json
file, if it does not contain mandatory settings, or if the provided values have a wrong format.
Viewing Logs
The Configuration Manager allows you to display logs of detected components.
To view logs in the web browser, you must first add the
relayr
user to thesystemd-journal
group:
usermod -a -G systemd-journal relayr
To view logs, click the See logs button, available in the following views:
- On the List of detected components:
- On the component's configuration form:
The Configuration Manager opens the component logs, as shown below.
In the Printed lines field, you can select how many lines of logs you want to view.
Managing User Accounts
When you install the Configuration Manager, no user account is created, by default. You need to create the admin account, using the configuration script. See here for more information.
Once you've created the admin account, you can log in to the Configuration Manager and manage all user accounts in the Account Settings section of the user interface.
In the Account Settings page, you can perform the following actions:
- Change your password.
- Add a new user.
- Delete users.
- Change a user's password.
A user name can only contain letters [a-z], [A-Z] and numbers [0-9].
Full account settings are accessible to system administrators only. Other users can only change their own password.
Configuration File Example
{
"web_server": {
"host": "127.0.0.1",
"port": 21080,
"database_path": "/var/cache/relayr/gwa-config-mgr-cpp/gwa-config-mgr-db.sqlite3",
"use_ssl": true,
"private_key_path": "key.pem",
"certificate_path": "cert.pem"
},
"health_monitor": {
"mqtt_connection": {
"host": "127.0.0.1",
"port": 1883,
"keepalive": 5
}
}
}