IOx (IOs + linuX) is Cisco's Application Hosting Infrastructure for Cisco IOS XE devices (e.g. CSR1000v). IOx enables hosting of applications and services developed by Cisco and third-party developers in network edge devices across diverse hardware platforms.
The Guest Shell is a built-in Linux container (LXC) with a CentOS 7 running on Cisco IOS-XE platforms managed by IOx. It is designed to install, update and operate custom Linux applications. The guest shell is bundled with the system image.
The next part explains how to enable guest shell on Cisco CSR 1000v router and configure diverse guest shell parameters. It includes a guest shell IP address, default gateway and resources (CPU, RAM). The router that we are going to use is CSR 1000v (OS XE Software, Version 16.07.01) with permanent (evaluation) license. The license expires 60 days from the time it is activated. The AX feature set is enabled and the maximum throughput is 2500 Mbps. The entire process of licensing CSR1000v for ax license is explained in the article CSR1000v Installation on QEMU VM.
Note: VMware Workstation 15.1.0 hypervisor is used to run CSR 1000v VM.
From within Guest Shell applications have access to the networks of the host platform, bootflash, and IOS CLI.
1. Initial CSR1000v Configuration
hostname CSR1
Interface GigabitEthernet2
ip address 172.17.100.85 255.255.0.0
2. Guest Shell Configuration
Firstly, enable iox service, as it is disabled by default.
CSR1(config)# iox
Configure the VirtualPort group to provide IP connectivity to guest shell container. The interface virtualportGroup 0 is a routed L3 interfaces which connects the container to IOS-XE. Therefore, the IP address 10.0.0.254/24 configured for Vi0 represents a default gateway address for the guest shell container.
CSR1(config)# interface virtualportGroup 0
CSR1(config-if)# ip address 10.0.0.254 255.255.255.0
CSR1(config-if)# exit
Now, configure the guest shell IP address 10.0.0.1/24 and the default gateway, as well. We will assign CPU quota 1500 and the RAM size 1024 MB.
CSR1(config)# app-hosting appid guestshell
CSR1(config-app-hosting)# vnic gateway1 virtualportgroup 0 guest-interface 0 guest-ipaddress 10.0.0.1 netmask 255.255.255.0 gateway 10.0.0.254 name-server 8.8.8.8 default
CSR1(config-app-hosting)# resource profile custom cpu 1500 memory 1024 vcpu 1
CSR1(config-app-hosting)# ^Z
As the last step, we will enable guest shell from privileged exec mode.
CSR1# guestshell enable
Note: In order to build connectivity between guest shell subnet 10.0.0.0/24 and other network devices, we must configure route to 10.0.0/24 on these devices. However, if we do not need to access the guest shell subnet NAT (PAT) from other networks, we can hide the subnet 10.0.0/24 behind the interface Gi2. In that case, guest shell can access the other network but not vice versa (expect the established connections). Below is the particular configuration.
ip access-list standard NAT_ACL
permit 10.0.0.0 0.0.0.255
Interface GigabitEthernet1
ip nat outside
Interface VirtualPortGroup0
ip nat inside
To check status of guest shell, resource reservation and IP settings, issue the command below. Notice the running state of the guest shell container (Picture 1).
CSR1# show app-hosting list
Picture 1 - Guest Shell Status and Configured Parameters
In order to check actual resource utilization, issue the show app-hosting command for appid guest shell (Picture 2).
CSR1# show app-hosting utilization appid guestshell
Picture 2 - Checking Guest Shell Resource Utilization
3. Guest Shell Operation
To run guest shell command from IOS-XE CLI, issue the command below. Notice, the guest shell container is running Linux CentOS 7.8.2003 (Picture 3).
CSR1# guestshell run cat /etc/redhat-release
Picture 3 - Running Linux Commands From IOS-XE CLI
In case, we need to enter the guest shell, issue the command guestshell (Picture 4).
CSR1# guestshell
[guestshell@guestshell ~]$
The python script /usr/lib/python2.7/site-packages/dohost.py is used to run IOS-XE commnad from guest shell. The script dohost.py is started by the bash script /usr/bin/dohost. The prerequisite is enabled ip http server in IOS-XE CLI.
To check the configuration of the interface Vi0 from the guest shell, issue the command bellow:
[guestshell@guestshell ~]$ dohost 'show run int vi0'
Picture 4 - Running IOS-XE Command from Guest Shell
The disk /dev/sda1 is mounted as the directory /bootflash in Guest shell (Picture 5). In fact, it represents IOS-XE flash storage - the directory bootflash:/.
Picture 5 - Mounted disk /dev/sda1 in Guest Shell
In order to share files between guest shell and IOS-XE, copy the file into the tobootflash:/ (IOS-XE) or /bootflash (Guest Shell).
4. Disabling and Destroying Guest Shell Container
To disable guest shell container, issue the command below. Data are preserved and available once guest shell is re-enabled.
CSR1# guestshell disable
To delete data stored in a guest shell container, you must destroy the container once it is disabled.
CSR1# guestshell destroy
As the last step, disable iox process:
CSR1(config)# no iox
5. SSH Server
In order to connect to guest shell container via SSH do following:
- Change the password for the user guestshell with the passwd command
- Create a new sshd_configi file:
$ sudo cp /etc/ssh/sshd_config-cisco /etc/ssh/sshd_config
- Enable password authentication for the user guestshell.
$ sudo sed -i 's/PasswordAuthentication no/PasswordAuthentication yes/g' /etc/ssh/sshd_config
- Restart ssh service.
$ sudo systemctl restart sshd
6. Conclusion
So far, we have successfully enabled guest shell on Cisco CSR 1000v (OS XE Software, 16.07.01). As the next step, we are going to install Urban Terror server 4.3 on Cisco CSR 1000v.
End.