Debian upgrade tutorial

Debian is a very robust Linux distribution that is very popular in the world of web servers. Its package management system (dpkg/apt) is one of the best and makes upgrading from one major release to the following one a straightforward operation.

This tutorial describes how to perform a major release upgrade of a Debian system. It covers the upgrade from the previous major release Debian 9 (Stretch) to the current major release Debian 10 (Buster), but the steps are similar for the other ones.

Note:
It is strongly recommended to upgrade a Debian system only from a major release to the following one. To upgrade for example from Debian 8 to Debian 10, an upgrade to Debian 9 should be performed first.
Most of the Shell commands described require root privileges.

Preparations

Before starting the upgrade process, there are some preparations to perform on the currently installed system.

System and data backup

Even if the upgrade tools are quite reliable, it is strongly recommended to backup the whole system or at least the important data or configuration information. A hardware failure in the middle of an upgrade for example may render the system in an unusable state.

For virtual machines, taking a VM snapshot is recommended to make sure that the full system is recoverable.

The backup of data and configuration files to a remote system via ssh may be performed using the scp or rsync commands.

Example: backup/restore using scp

The scp command allows copying files and directories (recursively) from one machine to another over ssh. It allows preserving the file owners and access permissions (It should be called using the root user).

To backup a local directory to a remote machine:

scp -rp /path/local_directory/ root@remote_machine:/path/remote_directory/

To restore a directory from a remote machine:

scp -rp root@remote_machine:/path/remote_directory/ /path/local_directory/

Example: backup/restore using rsync

Like scp, the rsync command allows copying files and directories over ssh from one machine to another. Also, it allows preserving file owners and access permissions. In addition to using ssh, it offers the possibility of using the rsync protocol, but the remote server must be configured to allow that.

To backup a local directory to a remote machine over ssh:

rsync -avz /path/local_directory/ root@remote_machine:/path/remote_directory/

To restore a directory from a remote machine over ssh:

rsync -avz root@remote_machine:/path/remote_directory/ /path/local_directory/

Removing unused packages

The Debian package manager has the concept of auto-packages. These are the packages that are automatically installed to satisfy dependencies.
After some time and as packages get updated and removed, some of the auto-packages become obsolete because of a dependency change or when the packages needing them are removed.

Before upgrading a Debian system, it is recommended to remove these obsolete packages because there is no purpose from upgrading unused packages.

To remove these packages, the following command may be used:

apt autoremove

Checking for on-hold packages

The Debian package manager also has the concept of on-hold packages. When a package is marked on-hold, it is marked to be excluded from update operations. This is generally used by system administrators to keep certain packages at a particular version.

Because the upgrade operation needs to upgrade all of the system packages to satisfy dependencies, the packages that are marked on-hold should be released first.

The following command shows the list of packages that are marked on-hold:

apt-mark showhold

To release a package, the following command may be used:

apt-mark unhold package_name

Disabling APT pinning

The Debian package manager also has the concept of pinning. This is used to give a higher priority to a repository over another or to prevent certain packages or package versions from being installed. APT pinning is configured in the file /etc/apt/preferences or the files stored in the directory /etc/apt/preferences.d/.

It is recommended to disable APT pinning before starting the upgrade process by removing (or just moving) these files.

Fixing broken packages

Sometimes, some of the system packages are not installed correctly and need to be fixed. Before starting the upgrade operation, it is recommended to fix any such packages.

The following command performs a database audit and lists packages that are installed only partially and suggests what to do with them:

dpkg --audit

Disk space

Because the upgrade operation will first download all the new packages that will be installed, the system should have sufficient disk space. The new packages are downloaded to the cache directory /var/cache/apt/archives/.

The following command shows the disk usage of the partition that holds the cache directory:

df -h /var/cache/apt/archives/
Filesystem      Size  Used Avail Use% Mounted on
/dev/vda1        25G  2.5G   22G  11% /

Updating the system to the latest available minor release

The currently installed Debian release details may be shown using the lsb_release command:

lsb_release -a
Distributor ID: Debian
Description:    Debian GNU/Linux 9.3 (stretch)
Release:        9.3
Codename:       stretch

Before starting the major upgrade operation, it is recommended to update the system to the latest available minor release as this will include the latest bug fixes that may avoid potential errors in the upgrade process. For example updating from Debian 9.3 to 9.12 (the latest available update as of this writing).

Without change to the repositories, the update operation may be performed using the following commands:

apt clean
apt update
apt upgrade
apt full-upgrade
reboot

After the update, the lsb_release command will show the the latest minor release details:

lsb_release -a
Distributor ID: Debian
Description:    Debian GNU/Linux 9.12 (stretch)
Release:        9.12
Codename:       stretch

Starting the upgrade

After performing the preparations and updating the system to the latest minor release, the upgrade operation may be initiated.

The new repositories

The file /etc/apt/sources.list contains the Debian repositories related to the currently installed major release (Debian 9 stretch). After backuping the file, it should be changed to point to the repositories of the target release (Debian 10 buster).

The original content of the file /etc/apt/sources.list may be similar to the following (different from server to server):

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

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

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

To backup the file and replace the word stretch by buster, the following commands may be used:

cp /etc/apt/sources.list /etc/apt/sources.list_backup
sed -i s/stretch/buster/

After the change, the content of the file should be like the following:

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

deb http://deb.debian.org/debian-security/ buster/updates main
deb-src http://deb.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

Upgrading the system

After changing the repositories to point to the target release, the upgrade operation may be performed using the following commands:

apt clean
apt update
apt upgrade
apt full-upgrade
reboot

After the upgrade operation is finished, the lsb_release command will show details about the newly installed major release:

lsb_release -a
Distributor ID: Debian
Description:    Debian GNU/Linux 10.3 (buster)
Release:        10.3
Codename:       buster

References

Debian 10 buster release notes: https://www.debian.org/releases/buster/amd64/release-notes/index.en.html

Debian 10 buster upgrade reference: https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.html