6. Upgrading Debian to the newest version

by Double Bastion - Updated January 27, 2022

If you already have Debian 11 installed on your server, please go to the next chapter.

Follow the steps from below to upgrade Debian 10 (Buster) to Debian 11 (Bullseye) if you either need to run the upgrade as part of your server’s maintenance, or if you have just rented a server with Debian 10 already installed, and the hosting company doesn’t offer servers with Debian 11 preinstalled.

First read the official upgrade documentation and take note, if what is described there is applicable to your situation.

As an additional precaution, open the default ssh port 22 in the firewall with UFW:

ufw allow 22

It’s important that you make sure you have a second way of accessing your server besides SSH, in case you loose SSH access to the server due to unexpected network issues that can happen during upgrade. Some hosting providers offer a web console that allows accessing the server without SSH, while other hosting companies offer a rescue mode boot up which you can use to log in to a different functional server and from there you can mount the hard drive of your disfunctional server, so that you can edit any files; then you can restart the server to apply the new changes.

6.1. Back up all the important data

Make a backup copy of all the important data stored on the server. For example, you should create compressed archives of the following directories: /var/www , /etc , /var/vmail , /var/lib/mysql , /var/lib/dpkg , /srv/scripts , /var/lib/asterisk , /var/spool/asterisk. It’s also recommended to make a backup copy of the /var/lib/apt/extended_states file and to save the output of the dpkg --get-selections "*" command. Also, you will want to make backup copies of all the SQL databases of your websites and applications.

Save all the backups in a safe location, like on an external hard drive that only you can access, adding the date of the backup to the name of the folder in which you store them.

6.2. Check the sources.list file

We will install all available Buster updates before upgrading to Bullseye. On some systems, the package source is defined as “stable” in the sources.list file instead of “buster” or “bullseye”. To avoid an accidential early upgrade to Bullseye, please check the sources.list and ensure that it contains “buster” and not “stable” as source:

Open the /etc/apt/sources.list file:

nano /etc/apt/sources.list

The content should be similar to this:

deb http://deb.debian.org/debian buster main
deb-src http://deb.debian.org/debian buster main                 

deb http://security.debian.org/debian-security buster/updates main
deb-src http://security.debian.org/debian-security buster/updates main

deb http://deb.debian.org/debian buster-updates main  
deb-src http://deb.debian.org/debian buster-updates main

Next, upgrade all Buster packages to prepare the system for the final upgrade to Bullseye.

Update the sources database:

apt-get update

Perform the first upgrade:

apt-get upgrade

Then run:

apt-get dist-upgrade

6.3. Check the state of installed packages to ensure that no packages are ‘on hold’ or with any error status

This test is important. You have to check the state of the installed packages to ensure that no packages are ‘on hold’ or with a status of ‘Half-Installed’ or ‘Failed-Config’ or with any error status. Your system and the apt database must be in good standing before proceeding with the upgrade. If there are any ‘on hold’ or broken packages, you should fix these problems before the upgrade. In the case of an ‘on hold’ package, you can ‘unhold’ it with the apt-mark unhold package-name command, then upgrade it with apt-get install package-name, and then, after the operating system upgrade, you can mark it as ‘on hold’ again with apt-mark hold package-name, to exclude it from being upgraded automatically during routine bulk software upgrades.

Check if any packages are ‘on hold’ with:

dpkg --get-selections | grep hold

Check if there are any packages with a status of ‘Half-Installed’, ‘Failed-Config’ or any error status, by running:

dpkg --audit

If both commands don’t return any packages, you can proceed with the upgrade.

6.4. Update the /etc/apt/sources.list file for Bullseye

Edit the /etc/apt/sources.list file again:

nano /etc/apt/sources.list

Replace its content with the following lines:

deb http://deb.debian.org/debian bullseye main
deb-src http://deb.debian.org/debian bullseye main

deb http://deb.debian.org/debian-security/ bullseye-security main
deb-src http://deb.debian.org/debian-security/ bullseye-security main

deb http://deb.debian.org/debian bullseye-updates main
deb-src http://deb.debian.org/debian bullseye-updates main

Then run the following command to update the sources database:

apt-get update

6.5. Upgrade to Debian 11 (Bullseye) in two steps

It is recommended to do the upgrade in two steps, by first running “apt-get upgrade” to install the base packages, then running “apt full-upgrade” to do the actual distribution upgrade.

First run:

apt-get upgrade

Then perform the distribution upgrade by running:

apt full-upgrade

During the upgrade process you will be asked multiple times if you want to overwrite certain configuration files with the new versions, or to keep the current files. Each time, type N and press Enter to keep the current configuration file, since you don’t want to loose the settings contained in that file.

A reboot will be required to finish the upgrade and load the new kernel:


6.6. Check the upgrade

To check which Debian version is currently installed on the system, take a look at the /etc/os-release file:

cat /etc/os-release

The output should look like this:

PRETTY_NAME="Debian GNU/Linux 11 (bullseye)"
NAME="Debian GNU/Linux"
VERSION="11 (bullseye)"

Note: If, after upgrading Debian, Fail2ban gives an error when when you restart it, you will have to uninstall and then reinstall it. First copy the /etc/fail2ban/jail.local file and the /etc/fail2ban/filter.d directory to a safe location:

cp /etc/fail2ban/jail.local /root/Documents
cp -r /etc/fail2ban/filter.d /root/Documents

Then uninstall Fail2ban:

apt-get purge fail2ban

You also have to delete the entire Fail2ban directory before reinstalling:

rm -r /etc/fail2ban

Reinstall Fail2ban:

apt-get install fail2ban

Don’t forget to configure Fail2ban after installation, using the configuration file and the filter files directory that you have saved earlier, like this:

cp /root/Documents/jail.local /etc/fail2ban
cp -r /root/Documents/filter.d/* /etc/fail2ban/filter.d
systemctl restart fail2ban

After you make sure that you can log in using SSH on your custom SSH port, you can close port 22 in the firewall with UFW:

ufw delete allow 22

6.7. Install and configure the latest version of PHP

Debian 11 comes with a new version of PHP, namely PHP 7.4. During the operating system upgrade, some PHP 7.4 packages will be installed, but to fully install PHP 7.4 and use it instead of PHP 7.3, which was the default version in Debian 10, you will have to install all the PHP 7.4 packages specified in the Install PHP chapter, and then configure PHP as described there. So, follow all the steps described in the Install PHP chapter.

After you have installed and configured PHP 7.4, you can uninstall all the php7.3 packages with:

apt-get purge php7.3*
You can send your questions and comments to: