Blog

:: CCIE EI – 5.2.b Guest shell

:: Disclaimer

This post is based on my own research based on the described topic. I’ve done an extensive research to grasp the correct resources to fill my knowledge in the best way possible. It is possible that I’m not able to mention other resources due to my visibility on the net. I’m happy to learn more if these are available.

Let’s go!

:: Introduction

Guestshell is one of the topics from the CCIE Enterprise Infrastructure Lab exam. I’m trying to learn as much as possible about this topic.

Before I dive in, I want to expose the implementations I got working successfully:

  • Enabled Guestshell
  • Enabled Guestshell and enable NAT to overcome routing

There are many other options available, but I will leave that to another blog post.

I’ve used to below software images in my lab environment.

PlatformImage
CSR1000vIOS-XE 17.03.03a
Catalyst 8000vIOS-XE 17.05.01a
Both boot in autonomous mode

Please note that the configuration and installation on other platforms and versions can be slightly different. Guest shell is evolving fast and functions are added with almost every new release. Please check with the configuration guide of the device you need to enable it on.

:: What is Guestshell?

Guestshell is a Linux container-based on Centos 8 LXC (note: CentOS version depends on IOS-XE version used). It contains package management with YUM and Python. It runs as a container inside IOS-XE and you are able to installed and use applications on it.

To visualize it better, I’ve enabled HTTP services on a CSR1000v and logged into the GUI of the router. When you go to Configurations / Services and choose iox, you will see the following screen:

Welcome 17.3.3 Dashboard Monitoring Configuration O Administration Licensing Configuration • > Services • > IOx Cisco Systems CISCO Cisco IOx Local Manager Docker Layers Applications guestshell asco Systems Guest Shell XE for x86_64 VERSION 3.1.0 Munory * System Info System Setting RUNNING custcn•l 50.0% System Troubleshoot O Add New C Refresh
screenshot is taken from the CSR1000v after enabling the HTTP services

It is clear you can install different applications on your Cisco router. Just like Docker. This one is based on iox, which is a cisco-developed end-to-end application framework. One OS containing different isolated application environments. Please note that applications or users can not compromise the host system, which is IOS-XE. Guestshell does have access to a specific portion of the bootflash to make file sharing easier, but you cannot access the software on the bootflash from the Guestshell.

Just for the record: HTTP service is not mandatory for IOx or Guest shell.

:: What are the use-cases for IOx?

  • Install and use Thousand eyes agent directly on the router
  • Install Minecraft server 🙂
  • Create homebrew application packages for specific purposes
  • more…

:: What are the use-cases for guest shell?

Enable supporting applications like:

  • On-device packet capture
  • Share tcl or python scripts for EEM
  • Run iPerf3 for load testing
  • Many others…

:: Topology

I’ve made a simple topology to learn more about Guestshell, EEM, Python script. I also use the CCIE Host VM to get familiar with the look and feel.

Here is what it looks like:

Desert_of_the_real is my exit towards my LAN and Internet.
LAB is a connection towards my SD-WAN lab with vManage and a bunch of CSR1K routers
CCIE_Host is the famous CCIE Host VM, which is also used in the CCIE EI lab.
GinnyPig is a vIOS L3 router from CML
TestMonkey is a CSR1000v
LabRat is a Catalyst 8000v

All nodes are bind to Desert_of_the_real with 10.36.106.0/24. I’m using 192.168.30.0/24 as the internal interfacing between the router and the guest shell application.

Let’s dive straight into the part of why you are visiting this blog and save the details for later.

:: Configuration

For both CSR1000v and the CAT8000v, the config is the same. I’ve used a different internal IP address of 192.168.30.x because I want to enable routed access to the guest shell later on.

First, we enable the iox feature:

TestMonkey#conf t
Enter configuration commands, one per line.  End with CNTL/Z.
TestMonkey(config)#iox
TestMonkey(config)#
*Sep 19 10:57:48.073: %UICFGEXP-6-SERVER_NOTIFIED_START: R0/0: psd: Server iox has been notified to start
*Sep 19 10:58:00.925: %IM-6-IOX_ENABLEMENT: R0/0: ioxman: IOX is ready.
TestMonkey(config)#
TestMonkey(config)#
LabRat#conf t
Enter configuration commands, one per line.  End with CNTL/Z.
LabRat(config)#iox
LabRat(config)#
*Sep 19 10:58:26.468: %UICFGEXP-6-SERVER_NOTIFIED_START: R0/0: psd: Server iox has been notified to start
*Sep 19 10:58:38.419: %IM-6-IOX_ENABLEMENT: R0/0: ioxman: IOX is ready.
LabRat(config)#
LabRat(config)#
!
! TestMonkey CSR1000v
!
interface VirtualPortGroup0
ip address 192.168.30.1 255.255.255.0
 exit
