Deploying IOx Applications

Guidelines for IOx Applications

This section provides guidelines for deploying IOx applications.

One of the most commonly used applications is Cisco Cyber Vision. See the Cisco Cyber Vision support page for more information.

Cisco Catalyst IE3400 Rugged, IE3400 Heavy Duty, and IE3300 Rugged Series Switches support both LXC and Docker based applications with ARM64 architecture.

Both IPv4 and Ipv6 configurations are supported.

Place the application package or tar file in the flash or SD card in the IOS partition for configuring with the CLI.

Use the application Gigabit Ethernet interface (AppGig1/1) on the switch for forwarding the Layer 2 application traffic. Ensure that the interface is up on the switch and configured for a trunk port.

When configuring applications:

  • Configure Layer 2 interfaces with Ap1/1 and VLAN with an IP address in same VLAN network.

  • Configure gateway interfaces for IOx applications to an SVI or IP address in same network.

You can configure multiple guest or Layer 2 interfaces [0-63] for an application, and each interface can be placed in a different VLAN.

You can configure up to three gateway interfaces.

IOx infra supports configuring multiple gateways; you can configure one default gateway to support all the interfaces.

The application configuration allows options to configure Docker runtime options.

Limitations for IOx Applications

This section provides limitations for IOx applications:

  • Cisco IOx applications support IE3400/H, IE3300-8U2X, and IE3300-8T2X platforms.

  • The CCV sensor support on IE3300-8T2S and IE3300-8P2S is limited to hardware version 6 or later. Check the output of the show version command to see the hardware version.

Methods of Deploying IOx Applications

There are two methods of deploying IOx applications to a Cisco Catalyst IE3400 Rugged, IE3400 Heavy Duty, and IE3300 Rugged Series Switches:

  • IOS-XE CLI: The CLI that is part of the switch software for connecting to the switch on the device.

    You can use the CLI on an IOx-enabled device to manage the device and deploy applications. You do not need to enable the web server on the IOS-XE device.

    For more information, see Deploying IOx Applications Using the IOS-XE CLI.

  • Cisco IOx Local Manager (GUI): A platform-specific application that is installed on a host system as part of the installation of the Cisco IOx framework on that device.

    You can access Cisco IOx Local Manager from the Cisco Catalyst IE3400 Rugged, IE3400 Heavy Duty, and IE3300 Rugged Series Switches web-based user interface.

    For more information, see Deploy an Application using Cisco IOx Local Manager.

  • Cisco IOx Local Manager provides resource profiles, such as tiny, exclusive, default and custom. If you choose a custom profile, you can modify CPU, memory and disk values. See Methods of Deploying IOx Applications and Deploy an Application using Cisco IOx Local Manager.

The following sections in this document contain instructions for deploying IOx using each method.

Deploying IOx Applications Using the IOS-XE CLI

To deploy IOx applications using the IOS-XE CLI, you need to configure the application and then install, activate, and start it.

Figure 1. Example of IOx Deployment with Application

The preceding illustration shows an example configuration of an IOx network on a Cisco Catalyst IE3400 Rugged Series Switch. The dedicated interface AppGigabitEthernet1/1 for IOx support is configured as a trunk and is internally connected to a Linux bridge. In the example, a single application, Iperf_3, is assigned the IP address 192.168.0.2 to the guest interface. The default gateway is assigned on SVI LAN 10 with the IP address of 192.168.0.1. For an illustration without interface examples, see the section Configuring the Network and IOx in this guide.

Configure an Application Using the CLI

Enter the commands in the following procedure to configure an application using the IOS-XE CLI.


Note

The following procedure describes how to install and run the iPerf application.

Before you begin

SUMMARY STEPS

  1. enable
  2. configure terminal
  3. app-hosting appid iperf_3
  4. app-vnic AppGigabitEthernet trunk
  5. vlan 10 guest-interface 0
  6. guest-ipaddress guest_ip_address netmask|prefix number
  7. exit
  8. exit
  9. app-default-gateway default_gateway_address guest-interface guest_interface number
  10. end

DETAILED STEPS

  Command or Action Purpose

Step 1

enable

Example:

switch#enable

Enables privileged EXEC mode. Enter your password if prompted.

Step 2

configure terminal

Example:

switch#configure terminal

Enters global configuration mode.

Step 3

app-hosting appid iperf_3

Example:

switch(config)#app-hosting appid iperf_3

Configures an application name and enters application-hosting configuration mode.

Step 4

app-vnic AppGigabitEthernet trunk

Example:

