ESF 7.4 Upgrade Changes

This section will list the changes and upgrades made in ESF 7.4.0 and that need to be considered when updating from a previous release. It is possible to perform an upgrade from ESF 7.0.2, ESF 7.1.x, ESF 7.2.x and ESF 7.3.x to ESF 7.4.0 and the upgrader will preserve existing configurations.

Upgrade timeout

The RPM install/upgrade process has configurable guard timeout, the timeout value is set to 15 minutes by default. The purpose of the timeout is to ensure that the RPM installation eventually terminates. In fact, if the timeout triggers, the installation/upgrade will be interrupted and the gateway may be left in a broken state.

The timeout value can be configured by setting the following variable from the shell that will execute the dnf command:

export ESF_INSTALL_TIMEOUT_SECONDS="<value in seconds>"

<value in seconds> must be an integer greater or equal than 900 (15 minutes), if it is not, the default 15 minutes timeout will be used.

It is highly recommended to increase the default value if H2 Database migration needs to be performed.

Upgrade between different jvm versions

The upgrade to ESF 7.3.0 does not work out-of-the-box if the JVM has been upgraded from 1.8 to 17. The starting script for ESF < 7.3.0 has some JVM options that are not working on Java 17 and preventing the framework from starting. The following scenarios are possible:

1. Upgrading from Java 8 with ESF in development mode.
2. Upgrading from Java 8 with ESF in production mode.

In scenario 1 you can replace the scripts located in /opt/eurotech/esf/bin with those found here.

In scenario 2, before starting the upgrade procedure you need to replace the scripts as before, and reload the fingerprints from the ESF UI. A link to the fingerprint reload procedure can be found here. After following the previous steps, you can update ESF and the JVM.

H2 Database

ESF 7.0.2 uses H2 v.1.4.199 whereas ESF 7.4.0 uses H2 v.2.1.214. If coming from 7.0.2, the upgrader will migrate persisted DB instances to the new H2 version. There are some important changes in this version upgrade that can break custom bundles/applications. See H2Db Service for more details.

❗️

Migration of persisted H2 instances

The ESF upgrade process tries to migrate the persisted H2 instances to the new version. It is possible to disable this behaviour by setting the environment variable from the shell that will execute the dnf upgrade command:

export H2_UPGRADE_SKIP_MIGRATION="true"

It is recommened to set the ESF_INSTALL_TIMEOUT_SECONDS variable to a large value, since the migration process can take hours in case of large database instances.

By default, the upgrade process will try to defragment the persisted database instances to try save some disk space. This process can fail and, as result, the database file can become corrupted. The defragmentation can be disabled by setting:

export H2_UPGRADE_DEFRAG="false"

Depending on the database structure and the available free space on the device, the migration process can fail or produce a corrupted database. In such case, on the next restart, ESF will remove and create an empty database with the same name.

By default, the upgrade process creates a backup of the migrated databases. This can be disabled by setting:

export H2_UPGRADE_KEEP_OLD_DB="false"

To have the migration be successful there must be enough space for the database backup (if option H2_UPGRADE_KEEP_OLD_DB is not false) and for intermediate files, that usually are smaller than the database itself depending on the obtained compression level.

The intermediate files are created in the same location of the database and removed after usage. If there is not enough space in such partition, the path for the temp files can be changed using:

export H2_UPGRADE_TMP_DIR="/mnt/data/"

The use of temporary filesystem paths like /tmp/ requires high attention. Reasons are clearly explained in this Unix StackExchange post.

If H2_UPGRADE_KEEP_OLD_DB is not false the backup is guaranteed given that there is enough free space and the gateway is not shut down/powered off.

We suggest H2 persisted instances that contain critical data to be backuped manually before the upgrade.

Some useful Q&A

Q: Are the databases processed one at a time or in batch?

      A: The upgrade will process the persisted database instances one at a time. So at each iteration there needs to be enough space for the database that is being processed.

Q: How much space will the defragmentation save?

      A: It highly depends on the contents of the database. Note that the migrated database is not defragged, so it may be bigger than the original.

Network configuration changes

In previous ESF versions, the current network configuration is computed from system level configuration files and the /opt/eurotech/esf/user/kuranet.conf configuration file. For this reason it was not possible to configure networking changing only the snapshot.

Even if the network configuration properties are stored in the snapshot in previous versions as well, they are read by the implementation only in case of a configuration update and not on ESF startup.

Starting from ESF 7.1.0, the kuranet.conf file is no longer used, and the network configuration is computed basing on the snapshot only, also on ESF startup.

This allows to seed the initial network configuration by changing only the snapshot_0.xml and perform network configuration changes as regular configuration updates, for example by applying a new snapshot/performing a rollback from ESF Gateway Administration Console and/or using the CONF-V2 request handler and REST APIs.

The properties that describe the network configuration are documented in the Network Configuration section.
The previous versions included more properties that the ones defined in Network Configuration for internal implementation details. These additional properties have been removed in ESF 7.1.

REST API Authentication Changes

ESF 7.4.0 introduces introduces support for session management in REST APIs and the new Session V1 REST API, that allows to perform authentication and session creation. The new REST API supports both certificate and password based authentication and is more suitable for being used by a browser based application providing increased security.

In an ESF 7.4.0 fresh installation, the previously available authentication methods like BASIC authentication and certificate based authentication without session management will be disabled by default, leaving only the Session V1 REST APIs available for authentication.

The previous authentication methods are still available but must be explicitly enabled in REST Service configuration by setting the Basic Authentication Enabled and/or Enable Certificate Authentication Without Session Management configuration parameters to true.

If ESF is upgraded from a previous version, the Basic Authentication Enabled and Enable Certificate Authentication Without Session Management configuration parameters will be set to true, leaving the previous authentication methods enabled.

Backwards incompatible changes

Administrative Web UI CSS

Changes have been made to the ESF Web UI default appearance. In particular, updates have been made to the login page and to some logos in the main page displayed after a successful login.

Due to these changes, the ESF 7.4.0 installer will not merge the existing CSS with the updated one but it will simply replace the existing skin.css file available in /opt/eurotech/esf/console/skin/ withe the ESF default one.
Additionally, the ESF upgrader will replace the following files in /opt/eurotech/esf/console/skin/ with a more up to date version:

• esf_login_background.png
• esf_logo.png
• eurotech_everyware_gateway.png
• eurotech_logo.png
• favicon-16x16.png
• favicon-32x32.png
• favicon-96x96.png
• favicon.ico

🚧

If the ESF 7.4.0 installer has been used to upgrade an existing ESF installation that has changes to ESF Web UI skin (css and/or associated files), the customer will need to re-apply those modifications.