.. _upgrading_opensuse_on_a_node:

=================================
Upgrading openSUSE Leap on a Node
=================================

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

.. 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 installed, it can be installed with
    ``zypper 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::

    systemctl stop salt-minion
    zypper refresh
    zypper update

Configuring the system for the upgrade
------------------------------------

.. note::

    If you are upgrading from Leap 15.4, you must import the new 4096 bit RSA signing keys. 
    This was introduced as part of openSUSE Leap 15.5 and backported to 15.4 via a maintenance update.
    Users of other versions can skip this step.

Import the new 4096 bit RSA signing keys (required for Leap 15.4 users):

.. code::

    rpm --import https://download.opensuse.org/repositories/openSUSE:/Tools/openSUSE_15.4/repodata/repomd.xml.key
    rpm --import https://download.opensuse.org/distribution/leap/15.5/repo/oss/gpg-pubkey-3dbdc284-53674dd4.asc

Replace your current version (15.5 in this example) with the version variable if not already present:

.. code::

    sed -i 's/15.5/${releasever}/g' /etc/zypp/repos.d/*.repo

Refresh the repos using your target version (replace 15.6 with your target version):

.. code::

    zypper --releasever=15.6 refresh

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
    ``zypper dup`` completes because bonding may fail to function properly if
    any changes are made while the previous distribution is still running.

Run the following command (replace 15.6 with your target version):

.. code::

    zypper --releasever=15.6 dup --allow-vendor-change

Alternatively, to download and install packages in heaps (replace 15.6 with your target version):

.. code::

    zypper --releasever=15.6 dup --download-in-heaps --allow-vendor-change

Finally, run the bonding setup and reboot:

.. code::

    bonding-setup
    systemctl reboot --ignore-inhibitors

