Running a Cisco IOx App on a Cisco IE3x00 Series Switch

This document describes how to enable IOx, configure an IOx application, and run an IOx application on Cisco Industrial Ethernet 3x00 switches. In Cisco IOS-XE Release 17.2.1, application hosting supports docker containers.

An additional license is not required to run IOx on Cisco IE3400 and CiscoIE3400H Switches as IOx is included in the Network Essentials feature set.

Supported Platforms

  • Cisco Industrial Ethernet 3400 Rugged Series (IE3400)
  • Cisco Industrial Ethernet 3400 Heavy Duty Series (IE3400H)
  • Cisco Industrial Ethernet 3300 Rugged Series (IE3300) with Hardware revision V06 and above.

Note: Use the “show inventory” CLI to find the H/W revision.

Before you begin, ensure that Cisco IOS-XE Release 17.2.1 is running on your switch. For more information about the Cisco IE3400 and Cisco IE3400H Switches, see the following documentation:

Cisco IE3300

https://www.cisco.com/c/en/us/support/switches/catalyst-ie3300-rugged-series/series.html

Cisco IE3400

https://www.cisco.com/c/en/us/support/switches/catalyst-ie3400-rugged-series/series.html#~tab-documents

Cisco IE3400H

https://www.cisco.com/c/en/us/support/switches/catalyst-ie3400-heavy-duty-series/series.html#~tab-documents

Platform Support Matrix

Platform CPU Architecture CPU (Units) Memory (MB) Storage (MB)
IE-3300 ARM 64-bit 1400 1248 3800

System Resources Available for IOx

For the system resources requirements, see the Platform Matrix on DevNet:

https://developer.cisco.com/docs/iox/#!platform-support-matrix/platform-support-matrix

Formatting an SD Card and Enabling IOx

An SD card must be formatted with the ext4 file system before you can enable Cisco IOx on the card. Note that a Cisco IE3400 and Cisco IE3400H Switch cannot boot from a card that is formatted with this file system.

Formatting an SD card permanently deletes any data that is on that card.

To format an SD card:

  1. Put the SD card in the card reader on the device.
  2. Enter the format sdflash: ext4 command to format the SD card with the ext4 file system. Leave the card in the drive when the operation completes.
  IE3400# format sdflash: ext4
  Format operation may take a while. Continue? [confirm]
  Format operation will destroy all data in "sdflash:". Continue? [confirm]
  format completed with no errors

  Format of sdflash: complete
  IE3400#

Enabling Cisco IOx

IOx is disabled by default and needs to be enabled. During enablement, IOx copies a number of essential files to the SD card. Disable IOx before removing the card.

Use an SSH client to access the switch, and enter the following commands to enter terminal monitor mode and enable IOx:

  • term mon
  • conf t
  • iox
   IE3400# conf t
   IE3400(config)# iox
   Warning: Do not remove SD flash card when IOx is enabled or errors on SD device could occur.
   Apr  9 00:50:38.145: %UICFGEXP-6-SERVER_NOTIFIED_START: R0/0: psd: Server iox has been notified to start
   Apr  9 00:51:44.766: %IM-6-IOX_ENABLEMENT: R0/0: ioxman: IOX is ready.

Enter the following commands to verify that CAF, IOxman, Libvirtd, and Dockerd are in Running state:

  • end
  • show iox
   IE3400(config)# end
   IE3400# show iox
   IOx Infrastructure Summary:
   ---------------------------
   IOx service (CAF) 1.10.0.1 : Running
   IOx service (HA)          : Not Supported
   IOx service (IOxman)      : Running
   IOx service (Sec storage) : Not Supported
   Libvirtd   1.3.4          : Running
   Dockerd    18.03.0        : Running

Configuring the AppGigabitEthernet Interface

For network connectivity to IOx applications, Cisco IE3400 and Cisco IE3400H Switches provide an internal virtual switch interface called AppGigabitEthernet1/1. This interface connects to an internal Linux bridge to which the different IOx apps are connected. Apps can have one or more interfaces and be placed in any VLAN.

Note: Only L2 mode ("switchport") is supported for an AppGigabitEthernet1/1 interface.