switch(config-app-hosting)#app-vnic AppGigabitEthernet trunk

Configures AppGigabitEthernet trunk and enters application-hosting trunk-configuration mode.

Step 5

vlan 10 guest-interface 0

Example:

switch(config-config-app-hosting-trunk)#vlan 10 guest-interface 0

Configures a VLAN guest interface and enters application-hosting VLAN-access IP configuration mode. The configuration places Eth0 into vlan 10.

Step 6

guest-ipaddress guest_ip_address netmask|prefix number

Example:

  • IPv4

    (config-config-app-hosting-vlan-access-ip)#
guest-ipaddress 192.168.0.2 netmask 255.255.255.0

  • IPv6

    (config-config-app-hosting-vlan-access-ip)#
guest-ipv6address 2001::1 prefix 64

Configures a static IP address. The subnet for this IP address on the VLAN (in this example vlan 10) must match the subnet configured for the IP address assigned to vlan 10 interface. See the preceding examples.

Step 7

exit

Example:

switch(config-config-app-hosting-vlan-access-ip)#exit

Exits submode.

Step 8

exit

Example:

switch(config-config-app-hosting-trunk)#exit

You must enter exit again because of the nested submodes.

Step 9

app-default-gateway default_gateway_address guest-interface guest_interface number

Example:

switch(config-app-hosting)#app-default-gateway 192.168.0.1 guest-interface 0

Configures the default gateway for the application. The VLAN ID interface of the switch is used as the gateway.

Note

 

No more than three gateways are supported.

Step 10

end

Example:

switch(config-app-hosting)#end

Ends the session.

Configure Docker Run-Time Options

You can add a maximum of 30 lines of run time options. The system generates a concatenated string from line 1 through line 30. A string can have more than one Docker run time option.

When a run time option changes, do the following: Stop, deactivate, activate, and then start the application for the new run time options to take effect.

Before you begin

SUMMARY STEPS

  1. app-hosting appid iperf_3
  2. app-resource docker
  3. run-opts 1 "--entrypoint '/bin/sleep 10000'"
  4. exit
  5. end

DETAILED STEPS

  Command or Action Purpose

Step 1

app-hosting appid iperf_3

Example:

switch(config)#app-hosting appid iperf_3

Configures an application name and enters application-hosting configuration mode.

Step 2

app-resource docker

Example:

switch(config-app-hosting)#app-resource docker

Enters application-hosting docker-configuration mode.

Step 3

run-opts 1 "--entrypoint '/bin/sleep 10000'"

Example:

switch(config-app-hosting-docker)#run-opts 1 "--entrypoint '/bin/sleep 10000'"

Specifies the Docker run time options.

Step 4

exit

Example:

switch(config-app-hosting-docker)#exit

Exits application-hosting docker-configuration mode.

Step 5

end

Example:

switch(config-app-hosting)#end

Ends session.

Configure Application Resources

Complete the following steps to activate application hosting, which is required before resource changes take effect.

Before you begin

Check memory and storage using the command show app-hosting resource.

SUMMARY STEPS

  1. app-hosting appid iperf_3
  2. app-resource profile custom
  3. cpu value
  4. memory value
  5. persist-disk value
  6. end

DETAILED STEPS

  Command or Action Purpose

Step 1

app-hosting appid iperf_3

Example:

switch(config)#app-hosting appid iperf_3

Configures an application name and enters application-hosting configuration mode.

Step 2

app-resource profile custom

Example:

switch(config-app-hosting)#app-resource profile custom

Configures the custom application resource profile, and enters custom application resource profile configuration mode.

Note

 

Only the custom profile name is supported.

Step 3

cpu value

Example:

switch(config-app-resource-profile-custom)#cpu 500

Configures CPU units.

Step 4

memory value

Example:

switch(config-app-resource-profile-custom)#memory 256

Configures memory in megabytes.

Step 5

persist-disk value

Example:

switch(config-app-resource-profile-custom)#persist-disk 256

Configures disk space in megabytes.

Step 6

end

Example:

switch(config-app-resource-profile-custom)#end

Ends the session.

IOx Application Installation, Activation and Startup

After you configure an application in the IOS-XE CLI, you activate the application by taking it through three states.

You first install the application using the app-hosting install command, which after installation, the application moves to the deployed state. During installation, the sign verification of the application is checked, if the check is enbled. For more information, see the section IOX Application Sign Verification.

After installation, you activate the application using the app-hosting activate command. During activation, the application is assigned resources on the switch; activation fails if there are not enough resources available.