!
app-hosting appid guestshell
 app-vnic gateway0 virtualportgroup 0 guest-interface 1
  guest-ipaddress 192.168.30.10 netmask 255.255.255.0
 app-default-gateway 192.168.30.1 guest-interface 1
!
 app-resource profile custom
  cpu 1500
  memory 512
 name-server0 1.1.1.1
exit
!
end
!

Console output:

*Sep 19 11:01:24.061: %LINEPROTO-5-UPDOWN: Line protocol on Interface VirtualPortGroup0, changed state to up
*Sep 19 11:01:25.124: %DHCP-6-ADDRESS_ASSIGN: Interface GigabitEthernet1 assigned DHCP address 10.36.106.53, mask 255.255.255.0, hostname TestMonkey
!
! LabRat CAT8000v
!
interface VirtualPortGroup0
ip address 192.168.30.2 255.255.255.0
 exit
!
app-hosting appid guestshell
 app-vnic gateway0 virtualportgroup 0 guest-interface 1
  guest-ipaddress 192.168.30.11 netmask 255.255.255.0
 app-default-gateway 192.168.30.2 guest-interface 1
!
 app-resource profile custom
  cpu 1500
  memory 512
 name-server0 1.1.1.1
exit
!
end
!

Console output:

LabRat(config)#
*Sep 19 11:03:26.856: %LINK-3-UPDOWN: Interface VirtualPortGroup0, changed state to up
*Sep 19 11:03:27.857: %LINEPROTO-5-UPDOWN: Line protocol on Interface VirtualPortGroup0, changed state to up
*Sep 19 11:03:34.930: %DHCP-6-ADDRESS_ASSIGN: Interface GigabitEthernet1 assigned DHCP address 10.36.106.38, mask 255.255.255.0, hostname LabRat

Enable guest shell:

TestMonkey#guestshell enable 
Interface will be selected if configured in app-hosting
Please wait for completion
guestshell installed successfully
Current state is: DEPLOYED
guestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

TestMonkey#
*Sep 19 11:19:26.871: %IM-6-IOX_INST_INFO: R0/0: ioxman: IOX SERVICE guestshell LOG: Guestshell is up at 08/19/2021 11:19:26
TestMonkey#
LabRat#guestshell enable
Interface will be selected if configured in app-hosting
Please wait for completion
Current state is: DEPLOYED
guestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

LabRat#
*Sep 19 11:19:39.731: %IM-6-IOX_INST_INFO: R0/0: ioxman: IOX SERVICE guestshell LOG: Guestshell is up at 08/19/2021 11:19:39

Verification for iox and guest shell:

TestMonkey#show iox

IOx Infrastructure Summary:
---------------------------
IOx service (CAF) 1.11.0.5     : Running
IOx service (HA)               : Not Supported 
IOx service (IOxman)           : Running 
IOx service (Sec storage)      : Not Supported 
Libvirtd 1.3.4                 : Running

TestMonkey#show iox detail 

IOx Infrastructure Summary:
---------------------------
IOx service (CAF) 1.11.0.5     : Running
IOx service (HA)               : Not Supported 
IOx service (IOxman)           : Running 
IOx service (Sec storage)      : Not Supported 
Libvirtd 1.3.4                 : Running



------------------ show platform software process list r0 name caf ------------------
Name: run_ioxn_caf.sh
  Process id       : 11245
  Parent process id: 11141
  Group id         : 11245
  Status           : S
  Session id       : 10268
  User time        : 11
  Kernel time      : 7
  Priority         : 20
  Virtual bytes    : 6488064
  Resident pages   : 1092
  Resident limit   : 18446744073709551615
  Minor page faults: 10556
  Major page faults: 0




------------------ show platform software process list r0 name libvirtd ------------------
Name: libvirtd.sh
  Process id       : 5366
  Parent process id: 1
  Group id         : 5366
  Status           : S
  Session id       : 5366
  User time        : 0
  Kernel time      : 0
  Priority         : 20
  Virtual bytes    : 4083712
  Resident pages   : 396
  Resident limit   : 18446744073709551615
  Minor page faults: 624
  Major page faults: 0

