Getting Started with IOS-XE Guestshell (Cisco Catalyst - On-box Python & Linux Shell)

In this video, I wanted to take a couple  of minutes and look at a feature called guestshell. This is something that is available on  Cisco's Catalyst 9000 series switches, some of the older 3800 series switches, as well as the new  Catalyst 8000 routers, and even some of the ISR 4000s. In these newer platforms, Cisco has built  something that they call application hosting.

While we call the feature guestshell,  in reality it's just the ability to run a lightweight native linux container directly on  top of a Catalyst device - so that we can have access to a linux shell and a Python interpreter  right on our Catalyst series switch or router. This opens up a lot of possibilities for being  able to run custom scripts and commands and help with troubleshooting by being able to run  Python scripts directly on the box itself. So let's go ahead and just dive right into  'how do we get this running on our device?

'. . .

For the purpose of this video, I'll be using a  Catalyst 8000v. This is a virtual router image that's offered by Cisco and easy to stand up in a  lab - which is why I'm using it for today's video. So as you can see on the screen, I currently  have the Catalyst 8000v command line up.

The first thing that we'll do is a command "show  iox". IOX is the underlying application hosting subsystems that allow us to run containers on top  of our switch. Now as we can see here most of the services are showing that they're either not  running or not supported on this device.

So the first thing that we'll have to do is enable the  IOX services to allow us to build our containers on top of this router. So we'll go "config t" and  we'll just type the command "iox". .

. and now if we go back to check the status of those services,  we can see now that we have the services that were previously listed as not running are now showing  that they are in fact running. Next we're going to walk through a little bit of pre-configuration  that's going to be required for our Linux-based guest shell container to be able to communicate  with the outside world.

So first we'll start with configuring a NAT policy. We'll create a standard  access list and we'll name it "IOX_NAT". .

. and the IP range that we'll be using for our container is  192. 168.

100. 0. Next we'll enter our NAT statement which is going to be "ip nat inside source list  IOX_NAT interface gigabitethernet 1 overload".

. This will allow our container to communicate with  the outside world by NAT'ing it to the gigabit ethernet 1 interface on our virtual router. Next  we'll go to that interface and mark it as the outside NAT interface with the command "ip nat  outside".

. Now for the container side of things, we're actually going to create a virtual port  group interface that'll be used for communication directly with the container. This interface  will act as the upstream gateway from the container itself, to be routed out our gigabit  one interface.

So we'll start with "interface virtualportgroup 0" - then we'll add our IP  address, which for this interface will use 192. 168. 100.

1. Similarly we'll do an "ip nat  inside". Now that our NAT configuration is done, we'll have to specify some configuration for  the container itself.

So we'll begin by doing "app-hosting appid guestshell" - then we'll create  a virtual network interface for our container, and link that to the virtualportgroup 0.  We'll do this using the command "app-vnic gateway 0 virtualportgroup 0 guest-interface  0". Under this config section we'll also apply the IP configuration for our container  by doing "guest-ipaddress 192.

168. 100. 5 netmask 255.

255. 255. 0".

We'll also specify a  default gateway for the interface, with the command "app-default-gateway 192. 168. 100.

1" and  that is out guest-interface 0. And lastly we want to set a DNS server so we'll just use "nameserver0  8. 8.

8. 8". Once we're done with all of that, we're ready to enable our guest shell container and  start making use of it.

So for this we'll actually drop all the way down to normal exec-mode.  And first we'll do a "show app-hosting list" and we'll see that right now we have no containers  available or running. We'll automatically deploy and activate the guest shell container with the  command "guestshell enable" and this will take just a second to complete.

. . In the background,  this is loading the guest shell container, getting it ready for deployment, and then it'll  spin it up and make it ready for us to use.

And so we can see it was deployed, activated,  and now it is running successfully. Again - we can check this using the "show app-hosting list"  command. .

. and yep we see that our guest shell app is running. Before we jump into our container. 

we can also see some additional details by doing "show app-hosting detail appid guestshell". The  output of this command will show some additional detail on the container itself. For example, that  it is an LXC Linux container.

It is version 3. 2. It'll also show what hardware resources  we have reserved for this container.

