Skip to content

Live upgrade of the Mediation Controller

Important

The documentation for live upgrading the Mediation Controller is intended for any Mediation Controller 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:

1
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:

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

Disk space extension for virtual appliances

Systancia Cleanroom 4.4 or 4.5 virtual appliances require a 2 GB disk extension to be added to the /usr partition. This operation is necessary in order to have sufficient disk space for the upgrade and to avoid getting stuck during the operation.

When connecting to the Mediation Controller, whether via SSH or console mode, a welcome message will inform you that you are connected to a Systancia machine. An additional line indicates the version of the appliance.

Example

A Mediation Controller virtual appliance running version 4.5 will give the following result:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
            ____            _                   _
        / ___| _   _ ___| |_ __ _ _ __   ___(_) __ _
        \___ \| | | / __| __/ _  | '_ \ / __| |/ _  |
            ___) | |_| \__ \ || (_| | | | | (__| | (_| |
        |____/ \__, |___/\__\__,_|_| |_|\___|_|\__,_|
                |___/
#################################################################
# WARNING:                                                      #
# You must have specific authorization to access this machine.  #
# Unauthorized access to this machine is prohibited and will be #
# considered as intrusion.                                      #
# Unauthorized users will be logged, monitored, and could be    #
# prosecuted.                                                   #
#################################################################
Systancia Cleanroom 4.5.0 B77

If the machine is not a virtual appliance provided with version 4.4 or 4.5, this chapter can be skipped to proceed with the upgrade.

Backup strongly recommended

The following steps will make changes to the Mediation Controller's disk partitioning. If manual changes have been made, the following instructions may not be suitable, resulting in the machine becoming blocked.

Before proceeding, please back up the machine or, if necessary, duplicate the virtual machine. Snapshots cannot be used because, particularly with VMware, they block the ability to expand a disk.

At the hypervisor level, extend the virtual machine's disk space by an additional 2 GB. If it is not possible to extend the disk, check that there are no snapshots, and if not, shut down the virtual machine if live extension is not supported.

Once the disk space has been extended at the virtual machine level, the following commands, to be executed as root, are necessary in order to extend the /usr partition:

1
2
3
4
5
6
echo 1 > /sys/class/block/sda/device/rescan
start_lvm_partition=`fdisk -l /dev/sda | grep LVM | awk '{print $2}'`
echo -e "d\n2\nn\ne\n2\n\n\nn\n$start_lvm_partition\n\nt\n5\n8E\nw" | fdisk /dev/sda
pvresize /dev/sda5
lvresize -l +100%FREE /dev/mapper/SystanciaLVMGroup-usr
resize2fs /dev/mapper/SystanciaLVMGroup-usr

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):

1
2
3
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 Microsoft SQL Server drivers

Additional steps are required if Microsoft SQL Server drivers are installed (this is the case on virtual appliances provided by Systancia).
To check whether they are present on the server, the following command can be executed as root:

1
apt list --installed ms*

If no response appears, then the drivers are not installed and you can proceed to the mirror preparation step.
Otherwise, if the drivers are installed, two packages should be listed: msodbcsql17 and mssql-tools. Follow the instructions in this section.

Examples

A server on which the drivers are not installed would have the following result from the previous command:

1
Listing... Done

A server on which the drivers are installed will have a result similar to this (the package versions may differ):

1
2
3
Listing... Done
msodbcsql17/bullseye,now 17.10.6.1-1 amd64 [installed]
mssql-tools/bullseye,now 17.10.1.1-1 amd64 [installed]

The following commands are necessary to install a specific version of the packages to ensure a successful upgrade:

1
env ACCEPT_EULA=Y apt install -y --allow-downgrades odbcinst=2.3.6-0.1+b1 odbcinst1debian2=2.3.6-0.1+b1 libodbc1=2.3.6-0.1+b1 unixodbc=2.3.6-0.1+b1 mssql-tools=17.9.1.1-1 msodbcsql17=17.9.1.1-1

Configure the Microsoft repository adapted to Debian 12 to prepare for the upgrade:

1
echo "deb [arch=amd64] https://packages.microsoft.com/debian/12/prod bookworm main" > /etc/apt/sources.list.d/mssql-release.list

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):

1
2
3
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:

1
2
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:

1
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 Mediation Controller server via SSH and switch to root, then open a screen as indicated above.

Start by updating certain specific packages so that the version upgrade can be performed. An error message is expected when executing the first command, but the error will be corrected with the second command:

1
2
apt install -y python3-cleanroom-django-mssql python3-ipdiva-ua-parser python3-ipdiva-user-agents python3-ipdiva-django2
apt install -y --fix-broken

When upgrading a Mediation Controller 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:

1
2
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/shibboleth/shibboleth2.xml To keep, answer N
/etc/shibboleth/shibd.logger Apply changes, answer Y
/etc/default/ntpsec Apply changes, answer Y
/etc/snmp/snmpd.conf Apply changes, answer Y
/etc/logrotate.d/IPdivaServer Apply changes, answer Y
/etc/ssh/sshd_config To keep, answer Keep the local version currently installed
/etc/ssh/ssh_config Apply changes, answer Y
/etc/apache2/ports.conf To keep, answer N
/etc/init.d/apache2 To keep, answer N
/etc/modsecurity/modsecurity.conf-recommended Apply changes, answer Y
/etc/ipdiva/httpd/commonParameters.conf Apply changes, answer Y
/etc/ipdiva/care/djangosettings.ini Apply changes, answer Y
/etc/crontab Apply changes, answer Y
/etc/openssl.cnf Apply changes, answer Y
/etc/audit/rules.d/audit.rules To keep, answer N
/etc/pam.d/su To keep, answer N
/etc/sysctl.conf To keep, answer N

Accept the glibc package configuration message:

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:

1
2
3
4
systemctl start collectd
systemctl enable collectd
apt autoremove -y
reboot

Actions specific to Mediation Controllers Cluster

On the SLAVE Mediation Controller server, run the following commands to resynchronize the shared secret between the MASTER Mediation Controller and the SLAVE:

1
2
hostManagerCtl masterSynchro /etc/ipdiva/secure/secret /etc/ipdiva/secure/secret
systemctl restart apache2

Upgrading the PostgreSQL database instance

On the Mediation Controller server, update the PostgreSQL database instance from version 13 to version 15. To do this, execute the following instructions with the appropriate root rights.

Check the status of the Postgresql instances before migration:

1
pg_lsclusters

Run the following commands to update the database instance to PostgreSQL version 15:

1
2
3
4
pg_dropcluster --stop 15 main
systemctl stop postgresql
pg_upgradecluster 13 main
systemctl start postgresql

Check that the database instance has been successfully upgraded. Two instances should appear, one in version 13 and the other in version 15, which is the only active one. The check is performed with the following command:

1
pg_lsclusters

If the upgrade was successful, the version 13 database instance can be deleted:

1
pg_dropcluster 13 main

The deletion of version 13 PostgreSQL packages can be initiated:

1
apt -y --purge autoremove postgresql-client-13 postgresql-13

Migration of the cyberelements Cleanroom database

The product configuration is stored in the database, which needs to be migrated so that it can contain the configurations of the changes made by the new version. The operation is performed on the Mediation Controller as root.

Cluster architecture

For a cluster architecture, it is necessary to perform the operation from only one Mediation Controller, regardless of which one.

It is also necessary to run the following command:

1
python3 /var/lib/ipdiva/care/manage.py migrate

Data migration is triggered with a command equivalent to this one:

1
python3 /var/lib/ipdiva/care/manage.py migrate --database=<org_clr>

Where <org_clr> must be replaced with the name of the organization to be migrated. Please note that if the Mediation Controller has multiple organizations (multi-tenants), then you will need to run the command as many times as there are organizations to migrate.

Example

For a cyberelements Cleanroom platform that has the organizations systancia and systancia-test, you will need to run the following commands:

1
2
python3 /var/lib/ipdiva/care/manage.py migrate --database=systancia
python3 /var/lib/ipdiva/care/manage.py migrate --database=systancia-test

Following the database migration, the Apache2 service must be restarted:

1
systemctl restart apache2

Restoring configurations

Some configurations were overwritten during the upgrade process and need to be restored.

commonParameters.conf file:

Move the <Location> tags relating to HTML5 gateways, which are usually located at the end of the file, from the /etc/ipdiva/httpd/commonParameters.conf.dpkg-old file to /etc/ipdiva/httpd/commonParameters.extra.conf (create the file if it does not exist). If no <Location> tags are present, the following examples can be copied.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<Location /HTML5/>
    Order allow,deny
    Allow from all
    ProxyPass http://127.0.0.1:1234/systanciaHTML5-6.0/ flushpackets=on
    ProxyPassReverse http://127.0.0.1:1234
</Location>

<Location /HTML5/websocket-tunnel>
    Order allow,deny
    Allow from all
    ProxyPass ws://127.0.0.1:1234/systanciaHTML5-6.0/websocket-tunnel
    ProxyPassReverse ws://127.0.0.1:1234/systanciaHTML5-6.0/websocket-tunnel
</Location>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<Location /HTML5-1/>
    Order allow,deny
    Allow from all
    ProxyPass http://127.0.0.1:1234/systanciaHTML5-6.0/ flushpackets=on
    ProxyPassReverse http://127.0.0.1:1234
</Location>

<Location /HTML5-1/websocket-tunnel>
    Order allow,deny
    Allow from all
    ProxyPass ws://127.0.0.1:1234/systanciaHTML5-6.0/websocket-tunnel
    ProxyPassReverse ws://127.0.0.1:1234/systanciaHTML5-6.0/websocket-tunnel
</Location>

<Location /HTML5-2/>
    Order allow,deny
    Allow from all
    ProxyPass http://127.0.0.1:1235/systanciaHTML5-6.0/ flushpackets=on
    ProxyPassReverse http://127.0.0.1:1235
</Location>

<Location /HTML5-2/websocket-tunnel>
    Order allow,deny
    Allow from all
    ProxyPass ws://127.0.0.1:1235/systanciaHTML5-6.0/websocket-tunnel
    ProxyPassReverse ws://127.0.0.1:1235/systanciaHTML5-6.0/websocket-tunnel
</Location>

djangosettings.ini file:

Copy the information from line 2 “allowed_hosts” of the /etc/ipdiva/care/djangosettings.ini.dpkg-old file to the /etc/ipdiva/care/djangosettings.ini file. This can be automated with the following command as root:

1
sed -i "2c\\`sed -n '2p' /etc/ipdiva/care/djangosettings.ini.dpkg-old`" /etc/ipdiva/care/djangosettings.ini

Applying restorations:

In order to apply the restorations, a restart of the Apache2 service is necessary as root:

1
systemctl restart apache2

Validation

Once the upgrade has been completed, the Cleanroom cyberelements infrastructure must be validated to ensure it is functioning correctly before going back into production. If validation fails, consider rolling back by restoring the Cleanroom cyberelements server backups.

Access the administrator interface for an organization, then go to the “About” menu in the control bar to check that the Mediation Controller version has been successfully upgraded to 4.6.

Initial tests of the platform's functionality can be initiated, but we recommend using version 4.6 of Edge Gateway to ensure optimal performance of cyberelements Cleanroom applications.