Upgrading Debian 11 to Debian 12 (bookworm)

Upgrading Debian 11 to Debian 12 is usually not complicated if you already have a clean, fully mastered Debian 11 installation. In this note (which I use myself) we go through the main migration steps.

Some services may not restart

Some services may fail to restart because their configuration has changed or has become incompatible, and will need a small fix.

So plan it for a quiet moment.

Every command is run as root, through the server's KVM console or over SSH. No pointless sudo, become root.

1. What's new in Debian 12 that matters for a VPS?

Here is the list of important packages for a VPS that will be upgraded if installed:

Package	Debian 11	Debian 12
Apache	2.4.54	2.4.57
Dovecot	2.3.13	2.3.19
Exim	4.94	4.96
GnuPG	2.2.27	2.2.40
libc	2.31	2.36
Linux	5.10	6.1
MariaDB	10.5	10.11
Nginx	1.18	1.22
OpenLDAP	2.4.57	2.5.13
OpenSSH	8.4p1	9.2p1
Perl	5.32	5.36
PHP	7.4	8.2
Postfix	3.5	3.7
PostgreSQL	13	15
Python 3	3.9.2	3.11.2
systemd	247	252

1.2/ Replacement of the NTP package with NTPsec

NTP is a protocol used to keep the server's clock in sync.

If you already have the ntp package, it will be replaced by ntpsec, a security-hardened derivative of the ntp package.

If you have no ntp daemon or equivalent, the systemd-timesyncd package will be installed.

1.3/ Replacement of Puppet 5 with Puppet 7

Warning: do not upgrade servers running a Puppet agent older than version 7 before upgrading the server that hosts the puppetmaster.

Always upgrade the puppetmaster before all other servers.

1.4/ Replacement (not enforced) of rsyslog with systemd-journald

This is the unpleasant part for old-timers.

It's a good time to consider dropping rsyslog in favour of systemd-journald and its binary journals, which many of the tools you probably use can't read.

After migrating to Debian 12, you can remove rsyslog with these commands:

bash

apt-mark auto rsyslog
apt autoremove

To read the binary journals, instead of using tail (a small tear in the eye), you'll need:

bash

journalctl -ef

If you keep rsyslog anyway (at least for a while), all logs will still be written by default to a single file, /var/log/syslog (the alternative files can be removed).

1.5/ Python3: change for installing external packages

By default, it is no longer allowed to install Python packages that are not packaged by Debian.

It is possible to bypass this restriction, but it is not advised.

External packages must now be installed in isolated Python environments, using pipx or a virtual environment (python -m venv).

2. How to upgrade Debian 11 to 12?

Before upgrading, your server must be backed up off site, in another datacenter. And I also advise keeping a copy with an independent host and a copy at home.

An upgrade can go wrong, destroy data, or leave the server unbootable: databases must be dumped to SQL before any file backup, and take a snapshot as well if it's a virtual machine. Set aside time to repair in case of trouble, and be able to reboot in rescue mode.

WARNING: PHP 7.4 will be replaced by PHP 8.2 !!!

If your site (WordPress, Dolibarr…) or your scripts depend on extensions or syntax specific to PHP 7.4, test before migrating to production.

Your server is normally already up to date, since you are conscientious. If not, it absolutely has to be before you start:

bash

apt update
apt upgrade
reboot # if needed

2.1/ Update the source-list files

A new repository section appears. On a server, in theory it won't be needed, but it's possible to include it: non-free-firmware.

In /etc/apt/sources.list or /etc/apt/sources.list.d/*, replace bullseye with bookworm:

deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb http://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
deb http://security.debian.org bookworm-security main contrib non-free non-free-firmware

IMPORTANT: the name to use is deb.debian.org, which automatically points to the nearest mirror.

Or move into the directory and replace bullseye with bookworm in a single command:

bash

sed -i 's/bullseye/bookworm/g' *.list

2.2/ Update the list of available packages

bash

apt update

2.3/ Minimal upgrade

This step upgrades the system packages that neither add new dependencies on new packages nor remove any:

bash

apt -o Apt::Get::Assume-Yes=true -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" upgrade --without-new-pkgs

2.4/ Check disk space before the full upgrade

I advise cleaning up disk space and checking available space before the full upgrade:

bash

apt clean
apt --purge autoremove
apt -o APT::Get::Trivial-Only=true full-upgrade

[ ... ]
XXX upgraded, XXX newly installed, XXX to remove and XXX not upgraded.
Need to get xx.xMB of archives.
After this operation, AAAMB of additional disk space will be used.

If there is not enough room, this message appears:

E: You don't have enough free space in /var/cache/apt/archives/.

2.5/ Final upgrade

bash

apt -o Apt::Get::Assume-Yes=true -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" full-upgrade
apt --purge autoremove

If all went well:

bash

reboot

If anything went wrong, analyse the situation before rebooting. If you'd rather not handle this yourself, ask for a quote.

See also

• Reboot an OVH VPS in rescue mode.
• Upgrading Debian 12 to Debian 13 (trixie).
• Debian 12 release notes, "Upgrades" chapter: the official reference.