.. _upgrading_debian_on_a_node:

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

.. code::

    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:

.. code::

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

.. code::

    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:

.. code::

    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.

.. code::

    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:

.. code::

    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:

.. code::

    rm /etc/apt/preferences.d/bonding
