2.2. Configuring Boro Solution¶

Note

Sections of this chapter are the instructions for the configuration of the Boro Solution application after it has been successfully installed and launched. Thus, instructions are applied to the operating server if it has not been separately negotiated.

2.2.1. Migrating Projects from Boro service¶

The Boro architecture implies the possibility of migrating projects from the Boro service to the local server of Boro Solution. The process of migration is carried out in several stages:

Export of a project from the Boro service (made upon request by a technical support engineer)
Import of the received project by a Boro Solution administrator
Starting the probe
Applying the probe configuration

Project Migration¶

The project migration is made separately for each project through the export and further import of a project file in the JSON format. The exporting file includes the following settings:

General project settings: a project name, access parameters to FTP/SFTP servers, SAML authentication settings, and other.
Key for connecting the probe to the project.
Full profile configuration: records, thresholds, KPI, and all notification types.
Saved configurations of all probes. This includes configuration for each running probe, that is created automatically when exporting the project.
Records about all projects, that were run in the project. This additionally includes history of probes updates.

Important

There is no possibility to migrate task statistics, event and alarm journals.

To receive the exported project file, contact an Elecard technical support engineer.

To migrate a project to a server, you should first create an arbitrary-named project into which you will import the required project. Then login as the server administrator (the Superadmin role) and go to the users tab Admin ➝ Users. Click the name of the user that created a target project. In the User info tab, find a required project in the Projects section. Upload a configuration file using the Choose File button and click the Import button to start a migration process.

Running and configuring probes¶

You may use the following methods to run probes on a new server:

Running new probes

It is the easiest way to run probes. Download the probe archive on the Boro Solution server, unpack the archive, and run the probe. Using this method, you can run a required number of probes. In case if the probe was launched as the service, you need to set up it again. Detailed instructions are given in the Probe as service section. Then go to the web interface and rename probes (you may use new names).
Changing a configuration file of probes that worked with the service

Previously used probes can be saved for the further use on the server, for it you need to specify a new server address in the configuration. Using this method, all tasks of the probe will be started, however notification and settings profiles won’t be applied. In the section below, there is the description of how to restore the settings. Stop the running probe and open the configuration file monitor.cfg and edit the following:

In the server string specify the server address in the format "https://ip_or_hostname:8443".

In OS Linux, the following script can be used:
Script allows automating the process of replacing the server address when working in console. This is helpful, if addresses should be replaced for many probes.
SERVER_PUBLIC_NAME="ip_or_hostname" sed -i "s#\"server\": \"[^\"]*\"#\"server\": \"https://${SERVER_PUBLIC_NAME}:8443\"#" /PATH/TO/BORO/PROBE/monitor.cfg
After editing the probe configuration, run the probe to check whether the probe is displayed in web interface of the Solution server.

Applying Probe Configuration¶

When using any method of probe restoring you need to apply the configuration from the list of saved configurations on the server. Go to the probe page and click the Apply probe configuration button. Select the import live tasks (import) configuration for the required configuration and click the Show button. If necessary, update IP addresses of network interfaces and apply the configuration. As a result, the list of tasks will be restored with all profiles of settings and notifications. Please note that imported profiles will have the “(import)” word in its title. You can change notification names, this won’t require the reconfiguration of tasks.

2.2.2. Changing the Server Name (Hostname)¶

To change the server name that was set in the SERVER_PUBLIC_NAME variable, once Boro Solution is installed you need to follow the steps below:

Request from a technical support engineer a new certificate for a new name or an IP address of the server.
As the server administrator (the Superadmin role), upload the received certificate in the Admin ➝ Certificates tab.
If needed, update the Host name in the Admin ➝ Email tab.

In the console of the Boro Solution server run the following command from the superuser:

NEW_SERVER_PUBLIC_NAME="local_BoroServer_ip_or_hostname"        #set new IP address or hostname of the BoroServer
sed -i "s#client_api_base_url: .*#client_api_base_url: \"https://${NEW_SERVER_PUBLIC_NAME}:8443\"#;
        s#turn:turn:[^:]*:3478#turn:turn:${NEW_SERVER_PUBLIC_NAME}:3478#" \
        /opt/elecard/boro-rails-server/config/.env.yml
sudo systemctl reload boro_puma.default
if [ -e /etc/coturn/turnserver.conf ]; then
  sed -i "s/^realm=.*/realm=${NEW_SERVER_PUBLIC_NAME}/" /etc/coturn/turnserver.conf
  sudo systemctl restart coturn
fi

Specify a new hostname instead of local_BoroServer_ip_or_hostname. This will change a server address in the probe configuration file and a STUN/TURN server address.

Previously downloaded probes will not be able to connect the server. To resume its operation, update the server value in the monitor.cfg file. After editing the probe configuration, run the probe to check whether the probe is displayed in web interface of the Solution server.

2.2.3. Changing the Location of the Database Files¶

To change the folder of storing the database files, run the following command from the superuser:

# Step #0: setup environment:
NEW_DB_LOCATION="/PATH/TO/NEW/DB/LOCATION"        # set path to new location of DB files

