Skip to content

Upgrade openITCOCKPIT 4 to openITCOCKPIT 5

Road to openITCOCKPIT 5

These instructions describe how to update your current installation of openITCOCKPIT 4.8.7 (or newer) to openITCOCKPIT 5.

Info

Before beginning the upgrade, please be sure to create a backup of your system! We recommend testing both your backup and update processes in a test environment before using them on a live system.

Prerequisites

  • Make sure that:
  • Your openITCOCKPIT installation is up to date
  • openITCOCKPIT >= 4.8.7
  • All operating system updates have been installed
  • A working backup of your openITCOCKPIT installation is available (in case something goes wrong)
  • You have at least 20 GB free hard disk space
  • Execute all commands as root user

Docker setup?

For Docker (or any other container runtime) based installations of openITCOCKPIT no manually upgrade process is required. All you have to do is stop the containers, pull the new images and start the containers again.

Please see the container update instructions for more information.

Supported operating systems:

openITCOCKPIT 5 can be installed on the following operating systems:

Ubuntu Noble (24.04) Ubuntu Jammy (22.04) Debian Bookworm (12) Enterprise Linux* 8 Enterprise Linux* 9

*Enterprise Linux includes Red Hat Enterprise Linux and RHEL based distributions such as: CentOS, Rocky Linux AlmaLinux or Oracle Linux.

Unsupported operating systems:

Warning

Older releases of Ubuntu or Debian (e.g. Ubuntu Focal or Debian Bullseye) are not supported by openITCOCKPIT 5 Please update your operating system first, before you continue.

Preparing the system

Step 1 - Enable non-free repositories

By default, the non-free repositories are enabled an all installations of openITCOCKPIT. It's recommended check if your system is configured to access contrib and non-free packages.

Ubuntu users

Make sure the universe repositories have been activated on your system.

add-apt-repository universe
Debian users

Make sure that the non-free repositories have been activated on your system. Ensure you have enabled contrib and non-free repositories in /etc/apt/sources.list.d/debian.sources

Types: deb deb-src
URIs: mirror+file:///etc/apt/mirrors/debian.list
Suites: bookworm bookworm-updates bookworm-backports
Components: main contrib non-free non-free-firmware

Types: deb deb-src
URIs: mirror+file:///etc/apt/mirrors/debian-security.list
Suites: bookworm-security
Components: main contrib non-free non-free-firmware

Step 2 - Update the operating system

apt-get update
apt-get dist-upgrade

Step 3 - Back up the database

Warning

Make sure that there is sufficient free hard disk space before you attempt to create a backup!

mysqldump --defaults-extra-file=/opt/openitc/etc/mysql/dump.cnf --databases openitcockpit --flush-privileges --triggers --routines --no-tablespaces --events --hex-blob \
  --ignore-table=openitcockpit.nagios_externalcommands \
  --ignore-table=openitcockpit.nagios_hostchecks \
  --ignore-table=openitcockpit.nagios_logentries \
  --ignore-table=openitcockpit.nagios_servicechecks \
  --ignore-table=openitcockpit.nagios_systemcommands \
  --ignore-table=openitcockpit.nagios_timedeventqueue \
  --ignore-table=openitcockpit.nagios_timedevents \
  --ignore-table=openitcockpit.statusengine_dbversion \
  --ignore-table=openitcockpit.statusengine_host_acknowledgements \
  --ignore-table=openitcockpit.statusengine_host_downtimehistory \
  --ignore-table=openitcockpit.statusengine_host_notifications \
  --ignore-table=openitcockpit.statusengine_host_notifications_log \
  --ignore-table=openitcockpit.statusengine_host_scheduleddowntimes \
  --ignore-table=openitcockpit.statusengine_host_statehistory \
  --ignore-table=openitcockpit.statusengine_hostchecks \
  --ignore-table=openitcockpit.statusengine_hoststatus \
  --ignore-table=openitcockpit.statusengine_logentries \
  --ignore-table=openitcockpit.statusengine_nodes \
  --ignore-table=openitcockpit.statusengine_perfdata \
  --ignore-table=openitcockpit.statusengine_service_acknowledgements \
  --ignore-table=openitcockpit.statusengine_service_downtimehistory \
  --ignore-table=openitcockpit.statusengine_service_notifications \
  --ignore-table=openitcockpit.statusengine_service_notifications_log \
  --ignore-table=openitcockpit.statusengine_service_scheduleddowntimes \
  --ignore-table=openitcockpit.statusengine_service_statehistory \
  --ignore-table=openitcockpit.statusengine_servicechecks \
  --ignore-table=openitcockpit.statusengine_servicestatus \
  --ignore-table=openitcockpit.statusengine_tasks \
  --ignore-table=openitcockpit.statusengine_users \
  --ignore-table=openitcockpit.customalerts \
  --ignore-table=openitcockpit.customalert_statehistory \
  --ignore-table=openitcockpit.sla_availability_status_hosts_log \
  --ignore-table=openitcockpit.sla_availability_status_services_log \
  --ignore-table=openitcockpit.sla_host_outages \
  --ignore-table=openitcockpit.sla_service_outages \
  >/root/openitcockpit_dump_v4_upgrade.sql

