PDF(422.0 KB) View with Adobe Reader on a variety of devices
ePub(347.2 KB) View in various apps on iPhone, iPad, Android, Sony Reader, or Windows Phone
Mobi (Kindle)(635.7 KB) View on Kindle device or Kindle app on multiple devices
Updated:May 6, 2019
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.
The IR1101 is a bit different in comparison with most other IOx platforms as these are mainly x86 based. The IR1101 is based on the ARM64v8 architecture so you cannot deploy containers or IOx packages built for x86 on the platform directly. This document starts from scratch and prepares the environment for building ARM64v8-based Docker containers and explains how to build, package and deploy them on the IR1101 with the use of an x86 PC.
As an example, a very small Python script that is a simple webserver is used and a Docker container is built around to eventually package it to run on the IR1101. The only thing the webserver will do is to listen on a predefined port (9000) and to return a simple pagev when it receives a GET request. This allows you to test the capability to run your own code and allows to test the network access to the IOx application once it starts to run.
The package will be built by the Docker tools, with the use of Alpine Linux. Alpine Linux is a small Linux image (around 5MB), which is often used as a base for Docker containers.
As most of the Desktop/Laptop/VMs around are all x86 based, you need to emulate the ARM64v8 architecture on the x86 based machine where the container is built. You can do this easily with the use of Quick Emulator (QEMU) user emulation. This allows execution of executables in a non-native architecture just as it would run on it's native architecture.
Part 1. Build the IOx Package for IR1101
1. Install and Prepare IOx Client on the Linux Host
You need ioxclient in order to package the Docker container as an IOx package once it's built, so let's prepare this first.
Launch ioxclient for the first time in order to create a mandatory profile. As you will only use ioxclient to package the Docker container, the values can be left as default:
jedepuyd@deb9:~$ ioxclient -v
ioxclient version 188.8.131.52
jedepuyd@deb9:~/iox_aarch64_webserver$ ioxclient profiles reset
Active Profile : default
Your current config details will be lost. Continue (y/N) ? : y
Current config backed up at /tmp/ioxclient731611124
Config data deleted.
jedepuyd@deb9:~/iox_aarch64_webserver$ ioxclient -v
Config file not found : /home/jedepuyd/.ioxclientcfg.yaml
Creating one time configuration..
Your / your organization's name :
Your / your organization's URL :
Your IOx platform's IP address[127.0.0.1] :
Your IOx platform's port number :
Authorized user name[root] :
Password for root :
Local repository path on IOx platform[/software/downloads]:
URL Scheme (http/https) [https]:
Your IOx platform's SSH Port:
Your RSA key, for signing packages, in PEM format:
Your x.509 certificate in PEM format:
Activating Profile default
Saving current configuration
ioxclient version 184.108.40.206
2. Install and Prepare the Docker Environment on the Linux Build Machine
This Docker is used to build a container from the Alpine base image and to include the necessary files for the use case. The given steps are based on the official installation guides from Docker Community Edition (CE) for Debian: https://docs.docker.com/install/linux/docker-ce/debian/
jedepuyd@deb9:~$ sudo apt-get install docker-ce docker-ce-cli containerd.io
Reading package lists... Done
Building dependency tree
Processing triggers for systemd (232-25+deb9u9) ...
In order to be able to access/run Docker as a regular user, add this user to the Docker group and refresh group membership:
jedepuyd@deb9:~$ sudo usermod -a -G docker jedepuyd
jedepuyd@deb9:~$ newgrp docker
3. Install the QEMU User Emulation Packages
After you have installed Docker, you need to install the QEMU user emulators. Use the statically linked QEMU emulator from within the Docker container so you can run the container for ARM64v8 on our x86-based Linux machine, although the target container will be designed for the ARM64v8 architecture.
Install the packages:
jedepuyd@deb9:~$ sudo apt-get install qemu-user qemu-user-static
Reading package lists... Done
Building dependency tree
Processing triggers for man-db (220.127.116.11-2) ...
After the installation, here are the statically linked QEMU emulators available in /usr/bin:
jedepuyd@deb9:~$ ls -al /usr/bin/qemu-*static
-rwxr-xr-x 1 root root 3468784 Nov 8 16:41 /usr/bin/qemu-aarch64-static
-rwxr-xr-x 1 root root 2791408 Nov 8 16:41 /usr/bin/qemu-alpha-static
-rwxr-xr-x 1 root root 3399344 Nov 8 16:41 /usr/bin/qemu-armeb-static
-rwxr-xr-x 1 root root 3391152 Nov 8 16:41 /usr/bin/qemu-arm-static
-rwxr-xr-x 1 root root 2800400 Nov 8 16:41 /usr/bin/qemu-cris-static
The first one in the list, is the one you need: aarch64 is the arch-name for ARM64v8 for Linux.
4. Test if an aarch64/ARV64v8 Container Runs on x86 Linux Machine
Now that you have Docker and the necessary QEMU binaries installed, you can test if you are able to run a Docker container built for ARM64v8 on the x86 machine:
jedepuyd@deb9:~$ docker run -v /usr/bin/qemu-aarch64-static:/usr/bin/qemu-aarch64-static --rm -ti arm64v8/alpine:3.7
Unable to find image 'arm64v8/alpine:3.7' locally
3.7: Pulling from arm64v8/alpine
40223db5366f: Pull complete
Status: Downloaded newer image for arm64v8/alpine:3.7
/ # uname -a
Linux 1dbba69b60c5 4.9.0-8-amd64 #1 SMP Debian 4.9.144-3.1 (2019-02-19) aarch64 Linux
As you can see in the output, arm64v8 Alpine container is obtained and made to run with access to the emulator.
If you request the architecture of the container, you can see that the code is compiled for aarch64. Exactly as the target arch for the container should be for IR1101.
5. Prepare Files to Build the Docker Webserver Container
Now that all preparation is done, you can go ahead and create the necessary files for the webserver container that needs to be run on IR1101.
First file is webserver.py, the Python script which you want to run in the container. As this is just an example, obviously, you will replace this with the actual code in order to run in your IOx application:
This code contains the logic in order to write to a logfile, which will be available for consultation from Local Manager.
Second file that is needed is the Dockerfile. This defines how the container is built:
jedepuyd@deb9:~/iox_aarch64_webserver$ vi Dockerfile
jedepuyd@deb9:~/iox_aarch64_webserver$ cat Dockerfile
COPY qemu-aarch64-static /usr/bin
RUN apk add --no-cache python
COPY webserver.py /webserver.py
The Dockerfile defines how the container will be built. Start from the Apline base image for ARM64v8, copy the emulator in the container, run the apk in order to add the Python package and copy the webserver script into the container.
Last preparation which is needed before you can build the container is to copy qemu-aarch64-static to the directory from where you will build the container:
As you can see, the CPU architecture is set to aarch64. In order to gain access to TCP port 9000, use rootfs.tar as the rootfs and on start, you can run python/webserver.py.
Last thing to do before you can package is to extract the rootfs.tar from the Docker container:
jedepuyd@deb9:~/iox_aarch64_webserver$ docker save -o rootfs.tar iox_aarch64_webserver
At this point, you can use ioxclient in order to build the IOx package for IR1101:
jedepuyd@deb9:~/iox_aarch64_webserver$ ioxclient package .
Currently active profile : default
Command Name: package
No rsa key and/or certificate files provided to sign the package
Checking if package descriptor file is present..
Validating descriptor file /home/jedepuyd/iox_aarch64_webserver/package.yaml with package schema definitions
Parsing descriptor file..
Found schema version 2.7
Loading schema file for version 2.7
Validating package descriptor file..
File /home/jedepuyd/iox_aarch64_webserver/package.yaml is valid under schema version 2.7
Created Staging directory at : /tmp/017226485
Copying contents to staging directory
Creating an inner envelope for application artifacts
Calculating SHA1 checksum for package contents..
Updated package metadata file : /tmp/017226485/.package.metadata
Root Directory : /tmp/017226485
Output file: /tmp/475248592
SHA1 : 95abe28fc05395fc5f71f7c28f59eceb1495bf9b
SHA1 : bdf5596a0747eae51bb0a1d2870fd09a5a16a098
SHA1 : e65a6fcbe96725dd5a09b60036448106acc0c138
Generated package manifest at package.mf
Generating IOx Package..
Package generated at /home/jedepuyd/iox_aarch64_webserver/package.tar
Right now, there is a package in order to deploy on the IR1101 ready as package.tar. The next part explains how to prepare the device for deployment.
Part 2. Configure the IR1101 for IOx
1. Enable the Webinterface, IOx and Local Manager
Local Manager is a GUI in order to deploy, activate, start, manage and troubleshoot IOx applications. For IR1101, it is embedded in the regular management web interface. So, you need to enable that first.
Perform these steps on the IR1101 in order to enable IOx and the web interface.
Enter configuration commands, one per line. End with CNTL/Z.
BRU_IR1101_20(config)#ip http server
BRU_IR1101_20(config)#ip http secure-server
BRU_IR1101_20(config)#ip http authentication local
BRU_IR1101_20(config)#username admin privilege 15 password 0 cisco
The last line adds a user with privilege 15 permissions. This user will have access to the web interface and IOx local manager.
In short, the IOx applications can communicate with the outside world with the use of the VirtualPortGroup0 interface (comparable with the Gi2 on IR809 and Gi5 on IR829 interfaces).
BRU_IR1101_20(config-if)# ip address 192.168.1.1 255.255.255.0
BRU_IR1101_20(config-if)# ip nat inside
BRU_IR1101_20(config-if)# ip virtual-reassembly
As you configure the VirtualPortGroup0 interface as Network Address Translation (NAT) inside, you need to add the ip nat outside statement on the Gi 0/0/0 interface in order to allow communication to and from the IOx applications with the use of NAT:
For this guide, use statically configured IPs per IOx application. If you want to dynamically assign IP addresses to the applications, you will need to add the configuration for a DHCP server in the subnet of VirtualPortGroup0.
Part 3. Access Local Manager and Deploy the IOx Application
After you add these lines to the configuration, you can access the IR1101 with the use of the web interface. Navigate to the Gi 0/0/0 IP address with the use of your browser as shown in the image.
Use the privilege 15 account created in Step 1. in order to login to the web interface and navigate to Configuration - IOx as shown in the image.
In the IOx Local Manager login, use the same account to continue as shown in the image.
Click Add New, select a name for the IOx application and choose the package.tar which was built in Part 1 as shown in the image.
Once the package is uploaded, you can activate it as shown in the image.
In the Resources tab, open the interface setting in order to specify the fixed IP that you want to assign to the app as shown in the image.
Click OK, then Activate. Once the action completes, navigate back to the main Local Manager page (Applications button on the top menu), then start the application as shown in the image.
After you go through these steps, your application should run and be available through port 9000 with the use of the Gi 0/0/0 interface of the IR1101.
Use this section in order to confirm that your configuration works properly.
In order to verify, you can access the IP address of the Gi 0/0/0 interface on the IR1101 with the use of port 9000.
If all goes well, you should see this as follows, as it was created in the Python script.
This section provides information you can use in order to troubleshoot your configuration.
In order to troubleshoot, you can check the logfile which you create in the Python script with the use of a local manager.
Navigate to Applications, click Manage on the iox_web aplication, then select the Logs tab as shown in the image.