Upgrade ESF

The RPM file used to a fresh ESF install can be used to upgrade an existing installation. The RPM file, indeed, contains all the resources needed to upgrade/install ESF. The upgrade will preserve all the user preferences, scripts and snapshots.

📘

Check the gateway-specific page if more detailed installation instructions or additional preliminary steps are needed for your device.

The upgrade procedure will generate two log files, kura_uninstall_<timestamp>.log and kura_install_<timestamp>.log in the /opt/eurotech/esf/log/ folder. The logs will also be appended to the systemd journal using the ESF syslog identifier, and it can be inspected using the journalctl -t ESF command.

Please note that if the platform does not use persistent storage for systemd journal, the logs in systemd journal will be lost after device reboot.

🚧

Supported upgrade paths

It is possible to perform an upgrade from ESF 7.0.2, ESF 7.1.x, ESF 7.2.x, ESF 7.3.x and ESF 7.4.0 to ESF 7.5.0 and the upgrader will preserve existing configurations. See section Upgrade changes for more details on the operations performed during the update and for backwards incompatible changes.

In the case of different upgrade requirements, please keep in touch with your Eurotech sales representative for the quotation of a specific Professional Service.

How To Update

RPM

To upgrade ESF using .rpm files, use the following command:

dnf upgrade esf-*.rpm
reboot

🚧

On already deployed devices, the rpm install may require the installation of the ESF RPM GPG key used to sign and verify the ESF RPM.

The ESF RPM Key comes pre-installed in EL 27.1.0 and EL 30.0.0.

The Key is available here. To install in the target device, run the following command:

rpm --import <key>

Debian

Upgrade using Debian packages is only supported for ESF generic distribution profiles (esf-generic.deb).

Upgrade of the old Raspberry PI debian packages is not supported (e.g. esf-raspberry-pi.deb).

Debian package upgrade should be performed with the following commands:

apt install -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" ./esf-generic_<version>_<arch> .deb
reboot

The extra --force-confdef and --force-confold options are needed to prevent apt from showing user prompts in certain circumstances. User prompts are not desirable especially in the case of an unattended upgrade (e.g. debian package upgrade performed with an Ansible playbook).

The prompt will appear in the case when a new version of a configuration file has been shipped in the Debian package of the new ESF version and the user changed that configuration file. The correct behavior in this case is to keep the existing version of the configuration file (the --force-confold option forces this behavior without the prompt).

Upgrade changes

This section will list the changes and upgrades made in this ESF version and that need to be considered when updating from a previous release.

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.

H2 Database

ESF 7.0.2 uses H2 v.1.4.199 whereas ESF 7.5.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.

Since ESF 7.4.0, in a 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.5.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.5.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.

Systemd unit management

ESF 7.5.0 introduces restrictions on the systemd units that ESF process is allowed to start and stop. See Systemd Unit Management page for more details.

Snapshot after upgrade

ESF upgrader currently loads that latest snapshot from previous version on the device, processes it and uses the result as the snapshot_0.xml for the upgraded version. All the other snapshots of the previous ESF version are lost.

This is due to the fact that previous snapshots may not be compatible anymore with the new ESF version after the upgrade.