Not to be confused with Cisco IOS shell (IOS.sh) that provides shell scripting capability to the Cisco IOS command-line-interface (CLI).
Guestshell is a virtualized Linux-based environment, designed to run custom Linux applications, including Python for automated control and management of Cisco devices. It also includes the automated provisioning (Day zero) of systems. This container shell provides a secure environment, decoupled from the host device, in which users can install scripts or third-party software packages and run them.
Enabling the guest shell
IOx takes upto two minutes to start. CAF, IOXman, and Libirtd services must be running to enable Guest Shell successfully.
R1(config)#iox (Enables the IOx service)
To check if the service is running we can use the following command:
R1#show iox-service
IOx Infrastructure Summary:
———————–
IOx service (CAF) : Running
IOx service (HA) : Not Supported
IOx service (IOxman) : Running
Libvirtd : Running
Note: this can take a minute or two to start, when ready you should see a similar message to this:
*Jul 7 07:59:31.664: %IM-2-IOX_ENABLEMENT: R0/0: ioxman: IOX is ready.
If we try to enable the guestshell at this point you might see the following message depending on what platform you are running:
Router#guestshell enable
Interface will be selected if configured in app-hosting
Please wait for completion
% Error: No interface configuration for guestshell
Their are a couple of ways to configure the guestshell feature.
1) With the guestshell enable command with arguments (supported in Cisco IOS XE 16.6.x or earlier)
2) Enabling the guestshell using application hosting. (IOS XE Fuji 16.7.1 or later)
Were going to look at the application hosting example for the CSR1000v running 16.11.01b. First we need to configure a Virtual Portgroup interface that interacts with the IOx Guest Shell Container.
DNS resolution within Guest Shell is independent of host platform itself. The name-server we have configured below will automatically get injected into the /etc/resolv.conf file on the CSR1000v. For NX-OS you must explicitly configure the /etc/resolv.conf entry.
interface VirtualPortGroup0
description ** Virtual Link to Container **
ip address 192.168.35.1 255.255.255.0
ip nat inside
interface GigabitEthernet1
description ** outside interface towards internet **
ip address dhcp
ip nat outside
ip nat inside source list NAT_ACL interface GigabitEthernet1 overload
ip access-list standard NAT_ACL
permit 192.168.0.0 0.0.255.255
ip route 0.0.0.0 0.0.0.0 192.168.255.1
app-hosting appid guestshell
app-vnic gateway0 virtualportgroup 0 guest-interface 0
guest-ipaddress 192.168.35.2 netmask 255.255.255.0
app-default-gateway 192.168.35.1 guest-interface 0
app-resource profile custom
cpu 1500
memory 512
name-server0 8.8.8.8
end
R1#guestshell enable
Interface will be selected if configured in app-hosting
Please wait for completion
guestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully
*Jul 7 08:14:21.046: %IM-6-IOX_INST_INFO: R0/0: ioxman: IOX SERVICE guestshell
LOG: Guestshell is up at 06/07/2020 08:14:21
R1#show app-hosting list
App id State
------------------------------------------------------
guestshell RUNNING
Once the guest service is running we can login to the guestshell or run applications hosted inside the guestshell container, to login we enter the following command: guestshell
[guestshell@guestshell ~]$
Running Linux commands from the CLI
The guestshell run command is the IOS equivalent of running Linux executables, and when running a Python script from IOS, specify the absolute path.
guestshell run pwd
guestshell run ls -l
guestshell run bash (Environment variables can be customised in bashrc or . bash_profile)
Accessing the CLI from the Guest Shell (dohost)
We can also access the CLI from within the guest shell, however commands are limited to exec privilege. No access to config mode.
[guestshell@guestshell ~] dohost “show version”
Note: The dohost command requires the ip http server command to be configured on the device.
GuestShell Container Version
To check the guestshell container version we can use some of the following commands:
cat /etc/*-release
hostnamectl
uname -a
uname -mrs
cat /proc/version
lsb_release -a (did not work for me)
Installing Applications
You can install additional applications if you wish, for example:
To Install Git we can use the following command CentOS commands:
#GIT
[guestshell@guestshell /]$ sudo yum install git
[guestshell@guestshell /]$ git –version
git version 1.8.3.1
#MTR
[guestshell@guestshell /]$ sudo yum install mtr
#TCPDUMP
guestshell run sudo tcpdump -qns 0 -X -r flash:capture.pcap
Python-On-Box
The Guest Shell is based on Cent OS 7, and comes with Python 2.7.5 pre-installed.
[guestshell@guestshell ~]$ python –version
Python 2.7.5
NOTE:
In CentOS 7 releases prior to 7.7, it was necessary to make Python 3 available for installation by setting up third-party repositories, such as the IUS repository, because the CentOS base repository did not provide a Python 3 package. As of CentOS 7.7, Python 3 is available in the base package repository.
To install Python 3 on the Guest container we can use one of the following methods.
IUS Repository Example:
[guestshell@guestshell ~]$sudo -E yum -y install https://centos7.iuscommunity.org/ius-release.rpm
[guestshell@guestshell ~]$sudo -E yum -y install python35u-3.5.3
[guestshell@guestshell ~]$python3.5 –version
Python 3.5.3
Update the CentOS container packages and install python 3:
yum update -y
yum install -y python3
[guestshell@guestshell ~]$ python3 –version
Python 3.6.8
You can use the following command from the CLI to execute your python scripts :
#guestshell run python /flash/sample_script.py parameter1 parameter2″
From within the GuestShell itself you can use the following command:
[guestshell@guestshell ~]$ python /flash/sample_script.py
Integrating Guest Shell and EEM scripts
We can combine EEM, GuestShell and Python scripts to create powerful event driven scripts. A very basic example can be found below:
We have an EEM policy named “INTERFACE-DOWN” that looks for a syslog pattern, when a match is found for interface GigabitEthernet0/0, it triggers the exec CLI command that executes the on-box Python script named “EEM-interface-down.py”
event manager applet INTERFACE-DOWN
event syslog pattern "LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet0/0, changed state to down"
action 0.0 cli command "en"
action 1.0 cli command "guestshell run python3 EEM-interface-down.py"
# EEM-interface-down.py
#!/usr/bin/env python3
# import modules
# CLI Module necessary to run config or exec commands on the host
import cli
# Time Module required for the sleep function
import time
# Remove old route
cli.configure('no ip route 192.168.10.1 255.255.255.255 10.10.10.10');
time.sleep(3)
# Add new route
cli.configure('ip route 192.168.10.1 255.255.255.255 20.20.20.20');
Example: Running CSR1000v on CML-P with GuestShell
External Links
https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1612/b_1612_programmability_cg/guest_shell.html
https://github.com/CiscoDevNet/python_code_samples_network (Some On-Box and Off Box Python Examples)
Hey thanks for this nice article, saved me some time