*************************
Upgrade Pollux to Quantum
*************************

.. contents::


.. warning:: For Quantum Debian was upgraded to Debian 13 (Trixie).

  Therefore:

      * the upgrade to Quantum will take longer than usual
      * upgrade from older version than XiVO Maia (2024.05) are not supported (you need first to upgrade
        to a version above or equal to Maia before being able to upgrade to Quantum).

    Please read carefully :ref:`Debian 13 (Trixie) upgrade notes <debian_13_upgrade_notes>` page
    and specifcally the :ref:`Major changes associated with Debian 13 <debian_13_upgrade_notes_changes>`.

    Note also that upgrade to Debian 13 on MeetingRooms and Edge is manual (see manual procedure below).


Before Upgrade
==============

On XiVO PBX
-----------

N.A.

On XiVO CC
----------

* SpagoBI container was removed: remove any mention of spagobi service in any configured docker compose override file.

On MDS
------

N.A

On Edge
-------

* Ensure ``XIVO_MDS_HOST...`` variables have the correct separator between *hostname* and *IP* for new docker compose:

  .. important:: **This is a mandatory step**: Edge :file:`.env` file contains ``XIVO_MDS_HOST_MDS...`` variables
    used as an ``extra_hosts`` value in the kamailio compose file.

    They were defined with ``hostname: IP`` (with *column* followed by a *space* between *hostname* and *IP*
    which is not supported anymore by docker compose).
    They **MUST** now be defined with an ``=`` separator between *hostname* and *IP* like: ``hostname=IP``

    The ``XIVO_MDS_HOST_DEFAULT`` won't be used anymore, but you must wait :ref:`the upgrade end<pollux_to_quantum_after_upgrade>` to remove it.

    The changes needed are illustrated in the tables below:

    **For .env file:**

    +----------------------------------------------+------------------------------------------+
    | Before                                       | After                                    |
    +==============================================+==========================================+
    | .. code-block:: ini                          | .. code-block:: ini                      |
    |  :caption: ``.env`` file extract             |  :caption: ``.env`` file extract         |
    |  :emphasize-lines: 4                         |  :emphasize-lines: 4                     |
    |                                              |                                          |
    |  ...                                         |  ...                                     |
    |  TURN_EXTERNAL_IP=DMZ_IP1                    |  TURN_EXTERNAL_IP=DMZ_IP1                |
    |  XIVO_MDS_HOST_DEFAULT="default=LAN_IP2"     |  XIVO_MDS_HOST_DEFAULT="default=LAN_IP2" |
    |  XIVO_MDS_HOST_MDS1="mds1: LAN_IP3"          |  XIVO_MDS_HOST_MDS1="mds1=LAN_IP3"       |
    +----------------------------------------------+------------------------------------------+

  Run the commmand below to change separator in ``XIVO_MDS_HOST...`` variables:

  .. code-block:: bash

   sed -i '/XIVO_MDS_HOST/s/: /=/' /etc/docker/edge/.env
  
* If Edge is used in a :ref:`Resilient architecure <resilience_architecture>` adjust Edge configuration as follows:

  * Add the ``XIVO_HOST_STANDBY`` and ``XIVOCC_HOST_STANDBY`` variables in Edge :file:`.env` file (replace <..._IP> with their actual values):

    .. code-block::

      XIVO_HOST_STANDBY=<XIVO_STANDBY_IP>
      XIVOCC_HOST_STANDBY=<XIVOCC_STANDBY_IP>

  * Also ensure that XiVO Standby IP is among the allowed peers for TURN configuration in Edge :file:`.env`:

    .. code-block::

      TURN_ALLOWED_PEERS="--allowed-peer-ip=<XIVO_MAIN_IP> --allowed-peer-ip=<XIVO_STANDBY_IP> --allowed-peer-ip=... (MDS_IP, MEETINGROOM_IP, etc)"

* Upgrade system to Debian 13 (Trixie):

  #. Rewrite the apt preferences for docker-ce and containerd.io:

     .. code-block:: bash

      #set docker-ce preferences
      cat > /etc/apt/preferences.d/docker-ce << EOF
      Package: docker-ce*
      Pin: version 5:28*
      Pin-Priority: 1000
      EOF

      cat > /etc/apt/preferences.d/containerd <<EOF
      Package: containerd.io*
      Pin: version 2.*
      Pin-Priority: 1000
      EOF


  #. Ensure override for containerd service is installed:

     .. code-block:: bash

      mkdir -p /etc/systemd/system/containerd.service.d
      cat > /etc/systemd/system/containerd.service.d/override.conf <<EOF
      [Service]
      LimitNOFILE=100000
      EOF

      systemctl daemon-reload

  #. and then follow the :ref:`Debian 13 upgrade manual procedure <upgrade_trixie>`


