products:cockpit:1.0:installguide:migrationredpeakscockpit

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 folders:
    • agentupdates
    • bck
    • certificates
    • db
    • logs
    • scripts
    • snapshots
    • updates
    • upload
    • uploads
  • the file conf/tomcat-users.xml
  • the file bin/setenv.sh, copied as is to bin/setenv-override.sh: memory, ports and every custom JVM option are kept. The script adds the Tomcat shutdown port at the end

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:

  • conf/server.xml. The Tomcat 11 file is delivered and the old one is kept as conf/server.xml.bak. The keystore stays certificates/.keystore with its default password, the certificates folder is carried over. Change the certificate only from the web superadmin UI. The script warns when the old file used another keystore path or password, the value is never displayed.

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

Prerequisites

  • A root shell on the server.
  • Java 21 or later. Check with java -version. When Java is missing or older, see Install JAVA or run ./install_java.sh from the delivery package: it downloads an OpenJDK 25, installs it in /opt/java and registers it as the system java.
  • A MySQL admin account (root or equivalent) for the backup of the databases.
  • MySQL installed on the host: the MySQL client must be the MySQL one, not MariaDB. mysqldump --version must print MySQL.
  • The list of your MySQL databases: in Pro.Monitor Cockpit, Administration > DB Connectors.
  • Disk space: the size of your MySQL databases in /root, and the size of the old installation folder in /opt.
  • A downtime window: the UI and the collector calls are unavailable from the backup to the start of Redpeaks Cockpit.
  • The old bin/setenv.sh checked, see below.

Check the old setenv.sh

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

  • Paths into the old installation folder, for example -Djavax.net.ssl.trustStore=/opt/Pro.Monitor-Cockpit/certificates/.keystore. Tomcat 11 reads it at start for the HTTPS connector. HTTPS does not start once the old folder is removed, or at once when the user redpeaks-cockpit cannot read the file. Redpeaks Cockpit builds its own trust store, remove this option or point it to /opt/redpeaks-cockpit/certificates/.keystore in setenv-override.sh after the migration.
  • Any other path: it must exist and be readable by the user redpeaks-cockpit.
  • A symbolic link or not a regular file: the script refuses it. Replace it with a plain copy of the file.
  • JVM options removed from Java 21, for example -XX:MaxPermSize or -XX:+UseConcMarkSweepGC. Test them with the Java of the server:
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:

  • Redpeaks-Cockpit.tar.gz : The application package
  • migrate.sh : The migration script, Tomcat 9 to Tomcat 11
  • dump-databases.sh : The backup script of the MySQL databases
  • restore-databases.sh : The rollback script of the MySQL databases
  • install_java.sh : The Java install script
  • install.sh : The install script, new installation only
  • update.sh : The update script, Redpeaks Cockpit only

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:

  • the service promonitor-cockpit is not found: edit OLD_SERVICE at the top of migrate.sh when Pro.Monitor Cockpit was installed under another service name
  • the old bin/setenv.sh is a symbolic link or not a regular file
  • /opt/redpeaks-cockpit already exists: the instance is already migrated, use update.sh
  • the target folder already exists: an earlier attempt, contact the support
  • the service promonitor-cockpit cannot be disabled: it would start again at boot on the same ports

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

  • Login to the UI, then check each tenant: organizations, systems, alarms, dashboards.
  • Collectors screen: every collector is connected again.
  • The application answers on the same URL as before, reverse proxy included.

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

  • Next versions: the web superadmin UI with the delivery zip, or update.sh from the delivery package when a new Tomcat version is embedded. update.sh keeps your data and setenv-override.sh as is, keeps the previous version folder and refuses a downgrade.
  • Memory, ports and JVM options: edit /opt/redpeaks-cockpit/bin/setenv-override.sh only, one option per line JAVA_OPTS="$JAVA_OPTS -Xmx4096m", then restart. Never setenv.sh: it is replaced on each update.
  • New paths and service name for the other procedures of the install guide:
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
products/cockpit/1.0/installguide/migrationredpeakscockpit.txt · Last modified: by sfidan