- Table of Contents
- 10: Module Overview and Installation
- 2.0IOx Software Workflow on the Compute Module
- 3.0Configuring the Compute Module Using CGR IOS
- 3.1Define User Credentials
- 3.2Enable Licensing
- 3.3Configure SSHv2 to Enable Hypervisor/IOS Bundle installation
- 3.4Create a DHCP Pool for IOx and CAF on the Module Host-OS
- 3.5DHCP Pool for Application Hosted on Module
- 3.6IOS Physical Interface Configuration
- 3.7Server-Module Internal Management Interface
- 3.8Server-Module Internal Data Interface
- 3.9Routing
- 3.10Enable HTTP and SCP
- 3.11CPU Allocation
- 3.12Line Setting
- 3.13Console Login
- 3.14Version Check of Host-OS Version on Module
- 3.15Server-Module Reload
- 3.16BIOS Validation
- 3.17Temperature Monitoring
- 3.18LED Monitoring
- 3.19Internal Management Interface Monitoring
- 4.0Monitoring and Verifying Server-Module Interfaces
- 5.0Application Hosting on Server Module
- Using IOxclient to Bring Up Application
- 5.1Application Readiness
- 52 Proxy Settings
- 53 Prerequisites
- 5.4 Setup IOx Client
- 5.5 Create IOxclient Profile
- 5.6 Create a New Project Folder
- 5.7 Add Package Descriptor File
- 5.8 Image SCP to Host-OS
- 5.9 Package Application
- 5.10 Install Application
- 5.11 Payload Activation JSON File
- 5.12 Start Application
- 5.13 Monitor Application
- 5.14 Stop, Deactivate or Uninstall an Application
- 5.15 Troubleshooting
Installing the Compute Module
Note: In this document, the Compute Module is identified as a server-module in Cisco IOS commands.
Table of Contents
■
1 0: Module Overview and Installation
■2.0 IOx Software Workflow on the Compute Module
■3.0 Configuring the Compute Module Using CGR IOS
1 0: Module Overview and Installation
This section provides the following information:
■1.1 Module PIDs and Install Preparation
■1.2 Installing Hypervisor and Cisco IOS Images (Bundle Image)
■1.3 Inserting the Compute Module
■1.4 Installing the Server-Module Image
1.1 Module PIDs and Install Preparation
Before You Begin
Verify the following before downloading any software or installing or configuring the CGR 1000, compute module or software:
■Your network setup matches that shown in Network Setup.
■You have an Ubuntu14.04 system for installation (Recommended). The Ubuntu system must be on the same network as the devices to which you will push applications.
■Ensure that you download the latest images from Cisco.com.
■Ensure that you have one of the compute modules referenced in Module Part Number and Specifications
■You have reviewed all of the Pre-Installation Notes
Pre-Installation Notes
■Before you install the compute module, please note the following information:
–You can only install one compute module in a CGR 1120 and CGR 1240.
–For a CGR 1240, you must install the compute module in Slot 5. If a cellular module is installed in Slot 6 the maximum system operating temperature is derated to 50°C
–For a CGR 1120, you can install the compute module in any slot.
–Install only one Application hosting image per compute module. Recommended virtual machines: Windows 7 and Linux VM
■When installing a 3G/4G module and/or WPAN module in the CGR 1240, reserve the following slots:
–Populate slot 3 with either the 3G or 4G module
–Populate slot 4 with the WPAN module.
1.2 Installing Hypervisor and Cisco IOS Images (Bundle Image)
On the CGR 1000 Series, upgrade the Hypervisor and Cisco IOS images using the bundle install command:
Note: We exclude the Guest OS (GOS) image during the bundle install because it is already resident on the CGR 1000 and no update is required.
Note: The server-module Image for the compute module is not included in the CGR bundle image. You must install the server-image after you install the Module. Proceed to 1.3 Inserting the Compute Module.
1.3 Inserting the Compute Module
Before you physically install the compute module into an available CGR slot, review both of the possible options and associated commands required:
Option 1: If the target CGR slot is empty or previously hosted a compute module, do the following:
Option 2: If inserting the compute module into a CGR slot that previously hosted a different interface module:
2. Save the configuration, and reboot the CGR.
Verify Module Status
Enter the following show commands to verify the module status:
1.4 Installing the Server-Module Image
After physically installing the compute module, install the server-module image on the module:
cgr1120#server-module <slot-number> install flash: <image>
2.0 IOx Software Workflow on the Compute Module
The Compute module has the following interfaces that must be configured:
■Internal Interfaces (see Internal Interfaces - Config 01 and Internal Interfaces - Config 02 with NAT)
–Server-module Console: Virtual console line to Host-OS of the module that provides login using the Cisco IOS command-line interface without requiring any IOS networking.
–Internal Management Interface, gig<slot>/1: You can network via virtual IOS interfaces > VDS > ethernet_management interface on Host-OS. Interface provides basic reachability as well as moderate throughput to Host-OS. Used for copying application to IOx.
–Internal Data Interface, gig<slot>/2: We can network via physical IOS interfaces > VDS > CAF Virtual Switch > NAT/Bridged Interfaces to Application. In the examples that follow in section 3.0, we only conform to bridged interfaces. Purpose: Basic reachability as well as moderate throughput to Application and VM.
■Server-Module External Interfaces (see Server Module)
–USB0 and USB1: USB2.0 ports, 5V, for storage. Hot swap of USBs supported on Windows VM only. The USB ports cannot be used as a power source.
–Front Panel RJ45 Gigabit Ethernet Interface: Provides direct access to external network
Figure 2 Internal Interfaces - Config 01
Figure 3 Internal Interfaces - Config 02 with NAT
3.0 Configuring the Compute Module Using CGR IOS
After you physically install and power up the module in the CGR and install the Host-OS image, you can now configure the compute module from the CGR.
PLEASE READ THE FOLLOWING NOTES BEFORE CONFIGURING YOUR COMPUTE MODULE.
Note: When sending traffic over the internal gig {slot}/2 interface, from the application to IOS or the external machine, we are rate-limited to 4Mbps. For higher traffic, the external interface on the server module is the recommended option.
In addition, the MTU Setting must be1492 on both sender and receiver interfaces. The MTU setting on the Server module interface can scale only to 1492 and does not support path discovery. If the external machine supports MTU path discovery, then you can configure the CGR1000 gig{slot}/2 interface MTU to 1492, since IOS supports the feature. Using the above settings ensures fragmentation for any packet size will work.
Note: Throughout this section and others, the IP addresses we use are for illustration purposes only. Please update the IP addresses as needed to match your configuration. In many instances we have marked network-specific commands with: Update to match your configuration.
Note: You can employ Network Address Translation (NAT) in your configuration as seen in Internal Interfaces - Config 02 with NAT. However, we do not provide specific NAT configuration details in this document.
For details on NAT configuration, refer to the following documentation: http://www.cisco.com/c/en/us/tech/ip/network-address-translation-nat/index.html
■3.3 Configure SSHv2 to Enable Hypervisor/IOS Bundle installation
■3.4 Create a DHCP Pool for IOx and CAF on the Module Host-OS
■3.5 DHCP Pool for Application Hosted on Module
■3.6 IOS Physical Interface Configuration
■3.7 Server-Module Internal Management Interface
■3.8 Server-Module Internal Data Interface
■3.14 Version Check of Host-OS Version on Module
■3.19 Internal Management Interface Monitoring
3.1 Define User Credentials
Note: You must have privilege 15 to deploy applications [CAF/IOx limitation]. Otherwise, you will encounter an IOx authentication failure.
3.2 Enable Licensing
Ensure licensing configuration in place:
3.3 Configure SSHv2 to Enable Hypervisor/IOS Bundle installation
3.4 Create a DHCP Pool for IOx and CAF on the Module Host-OS
3.5 DHCP Pool for Application Hosted on Module
3.6 IOS Physical Interface Configuration
Interface ensures network access to the Host-OS and Application on the compute module via the IOS internal interface.
3.7 Server-Module Internal Management Interface
3.8 Server-Module Internal Data Interface
3.9 Routing
Note: In this case, the gateway to CGR 1000 is the switch (see Figure 2)
3.10 Enable HTTP and SCP
This is an example template to connect with the tools that manage application hosting (ioxclient, local manager, fog director). Enable SCP server in case required.
3.11 CPU Allocation
To optimize VDS/Hypervisor performance, enter the following configuration:
3.12 Line Setting
Example template to allow all protocol traffic (User-configurable)
3.13 Console Login
You can log into the console of the compute module from CGR by entering:
Escape sequence: Ctrl-Shift x, then disconnect command
Note: To log out of the module session, hit simultaneously ‘Ctrl+Shift+6’ followed immediately by ‘x’. Immediately enter ‘disconnect’ in IOS mode to prevent reconnection attempts to Host-OS
3.14 Version Check of Host-OS Version on Module
To check Host-OS version installed on the compute module from CGR:
3.15 Server-Module Reload
To reload the module you can power on/power off the compute module from the CGR using one of the two command options below. You must include slot number in which the module resides: (In the examples below, 3 is the slot number).
3.16 BIOS Validation
To verify that a BIOS validation has successfully occurred after a module or CGR reload (requires up to 20 minutes to complete):
3.17 Temperature Monitoring
Note: Server-module draws approximately 6 to 8W, which can cause it to heat up more than other modules.
The show env temp command displays the ambient temperature (CurTemp) of the module, not the CPU, which tends to be a few degrees higher.
The module supports a maximum temperature of to 50 C.
When higher temperatures exist, reduce frequent reloads of the module.
3.18 LED Monitoring
To check LED status of the module from CGR:
3.19 Internal Management Interface Monitoring
In the configuration below, IOS acts as DHCP server and Host-OS acts as DHCP client, to verify address assignment to server-module Host-OS.
4.0 Monitoring and Verifying Server-Module Interfaces
The Compute module has two USB ports and one RJ45 Gigabit Ethernet Interface on its front panel. Details on access and information accessible through those ports is noted in the sections below.
For details on LEDs and the front panel, refer to following chapter and page: Product Overview.
■4.2 External RJ45 Gigabit Ethernet Interface and ETH LEDs
4.1 USB0 and USB1 Ports
The two USB ports on the module support storage and file transfer. Use of the module’s external Gigabit Ethernet interface is recommended for faster transfer rates.
USB ports cannot be used as a power source.
You can hot-swap USBs on the module.
You can view details on the USB ports through the Host-OS and VM (Windows or Linux) on the module.
Note: The Host-OS for the USB ports display will vary based on the VM in use.
■To check USB0 and USB1 port status from Host-OS:
■To manually copy files from USB to Host-OS use the following example configuration:
Note: The Windows 7 and Linux images are labeled as vm.img throughout this guide.
4.2 External RJ45 Gigabit Ethernet Interface and ETH LEDs
The Gigabit Ethernet Interface is IOS-independent.
The Gigabit Ethernet interface has two LEDs (Speed, Link Status) to monitor auto-negotiation. You can monitor the interface by physical inspection of the front panel. See Product Overview.
Note: The Gigabit Ethernet interface cannot be used to SCP files (such as vm.img) to Host-OS/IOx since it is only accessible to the application only--not the Host-OS.
END INSTALLATION: You have now completed installation of the module and configured the basic steps to provide access to the Host-OS on the Compute module.
5.0 Application Hosting on Server Module
To install the Application Installation, follow these steps:
■Packaging an application [tool used: IOxclient] - Ensures application is compatible with our platform resources.
■Deploying an application [tool used: IOxclient or Local Manager] - Copy application to the server-module and deploy it based on user configuration.
■Monitoring an application [tool used: IOxclient, Local Manager] - Log in to a running application and monitor the same.
■Removing an application [tool used: IOxclient, Local Manager] - Stop, deactivate or uninstall an application.
Using IOxclient to Bring Up Application
5.1 Application Readiness
VM application should be in.img format. Image size to conform with PID disk space limitations.
Note : This release does not support Container-based and PaaS-styled applications.
■For a 64 GB Compute module, ensure at least 50 GB of usable space is available.
■For a 128 GB Compute module, ensure at least 106 GB of usable space is available.
5 2 Proxy Settings
■Ensure Proxy settings are configured appropriately (example Ubuntu VM template below, refine to suit your environment).
■Example configuration only. User needs to change according to user environment.
5 3 Prerequisites
Download IOxclient onto a standalone Ubuntu PC/VM (2-core PC with 8GB RAM). (For example, we employed an Ubuntu 14.04LTS on a standalone 2-core PC with 8GB RAM in our testing). Ensure PC meets conditions noted in 5.1 Application Readiness.
IOxclient is a command-line interface tool, which can communicate with the Host-OS IOx on the Compute module (server-module).
We support two user-interfaces:
■Local Manager, which manages an individual device
■Fog Director, which manages multiple devices (Cisco-developed interface)
5.4 Setup IOx Client
Execute IOx client. For the first time, register with an example device to create the default profile.
5.5 Create IOxclient Profile
You must create a profile for each device. You can create any number of profiles for a device or many devices. However, you can only have one active profile.
Commands listed below are interactive.
5.6 Create a New Project Folder
Note: The following example shows steps required to package and deploy a Windows VM. The same steps must be followed for an Unbuntu Linux-based VM.
From the ioxclient path, create a new project folder.
5.7 Add Package Descriptor File
In the winapp folder, manually add [vi edit] the package yaml file as shown below (copy and paste with exact syntax).
The example above is a Windows Application with 2 USB ports (configuration is valid for any number of USB ports) and 2 Ethernet interfaces (1 internal data interface, 1 front panel external data interface).
If you need to modify the yaml file for the Ubuntu Application, comment out OS type (#ostype: windows) and the rest of the script remains as is.
Brief Purpose of descriptor file: This is the file usually provided by an application developer to the application user/deployer. It comprises of cpu, memory, app type, path of image file and such user-application-specific details, based on user’s platform constraints.
CPU Units: Especially useful when we run multiple applications. Since engineering supports only one application for the current release, we can be generous in using the allowed ~7300 units. Example uses 6000 units. Disk: Random allocation of large numbers can result in corruption of image. For windows7 VM app, sample configuration recommendation of 10MB works fine. Memory: max. 3500MB.
If the image is located in the same ‘winapp’ folder, “file path” field need not be specified. If image however is too large to be hosted on the machine where IOXclient is installed (Specially true of 25GB+ Windows images), add ‘file path’. If default path used for image is /mnt/data/vm, no additional path info need to be specified except image name/label
Note: Syntax spacing of package.yaml file has to be exact. Use http://www.yamllint.com to validate the same.
Given that we support only one application, we recommend that you retain the image name as vm.img and mirror the working example provided.
5.8 Image SCP to Host-OS
Image can be copied using USB as well, if there is physical access to the device or a USB is already plugged in. Else, alternatively, IOXclient can be used to SCP image.
If the steps fail as provided in the example, check the ssh port setup while creating device profile (Step[3]). If not done, no need to recreate profile, alternatively, manually modify following file in the path where ioxclient tool is installed:
vi ~/.ioxclientcfg.yaml > goto our respective profile > edit ssh_port manually
Retry the ioxclient command line
SCP rate via Internal Interface ~3Mbps.
Note: We do not chmod 777 * the created.pem file. Else the SCP will fail..pem file permissions should be “chmod 0600 *.pem*”
5.9 Package Application
Packaging an application can be done using the IOxclient tool or SDK. For this Documentation Guide, we reference IOxclient as it can be used end-to-end from packaging to application deployment.
Once an application is packaged, any image name change, path change, descriptor file content change requires that the application be repackaged.
Once packaged, a package.tar will comprise of a manifest file, the yam descriptor file and the artifacts.gz which has all the actual application images/files.
5.10 Install Application
In the steps above, we are creating an appid (example label for an instance of application) to be installed on the device. By using different application IDs, we can reuse the application and install it again on the same device with a different appid). For our module, since we support only one application for this release, this feature may not be relevant.
5.11 Payload Activation JSON File
End User needs to manually add a payload activation file in son format. File needs to be in ‘winapp’ location.
Purpose of Payload Activation file: For end users to invoke the interfaces they need for their application (2 Ethernet interfaces and 1 USB interface, in this example). It is also used to specify a mandatory VNC password (valid for Windows and Linux Applications, it is especially needed for Windows App login as ssh is unsupported).
Due to security constraints, VNC password setting is mandatory.
5.12 Start Application
Start Application. To verify if running, login to Host-OS, and check top -b for running qemu-kvm command with specified resources and Appid name.
5.13 Monitor Application
We can use the following ioxclient option to verify a running application parameters.
To VNC Login to Windows application, open up port ip_addr:5900, and provide the specified vnc password in payload_act file (eg: ‘password’, in this case)
Recommended VNCClient: TightVNC latest version
For ssh login to an Ubuntu application we can alternatively use : ssh -p <port> -i <app_id.pem> appconsole@ip_addr. However, because of the limitation is that we can open only one console port, for multiple ssh sessions, we need to login via console, configure ssh server on our VM and use external/internal data interface for access.
For Ubuntu VM, the recommendation is to install ssh server on the Ubuntu application on first time bring-up so as to be enable multiple ssh sessions.
5.14 Stop, Deactivate or Uninstall an Application
■Stop an app (qemu-kvm process stops running).
■Deactivate an app (all the resources assigned to the app are released)
■Uninstall an application (remove all history of the AppID from CAF/IOx)
5.15 Troubleshooting
For troubleshooting, the following commands can be very useful. When providing logs to engineering for troubleshooting, please provide the information below.
Note: The following VNC viewer (TightVNC version 2.8.5) configuration must be employed:
■ColourLevel: Replace pal8 with rgb332 or rgb565
https://support.realvnc.com/knowledgebase/article/View/422/12/problems-connecting-to-vmware-qemu-xens-built-in-or-other-third-party-vnc-compatible-server-software
Feedback