Cisco Guest Shell & Python on NX-OS Explained with Examples

What is Gues Shell:

In addition to the NX-OS CLI and Bash access on the underlying Linux environment, switches support access to a decoupled execution space running within a Linux Container (LXC) called the “Guest Shell”.

Guestshell is a virtualized Linux-based environment (Shell Container) , designed to run custom Linux applications, including Python for automated control and management of Cisco devices.

From within the Guest Shell the network-admin has the following capabilities:

Access to the network over Linux network interfaces.
Access to the switch’s bootflash.
Access to the switch’s CLI.
Access to Cisco NX-API REST.
The ability to install and run python scripts.

How Guest Shell works:

How to access Guest shell:

switch_X# guestshell

[guestshell@guestshell ~]$ sudo su

[root@guestshell admin]#

Examples:

Running Python:

Switch> enable

Switch# guestshell enable

Switch#guestshell run python

Python 2.7.11 (default, March 16 2017, 16:50:55)

[GCC 4.7.0] on linux2

Type "help", "copyright", "credits" or "license" for more information.

>>>>

checking the latency across the network using Iperf:

[root@guestshell admin]# iperf -c 10.10.23.1

Connecting to host 10.10.23.1, port 5205

Linux basic commands:

[guestshell@guestshell~]$ pwd

/home/guestshell

[guestshell@guestshell~]$ whoami

guestshell

[guestshell@guestshell~]$ uname -a

Linux guestshell 3.10.101.cge-rt110 #1 SMP Sat Apr 01 08:02:01

Chvrf:

The chvrf command can be used in front of any command in the system to use the desired VRF.

Ping a host through the management VRF:

[guestshell@guestshell ~]$ chvrf management ping 10.70.42.150
PING 10.70.42.150 (10.70.42.150) 56(84) bytes of data.
64 bytes from 10.70.42.150: icmp_seq=1 ttl=53 time=19.2 ms
64 bytes from 10.70.42.150: icmp_seq=2 ttl=53 time=20.0 ms

The guest shell has been populated with common package managers. The yum package manager is installed, and will pull packages from the default CentOS 7 repositories. The locations of package repositories can be changed by modifying the “.repo” repository files in the /etc/yum/repos.d directory. The command yum list available will show all available packages in the repositories.

Installing the git client via yum, using the management VRF:

[guestshell@guestshell ~]$ sudo chvrf management yum install git
Loaded plugins: fastestmirror
base | 3.6 kB 00:00
extras | 3.4 kB 00:00
updates | 3.4 kB 00:00

Dohost:

Dohost command dohost permits you to run NX-OS commands from your shell terminal:

Basic dohost example:

[guestshell@guestshell ~]$ dohost 'show ip route'

Applying a for loop to Dohost:

[guestshell@guestshell ~]$ for x in {1..5}; do dohost "conf t ; interface l$x ; ip address 10.0.0.$x 255.255.255.255" ; done

 [guestshell@guestshell ~]$ 
 *Jul 4 22:32:39.252: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback1, changed state to up
 *Jul 4 22:32:39.253: %LINK-3-UPDOWN: Interface Loopback1, changed state to up
 *Jul 4 22:32:39.332: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback2, changed state to up
 *Jul 4 22:32:39.332: %LINK-3-UPDOWN: Interface Loopback2, changed state to up
 *Jul 4 22:32:39.415: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback3, changed state to up
 *Jul 4 22:32:39.415: %LINK-3-UPDOWN: Interface Loopback3, changed state to up
 *Jul 4 22:32:39.496: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback4, changed state to up
 *Jul 4 22:32:39.496: %LINK-3-UPDOWN: Interface Loopback4, changed state to up
 *Jul 4 22:32:39.566: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback5, changed state to up
 *Jul 4 22:32:39.567: %LINK-3-UPDOWN: Interface Loopback5, changed state to up

Loop on ping:

>>> for x in range(1,6):
 ... clip('ping 10.0.0.' + str(x))
 ...

Type escape sequence to abort.
 Sending 5, 100-byte ICMP Echos to 10.0.0.1, timeout is 2 seconds:
 !!!!!
 Success rate is 100 percent (5/5), round-trip min/avg/max = 1/1/1 ms

Type escape sequence to abort.
 Sending 5, 100-byte ICMP Echos to 10.0.0.2, timeout is 2 seconds:
 !!!!!
 Success rate is 100 percent (5/5), round-trip min/avg/max = 1/1/1 ms

Type escape sequence to abort.
 Sending 5, 100-byte ICMP Echos to 10.0.0.3, timeout is 2 seconds:
 !!!!!
 Success rate is 100 percent (5/5), round-trip min/avg/max = 1/1/4 ms

Type escape sequence to abort.
 Sending 5, 100-byte ICMP Echos to 10.0.0.4, timeout is 2 seconds:
 !!!!!
 Success rate is 100 percent (5/5), round-trip min/avg/max = 1/1/1 ms

Type escape sequence to abort.
 Sending 5, 100-byte ICMP Echos to 10.0.0.5, timeout is 2 seconds:
 !!!!!
 Success rate is 100 percent (5/5), round-trip min/avg/max = 1/1/1 ms

Useful python Script using cli library on guestshell:

Put config in a variable:

In the case of migrations, if we are pushing a lot of configuration, it can be easier to use the configure or configured commands which take a configuration block that is stored in a variable. First, we’ll make a variable that contains the commands needed to add a loopback and enable OSPF on it.

>>> BULK = '''interface l7
 ... ip address 10.0.0.7 255.255.255.255
 ... description Added by Python
 ... router ospf 1
 ... network 10.0.0.7 0.0.0.0 area 7'''
 >>>
 >>> configurep(BULK)
 Line 1 SUCCESS: interface l7
 Line 2 SUCCESS: ip address 10.0.0.7 255.255.255.255
 Line 3 SUCCESS: description Added by Python
 Line 4 SUCCESS: router ospf 1
 Line 5 SUCCESS: network 10.0.0.7 0.0.0.0 area 7

Multi ping and check hosts status:

>>> from cli import *
 >>> import re
 >>> for x in range(1,6):
 ... output = cli('ping 10.0.0.' + str(x))
 ... icmp_regex_pattern = r"100 percent"
 ... icmp_success = True if re.search(icmp_regex_pattern, output, re.MULTILINE) else False
 ... if icmp_success:
 ... print "Loopback" + str(x) + " Works!!!"
 ... else:
 ... print "Loopback" + str(x) + " is not responding!!!"
 ...
 Loopback1 Works!!!
 Loopback2 Works!!!
 Loopback3 Works!!!
 Loopback4 Works!!!
 Loopback5 IS is not responding!!!

Configure An interface:

guestshell run cat test.py
 #!/usr/bin/env python
 import cli

cli.cli('conf t ; interface l11 ; ip add 10.0.0.11 255.255.255.255')

CSR01#guestshell run python test.py

switch#
 *Jul 4 22:02:32.836: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback11, changed state to up
 switch#
 *Jul 4 22:02:32.837: %LINK-3-UPDOWN: Interface Loopback11, changed state to up

References:

[1] developer.cisco.com/docs/nx-os/#!guides-guest-shell/application-hosting-in-nx-os-guest-shell

[2] www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/166/b_166_programmability_cg/guest_shell.html

[3] https://the-packet-thrower.com/2017/10/22/cisco-is-coming-out-of-its-shell/