Name: libvirtd
  Process id       : 5395
  Parent process id: 5366
  Group id         : 5366
  Status           : S
  Session id       : 5366
  User time        : 5
  Kernel time      : 32
  Priority         : 20
  Virtual bytes    : 713617408
  Resident pages   : 2509
  Resident limit   : 18446744073709551615
  Minor page faults: 4129
  Major page faults: 42


TestMonkey#
TestMonkey#
TestMonkey#show app-hosting list
App id                                   State
---------------------------------------------------------
guestshell                               RUNNING

TestMonkey#show app-hosting detail
App id                 : guestshell
Owner                  : iox
State                  : RUNNING
Application
  Type                 : lxc
  Name                 : GuestShell
  Version              : 3.1.0
  Description          : Cisco Systems Guest Shell XE for x86_64
  Path                 : /guestshell/:guestshell.tar
  URL Path             : 
Activated profile name : custom

Resource reservation
  Memory               : 512 MB
  Disk                 : 1 MB
  CPU                  : 1500 units
  VCPU                 : 1

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:6a:c8:f9
   IPv4 address        : 192.168.30.10
   Network name        : VPG0

Port forwarding
  Table-entry  Service  Source-port  Destination-port
  ---------------------------------------------------

TestMonkey#

TestMonkey#sh run | sec app-hosting
app-hosting appid guestshell
 app-vnic gateway0 virtualportgroup 0 guest-interface 1
  guest-ipaddress 192.168.30.10 netmask 255.255.255.0
 app-default-gateway 192.168.30.1 guest-interface 1
 app-resource profile custom
  cpu 1500
  memory 512
 name-server0 1.1.1.1
TestMonkey#

Use Guest shell: 

TestMonkey#guestshell
[guestshell@guestshell ~]$ 
[guestshell@guestshell ~]$ uname -a 
Linux guestshell 4.19.157 #1 SMP Wed Feb 10 10:15:44 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux
[guestshell@guestshell ~]$ 
[guestshell@guestshell ~]$ ping 1.1.1.1
PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.
64 bytes from 1.1.1.1: icmp_seq=1 ttl=53 time=22.0 ms
64 bytes from 1.1.1.1: icmp_seq=2 ttl=53 time=21.8 ms
64 bytes from 1.1.1.1: icmp_seq=3 ttl=53 time=20.0 ms
^C
--- 1.1.1.1 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 5ms
rtt min/avg/max/mdev = 20.002/21.279/22.028/0.915 ms
[guestshell@guestshell ~]$

When changing the app-hosting configuration, make sure you disable the guest shell first, make the changes and enable guest shell again.

LabRat#guestshell disable 
Guestshell disabled successfully

Make your changes!!!

LabRat#
LabRat#gues
LabRat#guestshell en
LabRat#guestshell enable 
Interface will be selected if configured in app-hosting
Please wait for completion

*Sep 19 11:54:06.030: %IOSXE-6-PLATFORM: R0/0: IOx:  App verification successfulguestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

:: Guest shell NAT

For the CAT8000v, I couldn’t reach the Internet. Purposely, I’ve removed a routing entry on one of my upstream routers for the route to the guest shell IP address. The Guest shell couldn’t connect to the Internet and download packages.

So I decided to overcome that issue and use NAT to reach the Internet.

I’m going to configure an access list and attach this to a NAT overload statement. When initiating traffic from the guest shell, the outside interface GigibitEthernet1 will be the source of the traffic instead of the 192.168.30.11 address. Routing entries for network 192.168.30.11 or 192.168.30/24 is not needed in the network.

!
ip access-list standard GUESTSHELL-ACCESS
 10 permit 192.168.30.0 0.0.0.255
!
interface GigabitEthernet1
 ip nat outside
!
interface VirtualPortGroup0
 ip nat inside
!
ip nat inside source list GUESTSHELL-ACCESS interface GigabitEthernet1 overload
!

LabRat#
LabRat#guest
*Sep 19 12:27:28.383: %SYS-5-CONFIG_I: Configured from console by consoleshell
[guestshell@guestshell ~]$ 
[guestshell@guestshell ~]$ 
[guestshell@guestshell ~]$ 
[guestshell@guestshell ~]$ ping 1.1.1.1
PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.
64 bytes from 1.1.1.1: icmp_seq=1 ttl=54 time=21.9 ms
64 bytes from 1.1.1.1: icmp_seq=2 ttl=54 time=19.1 ms
^C
--- 1.1.1.1 ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 2ms
rtt min/avg/max/mdev = 19.114/20.485/21.857/1.378 ms

:: Resources

Learn more with the below resources!

Tags: , , , , , , , , , , , ,

This Post Has One Comment

Comments are closed.