# Step #1: check available space:
CUR_DB_DIR=$(realpath /var/lib/pgsql);
NEW_DB_LOCATION="$NEW_DB_LOCATION/pgsql";
mkdir -p "$NEW_DB_LOCATION";
if [ "$(findmnt -o TARGET -nT "$CUR_DB_DIR")" != "$(findmnt -o TARGET -nT "$NEW_DB_LOCATION")" ]; then
  DB_SIZE=$(du -s -B1M "$CUR_DB_DIR" | cut -f1)
  TARGET_FS_AVAIL=$(df -B1M --output=avail "$NEW_DB_LOCATION" | tail -1)
  if [ "$DB_SIZE" -gt "$TARGET_FS_AVAIL" ]; then
    echo "No sufficient space on destination FS:"
    printf "%22s - %9d MB\n" \
      "DB size" "$DB_SIZE" "target FS available" "$TARGET_FS_AVAIL"
  fi
fi

# Step #2: stop PostgreSQL:
PG_VER=$(psql -V | sed 's/psql (PostgreSQL) \([0-9]\+\)\.[0-9]\+.*/\1/');
systemctl stop postgresql-${PG_VER}.service;

# Step #3: move files:
echo "Start copying: \"$CUR_DB_DIR\" -> \"$NEW_DB_LOCATION\" ...";
time mv -Tf "$CUR_DB_DIR" "$NEW_DB_LOCATION";

# Step #4: update link and SELinux rules:
ln -Tfs "$NEW_DB_LOCATION" /var/lib/pgsql;
semanage fcontext --add --equal /var/lib/pgsql "$NEW_DB_LOCATION";
restorecon -R "$NEW_DB_LOCATION";

# Step #5: restore services:
systemctl restart postgresql-${PG_VER}.service \
  boro_sidekiq.default boro_puma.{web_api,default} \
  boro_golang.{worker,server};

# Step #6: check Solution status:
/opt/elecard/bin/status.sh

Notes:

Specify a new folder for storing database files instead of /PATH/TO/NEW/DB/LOCATION. Additional subdirectory pgsql will be created in the destination directory;
Due to the dangerous nature of the operations, execute the script gradually, piece by piece, checking errors on each step;
Moving files may take some time depending on the DB size and the speed of the storage device;
After finishing, check the Solution web interface.

2.2.4. Establishing Access to the Web Interface Over HTTPS¶

To configure access to the web interface over secure protocol, you need to go through steps below:

Add a rule to Firewall:

firewall-cmd --state && (firewall-cmd --permanent --add-service=https; firewall-cmd --reload);

Then you need to configure paths used for a certificate and key that should be used for establishing HTTPS connection. For this, you need go to the /etc/nginx/sites-available/boro.https.conf file and specify paths used for a certificate ssl_certificate and key ssl_certificate_key. Recommended examples of storing path are given in the boro.https.conf file. However, if you want to use custom paths, you need to consider the following restrictions:
- the files should have the same SELinux security context httpd_config_t;
- the files shouldn’t be located in the home directory of any user.
To add a configuration file with using the HTTPS port in nginx specify the following command:
```
ln -fs ../sites-available/boro.https.conf /etc/nginx/sites-enabled/boro.https.conf;
```

To check the configuration and restart nginx:

nginx -t && (restorecon /var/run/nginx.pid; systemctl restart nginx)

2.2.5. Enabling ControlAPI in Nginx¶

By default, access to API is prohibited for all IP addresses in the Nginx settings. To configure access, you need to edit the /etc/nginx/sites-include/boro.conf file on the Boro Solution server. Find the following block:

location /ctrl_api {
#    allow 10.1.1.0/16;
#    allow 2001:0db8::/32;
    deny all;
    try_files /dev/null @default;
}

To provide the access, uncomment the allow string and specify the IP address or a pool of IP address. You can specify a list of rules by giving multiple allow directives on a new line.
To allow access for all IP addresses, comment the string deny all in the following manner:
```
#    deny all;
```

To check the configuration and apply changes, restart nginx by entering the following command:

nginx -t && (restorecon /var/run/nginx.pid; systemctl restart nginx)

In case errors occur, fix them and try to reapply a new configuration.

Useful links: How To Whitelist IP in Nginx

2.2.6. Changing the Statistics Storing Period¶

By default, data storing period is 14 days. This means you can get access to the history (journals, statistics, graphics, alarms) for previously started tasks. Statistics is rotated during daily data cleanup, as a result data older than the specified storing period is cleaned.

To change a storing period, go to the /opt/elecard/boro-rails-server/config/.env.yml file and add the following strings:

db:
  keep_rotation_tables_days: xx

Instead of xx, specify a storing period (in days). Then apply changes:

systemctl restart boro_sidekiq.default

2.2.7. Resetting the Administrator Password¶

To change a compromised password, you should go to the server Administrator Panel. Find the user admin@admin.com, switch to the User Edit tab and set the new password.

If you have forgotten the password, the only solution is to reset it. Go to the server where the Boro Solution is installed, open the console and execute the following script as superuser. Instead of the USER_PASSWORD variable, set the new password value:

USER_EMAIL='admin@admin.com'
USER_PASSWORD='adm1n678'

su boro -c "
  cd /opt/elecard/boro-rails-server;
  source setup_env.sh;
  bin/rails r \"
    u = User.find_by!(email: '$USER_EMAIL');
    u.password = '$USER_PASSWORD';
    u.save(validate: false)
  \"
"