Upgrade the Operating System

To stay on a current operating system, you may need to upgrade Debian to a newer major release over time. This page describes how to do that, both with the helper script that automates the whole process, and manually.

The procedure is the same for the main Tenantos server and for every remote agent. Each machine is upgraded on its own, one major release at a time.

Note: You can have mixed setups, e.g. some agents on Debian 11 and some on Debian 12 or 13. There is no need to keep the operating systems of the main server and the remote agents on the same Debian release.

A major OS upgrade can break the system.

Before you start, make sure you have a full, restorable backup or a snapshot of the server, and read the official Debian release notes for the release you are upgrading to.

Supported upgrade path

You should upgrade only one major release at a time and reboot in between. Skipping a release is not supported.

To get from Debian 11 to Debian 13, perform the full procedure twice: first to Debian 12, reboot, then to Debian 13.

The main server and the remote agents are upgraded independently and in any order. You can upgrade the agents before the main server, or the main server first.

The upcp-agent command used to run the updater on an agent was added in Tenantos v1.0.39. If it is not available on an agent yet, run the Tenantos updater (upcp) on your main server first to update all agents to v1.0.39, which makes upcp-agent available.

Helper script

The script comes with no warranties. Use at your own risk. Our support is not responsible for unsuccessful OS upgrades. Make backups before proceeding.

The helper script automates the recommended procedure. It detects the running Debian release and the next target, updates the current system, performs the release upgrade, runs the Tenantos updater, and tells you when a reboot is required.

The same script is used on the main server and on remote agents. It automatically detects whether it runs on a main server or on an agent and uses the correct updater (upcp or upcp-agent).

wget -O debianUpgrade.sh https://documentation.tenantos.com/attachments/tenantos/debianUpgrade.sh
chmod +x debianUpgrade.sh
./debianUpgrade.sh

By default the script shows a warning and asks you to type Yes to confirm that you have a backup before it continues. To run it unattended and skip this prompt, pass the -y (or --yes) flag:

./debianUpgrade.sh --yes

The script installs screen if it is not already present and runs the upgrade inside a screen session that you are attached to, so the upgrade keeps running if your SSH connection drops.

Notes:

If your connection drops during the upgrade, reconnect to the server and run screen -d -r tenantos-os-upgrade to return to it.
Run the script on each machine separately. Start with the main server, then upgrade each remote agent the same way.
Running the script on an agent requires upcp-agent (added in Tenantos v1.0.39). If it is not available yet, run upcp on your main server first to update all agents, as described under Supported upgrade path.

Manual procedure

If you prefer to perform the upgrade yourself, follow the steps below on the machine you are upgrading. Repeat the full cycle for each major release hop and reboot in between.

Run these steps inside a screen or tmux session, so a dropped SSH connection cannot interrupt a half-finished upgrade and leave the system in a broken state.

1. Upgrade Debian to the next release

Upgrade Debian to the next release the usual way, one major release at a time. The procedure is documented in the official Debian release notes, which you should follow for the release you are upgrading to:

2. Run the Tenantos updater

On the main server run upcp, on a remote agent run upcp-agent.

Running the updater re-checks and repairs every Tenantos service configuration on the new operating system, sets up the repositories Tenantos manages for the new release, and reinstalls or reconfigures anything the release upgrade changed. Run it before rebooting, so the system comes back up in a consistent state.

Important: Run the Tenantos updater on every major release hop, not only on the last one. If you upgrade from Debian 11 to Debian 13, run it for the upgrade to Debian 12, and again for the upgrade to Debian 13.

3. Reboot

Reboot the server so it boots into the new OS. If you are going further (for example Debian 12 to Debian 13), start the cycle again after the reboot.