ABB Ability™ History has supported running the database and all the major software services in Linux. The installation packages are currently available within ABB's intranet (https://cpmplus-repository.abb.com/), but they are planned to be released on a public internet server at a later date.

Part of the ABB Ability™ History cpmPlus software is running on top of Microsoft's .NET, which can be installed from the cpmPlus repositories.

There are multiple versions of packages available; the Main and QA are mainly for testing purposes, and then versions with a version number like 5.3 are production releases.

📘

Currently, there is no way to create an RTDB database within ARM-based Linux. You need to create the database in Windows or x86/x64 Linux and copy it over. The default database location is /var/lib/rtdbdata.

Supported distributions and platforms

Summary of supported distributions:

Other distros based on the ones mentioned MAY work too, as long as they are properly based on one of the mentioned and use the same package manager.

However, Ubuntu is NOT supported! Ubuntu is theoretically Debian-based, but mixes packages from the Debian testing release with the actual release, making it incompatible!

Software Installation

Acquire::http::Proxy::cpmplus-repository.abb.com DIRECT;
Acquire::http::Proxy "http://gateway.zscaler.net:443";

sudo wget -P /usr/local/share/ca-certificates/ http://cpmplus-repository.abb.com/ABBRootCA.crt
sudo /usr/sbin/update-ca-certificates

echo "deb [trusted=yes] https://cpmplus-repository.abb.com/debian trixie main" | sudo tee /etc/apt/sources.list.d/cpmplus.list

sudo apt-get update
sudo apt-get install cpmplusdotnetruntime cpmplushistory

sudo apt-get remove cpmplusdotnetruntime cpmplushistory
sudo apt-get autoremove

Database and Service Configuration (systemd, all distributions)

IMPORTANT: The operating system must be restarted after installing the cpmPlus History for all system settings to take effect.

The cpmPlus services (RTDB services) are managed by the RTDB main service (RTDB_ServiceManager), which is configured to run as a systemd service.

Database user (cpmplus) and runcpm command

Installing cpmPlusHistory creates the user cpmplus on the system. User cpmplus is given access to the database directory when the database is created. Database services are run with the cpmplus user.

Any command line using direct access to the database should be prefixed with the runcpm command. This runs the command line as the cpmplus user.

Creating a new database

If you need a new database, you can create it in Linux or copy an existing one.

sudo RTDB_Create_New_Database /var/lib/rtdbdata --dsn rtdb

If you plan to install the system to support high availability, you need to add the qualifier --cc_on, i.e.:

sudo RTDB\_Create\_New\_Database /var/lib/rtdbdata  --dsn rtdb --cc\_on

Creating a database replica (e.g. for High Availability setup)

If you are creating a database replica of the first database (possible when the first database was created with --cc_on), you should copy the existing database to the newly created replica by taking a copy with RTDB_Backup and creating the index files for it with RTDB_ScanDB. I.e.:

runcpm RTDB_Backup --speed 100 -s /var/lib/rtdbdata -d /var/lib/rtdbbackup '*'
#Next copy the backup directory to the other computer, and do there:
runcpm RTDB_ScanDB -ab /var/lib/rtdbbackup '*'
runcpm cp /var/lib/rtdbbackup/*.Tab* /var/lib/rtdbdata/
#Clear columns that contain RowId values
runcpm praox rtdb -sql "UPDATE CurrentValues SET CSE=0, CSNE=0 WHERE CSE <> 0 OR CSNE <> 0"

And if you have not yet done so, insert the High Availability configuration parameters for the other node to SimpleConfig (see below).

Creating a database from a template

First, create a new database as shown above, then

sudo apt install cpmplushistorycpimstemplates cpmplushistorybasetemplates cpmplushistorynewdatabase<br />runcpm praox -constr "driver=rtdb core;dbq=<database location>" -ss "/usr/share/cpmplus/config/RTDB\_Create\_Production\_Database.sql"

Database repair with RTDB_ScanDB (corrupted or copied database)

The database may need to be repaired if it, for example, has been copied from another system (like Windows) or if any software with a direct database connection has been abruptly killed, causing database corruption.

📘

NOTE:-

The RTDB main service runs the RTDB_ScanDB automatically at startup, but sometimes it may be necessary to run a manual scan, if, for example, the database needs to be accessed before starting the main service, or if there is a need to run RTDB_ScanDB in paranoid mode, which makes more extensive checks in the database.

To perform a paranoid scan and automatically fix any problems in the database, run the command below:

runcpm RTDB_ScanDB -abp /var/lib/rtdbdata '*'

Service Configuration

Run the following commands to install the needed services.

High Availability Setup (RTDB-ConsistencyController)

This is needed if the database is a High Availability database.

runcpm RTDB_ConsistencyController -install /var/lib/rtdbdata

Check the /etc/hostname before this step. Some mandatory settings are needed to SimpleConfig:

runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "RTDB-ConsistencyController" -key MulticastIP -strvalue TCP SetSimpleConfig
runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "$(cat /etc/hostname):RTDB-ConsistencyController" -key MulticastAdapters -strvalue 10.1.1.11 SetSimpleConfig
runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "$(cat /etc/hostname):RTDB-ConsistencyController" -key Priority -strvalue 0 SetSimpleConfig
runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "OtherHost:RTDB-ConsistencyController" -key MulticastAdapters -strvalue 10.1.1.12 SetSimpleConfig
runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "OtherHost:RTDB-ConsistencyController" -key Priority -strvalue 1 SetSimpleConfig

runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "RTDB-CVMCServer" -key MulticastIP -strvalue TCP SetSimpleConfig
runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "$(cat /etc/hostname):RTDB-CVMCServer" -key MulticastAdapters -strvalue 10.1.1.11 SetSimpleConfig
runcpm RTDB\_Cmd dbc -datapath /var/lib/rtdbdata -section "OtherHost:RTDB-CVMCServer" -key MulticastAdapters -strvalue 10.1.1.12 SetSimpleConfig

You do not need to enter the entries for the other host if they are not yet known.

📘

Remarks:-

The length of the host name can not exceed 13 characters because the SimpleConfig section name column is max 40 characters.

The IP address in the above configuration indicates the network adapter to be used for communicating with the other replica. The IP address must belong to a protected network, preferably implemented with a direct Ethernet cable between the servers.

In case CC did not kick in when the system started, check that there is no empty MulticastAdapters properties in the SimpleConfig table.

Commonly Needed Services

runcpm RTDB_CVMCServer -install /var/lib/rtdbdata
runcpm RTDB_Transformator -install /var/lib/rtdbdata
runcpm RTDB_Scheduler -install /var/lib/rtdbdata

Vtrin-NetServer

Vtrin-NetServer is added as a service with CSCommon_CMD.

runcpm CSCommon\_Cmd -setini /var/lib/rtdbdata/RTDB.INI Services Vtrin-NetServer ON
runcpm CSCommon\_Cmd -setini /var/lib/rtdbdata/RTDB.INI Vtrin-NetServer BinaryPath "/usr/share/dotnet/dotnet /usr/share/cpmplus/netcore/Vtrin-NetServer.dll -d"

System Monitor

System Monitor produces database, service and general system diagnostics.

runcpm RTDB_SystemMonitor --install --databasepath /var/lib/rtdbdata/

Starting Services

Before you start the main service in 5.3 Q3/2022 or later, you need to change the owner and group of the database folder:

# In 5.3 Q3/2022 and later ONLY for databases created using older version!
sudo chown cpmplus --recursive /var/lib/rtdbdata
sudo chgrp cpmplus --recursive /var/lib/rtdbdata

Note that in the following commands, slashes in the database path must be replaced with hyphens

DO NOT START the services yet before all configuration steps are ready, such as the configuration of Vtrin-NetServer.config, but services are started with the command:

sudo systemctl enable rtdb@-var-lib-rtdbdata
sudo systemctl start rtdb@-var-lib-rtdbdata

You can view the service logs with:

sudo journalctl -r -u [[email protected]](mailto:[email protected])

Installing Engineering UI

The default data source [0] in the Vtrin-NetServer configuration should be the cpmPlus History database. You can install Engineering UI by running:

# Debian
sudo apt-get install cpmplushistoryengineeringui
# Arch Linux
sudo pacman -S cpmPlusHistoryEngineeringUI
# Alma/RHEL
sudo dnf install cpmPlusHistoryEngineeringUI

After restarting the database, the Engineering UI is automatically installed in the database and available via https://localhost/history/

Installing HTTPS Certificate (Let's Encrypt)

We have a package to automatically install an HTTPS certificate.

You might want to install cronie, which allows you to automatically update the certificate every 3 months(default period):

sudo pacman -S cronie
sudo systemctl enable cronie
sudo systemctl start cronie

To install and run the encrypt:

# in Arch
sudo pacman -S cpmPlusLetsEncrypt
sudo systemctl start rtdb\@-var-lib-rtdbdata
sudo /usr/bin/cpmPlusLetsEncryptInit

In case the update script needs to be run manually:

sudo /usr/share/cpmplus/letsencrypt/update.sh

The certificate will be located at /usr/share/cpmplus/netcore/vtrincert.pem, you need to update /usr/share/cpmplus/netcore/Vtrin-NetServer.config to:

There is a manual way to install an HTTPS certificate.

These instructions apply to getting the certificate from letsencrypt.org and installing it. The same instructions might partially apply to other providers, too. The commands must be executed when the View server is running with HTTP serving already enabled on port 80. If you have any directory access limitations, you have to lift them for the directory /srv/miaroot/.well-known/acme-challenge/ before you proceed. This can be done by creating the directory and placing a mia.config with the following contents in the directory:

After that, you can proceed with the actual commands:

certbot certonly -d mydomain.com -a webroot --webroot-path /srv/miaroot --text
sudo openssl pkcs12 -export -in /etc/letsencrypt/live/mydomain.com/fullchain.pem -inkey /etc/letsencrypt/live/mydomain.com/privkey.pem -passout pass:vtrincert -out /usr/share/cpmplus/mydomain.com.p12
sudo chown cpmplus /usr/share/cpmplus/mydomain.com.p12

Finally, set the certificate in the /usr/share/cpmplus/netcore/Vtrin-NetServer.config to the correct value:

Installing a self-signed HTTPS Certificate

If you use a lab certificate, you can create it in the same way as with Windows and then export both the private key and the certificate to P12 format. Make sure the friendlyname in certificate and the Vtrin server config match. vtrincert is the default friendlyname. Then use the same step as with the letsencrypt certificate:

certmgr -add -c -pem -p <password used for private key in export> -m My vtrincert.p12

You can also specify the .p12 (same as pfx) file name in the Vtrin-NetServer config.

For developers, you can use the following script to create vtrincert.p12. It will be located at /usr/share/cpmplus:

# !/bin/bash

TARGETPATH=/usr/share/cpmplus
PASS=vtrincert

echo Generating certificate

openssl req -newkey rsa:2048 -x509 -sha512 -days 365 -nodes -out /tmp/vtrincert.pem -keyout /tmp/vtrincert\_privatekey.pem -subj "/C=GB/ST=London/L=London/O=Global Security/OU=IT Department/CN=$(hostname)"
sudo openssl pkcs12 -export -in /tmp/vtrincert.pem -inkey /tmp/vtrincert\_privatekey.pem -passout pass:$PASS -out $TARGETPATH/vtrincert.p12

echo Certificate generated $TARGETPATH/vtrincert.p12

The certificate in the /usr/share/cpmplus/netcore/Vtrin-NetServer.config should be in the correct value vtrincert.p12 . After the certificate is created, grand cpmplus user the right to read it:

chown cpmplus:cpmplus vtrincert.p12

Trusting a certificate

If you need to trust a server certificate so that your clients, like NetSync, can operate over SSL, you can add it to the Linux store. On Debian, that is done by copying the certificate with extensions .crt to /usr/local/share/ca-certificates/ and running update-ca-certificates.

$: cp ca.crt /usr/local/share/ca-certificates/
$: update-ca-certificates
Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.

You can check the certificate details, like expiration, with the command:

$: openssl x509 -in ca.crt -noout -text

All programs on Linux use this store, and you should get no SSL errors after this when running

curl -v -L [https://yourownsrver/history](https://yourownsrver/history)

Configuring Vtrin-NetServer

The Vtrin-NetServer can be configured by using the /usr/share/cpmplus/netcore/Vtrin-NetServer.config file. Instructions on configuring it can be found in the Vtrin Server Configuration. You can start configuring by taking a copy of the /usr/share/cpmplus/netcore/Vtrin-NetServer.config.example.

Example Configuration

This is an example Vtrin-NetServer configuration. This assumes that the database is in /var/lib/rtdbdata, the admin user is root and that the port to listen to is 443 (the protocol is wss). It also adds the logfile path to one under the database directory. Below is the bash command to set up Vtrin-NetServer with the previously mentioned configuration( replace "MyVtrinDbDSN" with your VtrinDbDSN).

sed '/<system.runtime.remoting>/,/</system.runtime.remoting>/d' /usr/share/cpmplus/netcore/Vtrin-NetServer.config.example
| sed 's/MyVtrinDbDSN//var/lib/rtdbdata/g'
| sed 's/<add key="LogFile" value="" >/<add key="LogFile" value="/var/lib/rtdbdata/Diag/Vtrin-NetServer" >/g'
| sed 's/UserName" value="guest"/UserName" value=""/g'
| sed 's/</appSettings>/<add key="WebSocketServerSecurePort" value="443"></appSettings>/g' > Vtrin-NetServer.config

Docker

cpmPlus History can be run in a Docker container, and there is an image hosted in the cpmPlus repository. See this separate article for instructions: CpmPlus History in Docker

Upgrading

To upgrade the software, stop the RTDB service:

sudo systemctl stop rtdb\@-var-lib-rtdbdata

Upgrade the product to the new version using the package manager commands of the distribution. For example, in Debian:

sudo apt-get update
sudo apt-get upgrade

Or in Arch:

sudo pacman -Syu

If in Manjaro, the update fails to some Manjaro-specific packages, you may need to run Manjaro's tool pamac update

Upgrade the database with the following command:

runcpm RTDB\_Upgrade\_Database /var/lib/rtdbdata

The command is able to upgrade the RTDB 5.2 and later version database to the current version. It updates the TableDefinition structure of all standard RTDB database tables and copies any tables that are missing from the database, and loads new UIClass and UIString settings.

📘

NOTE:-

Upgrading the databases to the current version is generally mandatory because the new version may contain structure changes that are expected by the new software (if you really know that there are no structure changes or required UIClass/UIStrings changes, you can omit the database upgrade).

After upgrading, you can restart the service:

 sudo systemctl start rtdb\@-var-lib-rtdbdata

Troubleshooting

Unable to fetch some archives, and error 404 received when running apt-get install cpmplushistorymono

• Try removing the content of /var/lib/apt/lists directory:
• sudo rm -rf /var/lib/apt/lists/*
• sudo apt-get update

Package dependency issues with odbc that lead to unixodbc and libiodbc2

Some users seem to have the Microsoft package repo added to their system. That repo seems to contain some odbc packages that cause conflicts and don't allow unixodbc and libiodbc2 to be installed at the same time. Remove the Microsoft repo and only use distribution repos and the mono repo if needed.

If you are not sure if this is your issue, you can confirm it by trying to install unixodbc and libiodbc2. If one of those reports says it will REMOVE the other one, then you are facing this.

For example

sudo apt-get install unixodbc

results in:

The following packages will be REMOVED:
	libiodbc2

Inspecting the database with praox

You can command-line SQL access to the database with the praox tool. If the database was created with the --dsn rtdb, it is easy to access the database, for example:

runcpm praox rtdb -sql "select * from SimpleConfig"

Otherwise, you need to use a more complicated ODBC connection string:

runcpm praox -constr "driver=RTDB Core;dbq=/var/lib/rtdbdata" -sql "select * from SimpleConfig"

Categories: Pages using Tabber parser tag Linux