And if we scroll down just a little bit further,  we can also see the current network config. . .

and sure enough it looks like the configuration  that we specified was applied to our container successfully. One way to interact with our guest  shell container is by using the "guestshell run" command. This will take whatever command we input  and execute it on the guest shell, return it to our cli, without entering the container itself. 

So we'll do a "guestshell run uname -a". . .

and that'll output what you'd expect just  as if you were running it on a Linux system. Now that's helpful if you just want to run one  off commands, but if you want to get access to the linux shell itself - all you have to do is  use the "guestshell" command. Now we see that we have a Linux shell, and we can perform the same  "uname -a" command and see that we get the exact same output that we did when we ran that from the  catalyst command line.

We can also check that our networking config worked - let's go ahead and  try to "ping 8. 8. 8.

8". . .

and sure enough we do have internet access. Now for all intents and  purposes this is a live Linux system. So if we had an additional Linux package that we needed to  install, or we just wanted to run updates - this currently runs CentOS - so we can use the YUM  package manager to update or install.

For example, if I do a "sudo yum update" - this will go out  and fetch new updates available for the system. I'll go ahead and hit CTRL-C now, since I don't  actually want to allow the updates to complete. The real fun comes in now since we have access  to a python interpreter that's running on top of a catalyst device.

We have the ability to  run all sorts of different scripts to help us with device management, troubleshooting, or even  performance monitoring. For example, maybe we have an intermittent network issue that we need help  troubleshooting, and we could write a script, that on a given interval, runs a couple of different  troubleshooting commands, collects information, and then either logs that locally or sends an  email out to someone. Or we might be able to write a Python script that does ping and page load  testing to test performance from an edge device, where maybe we don't have a server or end  client that's capable of running that.

Also included within guest shell is a  Python module called cli - this allows us to run both exec-mode and configuration  commands on the catalyst CLI - which allows us to monitor and configure the device  straight from our python script itself. So let's take a look at this. We'll go ahead and  enter the python interpreter and we'll "import cli".

If we wanted to run an exec-mode command,  we would use the function "cli. execute". So for example in this case we'll do a "write mem" and  see if we can save the device configuration from python.

. . Pretty quickly we get back a similar  response that we would expect on a command line.

On the opposite side, if we wanted to run a  configuration command - let's say we wanted to configure a new interface - we can do that as  well. First I'll create an object that contains a multi-line comment, that creates interface  loopback 200, and then assigns an IP address to it. Now while I use a multi-line comment for this,  the function also supports using a Python list.

So you could list out each command  in order that it needs to be run. Now in order to create that interface, we'll use  the "cli. configure" function and pass that our "config_data" variable that contains the commands  we want to run.

The helpful thing here is that for each individual line of commands that we've  passed to it, we'll get a success or failure - if the command was successfully able to execute.  We can also make use of our normal validation methods by doing a "cli. execute" and passing  the command "show run interface loopback200".

Now of course, I'm just having all of this  output just dumped the command line. . .

but we could easily store this in a Python  variable and parse through it to make sure that everything completed correctly, and add in our own  error checking and validation. So now that we're done here, I'll go ahead and quit the python  interpreter. Another thing that's good to know about, is that like before when we could use the  "guestshell run" command to run something within the linux shell without leaving our Catalyst CLI  - the reverse is also true.

Within guest shell, we can use the "dohost" command to execute  something on the Catalyst CLI without having to leave our Linux shell. So for an example we'll  use the same "write mem" command from earlier. .

and we'll see that our device configuration  has been saved. Now once we're done, we can go ahead and just exit out of the guest shell. And if  we're done using our container for the time being, we can go ahead and use the "guestshell disable"  command to stop the container for now.

And we'll do a "show app-hosting list" - and we see  now that our container is no longer running but instead it's in the state 'deployed'. Now  if we were completely done and we never wanted to use the guest shell container again, we  would use "guestshell destroy". This command will completely remove the guest shell container  that we just built.

And we can again verify this by doing a "show app-hosting list". And we'll  see that there are now no applications found. Okay and that's it for this video.

I hope that  it was helpful - and thank you for watching! !