Live upgrade of the Edge Gateway¶

Important

The documentation for the live upgrade of the Edge Gateway is intended for any Edge Gateway running Debian 11. The Debian version can be checked using the following command (to be executed in SSH or console access):

1	`cat /etc/debian_version`

Information

As a reminder, the switch to Debian as root on machines must be performed using the following command:

su -

Planning and Preparation¶

Opening flows¶

When upgrading the product, many packages must be downloaded from the Debian repositories due to the transition from Debian version 11 to 12. TCP 80 access must be opened to security.debian.org and ftp.fr.debian.org.

To test the opening of streams on the machine, a synchronization of the Debian repositories can be launched. If error messages regarding access to the Debian repositories are displayed, then the network flow is not open, probably blocked by the corporate firewall. Repository synchronization can be initiated with the following command:

1	`apt update`

Downloading the mirror and necessary tools¶

The cyberelements Cleanroom 4.6 mirror can be downloaded from this link (requires the creation of a customer account): Systancia Marketplace

In addition to the mirror, third-party tools will be required for the upgrade process:

An SSH client (on Windows, the PuTTY tool can be used)
An SCP client (on Windows, the WinSCP or FileZilla tools can be used)

Installing and using the screen tool¶

The screen tool allows you to open multiple shell terminals in a single console. It is essential to use this tool to upgrade to cyberelements Cleanroom version, in order to remove dependency on the stability of network connectivity. In fact, without using the screen tool, the installation would be stopped in the event of a break in SSH connectivity with the Systancia Cleanroom servers.

By using the screen tool, when reconnecting to the shell console of the cyberelements Cleanroom equipment, the terminal in which the update process was executed can be retrieved.

The screen package should be installed using the following command line:

apt install --no-install-recommends screen

To open a new screen terminal, the following command must be executed:

1	`screen -S <ID>`

Replace <ID> with a name that identifies the session.

Example

For cyberelements version upgrades, the cye-upgrade dentifier is easily identifiable. The command would therefore be as follows:

1	`screen -S cye-upgrade`

To retrieve a terminal opened by screen, simply execute the following command:

1	`screen -r <ID>`

Replace <ID> with the name defined when the session was opened.

Example

The terminal previously opened with the cye-upgrade identifier can be retrieved with the following command:

1	`screen -r cye-upgrade`

To close the terminal once the upgrade is complete, enter the exit command or keyboard shortcut ctrl+d in the terminal.

Upgrade¶

Updating Debian packages¶

Since upgrading cyberelements Cleanroom requires upgrading Debian, it is recommended that you properly update Debian 11 packages before switching to Debian 12. To do this, run the following commands as root (system update then removal of unnecessary packages):

apt update
apt upgrade -y
apt autoremove -y

Messages asking you to modify the configuration of several configuration files may appear. In these cases, select the option to keep the current configuration.

Preparing the Cyberelements Cleanroom 4.6 mirror¶

The mirror retrieved during the preparation phase (file with the tgz extension) must be sent to the server via SCP. It should be placed in the /tmp/ directory.

Next, prepare the mirror by executing the following commands as root (residual files from an old version upgrade will be deleted):

mkdir -p /opt/systancia/repository
rm -rf /opt/systancia/repository/*
tar xvzf /tmp/*.tgz -C /opt/systancia/repository/

APT configuration¶

The APT package manager is configured to retrieve Debian 11 packages; it must be reconfigured to retrieve Debian 12 packages. It is also necessary to update the reference to the local cyberelements Cleanroom mirror. To do this, execute the following commands as root:

echo -e 'deb http://security.debian.org/debian-security/ bookworm-security main contrib non-free non-free-firmware\ndeb http://ftp.fr.debian.org/debian bookworm main contrib non-free non-free-firmware\ndeb http://ftp.fr.debian.org/debian bookworm-updates main contrib non-free non-free-firmware' > /etc/apt/sources.list
echo "deb file:///opt/systancia/repository/ bookworm ipdiva" > /etc/apt/sources.list.d/systancia.list

In addition to configuring the new repositories, we strongly recommend applying the following setting to instruct APT not to install recommended dependencies that are not strictly necessary, in order to reduce the number of components installed. The following command applies this setting asroot:

echo -e 'APT::Install-Recommends false;\nAPT::Install-Suggests false;' > /etc/apt/apt.conf.d/99norecommends

Finally, it is necessary to update the list of packages in the repositories with the following command:

1	`apt update`

Triggering the version upgrade¶

Access the Edge Gateway server via SSH and switch to root, then open a screen as indicated above.

When upgrading an Edge Gateway from Debian 11 to Debian 12, the collectd package is updated and becomes incompatible with the configuration file generated by cyberelements Cleanroom (/etc/collectd/collectd.conf). This may generate an error during the update.

To avoid this, disable collectd:

systemctl stop collectd 
systemctl disable collectd

After that, the upgrade can be initiated with the following command:

1	`apt dist-upgrade -y`

During the upgrade, you will be asked several questions about whether to keep configuration files and update them according to the standard Debian 12 configuration, or to keep the specific configuration in place. Here are our recommendations for most of the files you may encounter:

Configuration file	Recommended action
/etc/issue	To keep, answer `N`
/etc/issue.net	To keep, answer `N`
/etc/security/limits.conf	To keep, answer `N`
/etc/login.defs	To keep, answer `N`
/etc/snmp/snmpd.conf	Apply changes, answer `Y`
/etc/ssh/sshd_config	To keep, answer `Keep the local version currently installed`
/etc/pam.d/su	To keep, answer `N`
/etc/sysctl.conf	To keep, answer `N`
/etc/audit/rules.d/audit.rules	To keep, answer `N`
/etc/ssh/ssh_config	Apply changes, answer `Y`
/usr/share/tomcat10/logrotate.template	Apply changes, answer `Install the package maintainer's version`

Accept the automatic restart of services:

Once the upgrade is complete, run the following commands to reactivate collectd, remove unnecessary packages, and restart the machine:

systemctl start collectd
systemctl enable collectd
apt autoremove -y
reboot

Validation¶

Once the upgrade operation has been completed, a validation phase to ensure that the cyberelements Cleanroom infrastructure is functioning properly is required before returning to production. If validation fails, a rollback via the restoration of cyberelements Cleanroom server backups should be considered.

Access the administrator interface, then the Edge Gateways management menu. The updated Edge Gateways should report version 8.9 if they have successfully reconnected to the Mediation Controller.

If all servers have been upgraded, then all functional tests can be performed to validate the entire acceptance checklist.