Step 4 - Carry out the openITCOCKPIT 5 compatibility check

To ensure that your system is capable of being updated to openITCOCKPIT 5.x, we provide a compatibility script for checking your system(s).

Execute the following script on your openITCOCKPIT instance:

curl -s https://raw.githubusercontent.com/it-novum/openITCOCKPIT/development/bin/scripts/oitc4to5.sh | sudo /bin/bash

oitc4to5 successful compatibility check

No changes have been made to your system at this point!

Danger

Do not continue with the update if you receive any errors or warnings after carrying out the compatibility check!

First resolve the issues that have been highlighted and run the script again. Once you have resolved all errors, you can continue with the update.

Breaking Changes

While we tried to keep the openITCOCKPIT 5 as compatible as possible, a large update like this comes with some breaking changes.

Danger

During the update, all stored filters will be deleted.

We recommend to export the MySQL table openitcockpit.filter_bookmarks before the update, so you can use the information to recreate the filters after the update.

Truncate of current stored filters

Upgrade openITCOCKPIT

Your system is now prepared and ready to upgrade to openITCOCKPIT 5.

Step 1 – Sign out from openITCOCKPIT

openITCOCKPIT 5 ships with an entirely new frontend. For a soothe upgrade experience, it is recommended to sign out from from openITCOCKPIT first.

You can find the sign out button in the top right corner.

Sign out from openITCOCKPIT

Step 2 - Change Repository

openITCOCKPIT 5 uses a different repository address than openITCOCKPIT 4 does. This is to prevent unexpected system upgrades.

The new address ist: packages5.openitcockpit.io.

Warning

Currently openITCOCKPIT 5 is in beta. Please do not use this repository for production systems. The repository is automatically configured to use the nightly branch.

Ubuntu users
curl https://packages5.openitcockpit.io/repokey.txt | tee /etc/apt/keyrings/openitcockpit-keyring.asc
echo "deb [signed-by=/etc/apt/keyrings/openitcockpit-keyring.asc] https://packages5.openitcockpit.io/openitcockpit/$(lsb_release -sc)/nightly $(lsb_release -sc) main" > /etc/apt/sources.list.d/openitcockpit.list

apt-get update
Debian users
curl https://packages5.openitcockpit.io/repokey.txt | tee /etc/apt/keyrings/openitcockpit-keyring.asc
echo "deb [signed-by=/etc/apt/keyrings/openitcockpit-keyring.asc] https://packages5.openitcockpit.io/openitcockpit/$(lsb_release -sc)/nightly $(lsb_release -sc) main" > /etc/apt/sources.list.d/openitcockpit.list

apt-get update
RHEL8 users

Warning

Make sure to add your openITCOCKPIT license key to the end of the repository configuration file:

username=secret
password=e5aef99e-817b-0ff5-3f0e-140c1f342792

cat <<EOT > /etc/yum.repos.d/openitcockpit.repo
[openitcockpit]
name=openITCOCKPIT Monitoring System
baseurl=https://packages5.openitcockpit.io/openitcockpit/RHEL8/nightly/\$basearch/
enabled=1
gpgcheck=1
gpgkey=https://packages5.openitcockpit.io/repokey.txt
EOT

dnf --refresh check-update
RHEL9 users

Warning

Make sure to add your openITCOCKPIT license key to the end of the repository configuration file:

username=secret
password=e5aef99e-817b-0ff5-3f0e-140c1f342792

cat <<EOT > /etc/yum.repos.d/openitcockpit.repo
[openitcockpit]
name=openITCOCKPIT Monitoring System
baseurl=https://packages5.openitcockpit.io/openitcockpit/RHEL8/nightly/\$basearch/
enabled=1
gpgcheck=1
gpgkey=https://packages5.openitcockpit.io/repokey.txt
EOT

dnf --refresh check-update

Step 3 - Migrate license

