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.
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
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.
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:
- Upgrading from Java 8 with ESF in development mode.
- 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.
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
It is recommened to set the
ESF_INSTALL_TIMEOUT_SECONDSvariable 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:
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:
To have the migration be successful there must be enough space for the database backup (if option
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:
The use of temporary filesystem paths like
/tmp/requires high attention. Reasons are clearly explained in this Unix StackExchange post.
falsethe 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.
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.
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.
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.
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:
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.
Updated 3 months ago