Table of Contents

Migrate Pro.Monitor Cockpit to Redpeaks Cockpit

This page describes the one time migration of an existing Pro.Monitor Cockpit installation (Tomcat 9, service promonitor-cockpit) to Redpeaks Cockpit (Tomcat 11, service redpeaks-cockpit).
The migration is done from the OS with the migrate.sh script of the delivery package. Once migrated, the next versions are installed with update.sh or from the web superadmin UI.

This migration cannot be done from the web superadmin UI. The update page of Pro.Monitor Cockpit refuses the Redpeaks Cockpit package, and update.sh refuses a Pro.Monitor Cockpit installation.

Which script to use

Installed today Script
Nothing install.sh, see Install Redpeaks Cockpit
Pro.Monitor Cockpit on Tomcat 9, service promonitor-cockpit migrate.sh, this page
Redpeaks Cockpit on Tomcat 11, service redpeaks-cockpit update.sh or the web superadmin UI

The web superadmin UI updates only the application, the delivery zip holds no Tomcat. Use it when the release note announces no new Tomcat version. When a new Tomcat version is embedded (vulnerabilities, …), update from the OS with update.sh.

Check the installed service and Tomcat version:

systemctl cat promonitor-cockpit redpeaks-cockpit 2>/dev/null | grep -E '^# /|WorkingDirectory'
grep -m1 'Apache Tomcat Version' <WorkingDirectory>/RELEASE-NOTES

What changes

Item Before After
Application Pro.Monitor Cockpit Redpeaks Cockpit
Runtime Tomcat 9 Tomcat 11, Java 21 or later
Service promonitor-cockpit redpeaks-cockpit
Folder /opt/Pro.Monitor-Cockpit link /opt/redpeaks-cockpit to /opt/Redpeaks-Cockpit-<version>_<build>
System user as before redpeaks-cockpit, created when missing
HTTP and HTTPS ports bin/setenv.sh same ports, a reverse proxy needs no change
JVM settings: memory, ports, options bin/setenv.sh bin/setenv-override.sh

Carried over from the old installation:

The delivered bin/setenv.sh loads bin/setenv-override.sh last: the JVM keeps the last value of an option, your settings win. setenv.sh is replaced on each update, setenv-override.sh is kept as is.

Not carried over:

The old installation stays on the disk, stopped and disabled, for a rollback.

Prerequisites

Check the old setenv.sh

The old bin/setenv.sh becomes setenv-override.sh as is. Check it before the migration:

java $(grep -oE -- '-(XX:|Xm[sx]|Xss)[^ "]+' <WorkingDirectory>/bin/setenv.sh) -version

Expected: the Java version. Unrecognized VM option names the option to remove from the old setenv.sh.

A refused JVM option is not logged: systemctl start prints Tomcat started, then the service restarts in a loop every 10 seconds without any message.

We strongly advise a rehearsal on a test server with the same version and the same databases layout before the production migration.

Migration

1. Extract the delivery package

Extract the package in an empty folder of the root home directory. Do not copy the archive in /opt folder

mkdir /root/cockpit-upgrade && cd /root/cockpit-upgrade
tar -xzf Redpeaks-Cockpit-<version>_<build>.tar.gz

This will create the following files:

2. Back up the MySQL databases

./dump-databases.sh

The script:

  1. asks the MySQL admin user and password, the password is not displayed
  2. lists the databases of the MySQL server and asks for each one Dump <database>? [Y/n]. Press Enter on each question: the Cockpit databases are selected by default
  3. asks Stop promonitor-cockpit and dump these bases? [Y/n]. Nothing is stopped before this answer
  4. stops Pro.Monitor Cockpit, dumps and checks each database

Expected end:

All bases dumped in /root/bkp-cockpit-<YYYYMMDD>
Keep /root/bkp-cockpit-<YYYYMMDD>/mysql-admin.cnf for restore-databases.sh - delete it once the procedure is over
You can run migrate.sh now

Do not go on without the line You can run migrate.sh now.

The backup folder is /root/bkp-cockpit-<YYYYMMDD>. A backup is never overwritten: when this folder already holds a backup, the script stops.

Special cases for the backup

Before the backup, edit the configuration block at the top of both dump-databases.sh and restore-databases.sh with the same values:

Case Variable
MySQL runs in Docker MYSQL_CONTAINER : name of the MySQL container
MySQL listens on another host or port DB_HOST and DB_PORT
Backup on another disk BKP_DIR
Pro.Monitor Cockpit installed under another service name OLD_SERVICE : the old service name

3. Run the migration

Special case for the migration

Pro.Monitor Cockpit installed under another service name than promonitor-cockpit: before the migration, edit the configuration block at the top of migrate.sh.

Case Variable
Pro.Monitor Cockpit installed under another service name OLD_SERVICE : the old service name
Redpeaks Cockpit to install under another service name SERVICE : the new service name

The installation folder and the system user are asked by the script, nothing to edit for them.

This page uses the default service name redpeaks-cockpit. When SERVICE is changed, adapt every systemctl command of this page to the new name, and set the same name in NEW_SERVICE of dump-databases.sh and restore-databases.sh before the backup (step 2), and in SERVICE of update.sh before each update.

