Verify ESF Installation

For most Eurotech gateways, ESF will be pre-installed and automatically started on system start up. ESF is also monitored by the Monit utility; if the ESF Java process is terminated for some reason, Monit will attempt to restart ESF.

There are a few necessary steps to ensure that ESF is running as expected. First, verify that the Java process is running with the following command:

ps aux | grep java

This command should find a process with multiple arguments passed to the JVM. For most ESF-powered gateways, this will be the only Java process running. If there are multiple Java processes, the ESF process can be identified by searching for arguments assigned with "/opt/eurotech".

🚧
While there may be multiple Java processes running, and even multiple OSGi containers running, there can be only one ESF process. If multiple ESF processes are detected, the unit should be restarted.

Once the ESF process has been identified, it is important to check the ESF log files for errors. The first log file, located at /var/log/kura-console.log, logs results from the output of the OSGi process. Errors in this log file often indicate critical startup or runtime errors in the framework.

The second log file, located at /var/log/kura.log, logs results from the sl4j bundle within ESF. Information in this log file is reported from logging statements within the ESF framework.

If the ESF process is running and the logs files are clear of errors, the ESF framework is working correctly on the target system.

ESF Installation

This section provides instructions for installing ESF manually. The following steps outline how to install ESF on a Raspberry Pi.

Installing ESF with Debian Package

To install ESF on a Raspberry Pi, first make sure the device has the latest Raspbian image. Once the image is installed, boot the device and start a shell session.

ESF requires Oracle Java VM or Open JDK to be installed on the target device. Verify that Java 8 or above is installed with the following command:

java -version

If not, install it with the following command:

sudo apt-get update
sudo apt-get install oracle-java8-jdk

With Java installed, visit the ESF download page and locate the correct Debian package for the target system. Download the package and copy to the the Raspberry Pi.

Once the package is on the target device, ESF can be installed with the following command:

🚧
The first two 'apt-get' steps will update and upgrade the system. Skipping these steps may lead to unexpected installation problems.

🚧
In the latest Raspbian releases, the default network manager should be disabled before installing ESF, typing the following command:
sudo systemctl disable networking
Moreover, the wireless interface is disabled by default. Enable it typing the following command:
sudo rfkill unblock all

🚧
The installation process will attempt to remove previously installed versions of ESF. It is important not to run ESF during installation.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get purge dhcpcd5
sudo apt-get remove network-manager
sudo apt-get install gdebi-core
sudo gdebi esf_*.deb
sudo reboot

Once the Raspberry Pi has finished rebooting, verify that ESF is running as expected.

Installing ESF with RPM

For non-Debian based systems, ESF is installed with an RPM package. Visit the ESF download page to find the correct installation file for the target system.

Once the installation file has been copied to the target system, ESF can be installed with the following command:

🚧
The installation process will attempt to remove previously installed versions of ESF. It is important not to run ESF during installation.

sudo rpm -ivh ./esf_*.rpm
sudo reboot

Once the target device has finished rebooting, verify that ESF is running as expected.

ESF on Docker

ESF is also distributed as a Docker container based on RHEL Atomic 7.4 and CentOS 7.

To run the container, detached, execute:

# Replace <image> with either esf-rhel or esf-centos
docker run -d -p 80:80 -t <image>:latest

To list all the installed docker images type:

docker images

To list all the available instances (both running and powered off) type:

docker ps -a

To start and stop a docker instance, use:

docker stop <container id>
docker start <container id>

where ID is the identification number of the instance.

🚧
The ESF container is stateful. To preserve its configurations, use the docker stop and start commands.

Memory Size

The amount of memory assigned to the JVM that is running ESF can be adjusted with the following parameters that have to be passed when executing the Docker image:

-e ENV_XMS_SIZE='2048m' -e ENV_XMX_SIZE='2048m' -e ENV_XSS_SIZE='256k'

🚧
The memory assigned to ESF can be changed only when in development mode. In production mode, to change those values, a fingerprint reload is required.

Docker Container MAC Address

In order to prevent Stealing Link between different Docker installations, the developer should specify a different MAC address assigned to the ESF containers that connect to the same Cloud instance.

This can be achieved specifying the following property in the docker run command:

--mac-address <MAC address>
# parameter format: 12:34:56:78:9a:bc
# Be aware that Docker does not check if manually specified MAC addresses are unique.

🚧
In order to maintain a proper container functionality, the MAC address should not be changed across container restarts.

Logging

The ESF container log can be inspected using the following command:

docker logs <container id>

The user can specify a maximum size of the log size handled by the host, specifying the following parameter when invoking the ESF Docker container:

--log-opt max-size=50m

VPN Support

In order to have the VPN client running in ESF properly working, the --privileged option has to be specified during the ESF Docker image start.

Access to the container terminal

To access to the shell inside the container, run the following commad:

docker exec -it <container id> /bin/bash