On Meeting Rooms
----------------

* Upgrade system to Debian 13 (Trixie):

  #. Rewrite the apt preferences for docker-ce and containerd.io:

     .. code-block:: bash

      #set docker-ce preferences
      cat > /etc/apt/preferences.d/docker-ce << EOF
      Package: docker-ce*
      Pin: version 5:28*
      Pin-Priority: 1000
      EOF

      cat > /etc/apt/preferences.d/containerd <<EOF
      Package: containerd.io*
      Pin: version 2.*
      Pin-Priority: 1000
      EOF


  #. Ensure override for containerd service is installed:

     .. code-block:: bash

      mkdir -p /etc/systemd/system/containerd.service.d
      cat > /etc/systemd/system/containerd.service.d/override.conf <<EOF
      [Service]
      LimitNOFILE=100000
      EOF

      systemctl daemon-reload

  #. and then follow the :ref:`Debian 13 upgrade manual procedure <upgrade_trixie>`

.. _pollux_to_quantum_after_upgrade:

After Upgrade
=============

On XiVO PBX
-----------

* Reboot (Debian was upgraded)

On XiVO CC
----------

* xuc JVM option is now defined as ``JAVA_OPTS=${JAVA_OPTS_XUC:--Xms512m -Xmx2048m}`` (instead of ``JAVA_OPTS=-Xms512m -Xmx2048m``).
  Check that after the upgrade the xuc takes the correct parameters as expected on the installation.
  For example it may be possible to remove the override that defined `JAVA_OPTS=${JAVA_OPTS_XUC}`.
* Reboot (Debian was upgraded)

On MDS
------

* Reboot (Debian was upgraded)

On Edge
-------

* ``XIVO_MDS_HOST_DEFAULT`` variable is not needed anymore and should be removed from edge's :file:`.env`.

    **For .env file:**

    +----------------------------------------------+------------------------------------------+
    | Before                                       | After                                    |
    +==============================================+==========================================+
    | .. code-block:: ini                          | .. code-block:: ini                      |
    |  :caption: ``.env`` file extract             |  :caption: ``.env`` file extract         |
    |  :emphasize-lines: 3                         |                                          |
    |                                              |                                          |
    |  ...                                         |  ...                                     |
    |  TURN_EXTERNAL_IP=DMZ_IP1                    |  TURN_EXTERNAL_IP=DMZ_IP1                |
    |  XIVO_MDS_HOST_DEFAULT="default=LAN_IP2"     |  XIVO_MDS_HOST_MDS1="mds1=LAN_IP3"       |
    |  XIVO_MDS_HOST_MDS1="mds1=LAN_IP3"           |                                          |
    +----------------------------------------------+------------------------------------------+

  Then apply the changes to the container:

  .. code-block:: bash
    
    edge-dcomp up -d

On Meeting Rooms
----------------

N.A

.. _upgrade_trixie:

Upgrade to Debian 13
====================

These steps are to be done before an upgrade from Pollux to Quantum on **Edge** and **Meeting Rooms**

* Check GRUB **before upgrading**

    .. code-block:: bash

      install_device=$(debconf-show grub-pc | grep 'grub-pc/install_devices:' | cut -b3- | cut -f2 -d' ' | cut -d',' -f1)
      if [ "$install_device" -a ! -e "$install_device" ]; then
        echo -e "\e[1;31mYou must install GRUB BEFORE upgrading\e[0m"
      fi

* If it's broken you can fix it this way before rechecking

    .. code-block:: bash

      apt update
      apt install grub-pc
      dpkg-reconfigure grub-pc

* Check you are in Debian 12

    .. code-block:: bash

      if [ "$(cut -d '.' -f 1 /etc/debian_version)" -ne 12 ]; then
        echo -e "\e[1;31mSystem is not in Debian 12. Please upgrade first to Debian 12\e[0m"
        echo -e "\e[1;31mSee Luna to Maia Upgrade page.\e[0m"
      fi