After activation, you move the application to the running state using the app-hosting start command. During start, the application interfaces are created and assigned IP addresses.


Note

You can check the state of the application at any point of installation, activation, or start by using the show app-hosting list command. You can use the show app-hosting details command to see a description of the application with IP allocation, resource allocation, and other details.

Install, Activate, and Start the Application

Complete the following commands to install, activate, and start the IOx application on the switch and to configure the interfaces.

Before you begin

You must have configured the network and the IOx application. See the section Configuring the Network and IOx.

SUMMARY STEPS

  1. app-hosting install appid application_name package application_filename
  2. (Optional) Confirm the application's installation and state by entering the show app-hosting list command:
  3. app-hosting activate appid application_name
  4. app-hosting start appid application_name

DETAILED STEPS

Step 1

app-hosting install appid application_name package application_filename

Example:

IE3400-2-2006#app-hosting install appid iperf_3 package flash:iperf_3_eft_dockerimage_aarch.tar

Installing package 'flash:iperf_3_eft_dockerimage_aarch.tar' for 'iperf_3'. Use 'show app-hosting list' for progress.

IE3400-2-2006#show app-hosting list
App id State
---------------------------------------------------------
iperf_3 INSTALLING

IE3400-2-2006#
Oct 12 21:51:58.285: %IOXCAF-6-INSTALL_MSG: Switch 1 R0/0: ioxman: app-hosting: iperf_3 installed successfully Current state is DEPLOYED

IE3400-2-2006#show app-hosting list
App id State
---------------------------------------------------------
iperf_3 DEPLOYED

Installs the application and moves it into the deployed state.

Step 2

(Optional) Confirm the application's installation and state by entering the show app-hosting list command:

Example:

switch #sh app-hosting list
App id                                   State
---------------------------------------------------------
iperf_3                                  DEPLOYED

Step 3

app-hosting activate appid application_name

Example:

switch# app-hosting activate appid iperf_3                           

Current state is: ACTIVATED

Activates the application and assigns it switch resources.

Step 4

app-hosting start appid application_name

Example:

switch# app-hosting start appid iperf_3   
iperf_3 started successfully
Current state is: RUNNING

IOX Application Sign Verification

You can check sign verification of a Cisco IOx application during its installation. Application package signature ensures that an application package is valid and that the one installed on the device comes from a trusted source.

The configuration keyword start is available under application-hosting application configurations. If you use this keyword, then IOx infra automatically activates and starts the application after installation. Otherwise, you must explicitly use and activate and start CLI commands to start the application.

IOx infra checks for a signature in the following cases:

  • When signature verification is enabled.

  • When IOx infra uses bootflash as storage; it then checks for a signature regardless of signature verification status.

  • If an application is using a restricted resource, such as secure storage.

If signature verification is enabled, and the application is not signed, the application will not be allowed to install, activate or start.

However you cannot run non-Cisco applications if signature verification is enabled. However, you can run unsigned non-Cisco applications if the following criteria are met:

  • Signature verification is disabled.

  • An SD card is used for storage instead of boot flash.

  • The application is not using a restricted resource.

Use the app-hosting verification enable command to enable sign verification and the app-hosting verification disable command to disable sign verification.

You can see whether signature verification is enabled by entering the command show app-hosting infra. 

switch# show app-hosting infra 
IOX version: 2.11.0.0
App signature verification: enabled
CAF Health: Stable
Internal working directory: /flash11/iox

Application Interface Mapping
AppGigabitEthernet Port # Interface Name Port Type Bandwidth
1 VirtEth KR Port - Internal 1G


CPU:
Quota: 33(Percentage)
Available: 0(Percentage)
Quota: 1400(Units)
Available: 0(Units)

switch#

Note

You can enable or disable sign verification at any time regardless of any installed application states.

IOx Application Command Examples

This section provides examples of IOS-XE CLI commands for IOx applications.

View Resources on the Switch

The command in the following example shows the maximum resources and available resources on the switch for all iox applications:

switch# show app-hosting resource 
CPU:
Quota: 33(Percentage)
Available: 0(Percentage)
VCPU:
Count: 2
Memory:
Quota: 1248(MB)
Available: 0(MB)
Storage space:
Total: 2548(MB)
Available: 268(MB)

The command in the following example shows the CPU quota in units, whether app signature verification is enabled on the switch for IOx: 

switch# show app-hosting infra 
IOX version: 2.11.0.0
App signature verification: enabled
CAF Health: Stable
Internal working directory: /flash11/iox

