====== 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.
{{:common:icon_note.png}} 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 [[.:installpromonitor|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 |
{{:common:icon_info.png}} 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' /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-_'' |
| 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.
{{:common:icon_info.png}} 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 [[common:procedures:install_java|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)[^ "]+' /bin/setenv.sh) -version
Expected: the Java version. ''Unrecognized VM option'' names the option to remove from the old ''setenv.sh''.
{{:common:icon_note.png}} 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.
{{:common:icon_note.png}} 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-_.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:
- asks the MySQL admin user and password, the password is not displayed
- lists the databases of the MySQL server and asks for each one ''Dump ? [Y/n]''. Press **Enter** on each question: the Cockpit databases are selected by default
- asks ''Stop promonitor-cockpit and dump these bases? [Y/n]''. Nothing is stopped before this answer
- stops Pro.Monitor Cockpit, dumps and checks each database
Expected end:
All bases dumped in /root/bkp-cockpit-
Keep /root/bkp-cockpit-/mysql-admin.cnf for restore-databases.sh - delete it once the procedure is over
You can run migrate.sh now
{{:common:icon_note.png}} **Do not go on without the line** ''You can run migrate.sh now''.
The backup folder is ''/root/bkp-cockpit-''. 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.
{{:common:icon_note.png}} 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.
{{:common:icon_note.png}} 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-/logs-redpeaks-cockpit
./restore-databases.sh
The script:
- checks the backup and asks for each database ''Restore ? [Y/n]''
- asks ''Stop and disable redpeaks-cockpit? [Y/n]''
- asks to type ''RESTORE''. Any other answer cancels and changes nothing
- restores each database and compares it with the backup: '' IDENTICAL'' is expected for each one
- 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- ./restore-databases.sh
{{:common:icon_note.png}} 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-/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- # the old folder
rm -rf /root/bkp-cockpit- # 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'' |
{{:common:icon_note.png}} 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_.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 '' | 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 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 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 |