ESF 7 Upgrade and Backwards Incompatible Changes

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

Configuration changes

#### Web Console configuration

ESF 6.X WebConsole configuration section allowed to specify the username and password of the only console user.
ESF 7 allows multiple Console login identities, identities and respective credentials can be configured from the dedicated Identities section. See Gateway Administration Console Authentication for more details.
From ESF 7, the default admin user has the device serial number as default password.

#### Rest API configuration

ESF 6.x REST service provides a dedicated configuration section in the Web UI that allows to define REST users, password and roles.
ESF 7 maps REST users to Identities and Permissions. See Rest Service for more details.

## Filesystem structure changes

Some of parts of ESF installation directory layout changed from ESF 6.2 and ESF 7. All paths used in this section are relative to ESF installation root (usually /opt/eurotech/esf)

Deployment packages

### Console skin directory

### Log4j configuration file

An overview of the new framework filesystem structure is available in the Directory Layout page.

Startup script changes

ESF 7 contains the following changes to the startup scripts:

• The OSGi system bundle version has changed due to an Equinox framework update
• The kura.data.dir property has been superseded by kura.data
• The references to the dpa.properties and log4j.xml files are changed due to the changes to the file structure.

## Firewall changes

ESF 7 organizes its generated firewall rules in custom iptables chains and no longer flushes all tables on configuration update. This allows better coexistence with external applications that need to modify firewall rules. The procedure is transparent to the user and the Web Console will continue to show the firewall rules as in ESF 6.2.

File permission changes

ESF 7 introduces the following changes related to file permissions:

• The files in ESF root directory (/opt/eurotech/esf) will be readable and writable only by the owner user. The owner user is esfd on systemd based platforms and root otherwise.

• ESF will run with umask 0066, all new files created by it will be readable and writable only by the owner. This can be relaxed if needed by explicitly setting file permissions using the dedicated Java APIs.

Docker changes

ESF 7 provides Centos 8 and RHEL 8 based containers for aarch64 and x86_64.
The following features have been dropped from all containers (also x86_64):

• SSH server is no longer available in the container.
• The container no longer generates the /var/log/kura-console.log file inside the container. ESF standard output will still sent to the Docker logging framework.

Diagnostics Service changes

The Diagnostics Service includes the following additional features:

• Ability to log diagnostics metrics and alerts.
• The DiagnosticsService now exposes public APIs that allow to external applications to extend its functionality and/or retrieve current alert status.
• Added support for publishing eMMC 5.0 wear level indicators
• Added support for ReliaGATE 10-14 tamper detection functionalities.

Keystore service

A new keystore abstraction feature has been added in order to simplify the local and remote management of framework managed keystores.
The KeystoreService implementation is a factory component that needs to be instantiated for every keystore. The configuration of the instance allows the customer to specify the keystore location, password and password randomisation.
The password randomisation is a configuration option that gives the ability, once set to true, to randomise the password of the keystore at the next boot. From that point on, the specific keystore password will be managed by the framework instance and will be different from any other ESF instance.

The old feature that allowed to specify an SSL password in the kura.properties file to have it randomised at the first boot, is now deprecated and not supported. kura.ssl.keyStorePassword will not be used anymore by the framework to try to access the provided SSL keystore.

SSLManagerService

The SSLManagerService APIs have been reviewed with some methods deprecated. The code still supports the old behaviour.
The service itself has been changed to a factory component. For compatibility reasons, the framework instantiates at first boot a SSLManagerService instance with the same PID of the previous ESF versions. This will preserve compatibility with existing code.

In the updated version of the SSLManagerService implementation, the instance is now dynamically tied to a KeystoreService instance, updatable by the customer.

MqttDataTransport

The MqttDataTransport class now dynamically references a SSLManagerService instance. The service will use the SSL contexts and configurations provided by the SSLManagerService instance associated.
There is no more way to override the SSL configuration directly from the MqttDataTransport configuration.

ProvisioningService

The ProvisioningService configuration is now shown in the Cloud Connections section of the web ui, as another tab like CloudService, DataService and MqttDataTransport.

Provisioning is no longer limited to the default cloud connection.
It is still not possible to perform provisioning on multiple cloud connections on the same Everyware Cloud instance.

Birth Certificate

The Birth Certificate message, generated and reported to the cloud platform at every connection or feature update, has been updated. In particular, the following new metrics have been introduced:

• cpu_version: Reports version information about the CPU
• modem_firmware_version: Reports modem firmware version information, usually obtained running the AT+GMR command.
• extended_properties: Provides additional information about the gateway, the value of this metric is a string that contains a JSON object.

Starting from ESF 7, the content of the following metrics may be obtained from EL commands, the reported value might change after and upgrade from ESF 6.2 to ESF 7.

• model_id
• model_name
• serial_number
• bios_version
• firmware_version
• os_version
• os_arch

More details are available in the Extended Birth Certificate page

ProcessUtil deprecation

The following classes are deprecated and will be removed in a next ESF release:

• SafeProcess
• ProcessUtil
• LinuxProcessUtil
• ProcessStats

The methods in these classes are all replaced by the new CommandExecutorService.

Wi-Fi Interfaces

By default, every new installation of ESF disables the Wi-Fi interface. To enable it, the user can change the default configuration prior to ESF reboot and/or deployment. Once ESF has started, the user can activate the Wi-Fi interface using the Wi-Fi Configuration section of the ESF Web UI.

OSGi console

OSGi console previously available on port 5002 is now disabled by default if the gateway is configured in production mode on new installations.
OSGi console was previously used to initiate framework shutdown. Starting from ESF 7.0, a new method for ESF shutdown has been implemented.
OSGi console is not disabled if ESF is upgraded from 6.2 to 7.

Upgrader

It is possible to perform an upgrade from ESF 6.2 to ESF 7 and the upgrader will try to preserve existing configuration when possible.

The upgrader will apply the following changes:

• Align the root folder structure to the new layout preserving existing content
• Migrate the configurations of the REST and Console services
• Migrate firewall configuration
• File permissions
• Update framework managed keystores
• Update the SSL configuration
• [10-12 Only] Update RTC reference

Configuration migration

Web Console user

The upgrader will create a new identity for the console user with the same password. The kura.admin permission will be assigned to it.

HttpService configuration

The upgrader will enable HTTP port 80 to match the setup of ESF 6.X. HTTPS support will be disabled by default.

REST user configuration

The upgrader will create, for each role referenced by old REST configuration named ${role.name}, a new permission named rest.${role.name}.

The upgrader will create an identity for each user defined in old REST configuration with the same name and password. The upgrader will assign to the new identity all permissions created from the roles assigned to the old user.

If the console user has the same name as a REST user, a conflict will arise. This will happen for example with default ESF 6 configuration, where both the console user and the default REST user are named admin. In case of conflicts, the identity for the conflicting REST user will be named rest.old.${user.name}, where ${user.name} is the name of the old user. This can break existing REST clients.

🚧

Please note that after the ESF 7 upgrade, the credentials of the old console user will also allow to access all REST APIs. If this is not desired some action must be taken by the customer after the upgrade.

Firewall configuration

The upgrader will try to move all the firewall rules configured in ESF 6.2 to the new custom iptables rules. All the rules added to the INPUT, OUTPUT and FORWARD chains in the filter table and the ones in the INPUT, OUTPUT, PREROUTING and POSTROUTING chains in the nat table will be moved to the new chains and shown in the Web Console.

File permissions

The upgrader will apply the file permission changes described above to ESF root directory and will configure ESF to start with umask 0066.

Framework managed keystores

The upgrader will rework the framework managed keystores. In particular, it will create a new keystore named dmkeystore.ks that will contain the device management certificates and CAs previously contained in the .certificates.ks keystore.

Update the SSL configuration

A new SSLManagerService instance will be generated with the same PID of the corresponding component in ESF 6.2.0. The new SSLManagerService will be associated to a KeystoreService instance dedicated to the management of SSL certificates.

#### ProvisioningService configuration

The upgrader will migrate the current ProvisioningService configuration so that it appears in the Cloud Connections section of the web UI and it will assign it to the default org.eclipse.kura.cloud.CloudService instance. The upgrader will create a ProvisioningService instance for each cloud connection created from the org.eclipse.kura.cloud.CloudService factory.

[10-12 Only] Update RTC reference

The upgrader will migrate the current ClockService reference on 10-12 devices to use /dev/rtc1 instead of the default value inherited from ESF 6.2.0.

#### Flooding Protection and Fail2Ban configurations

The upgrader will create a default configuration for the flooding protection and fail2ban configurator. services. These services will be disabled in default configuration.