Guest shell

5.2.b i Linux environment

General information on “Linux environment”:

• Guest shell is first and foremost a containerized Linux environment
• Supported only on IOS-XE platforms (version 16.5 “Everest” or higher)
• The specific Linux OS depends on the device platform (eg. ISR 4000 = CentOS 7)
• Can be used to install and run applications, scripts, Configuring on a network device (router/switch)
• Access to all networks, boot flash and the IOS CLI of the host platform is provided
• For security purposes the Guest Shell and IOS-XE are strictly isolated from each other
• Additional network configuration for IOS-XE devices is not needed since they use the Management port

“Linux environment” CLI configuration commands:

## Enabling IOx service
Router(config)# iox

## Configuring Guest Shell
Router(config)# interface VirtualPortGroup <id>
Router(config-if)# ip address <ip> <mask>

Router(config)# app-hosting appid guestshell
Router(config-app-hosting)# app-vnic <gateway> VirtualPortGroup <id> guest-interface <id> guest-ipaddress <ip> netmask <mask>
Router(config-app-hosting)# app-default-gateway <ip> guest-interface <id>

## Enabling Guest Shell
Router# guestshell enable

## Entering Guest Shell
Router# guestshell

## Running a script from the CLI
Router# guestshell run python [script]

“Linux environment” CLI show commands:

## Show IOx service status
Router# show iox-service

## Show detailed app-hosting status
Router# show app-hosting detail

5.2.b ii CLI Python module

General information on “CLI Python module”:

• Python scripts can directly access the host device CLI with the custom “CLI” python module
• This includes show commands (exec mode) as well as configuration commands (global configuration mode)
• The CLI module provides integration with ZTP as well as EEM
• Python scripts can be triggered directly from an EEM applet

“CLI Python module” python commands:

## Importing the CLI Python module
import cli

## Executes on or several commands and returns the results (empty for configuration commands)
cli.cli(["command 1", "command 2", "command n"])

## Executes on or several commands and prints the results (empty for configuration commands)
cli.clip(["command 1", "command 2", "command n"])

## Executes on or several commands in Global Configuration Mode and returns the results
cli.configure(["command 1", "command 2", "command n"])

## Executes on or several commands in Global Configuration Mode and prints the results
cli.configurep(["command 1", "command 2", "command n"])

## Executes one command in EXEC Mode and returns the results
cli.execute("command")

## Executes one commands in EXEC Mode and prints the results
cli.executep("command")

5.2.b iii EEM Python module

General information on “EEM Python module”:

• The EEM python module requires a fully working Guestshell
• The EEM python module (import eem) can only be imported when registering a python script directly as EEM policy and NOT when triggering a python script as part of a EEM applet
• Triggering python scripts from EEM applets:
  • Python scripts can be triggered directly from EEM applets using the action command
  • Arguments can be handed over to the python script for further processing within the script
• Registering a python script as EEM policy:
  • Python scripts can be registered directly as EEM policies
  • For this to work a script directory has to be defined and each script needs to be registered individually
  • Before a python script can be registered, it has to be transferred (via TFTP, SCP, Configuring) to the defined directory
  • Advantage: The whole script is in one file and not split across the CLI and a python file.
  • Disadvantage: More “complicated” to write.
  • Important: Modifying an already registered script requires re-registering it (unregister and then register again)!

“EEM Python module” python commands:

## Importing the EEM Python module
import eem

## Help for the EEM Python module
dir(eem)
help(eem._eem)

Calling python scripts from EEM applets (example):

## Create new python file in the guest shell called "greet_new_user.py"
import cli
cli.executep("send log A NEW USER LOGGED IN - HURRAY!")

## Create new EEM applet to call the previously created python file
Router(config)# event manager applet GREET_NEW_USER
Router(config-applet)# event syslog pattern "%SEC_LOGIN-5-LOGIN_SUCCESS"
Router(config-applet)# action 1.0 cli command "enable"
Router(config-applet)# action 1.1 cli command "guestshell run python greet_new_user.py"

Registering a Python script as EEM policy:

Router(config)# event manager directory user policy <directory>
Router(config)# event manager policy <policy-file>

Python script w/ EEM python module (example):

## EVENT REGISTER - This equals "event ..." when doing EEM scipts direcly in the CLI.
## In fact even the whole syntax after ::cisco::eem::event_register_ is the same.
::cisco::eem::event_register_syslog pattern "Interface (.*), changed state to administratively down"

## MODULE IMPORT
import cli
import eem
import re

## Reading/Importing VARs of EEM. This equals the $_syslog_msg variable!
eem_vars = eem.event_reqinfo()
eem_msg = eem_vars['msg']

## Altering the variable to read out the affected interface.
regex_pattern_one = '^.*(Interface )'
regex_pattern_two = '(, changed).*$'

prereplace = eem_msg.replace('\n', '')
prealter = re.sub(regex_pattern_one, '', prereplace)
finalalter = re.sub(regex_pattern_two, '', prealter)

intf_name = finalalter

## Executing configuration via Python CLI module
cli.configure(['int ' + intf_name, 'no shutdown'])