Generic Profiles

ESF Generic Profiles are ESF installers that do not contain gateway specific customisations.
Generic profiles can be downloaded from ESF download page, and have the following filename patterns:

Installer typeWith Network Management SupportWithout Network Management Support
Debianesf-generic_<ESF version>_<arch>.debesf-generic-nn_<ESF version>_<arch>.deb
RPMesf-generic-<ESF version>-1.<arch>.rpmesf-generic-nn-<ESF version>-1.<arch>.rpm

Where <arch> is one of the supported architectures, for example x86_64, arm32, and arm64.

A generic ESF profile can work on systems that have available the dependencies listed in the packages dependencies section, and that have at least one physical Ethernet interface.

Profiles with network management support include an integration with NetworkManager; a commonly available tool for managing Linux networking. ESF leverages this tool for network configuration functionalities.

Installers with the nn are profiles without network management support that do not bundle the ESF Network Manager: all the network configurations need to be done outside of ESF. Functionalities missing in NN profiles compared to the full ESF profiles:

  • Networking interfaces configuration
  • Firewall configuration management
  • Network Threat management

📘

Note

Profiles without network management fully support network communication (e.g. establishing a connection to a cloud platform). They do not support configuring network interfaces (e.g. setting the IP address). In this case network configuration must be performed with external tools.

Initial network configuration

During the installation of a generic profile with network management support, the initial network configuration will be generated dynamically using the rules described below:

  • The existing wired and wireless Ethernet network interface names are sorted in ascending lexicographic order.

  • The first wired Ethernet interface in the list will be configured as follows:

    • Status: Enabled for WAN
    • Configure: Using DHCP
  • All other network interfaces will be disabled.

For example, if the system contains the following wired Ethernet interfaces: enp3s0, eno1, ens2 and a wireless Ethernet interface named wlp2s0, then eno1 will be enabled for WAN in DHCP client mode, and all other network interfaces will be disabled.

🚧

Predictable network interface naming

On systems that do not use systemd's predictable interface naming scheme (see Freedesktop reference) the primary network interface name might change whenever a re-enumeration is triggered (for example, after a reboot or after plugging in an external network adapter).

The advice is to install ESF on systems that use a reliable naming convention for network interfaces. All Eurotech devices support this feature.

Systemd consistent network interface naming assigns the name prefix based on the physical location of the device, see Understanding the Predictable Network Interface Device Names for further reference.

Initial firewall configuration

The initial firewall configuration will be as shown in the screenshot below. The rules for tun0 are meant to allow access to SSH and ESF Web UI from a VPN connection.

Please note that installing an ESF generic profile with network configuration support will replace the current network and firewall configuration with the one shown above.

Other ESF services

As said before, ESF generic profiles do not contain gateway specific customizations, this implies that the values of some configuration parameters may be incorrect and/or missing and must be manually filled after installation, for example the user might want to:

  • Configure the other network interfaces, if any.
  • Setup additional firewall rules.
  • Edit the /opt/eurotech/esf/framework/jdk.dio.properties with the correct GPIO mappings.
  • Set the device GPS port in the configuration of PositionService serial provider.

Package dependencies

To have all the ESF features working, the following dependencies are required:

General: setserial, zip, gzip, unzip, procps, usbutils, socat, gawk, sed, inetutils-telnet, mmc-utils (optional).

Security: polkit or policykit-1, ssh or openssh, openssl, busybox, openvpn.

Bluetooth: bluez or bluez5, bluez-hcidump or bluez5-noinst-tools.

Time: ntpdate, chrony, chronyc, cron or cronie.

Networking (only needed for profiles with network management support): network-manager or networkmanager, bind9 or bind, dnsmasq or isc-dhcp-server or (dhcp-server and dhcp-client), iw, iptables, modemmanager, hostapd, wpa-supplicant, ppp, iproute2.

Logs: logrotate.

Ansible: ansible or python-ansible or python3-ansible or python3-ansible-core.

Gps: gpsd.

Fail2ban & AIDE: python3-systemd or python-systemd, libpam-modules or pam-plugin-succeed-if, python3-fail2ban or python-fail2ban or fail2ban, aide.

Python: python3 or python.

