.. _upgrading_from_debian_8_to_debian_10:

====================================
Upgrading from Debian 8 to Debian 10
====================================

This document describes a process for upgrading a bonder, aggregator or private
WAN router from Debian 8 to Debian 10 in a reliable manner.

.. warning::

   Bonding does not support 32 bit in Debian 9 or 10. Only the 64 bit version of
   Debian 8 should be upgraded in this way, 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
-------------------------------

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

to ensure everything is updated to the latest versions on Debian 8 before continuing.

Configuring the system for Debian 10
------------------------------------

First, ensure that ``net.ifnames=0`` is in the grub linux command line. The
following command should ensure the file is in the correct state. This is a
safeguard to prevent interface names from being changed to the predictable
interface name scheme preferred in newer Linux installs.

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

Update the apt sources to target buster intead of jessie

.. code::

    rm -f /etc/apt/sources.list.d/*
    wget https://$(grep '^server =' /etc/bonding/bonding.conf  | awk '{ print $3 }')/sources/buster -O /etc/apt/sources.list

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.

.. code::

    apt-get update
    apt-get install debian-keyring debian-archive-keyring
    apt-get update
    APT_LISTCHANGES_FRONTEND=none DEBIAN_FRONTEND=noninteractive apt-get dist-upgrade
    rm -rf /var/lib/salt/pki/
    mv /etc/salt/pki/ /var/lib/salt/pki/
    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
