=================
Upgrading a node
=================

Before upgrading a node, please read our recommendations for `managing a
successful environment upgrade <../../software-releases-and-upgrades/effective-upgrades.html>`__.

Automated bonder upgrades
--------------------------

.. note::

    Aggregators must be upgraded using the individual method below, the
    automated method works only for bonders.

Bonders can be upgraded in bulk through the management server command
line. This method runs upgrade and restart commands on each bonder in
sequence. It is not intended as a completely unattended process—you may
be prompted for input from time to time. It is strongly recommended that
you configure SSH public keys; if you depend on password authentication,
you will be prompted for the bonder root password for each bonder
upgraded. If you have SSH public keys configured, ensure you enable
"agent forwarding" in your SSH client to avoid the password prompts.

Only online bonders are upgraded. Bonders that are not online at the
time the upgrade is executed will need to be upgraded manually later, or
the bulk upgrade script will need to be run again.

To upgrade bonders in bulk, follow these steps:

#. SSH into the management server.
#. Run this command:
   ``upgrade-bonders``
#. Review the list of bonders to be upgraded. Confirm the upgrade by
   typing Y, then <enter>. Each bonder will be upgraded in turn. This
   process may take a long time. Bonders already at the latest software
   version are ignored.
#. During the upgrade, each bonder downloads a new copy of its cached
   configuration file. If this fails, the bonder will offer the prompt
   "Go back and retry?". We recommend you type 1 to not retry. The
   upgrade on that bonder will quit with a failure. You should log into
   that bonder, troubleshoot the network issue preventing the installer
   from downloading the config file, and manually upgrade the bonder.
#. When the script finishes, it shows the name of any bonders whose
   upgrade failed. Investigate why these bonders failed to upgrade, then
   upgrade them manually or run the bulk upgrade script again.

Targeting particular bonders
+++++++++++++++++++++++++++++

The upgrade can be limited to certain bonders by providing arguments to
the script.

Targeting by bond IDs
^^^^^^^^^^^^^^^^^^^^^^

To upgrade individual bonders, provide their bond IDs on the command
line. Multiple IDs can be set. For example,

::

    upgrade-bonders 2 3 5

would upgrade only bonds 2, 3, and 5. No other bonders would be
upgraded.

.. warning::

    The argument refers to the bond ID, not the bonder or node ID.

Targeting by range of bond IDs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To upgrade a set of bonders whose bond ID falls into a certain range,
provide a single argument on the command line in the form
``low-ID:high-ID``. For example,

::

    upgrade-bonders 2:19

would upgrade bonders whose bond ID was between 2 and 19, inclusive.

.. note::
    Use the range method to speed up the upgrade process by updating
    multiple bonders in parallel. Suppose you have 240 bonders to upgrade.
    Running a single bulk upgrade process would take a very long time.
    However, you could run five bulk upgrades, each in its own SSH session
    with a different range of bond IDs. For example:

    - ``upgrade-bonders 1:49``
    - ``upgrade-bonders 50:99``
    - ``upgrade-bonders 100:149``
    - ``upgrade-bonders 150:199``
    - ``upgrade-bonders 200:250``

    The upgrade would complete about five times faster than if you only used
    a single upgrade process. Take care to ensure that the ranges don't
    overlap.

.. warning::

    Only bonders are upgraded, not aggregators. Because there are very few
    aggregators in a partner's environment, and because aggregators are a
    critical part of the SD-WAN service, they should be upgraded
    and restarted manually.

Manual node upgrade
--------------------

Bonding now supports the following distributions:

  - openSUSE Leap 15.6
  - openSUSE Leap 15.5
  - openSUSE Leap 15.4
  - Debian 12 "Bookworm"
  - Debian 11 "Bullseye"
  - Debian 10 "Buster" (see warning below)

.. warning::

    Debian 10 ("Buster") reached end-of-life on June 30, 2024 and will be
    **deprecated** in SD-WAN 6.9. It is supported only to allow migration
    of nodes to newer versions of Debian.

Nodes can be upgraded from any software version to the latest version.
It is not expected (or even possible) to upgrade through each new
version in turn until the most recent version is installed.

.. note::

    When upgrading a node, a reboot may be required to load the system into a
    supported kernel as well as ensuring the correct kernel modules are loaded.

To upgrade Bonding on a single host, `start a console session on the
host <../accessing-a-node.html>`__. Then, follow the instructions below for
the respective distribution.

openSUSE Leap
+++++++++++++

::

    zypper install bonding
    bonding-setup

Debian
++++++

::

    apt update
    apt install bonding

While Bonding restarts, bonders will go offline and aggregators will
drop traffic from their bonders. Bonding must be restarted immediately
after upgrading—it is not supported to upgrade the software while
allowing the current running version to continue running for an extended
period of time.

It is also encouraged to upgrade the packages on your hosts regularly to ensure
they have the latest versions:

openSUSE Leap
+++++++++++++

::

    zypper up

Debian
++++++

::

    apt update
    apt upgrade

Troubleshooting
---------------

If you see a message asking about overwriting a file called
``authorized_keys``, ``known_ips``, or other SD-WAN related files,
we recommend installing the package maintainer's version of the file
unless you plan on managing the contents of the file manually. To do so,
type "y" at the prompt and press <enter>.

::

    Configuration file `/root/.ssh/authorized_keys'
     ==> File on system created by you or by a script.
     ==> File also in package provided by package maintainer.
       What would you like to do about it ?  Your options are:
        Y or I  : install the package maintainer's version
        N or O  : keep your currently-installed version
          D     : show the differences between the versions
          Z     : start a shell to examine the situation
     The default action is to keep your current version.
    *** authorized_keys (Y/I/N/O/D/Z) [default=N] ? y
    Installing new version of config file /root/.ssh/authorized_keys ...

If you see a similar message saying "Modified (by you or by a script)
since installation. Package distributor has shipped an updated
version.", you should also type "y" to install the package maintainer's
version.
