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.
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.
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:
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:
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:
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
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