Edge Configuration Parameters

edge.env parameters list

Following is an explanation of the possible environment parameters that can be configured for your Edge network. The parameters come from an example edge.env file with comments. If a parameter is not listed here, then it is strongly advised NOT to change that parameter value manually.

The edge.env file can be found on your edge device at /var/ability/config/edge.env by default upon device creation. Please note that developers need to alter the Edge type variable for production, however the default settings are sufficient for development. In production they should tailor the network settings to the customer’s network environment as needed.

Azure IoT Hub-related properties

DPS_PROVISIONING_HOST

The host name of Azure DPS service. As of 2019-07-26 the global DPS server is used in all deployments.

DPS_ID_SCOPE=0nexxxxxxxx

DPS Id Scope of your Platform Instance

DEVICE_ID

Certificate

CERT_FILE=/var/ability/certs/edgedevice-cert.pem

KEY_FILE=/var/ability/certs/edgedevice-key.pem

Type definition

Information model type definition. Must be already registered in the corresponding type registry

EDGE_TYPE=abb.ability.device.edge.sample@2

Modules

Bootstrap proxy software image. It will be replaced with the version specified in your type definition when it gets delivered to your Edge.

EDGEPROXYIMAGE=abbability.azurecr.io/edge/proxy:2.4.15

The environment variable DOCKER_SERVICE_CREATE_TIMEOUT can be used to override the default service creation time out. In case of dealing with slower devices or networks, the timeout has to be increased to make sure service creation does not time out continuously.

DOCKER_SERVICE_CREATE_TIMEOUT=300000

Registry - The following shouldn't change for now:

IMAGEREGISTRIES={
    "abb": {
        "serveraddress":"https://abbability.azurecr.io",
        "username":"15439bb4-e82b-4f46-bbc1-810d51b3b8c0",
        "password":"3ZWyeikV1fGaR3W/ht+163Q+tUIVylc12Mx7L3nWTrg="
    }
}

Volumes

MODULES_VOLUME=/var/ability/modules

MQTT_VOLUME=/var/ability/mosquitto

MQTT_AUTH_VOLUME=/var/ability/mqtt_auth

Others

ACL_ALLOWED_SERVER_NAMES="^.+\\.core\\.windows\\.net$ ^.+\\.azure-devices.net$"

If a transparent proxy for outgoing traffic is installed (--with-traffic-acl), allow only HTTP/S traffic to these white-listed server name regexes. The value must be a quoted string of server names, separated with a space. Remember to escape back slash.

SYS_TRAIL_AGGREGATOR_CA_PEM="/etc/rsyslog-ca.pem"

Install the system journal and audit log aggregator during initial setup (setup.sh --audit). Location of PEM-encoded CA anchor for verifying the aggregator.

SYS_TRAIL_AGGREGATOR_HOST=abb-ability-edge-development-sys-log-dummy-certificate

Host name of the aggregator (it must not be an IP address). Point the value to a non-existent host to avoid using a log aggregator.

SYS_TRAIL_AGGREGATOR_PORT=6514

Port number of the TLS-capable syslog TCP service running on the aggregator. Point the value to an arbitrary port number to avoid using a log aggregator.

BLOCK_INCOMING_CONTACT_ON_IFACE=eth1

The typical configuration of an Edge computing device comes with two network interfaces - one that offers connectivity to LAN, and the other that offers connectivity to the Internet. This configuration item helps to filter incoming IP packets whose source address has been altered by a compromised upstream router and improbably manages to bypass OS built-in IP spoofing defence as well. Business units are advised to carefully inspect the network interface naming convention employed by the OS, and then to customize this configuration value accordingly.

LAYER2_CONNECTIVITY_HOST_IFACE

Layer 2 connectivity is prepared in a specialized container network. Depending on data in the IM, eligible containers will be granted direct access to the data link layer, to enable usage of sophisticated networking tricks such as IP multicast. The default values serve as an example, and result in a non-functional layer-2 connectivity unless they are further customized by business units.

LAYER2_CONNECTIVITY_HOST_IFACE is the name of the network interface on the container host that offers layer-2 network connectivity. It must offer LAN connectivity exclusively and must not offer internet connectivity. Business units are advised to carefully inspect the network interface naming convention employed by the OS, and then to customize this configuration value accordingly:

LAYER2_CONNECTIVITY_HOST_IFACE=eth2

LAYER2_CONNECTIVITY_GATEWAY_IP is the IP address of network gateway on the host network interface:

LAYER2_CONNECTIVITY_GATEWAY_IP=203.0.113.1

LAYER2_CONNECTIVITY_SUBNET_CIDR is the IP address block corresponding to the host network interface:

LAYER2_CONNECTIVITY_SUBNET_CIDR=203.0.113.0/24

LAYER2_CONNECTIVITY_CONTAINERS_CIDR is the IP address block vacant within the host network and ready to be allocated to containers as they come online:

LAYER2_CONNECTIVITY_CONTAINERS_CIDR=203.0.113.2/32

Assign default container network bridge to this CIDR block with gateway being the IP address. It must not overlap with any other CIDR blocks used on the container host:

CONTAINER_BRIDGE_IP_CIDR="172.17.0.1/16"

Assign NAT network that offers LAN access to this CIDR block. It must not overlap with any other CIDR blocks used on the container host:

LAN_ACCESS_NAT_CIDR="172.19.0.0/16"

Assign NAT network that offers Internet access to this CIDR block. It must not overlap with any other CIDR blocks used on the container host:

INTERNET_ACCESS_NAT_CIDR="172.20.0.0/16"

These network names are not dynamic configuration items, do not change them:

EDGENETWORK_EXT=iot-internet
EDGENETWORK_INT=iot-lan
EDGENETWORK_MACVLAN=iot-layer2

SSL_ENGINE=/files/libSecStoreEngine.so​

File path to OpenSSL engine program as seen from the Edge Proxy container. The program is maintained by the Edge Security team and supplies a TPM-sealed certificate key during the TLS handshake with Azure DPS and the IoT hub in production setup. If the value is empty, then the Edge Proxy will expect to find the certificate (granted by "CommonDevQAPlatform" CA) and plain text key to complete the TLS handshakes. Please note that this mode of operation is reserved for development and QA activities. A native software library installed on the container host interacts with TPM hardware in order to perform TLS client duties. The software library on the container host is granted to the proxy software container as a file mapping. The parameter SSL_ENGINE is the absolute path at which proxy software can locate the software library in its container.

LOGGER_LEVEL

Determines proxy software log verbosity. From least to most, the valid values are:

• "error"
• "warn"
• "info"
• "verbose"
• "debug"
• "silly"

The value "silly" tells proxy software to generate verbose log output that is helpful for Edge development and diagnosis. If left empty, the log level will be "info" by default.​

Time Zone

To set a default system time zone, run the following command:

rm /etc/localtime && ln -sf /usr/share/zoneinfo/Europe/Helsinki  /etc/localtime

Substitute the path to the zoneinfo file to the desired geolocation; the UTC time zone file is located at /usr/share/zoneinfo/UTC.

Time Synchronization

A fresh installation of the Ubuntu system automatically uses internet time reference to synchronize its clock. In case an internal time reference is preferred, edit /etc/systemd/timesyncd.conf and replace its content with:

[Time]
NTP=my-time-server.com

TIP

ABB It provides time.abb.com for any computers on the ABB Corporate Network.
If your Edge node is behind an internal firewall, insure the firewall supports NTP network access.

Then run the command systemctl restart systemd-timesyncd to make new changes effective immediately. Keep in mind that NTP synchronizes the system clock by altering it in tiny increments, hence a skewed system clock may take up to an hour to catch up with the standard time.

DHCP/Static IP for Network Interface

During OS setup, the installer prompts the user to choose an active/online network interface for automated DHCP configuration. Netplan is the default utility for configuring networking on Ubuntu 18.04. You can also select other network configuration tools if Netplan does not meet your needs, such as NetworkManager or System-networkd. Toward end of the setup the name of the network interface is written down in /etc/netplan/01-netcfg.yaml, as in this example:

network:
  version: 2
  renderer: networkd
  ethernets:
     enp0s31f6:
       dhcp4: true
       dhcp6: true

If this setup is already satisfactory, then the network is likely already online (inspect the output of the command ip a), and the network setup is ready for IoT Edge.

However - if the network interface was not chosen during OS setup, then run networkctl list to retrieve the names (LINK) of available network interfaces:

root@hzgl-tiny:/sys/class/net# networkctl list
IDX LINK             TYPE               OPERATIONAL SETUP
  1 lo               loopback           carrier     unmanaged
  2 enp2s0           ether              off         unmanaged
  3 enp0s31f6        ether              carrier     unmanaged
  4 docker0          ether              no-carrier  unmanaged
  5 docker_gwbridge  ether              routable    unmanaged
 17 veth15429c6      ether              degraded    unmanaged
 30 vetha620ecd      ether              degraded    unmanaged

Be aware that the OPERATIONAL column almost never indicates whether a cable is plugged into the corresponding ethernet card, therefore if the computer has more than one ethernet card, it is very important to determine which card has a cable plugged into it. Use the ethtool LINK_NAME command for this purpose and look for keyword "Link detected: yes", which signals that a cable is plugged in:

root@hzgl-tiny:/sys/class/net# ethtool enp0s31f6
Settings for enp0s31f6:
        Supported ports: [ TP ]
       ...
        ....
        Link detected: yes

Then, take a note of the link name (such as enp0s31f6), and instruct the OS to configure it automatically via DHCP by editing /etc/netplan/01-netcfg.yaml according to the example above, or specify a fixed IP address:

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s31f6:
      dhcp4: no
      dhcp6: no
      addresses: [192.168.1.2/24]
      gateway4: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8,8.8.4.4]

After making changes in the YAML files, run netplan apply to apply the DHCP/fixed IP settings, and shortly after the very latest network address will be presented in the output of the command ip a.

Be aware that the configuration above does not apply to Ubuntu 16.04 LTS, which is no longer supported by IoT Edge.

Edge Connection to the Internet

The standard Edge installation does not permit incoming connections from a WAN network adapter, and does not permit packets coming from public IP addresses on all network adapters. Business line modules can communicate freely over available LAN IP ranges and may open some port(s) to accept incoming connections from a LAN.

The standard Edge installation makes outgoing HTTPS connections to the Azure device provisioning service, Azure BLOB storage service, and Azure IOT hub. If your operating environment uses a network proxy, then the outgoing HTTPS connections to Azure will be made over the network proxy by default.

Block Traffic to Certain Ports

The product installer will configure a large set of firewall rules and it will erase all firewall rules related to docker container setup. Therefore, business units should consider manipulating firewall rules after running the product installer, and exercise extreme caution in the process.

To temporarily block incoming traffic to a certain port until the next system reboot, run the command: iptables -A INPUT -p tcp --dport PORTNUMBER -j DROP. Persistence of firewall settings across system reboots can be achieved by running the command iptables-save > /etc/iptables/rules.v4 && ip6tables-save > /etc/iptables/rules.v6.