* Check if ``/boot`` is a separate partition. If so ensure it is at least 768 MB in size, and has about 300 MB free.

    .. code-block:: bash

      boot_mount_point=$(df /boot --output=target |tail -n +2)
      if [ "${boot_mount_point}" = "/boot" ]; then
        echo -e "\e[1;31m/boot is a separate partition.\e[0m"
        echo "Please check it is at least 768 MB in size, and has about 300 MB free."
      else
        echo "/boot is not a separate partition. Nothing to do."
      fi

* Install new key and refresh the docker repository

  .. code-block:: bash

    # Add Docker's official GPG key:
    apt install ca-certificates curl
    install -m 0755 -d /etc/apt/keyrings
    curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
    chmod a+r /etc/apt/keyrings/docker.asc

    # Add the repository to Apt sources:
    tee /etc/apt/sources.list.d/docker.sources <<EOF
    Types: deb
    URIs: https://download.docker.com/linux/debian
    Suites: trixie
    Components: stable
    Signed-By: /etc/apt/keyrings/docker.asc
    EOF

* Remove the previous docker source file

  .. code-block:: bash

    rm /etc/apt/sources.list.d/docker.list

* Upgrade to Debian 13

    .. code-block:: bash

      # Move to trixie
      sed -i 's/bookworm/trixie/' /etc/apt/sources.list /etc/apt/sources.list.d/*.list
      apt update

      export DEBIAN_FRONTEND=noninteractive
      export APT_LISTCHANGES_FRONTEND=none
      force_yes="--allow-downgrades --allow-remove-essential --allow-change-held-packages"

      echo "Download packages..."
      apt full-upgrade -d --yes
      echo "Executing full upgrade actions..."
      apt full-upgrade --yes ${force_yes} -o Dpkg::Options::="--force-confnew"
      apt autoremove --yes

* **Before reboot** check potential network interface name change - see `Network interface names may change <https://www.debian.org/releases/trixie/release-notes/issues.en.html#network-interface-names-may-change>`_
  Use this script to know whether the change might happen.

    .. code-block:: bash

      echo ""
      echo "Checking potential network interface name change:"
      iface_rename=0
      # Check whether predictable name was deactivated
      if grep -q "net.ifnames=0" /proc/cmdline; then
        echo "  So-called 'Predictable Name' is deactivated per kernel cmdline (net.ifnames=0)."
        echo "  Skipping this check as unrelevant."
      else
        for net_iface in /sys/class/net/*; do
          net_iface_name=$(basename "${net_iface}")
          # Skip virtual interface
          if readlink -f "${net_iface}" | grep -q "virtual"; then
            continue
          fi
          echo -n "  ${net_iface_name} ... "
          net_iface_new_name=$(udevadm test-builtin net_setup_link "${net_iface}" 2>/dev/null| grep -oP 'ID_NET_NAME=\K.*')
          if [ "${net_iface_name}" = "${net_iface_new_name}" ]; then
            echo "OK (won't be renamed)"
          else
            if grep -q "${net_iface_name}" /etc/udev/rules.d/70-persistent-net.rules; then
                iface_rename=1
                echo -e "\e[1;33m WARNING: might be renamed to ${net_iface_new_name} but name should be kept via legacy udev rules\e[0m"
                echo "    Interface ${net_iface_name} is present in /etc/udev/rules.d/70-persistent-net.rules therefore it should not be renamed."
                echo -e "    \e[1;31mBEFORE REBOOTING\e[0m ensure this is actually true by checking this udev rules file."
                echo "    You might also consider to migrate legacy /etc/udev/rules.d/70-persistent-net.rules to a systemd .link files."
            else
                iface_rename=2
                echo -e "\e[1;31m NOK! ALERT: will be renamed to ${net_iface_new_name}\e[0m"
                echo -e "    \e[1;31mBEFORE REBOOTING\e[0m create a systemd .link file for this interface in order to ensure stable name"
                echo -e "\e[1;31m     If not done it will be impossible to reconnect via SSH after reboot\e[0m"
            fi
          fi
        done
        if [ $iface_rename -ne 0 ]; then
          echo "  Find an example of systemd .link file here:"
          echo "    https://wiki.debian.org/NetworkInterfaceNames#CUSTOM_SCHEMES_USING_.LINK_FILES"
        fi
      fi
      echo ""

* Reboot