Java: openjdk-17-jre-headlessortemurin-17-jdkorzulu-jre-x86-64orzulu-17-jre-x86-64 or zulu-17-jre-arm or zulu-jre-17 or openjdk-8-jre-headless or temurin-8-jdk or zulu-jre-arm or zulu-jre-8 .

Others (only for DEB installers): dos2unix, libtirpc3.

Java Heap Memory Assignment

ESF's Generic profile incorporates an adaptive heap memory allocation system during installation. The allocation follows a formula based on your gateway's available memory. If your gateway has less than 1024MB of RAM, ESF will set -Xms and -Xmx to 256MB. For gateways with more than 1024MB, one-quarter of the total RAM will be assigned to -Xms and -Xmx.

How to define GPIO mappings in jdk.dio.properties

The default configuration for the /opt/eurotech/esf/framework/jdk.dio.properties GPIO mapping in the generic installers is defined as follows:

#
# Copyright (c) 2023 Eurotech and/or its affiliates
#
#  All rights reserved.
#

#
# PLEASE FILL THE FILE WITH THE CONFIGURATION FOUND IN DOCUMENTATION
#

gpio.GPIOPin = initValue:0, deviceNumber:0, direction:3, mode:-1, trigger:3
uart.UART = baudRate:19200, parity:0, dataBits:8, stopBits:1, flowControl:0

The device-related guides allow to copy-paste a specific configuration. However, this is not recommended as the pin enumeration may change if new peripherals are attached to the system.

To discover the pin enumeration please refer to the device's manual. Possible ways to inspect GPIO devices are:

  • listing GPIO devices in /dev
  • listing GPIO devices in /sys/class/gpio
  • leveraging setserial or dmesg

In the following, an example enumeration found on the ReliaCOR 40-12 where GPIO devices have a symlink in /dev.

ls -al /dev/G*

lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_0 -> /sys/class/gpio/gpio543
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_1 -> /sys/class/gpio/gpio544
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_2 -> /sys/class/gpio/gpio545
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_3 -> /sys/class/gpio/gpio546
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_4 -> /sys/class/gpio/gpio547
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_5 -> /sys/class/gpio/gpio548
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_6 -> /sys/class/gpio/gpio549
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPI_7 -> /sys/class/gpio/gpio550
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_0 -> /sys/class/gpio/gpio535
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_1 -> /sys/class/gpio/gpio536
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_2 -> /sys/class/gpio/gpio537
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_3 -> /sys/class/gpio/gpio538
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_4 -> /sys/class/gpio/gpio539
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_5 -> /sys/class/gpio/gpio540
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_6 -> /sys/class/gpio/gpio541
lrwxrwxrwx 1 root root 23 Nov 27 13:17 /dev/GPO_7 -> /sys/class/gpio/gpio542

In this example, this will lead to the following jdk.dio configuration file:

gpio.GPIOPin = initValue:0, deviceNumber:0, direction:3, mode:-1, trigger:3
uart.UART = baudRate:19200, parity:0, dataBits:8, stopBits:1, flowControl:0

# input
543 = deviceType: gpio.GPIOPin, pinNumber:543, name:GPI_0
543 = deviceType: gpio.GPIOPin, pinNumber:544, name:GPI_1
545 = deviceType: gpio.GPIOPin, pinNumber:545, name:GPI_2
546 = deviceType: gpio.GPIOPin, pinNumber:543, name:GPI_3
547 = deviceType: gpio.GPIOPin, pinNumber:547, name:GPI_4
548 = deviceType: gpio.GPIOPin, pinNumber:548, name:GPI_5
549 = deviceType: gpio.GPIOPin, pinNumber:549, name:GPI_6
550 = deviceType: gpio.GPIOPin, pinNumber:550, name:GPI_7

# output
535 = deviceType: gpio.GPIOPin, pinNumber:535, name:GPO_0
536 = deviceType: gpio.GPIOPin, pinNumber:536, name:GPO_1
537 = deviceType: gpio.GPIOPin, pinNumber:537, name:GPO_2
538 = deviceType: gpio.GPIOPin, pinNumber:538, name:GPO_3
539 = deviceType: gpio.GPIOPin, pinNumber:539, name:GPO_4
540 = deviceType: gpio.GPIOPin, pinNumber:540, name:GPO_5
541 = deviceType: gpio.GPIOPin, pinNumber:541, name:GPO_6
542 = deviceType: gpio.GPIOPin, pinNumber:542, name:GPO_7