Enter the following commands to configure the AppGigabitEthernet1/1interface as a trunk and to allow the VLANs that IOx apps require:

  • conf t
  • interface AppGigabitEthernet1/1
  • switchport mode trunk
  • switchport trunk allowed vlan 1-4
  • end
IE3400# conf t
Enter configuration commands, one per line. End with CNTL/Z.
IE3400(config)# interface AppGigabitEthernet1/1
IE3400(config-if)# switchport mode trunk
IE3400(config-if)# switchport trunk allowed vlan 1-4
IE3400(config-if)# end
IE3400#

Before you can install an IOx app on a device, you must configure the appid, VLANs, and the IP address for the app. The appid parameter is string that you enter to identify the app. You can configure one app with several interfaces (for example, one for management and one for monitoring).

  • Network interfaces are represented as eth0, eth1… inside the app.
  • Configurable app resources include CPU, Memory, VCPU(s), and persistent disk.

Here is an example of the configuration that is needed. In this example:

  • appid is configured as iperf3.
  • eth0 network interface is in vlan 1.
IE3400#conf t
Enter configuration commands, one per line.  End with CNTL/Z.
IE3400(config)#app-hosting appid iperf3
IE3400(config-app-hosting)#app-vnic AppGigabitEthernet trunk
IE3400(config-config-app-hosting-trunk)#vlan 1 guest-interface 0 !place eth0 in Vlan 1
IE3400(config-config-app-hosting-vlan-access-ip)#guest-ipaddress 192.0.2.11 netmask 255.255.255.0
IE3400(config-config-app-hosting-vlan-access-ip)#exit
IE3400(config-config-app-hosting-trunk)#exit
IE3400(config-app-hosting)#app-default-gateway 192.0.2.1 guest-interface 0
IE3400(config-app-hosting)#app-resource profile custom
IE3400(config-app-resource-profile-custom)#cpu 1400
IE3400(config-app-resource-profile-custom)#memory 256
IE3400(config-app-resource-profile-custom)#vcpu 2
IE3400(config-app-resource-profile-custom)#end
IE3400#

Installing and Starting an App

This section explains how to copy, install, activate, and start an app.

If changes are to be made to the IOx application (network, resources, and so forth), the IOx application needs to be stopped, deactivated, activated where changed will be made and then the IOx application can be started.

Follow these steps in terminal monitor mode:

  1. Enter this command to copy the app package file to flash or sdflash, where file is the path and name of your app package:

    IE3400# copy file.tar [flash|sdflash]:

  2. Enter this command to install the app package, where appid is the ID that is assigned to the app:

    IE3400# app-hosting install appid appid package [flash|sdflash]:file.tar

  3. Enter this command to activate the app:

    IE3400# app-hosting activate appid appid

  4. When you see the message that the app is activated successfully, enter the following command to start the app:

    IE3400# app-hosting start appid appid

    Here is an example:

    IE3400# term mon
IE3400# copy http://192.168.3.3/tftp/iperf3_eft_dockerimage_aarch64.tar flash:
Destination filename [iperf3_eft_dockerimage_aarch64.tar]?
Accessing http://192.168.3.3/tftp/iperf3_eft_dockerimage_aarch64.tar...
Loading http://192.168.3.3/tftp/iperf3_eft_dockerimage_aarch64.tar !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7281152 bytes copied in 3.901 secs (1866195 bytes/sec)
IE3400# app-hosting install appid iperf3 package flash:iperf3_eft_dockerimage_aarch64.tar
Installing package 'flash:iperf3_eft_dockerimage_aarch64.tar' for 'iperf3'. Use 'show app-hosting list' for progress.
IE3400#
Apr  9 05:28:59.605: %IM-6-INSTALL_MSG: R0/0: ioxman: app-hosting: Install succeeded: iperf3 installed successfully Current state is   DEPLOYED
IE3400# app-hosting activate appid iperf3
iperf3 activated successfully
Current state is: ACTIVATED
IE3400#
Apr  9 05:30:32.088: %IM-6-ACTIVATE_MSG: R0/0: ioxman: app-hosting: Activate succeeded: iperf3 activated successfully Current state is in ACTIVATED
IE3400# app-hosting start appid iperf3
iperf3 started successfully
Current state is: RUNNING