AI-assisted content notice: This documentation was created with support from artificial intelligence and has been reviewed by humans for accuracy.

Update Debian Bookworm (12) to Debian Trixie (13)¶

Backup

Before you begin, make sure you have created a working backup of your system! On virtual machines, create a snapshot as well, so the complete upgrade can be rolled back.

Run all commands as the root user.

To always use the latest version of openITCOCKPIT, it is important to keep the underlying operating system up to date.
With this guide, you can upgrade your Debian Bookworm system to Debian Trixie.

openITCOCKPIT version

The upgrade installs the latest openITCOCKPIT version that is available for Debian Trixie. It is not possible to keep the previous openITCOCKPIT version during the operating system upgrade.

Duration and availability

Expect 15 to 60 minutes, depending on the number of packages and the performance of the system. From the moment PHP-FPM is stopped, the openITCOCKPIT web interface is not available until the configuration has been rewritten at the end of this guide.

Requirements¶

openITCOCKPIT version 5.x
No packages containing lxd
Internet access to download Docker repository keys
At least 5 GB free disk space on / - about 2 GB of packages are downloaded during the upgrade

Check the free disk space before you start:

df -h /

Remove all `lxd` packages¶

If lxd packages are installed on your system, they must be removed first. You can check with:

apt list --installed | grep lxd

If packages are installed, remove them with:

apt -y remove lxd*

Add Docker repository¶

openITCOCKPIT requires Docker - the graphing backend with Graphite and Grafana runs in containers. The repository is added so that Docker is installed from the official sources in a version that is supported by openITCOCKPIT:

# Create keyring directory
install -d -m 0755 /etc/apt/keyrings

# Store Docker GPG key
curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc

# Add repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
| tee /etc/apt/sources.list.d/docker.list > /dev/null

Install all updates (still on Bookworm)¶

Before starting the upgrade to Debian Trixie, make sure all available updates are installed:

apt update
apt -y full-upgrade

Stop PHP-FPM¶

Before the upgrade, PHP-FPM 8.2 should be stopped to avoid conflicts:

systemctl stop php8.2-fpm.service

If you are running a different PHP version, stop the corresponding phpX.Y-fpm.service instead.

Remove legacy systemd units¶

openITCOCKPIT 5.9 replaces Statusengine 3 by Statusengine 4. The cleanup service now starts /opt/openitc/statusengine4/worker/bin/db_cleanup, older installations used /opt/openitc/statusengine3/worker/bin/Console.php.

Units below /etc/systemd/system take precedence over the units shipped in /usr/lib/systemd/system. A leftover unit from Statusengine 3 shadows the new unit and the service fails with status=203/EXEC.

Check which unit is currently used:

systemctl cat statusengine_cleanup.service statusengine_cleanup.timer
ls -l /etc/systemd/system/statusengine_cleanup.*

If a unit below /etc/systemd/system exists, disable it, move it out of the way and enable it again:

systemctl disable statusengine_cleanup.timer
mkdir -p /root/backup_units
mv /etc/systemd/system/statusengine_cleanup.* /root/backup_units/
systemctl daemon-reload
systemctl enable --now statusengine_cleanup.timer

After this step both units must be loaded from /usr/lib/systemd/system.

Identify openITCOCKPIT packages¶

Next, gather all installed openITCOCKPIT packages and store them in a variable:

openitcockpit_upd=$(apt-mark showmanual | grep openitcockpit | grep -v '^openitcockpit-statusengine3-worker$' | xargs echo)" "$(apt-mark showauto | grep openitcockpit | grep -v '^openitcockpit-statusengine3-worker$' | xargs echo)

Do not pin openitcockpit-statusengine3-worker

Since openITCOCKPIT 5.9 the package openitcockpit-statusengine3-worker is replaced by openitcockpit-statusengine4-worker. If the old package is requested explicitly, apt aborts with openitcockpit-statusengine4-worker : Conflicts: openitcockpit-statusengine3-worker.

Update package sources¶

The Debian package sources now need to be adjusted to the new Trixie release:

for f in /etc/apt/sources.list /etc/apt/sources.list.d/*.list /etc/apt/sources.list.d/*.sources; do
    [ -f "$f" ] && sed -i 's/bookworm/trixie/g' "$f"
done

This also updates /etc/apt/sources.list.d/debian.sources and the openITCOCKPIT repository in /etc/apt/sources.list.d/openitcockpit.sources - both use the deb822 format.

Verify that no Bookworm source is left:

grep -rn bookworm /etc/apt/sources.list /etc/apt/sources.list.d/ 2>/dev/null

The grep command must not return any line.

Perform the upgrade¶

Now start the actual upgrade:

apt update

# Simulation (check only) - must not report unmet dependencies
apt -s full-upgrade $openitcockpit_upd

# Perform the upgrade
apt -y -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" full-upgrade $openitcockpit_upd

The Dpkg::Options keep existing configuration files without asking. Configuration files that are managed by openITCOCKPIT are rewritten by the update script in the last step.

If the upgrade fails, continue with:

dpkg --configure -a

Remove unnecessary packages¶

apt -y autoremove

Start PHP after the upgrade¶

systemctl restart php8.4-fpm.service

Update configuration¶

As the last step, update and regenerate all configuration files if needed.

openITCOCKPIT Master¶

If you are performing the update on an openITCOCKPIT Master system, use the following command:

openitcockpit-update --cc

openITCOCKPIT Satellite¶

On an openITCOCKPIT Satellite, use the following command:

/opt/openitc/frontend/UPDATE.sh

Reboot¶

A restart of the system is required to activate the new kernel:

reboot

Verification¶

After the reboot, check that the upgrade was completed successfully:

grep PRETTY_NAME /etc/os-release
systemctl --failed
systemctl status php8.4-fpm.service
systemctl status statusengine_cleanup.timer

systemctl --failed must not list any unit, and the cleanup timer must be loaded from /usr/lib/systemd/system/statusengine_cleanup.timer.