Upgrading Debian on a Node

This document describes a process for upgrading a bonder, aggregator or private WAN router between Debian versions in a reliable manner.

Warning

Bonding does not support 32 bit in Debian 9 or later. Only 64 bit versions should be upgraded, otherwise your node will be in an untested and unsupported state that is likely to fail.

Warning

Due to various changes in packages related to mobile broadband adapters, a modem that was working as a mobile broadband leg in Debian 8 may not work or may require different configuration to function correctly on Debian 10.

To minimize the risk when upgrading a Debian 8 bonder which utilizes a mobile broabdband leg, you should have tested that any modems installed will work when running on Debian 10, with the same firmware revisions.

Note

Distribution upgrades carry more risk than your typical package updates performed with apt-get upgrade as they change every installed package. This extra burst of activity could cause a disk near the end of its life to fail, or it could break any custom integrations managed outside of configuration on the management server.

Note

This document assumes all configuration for the node is performed on the management server and there are no custom packages or integrations manually configured. If that is not the case the steps may work as intended but the update process may ask additional questions not covered by this document.

You should confirm any externally managed applications still function after the distribution upgrade

Note

These steps should be performed in a tmux session to avoid interruptions in case of a network outage but it is not strictly required. Simply run tmux to enter a shell that can be resumed with tmux a if you lose connection to the server.

If tmux is not intalled, it can be installed with apt-get install tmux

Before the distribution upgrade

Warning

The following step involving interface names is required when upgrading from Debian 8. Users upgrading from other Debian versions can skip this step.

If upgrading from Debian 8, ensure that net.ifnames=0 is in the grub linux command line. This is required to prevent interface names from being changed to the predictable interface name scheme introduced after Debian 8:

cat /etc/default/grub | grep GRUB_CMDLINE_LINUX= | grep -qv net.ifnames=0 && sed -i 's/GRUB_CMDLINE_LINUX="/GRUB_CMDLINE_LINUX="net.ifnames=0 /' /etc/default/grub
update-grub

Ensure that the system and bonding packages are on the latest versions. You should set the bonding version to the latest version available on the Administration / Software Repository page on the management server and then run:

apt-get update
apt-get install bonding
apt-get upgrade

Configuring the system for the upgrade

Warning

It is highly recommended to only upgrade by one release at a time. Debian does not officially support skipping releases during an upgrade. Sometimes skipping an upgrade will work shortly after the release but may fail with later updates. In particular, upgrading Debian 10 directly to 12 is known to fail and must be upgraded to 11 before upgrading to 12.

Update the apt sources for your target Debian version. Replace TARGET_VERSION with one of: 'buster' (10), 'bullseye' (11), or 'bookworm' (12):

systemctl stop salt-minion
TARGET_VERSION='bookworm'
wget https://$(sed -n 's/^server[[:space:]]*=[[:space:]]*//p' /etc/bonding/bonding.conf)/sources/$TARGET_VERSION -O /etc/apt/sources.list
sed -i "s|debian/[[:space:]]*[a-z]\+[[:space:]]main|debian/ $TARGET_VERSION main|" /etc/apt/sources.list.d/bonding.list

Warning

The following step involving Quagga is required when upgrading from Debian 10. Users upgrading from other Debian versions can skip this step.

If upgrading from Debian 10, you must specify a pin priority in apt preferences in order to remove Quagga during the distribution upgrade (Quagga is not supported in Bonding on Debian versions greater than 10). This can be achieved by running the following command:

cat <<EOF >> /etc/apt/preferences.d/bonding
Package: quagga*
Pin: release a=now
Pin-Priority: -10
EOF

Failure to do so will result in Bonding being removed during the upgrade. Once the upgrade has been completed, be sure to remove this file (see below).

Performing the upgrade

This process can take some time to run to completion, and largely depends on the internet connection speed and the speed of the disk. It should not be interrupted once started.

Note

It is important to reboot the device as shortly as possible after this dist-upgrade completes because bonding may fail to function properly if any changes are made while the previous distribution is still running.

Note

During the upgrade, you may be prompted about these modified configuration files: /etc/systemd/journald.conf, /etc/ssh/sshd_config. In both cases, select the option to install the package maintainer’s version.

apt-get update
apt-get install debian-keyring debian-archive-keyring
apt-get dist-upgrade
systemctl reboot --ignore-inhibitors

Post-upgrade cleanup

There may be some unused packages previously installed that can now be removed. To automatically remove them:

apt-get autoremove

If an upgrade was just completed from Debian 10, be sure to remove the apt preferences file that was created during the configuration step:

rm /etc/apt/preferences.d/bonding