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:
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:
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 126.96.36.199 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
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:
lsb_release -a (did not work for me)
You can install additional applications if you wish, for example:
To Install Git we can use the following command CentOS commands:
[guestshell@guestshell /]$ sudo yum install git
[guestshell@guestshell /]$ git –version
git version 188.8.131.52
[guestshell@guestshell /]$ sudo yum install mtr
guestshell run sudo tcpdump -qns 0 -X -r flash:capture.pcap
The Guest Shell is based on Cent OS 7, and comes with Python 2.7.5 pre-installed.
[guestshell@guestshell ~]$ python –version
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
Update the CentOS container packages and install python 3:
yum update -y
yum install -y python3
[guestshell@guestshell ~]$ python3 –version
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 184.108.40.206');
Example: Running CSR1000v on CML-P with GuestShell
https://github.com/CiscoDevNet/python_code_samples_network (Some On-Box and Off Box Python Examples)