Application Interface Mapping
AppGigabitEthernet Port # Interface Name Port Type Bandwidth
1 VirtEth KR Port - Internal 1G


CPU:
Quota: 33(Percentage)
Available: 0(Percentage)
Quota: 1400(Units)
Available: 0(Units)

View IOx Application Information on the Switch

The command in the following example shows application-related information on the switch:

switch #show app-hosting list
App id                                   State
---------------------------------------------------------
iperf_3                                  RUNNING

The command in the following example shows detailed application-related information on the switch:

switch# sh app-hosting detail appid iperf_3
App id                 : iperf_3
Owner                  : iox
State                  : RUNNING
Application
  Type                 : docker
  Name                 : networkstatic/iperf_3
  Version              : latest
  Description          : 
  Author               : Brent Salisbury <brent.salisbury@gmail.com>
  Path                 : bootflash:iperf_3x86.tar
  URL Path             : 
Activated profile name : custom

Resource reservation
  Memory               : 500 MB
  Disk                 : 500 MB
  CPU                  : 173 units
  CPU-percent          : 5 %
  VCPU                 : 1

Platform resource profiles
  Profile Name                  CPU(unit)  Memory(MB)  Disk(MB)
  --------------------------------------------------------------

Attached devices
  Type              Name               Alias
  ---------------------------------------------
  serial/shell     iox_console_shell   serial0
  serial/aux       iox_console_aux     serial1
  serial/syslog    iox_syslog          serial2
  serial/trace     iox_trace           serial3

Network interfaces
   ---------------------------------------
eth0:
   MAC address         : 52:54:dd:67:81:6f
   IPv6 address        : ::
   Network name        : mgmt-bridge300
eth3:
   MAC address         : 52:54:dd:b2:4d:86
   IPv4 address        : 20.1.2.2
   IPv6 address        : ::
   Network name        : VPG0
eth1:
   MAC address         : 52:54:dd:f2:29:67
   IPv4 address        : 10.1.1.2
   IPv6 address        : 2001:1::5054:ddff:fef2:2967
   Network name        : mgmt-bridge-v2340


Docker
------
Run-time information
  Command              : 
  Entry-point          : /bin/sleep 10000
  Run options in use   : --entrypoint '/bin/sleep 10000'
  Package run options  : 
Application health information
  Status               : 0
  Last probe error     : 
  Last probe output    : 


switch#

Stopping, Deactivating, and Uninstalling the Application

The command in the following example stops the IOx application: 

switch# app-hosting stop appid iperf_3
iperf_3 stopped successfully
Current state is: STOPPED
switch#

The command in the following example stops the IOx application:

switch# app-hosting deactivate appid iperf_3
iperf_3 deactivated successfully
Current state is: DEPLOYED
switch#

The command in the following example stops the IOx application:

switch#
ie3400#app-hosting uninstall appid iperf_3
Uninstalling 'iperf_3'. Use 'show app-hosting list' for progress.
switch#

The following shows the list of app-hosting commands: 

switch# app-hosting ?
  activate      Application activate					<== to activate app
  clear         Clear console/aux connection				<== to clear console or aux session if connected
  connect       Application connect					<== to connect the app console or aux or session once in run state
  data          Application data					<== to upload files to the apps
  deactivate    Application deactivate					<== to deactivate an app
  debug         debug							<== for caf related debug commands
  install       Application install					<== to install app
  move          Move File						<== to move trace or core file
  settings      Application settings					<== to configure app specific setting using file
  start         Application start					<== to start an app
  stop          Application stop					<== to stop an app
  uninstall     Application uninstall					<== to uninstall an app`
  upgrade       Application upgrade					<== to upgrade app to new version	
  verification  Application signature verification setting (global) 	<== to enable/disable the sign verification

Deploy an Application using Cisco IOx Local Manager

Cisco IOx Local Manager provides a web-based user interface that you can use to manage, administer, monitor, and troubleshoot applications on a host system, and to perform various related activities. You can access Cisco IOx Local Manager from the Cisco Catalyst IE3400 Rugged, IE3400 Heavy Duty, and IE3300 Rugged Series Switches web-based user interface and use Cisco IOx Local Manager to deploy applications.

To access Cisco IOx Local Manager, choose Configuration > IOx (IOx appears under Services). In the Cisco IOx Local Manager log in window that appears, enter the user name and password that you use to log in to Cisco IOS, then click Log In.

For detailed information about Cisco IOx Local Manager, including how to add, deploy, activate, start, and stop applications, see Cisco IOx Local Manager Reference Guide.