Based upon IOx version 1.4 and EFM 1.1 and above.

Problem Description

The IOx EFM Broker is not initially configured for any upstream connection and only listens on port 8080 (http) for incoming connections[1]. As described in the EFM IOx Installation Guide, it is necessary that the following steps are taken to assure the incoming connection is ready:

IR829/IR809

1. For the IR809/IR829 it is recommended setting the EFM Application Ethernet ports to IOx-NAT so restarts of the application do not change the IP Address. In addition, unless the DHCP Pool for the IOX GuestOS is globally routable, a NAT statement needs to be defined to reach the specific ports for the IOx GuestOS and in particular for the EFM inbound broker listening ports (for example 8080 for http and 8484 for https).
2. On any other node, usually the next node upstream, it is necessary to define a broker to broker communication to the EFM IOx broker.

IE4000:

NAT statements are not applicable since the IP Address is defined by the following commands in the switch configuration:

iox

 host ip address 10.228.219.200 255.255.255.128 vlan 1

 host ip default-gateway 10.228.219.129

Solution

Deployment questions:

1. Is there a large number of edge hosts that need to connect to an upstream node?
2. For security reasons we recommend using https connections, but will the edge node certificates be installed on the IOx edge node to support this?
3. All communications are expected to be outbound?

We are not saying not to configure the NAT statement for inbound connections or installing the certificates to support inbound https connections. But there may be use cases where it does not justify the effort to reduce time or man hours for the task.

As alternative to installing the self-signed certificates and defining the NAT statements for inbound connections, it is possible to install a file that defines the upstream broker connection under the App-DataDir/upstream folder.

Using the ioxclient, it is possible to script the installation of the upstream connection or connections file(s).

Notes:

1. For each upstream broker connection, a unique file is created in the App-DataDir/upstream folder.
2. Remember that the node names defined in the connection must be unique. Therefore at least the edge node name must change for each connection to the same upstream broker.
3. The process described below only works on versions 1.1 and greater due to internal file structure are different and the configuration files are not located in the data partition of the application container.

Generating the upstream connection definition file

For every broker to broker connection in the EFM we need to define the following atttributes:

1. The Upstream broker name on this connection[2]
2. The Local Broker name on this connection
3. The URL to be used for the upstream connection. All broker to broker URL must end in “/conn”. For example, https://192.168.24.101:443/conn. [3]
4. Define if the connection is enabled at startup. True for enabled, false for disabled.

A text file needs to be created with these attributes in the following format (in a single line). The name of the file is the same as the Upstream broker name for consistency. Replace the following placeholders:

1. <upstreamName> with Upstream broker name on this connection
2. <localName> with Local Broker name on this connection
3. <upstreamURL> with the upstream broker URL, including the port and terminating in “/conn”.

{"name": "<upstreamName>", "brokerName": "<localName>", "url": "<upstreamURL>", "enabled": true}

For example:

File name: efmFogNode

{"name": "efmFogNode", "brokerName": "efmIR829edge", "url": "https://192.168.14.101:443/conn", "enabled": true}

Uploading the upstream broker connection file              

There are two ways to modify the EFF application configuration, the first using the Local Manager UI and the second is the ioxclient. The ioxclient allows for automation through scripting if needed.

Installing and upstream broker connection file using the Local manager

Connect via a web browser to the IOx router to the defined port for the Cisco IOx Local Manager. 

For usage of the local manager UI you have to use a browser to connect to the IOx device using the https connection to the port 8443. You have to log into the UI using the required credentials and the

Once logged in, the interface should show the Applications by selecting the Applications tab.

The EFM application is assumed to be installed and running, before we can make changes to the broker configuration file we must first stop the application. Simply select Stop in the Local Manager UI.

After the application has stopped, select the application name “efm” in the tabs.  This will expose additional tabs underneath to allow for more functions. Select the “App-DataDir” tab.

This application directory App-DataDir contains all configuration files and installed links.

First upload the server certificate by selection of the Upload button below the file list. Enter the target path upload/efmFogNode into the Path edit field of the pop up window. Pay attention not to forget the folder name in the path. Then hit the browse button in the pop up window and select the server certificate file in your local file system. After selecting of the Ok button the Local Manager will create a folder named efmFogNode in the upload directory.

To verify the files have been uploaded, you may check the content of the upload folder by selecting the upstream folder in the UI.

Now we start the application by select the Applications main management tab and the Start button for the eff application.

The broker will now start and try to connect the upstream broker as defined in the upstream file efmFogNode.

To verify that the broker is connected or connecting to the upstream broker, you may check the broker log file broker.log from the Logs tab inside the EFM management tab. There should line indicating that it was successfully connected to the upstream broker. An alternative is using the EFM System Administrator, selecting the upstream broker in the Brokers pane and expanding to see if the edge broker is shown underneath.

2017-12-19 21:07:11 INFO [upstream] - Successfully connected to the upstream broker 'efmFogNode' 

Installing and upstream broker connection file using the ioxclient

The EFM application is assumed to be installed and running, before we can make changes to the broker configuration file we must first stop the application. To stop the application type: 

ioxclient application stop EFM

Upload the upstream broker connection file using the ioxclient command: 

ioxclient application appdata upload EFM efmFogNode upstream/efmFogNode

Now we start the application:

ioxclient application start EFM

To verify that the broker is connected or connecting to the upstream broker, you may check using the Local Manager the broker log file broker.log from the Logs tab inside the EFM management tab. There should line indicating that it was successfully connected to the upstream broker. An alternative is using the EFM System Administrator, selecting the upstream broker in the Brokers pane and expanding to see if the edge broker is shown underneath.

2017-12-19 21:07:11 INFO [upstream] - Successfully connected to the upstream broker 'efmFogNode'

[1]See the tech note Kinetic EFM - Installing Certificates to support HTTPS for C-Broker on IOXto install the SSL certificates in order to also listen to port 8484 (https).

[2]In the EFM and DSA IoT architecture, the broker names defined in a connection are not unique to the node, but only used per connection. They must be unique names between the same brokers.

[3]The URL can use a numeric IP address. The current EFM IOx package does not contain an /etc/resolv.conf or obtain it from the GuestOS and therefore cannot use DNS for name resolution.