Users of the openITCOCKPIT Community Edition and Enterprise Edition can continue to use their existing license key. It is important to change the repository address to packages5.openitcockpit.io in the file /etc/apt/auth.conf.d/openitcockpit.conf before you continue with the update.

The file should look like this:

machine packages5.openitcockpit.io login secret password e5aef99e-817b-0ff5-3f0e-140c1f342792

To apply the changes, run the following command:

apt-get update

Step 4 - Updating openITCOCKPIT

Warning

Stable SSH connection is required! The update process may take a while. To prevent SSH connection problems, we recommend using tmux or screen.

During the update you may be asked if you want to overwrite some configuration files with newer versions. These configuration files belong to the operating system, so you can choose whether you want to keep your current versions or update to the newer versions. This will have no impact on the openITCOCKPIT update.

To start the update, execute:

apt-get dist-upgrade

Step 5 - Clear browser cache

Before logging into your new openITCOCKPIT interface, you should clear your browser cache

Mozilla Firefox: https://support.mozilla.org/en-US/kb/how-clear-firefox-cache

Google Chrome: https://support.google.com/accounts/answer/32050?co=GENIE.Platform%3DDesktop&hl=en

Step 6 - Reboot the system

A system restart is recommended, but not required.

The update to openITCOCKPIT 5 is now completed 🎉.

Updating the openITCOCKPIT satellite systems (only applies to distributed monitoring)

The Update process for openITCOCKPIT Satellite Systems is straight forward. openITCOCKPIT 5 can also communicate with openITCOCKPIT 4 satellites. While an upgrade is recommended, it is not required (at least for now)

Step 1 - Update the operating system

apt-get update
apt-get dist-upgrade

Step 2 - Change Repository

openITCOCKPIT 5 uses a different repository address than openITCOCKPIT 4 does. This is to prevent unexpected system upgrades.

The new address ist: packages5.openitcockpit.io.

Step 3 - Carry out the openITCOCKPIT Satellite 5 compatibility check

To ensure that your system is capable of being updated to openITCOCKPIT 5.x, we provide a compatibility script for checking your system(s).

Execute the following script on your openITCOCKPIT Satellite instance:

curl -s https://raw.githubusercontent.com/it-novum/openITCOCKPIT/refs/heads/development/bin/scripts/oitcSat4to5.sh | sudo /bin/bash

Step 4 - Updating openITCOCKPIT Satellite

apt-get update
apt-get dist-upgrade

Known problems

PHP 8.0 on RHEL

openITCOCKPIT requires PHP in version 8.1 or newer. Some Enterprise Linux installations still use PHP 8.0, in this case you need to upgrade your PHP version first.

Due to the amount of support complexity with Enterprise Linux systems, only the openITCOCKPIT Enterprise Edition is avaiable for Red Hat Enterprise Linux and RHEL based distributions such as: CentOS, Rocky Linux AlmaLinux or Oracle Linux.

Please get in touch with us if you need assistants upgrading your installation of openITCOCKPIT.

Before you start, make sure you have installed the latest updates for your system:

dnf --refresh check-update

dnf update

This document assumes that you have installed PHP from Remi's RPM repository.

To upgrade your PHP version, please run the following command:

dnf module switch-to php:remi-8.1

This will switch your system to the latest version of PHP 8.1. You can also go with PHP 8.2 or 8.3.

To finish the upgrade, please run the following command:

openitcockpit-update

Grafana

The Grafana version shipped with openITCOCKPIT 5 will now use MySQL as database backend. This improves the API performance of Grafana by a lot. This change only affects traditional installations of openITCOCKPIT. Docker installations of openITCOCKPIT will continue to use SQLite as database backend for Grafana. How ever, it is possible to switch the database backend of Grafana in Docker installations as well if preferred.

This change requires to re-syncronize Grafana User Dashboards. You can do this by selecting all Grafana Dashboards and clicking on the Synchronize button at the bottom of the page.

Synchronize Grafana User Dashboards

openITCOCKPIT will re-create all automatically generated Grafana dashboards automatically. It is also possible to force the re-creation of all Grafana dashboards by running the following command:

openitcockpit-update --cc
oitc cronjobs -f

Troubleshooting

Network error

If you find you are having connectivity errors with your system, you can try to repair the installation. To do this, use the following command:

apt-get install -f

If your openITCOCKPIT version is < 4.8.7

For the update process to complete successfully, you must be using at least version 4.8.7 of openITCOCKPIT.

What if I use Ubuntu Bionic, Debian Buster or openITCOCKPIT 3?

Please get in touch with us.