Run

./migrate.sh

The script reads the old installation and its ports, prints a summary, then asks:

Question Answer
Enter the HTTP port and Enter the HTTPS port asked only when the ports cannot be read from the old setenv.sh: give the old ports
Do you want to use this directory? (/opt) yes
Do you want to use this user? (redpeaks-cockpit) yes
Do you want to overwrite it? asked only when redpeaks-cockpit.service already exists: answer no and contact the support
Proceed with the migration? yes, after reading the summary
Do you want to stop it now? asked only when Pro.Monitor Cockpit still runs
Do you want to start the service now? no, the start is done at step 4

Everything displayed is also written in migration.log, next to the script.

The script stops before any installation when:

4. Start Redpeaks Cockpit

Open a second terminal before the start, to follow the new log lines only:

tail -n 0 -F /opt/redpeaks-cockpit/logs/server.log | grep --line-buffered -E "Context loaded for tenant|Exception when fetching Server TenantContext"

In the first terminal:

systemctl start redpeaks-cockpit

Expected: one Context loaded for tenant line per tenant.

On Exception when fetching Server TenantContext: stop at once with systemctl stop redpeaks-cockpit, then roll back (step 6). Do not use the UI before.

5. Check

6. Roll back when needed

Keep the logs of Redpeaks Cockpit for the support, then restore the databases:

cp -a /opt/redpeaks-cockpit/logs /root/bkp-cockpit-<YYYYMMDD>/logs-redpeaks-cockpit
./restore-databases.sh

The script:

  1. checks the backup and asks for each database Restore <database>? [Y/n]
  2. asks Stop and disable redpeaks-cockpit? [Y/n]
  3. asks to type RESTORE. Any other answer cancels and changes nothing
  4. restores each database and compares it with the backup: <database> IDENTICAL is expected for each one
  5. asks to enable and start Pro.Monitor Cockpit, then prints the command to follow its log

Restore on another day than the backup: give the backup folder.

BKP_DIR=/root/bkp-cockpit-<YYYYMMDD> ./restore-databases.sh

Everything collected since the backup is lost: alarms, metadata, configuration changes.
Never switch back by restarting promonitor-cockpit alone once Redpeaks Cockpit has started: Pro.Monitor Cockpit would run on databases already changed by Redpeaks Cockpit.

When a database is DIFFERENT, the script stops and Pro.Monitor Cockpit stays stopped: contact the support.

7. Clean up

Delete the MySQL credentials file at once, migration validated or not:

rm /root/bkp-cockpit-<YYYYMMDD>/mysql-admin.cnf

After some days of normal run, remove the old installation and the backup. Before, check that setenv-override.sh holds no path into the old folder, HTTPS would not start at the next restart:

grep -n 'Pro.Monitor-Cockpit' /opt/redpeaks-cockpit/bin/setenv-override.sh
rm /etc/systemd/system/promonitor-cockpit.service
systemctl daemon-reload
rm /opt/Pro.Monitor-Cockpit                    # the old link
rm -rf /opt/Pro.Monitor-Cockpit-<old version>  # the old folder
rm -rf /root/bkp-cockpit-<YYYYMMDD>            # holds the whole configuration of your tenants

After the migration

Before After
systemctl start promonitor-cockpit systemctl start redpeaks-cockpit
/opt/Pro.Monitor-Cockpit/bin/setenv.sh /opt/redpeaks-cockpit/bin/setenv-override.sh

Never edit the application field of about.ini. The update scripts and the web superadmin UI rely on it to refuse a wrong package.

Error messages

Message Meaning
run this script as root start the script from a root shell
already holds a dump or dump_<database>.sql exists a backup is never overwritten, set a new BKP_DIR
mysqldump is the MariaDB client install the MySQL client, or set MYSQL_CONTAINER when MySQL runs in Docker
MySQL connection failed - fix or delete <file> wrong MySQL credentials: delete the file, the script asks again
redpeaks-cockpit is running - the bases are already migrated the backup runs after the migration, too late: contact the support
databases.txt not found - the dump did not complete the backup failed, or BKP_DIR is the wrong folder
restore cancelled RESTORE not typed exactly, nothing changed
base(s) differ from the dump do not restart, contact the support
declares application 'Pro.Monitor-Cockpit' update.sh was run on Pro.Monitor Cockpit, use migrate.sh
this Java version is too old install Java 21 or later
Shutdown port <port> is also the HTTP or HTTPS port the old conf/server.xml uses an HTTP or HTTPS port as shutdown port, nothing changed: contact the support
does not load setenv-override.sh damaged delivery package, nothing changed: contact the support
is not a regular file - copy refused - nothing was changed the old bin/setenv.sh is a symbolic link: replace it with a plain copy, then run the script again
looks installed, use the update script /opt/redpeaks-cockpit already exists: the instance is already migrated, use update.sh
Target directory <folder> already exists an earlier attempt left the folder: contact the support
The previous server.xml uses another keystore path or password warning only, see Not carried over above