Cisco IOS-XE Guest Shell: On-Box Python Automation

Guest Shell puts a Linux container on the switch itself, sharing the kernel with IOS-XE but isolated from the host filesystem and processes. That changes what is practical: instead of a central tool pulling data on the network's schedule, the device can run its own Python and bash logic exactly when something happens locally — an interface event, a scheduled check, a configuration audit. This article covers enabling it, the networking plumbing that trips people up first, what to do with it, and what it cannot do.

What Guest Shell is and is not

Guest Shell is a built-in IOx-hosted LXC container bundled with the IOS-XE image on supported releases. You can install scripts and packages inside it, and it does not modify the host IOS-XE filesystem or processes. The explicit limitation: it cannot be used for data-plane forwarding. It is a management-plane tool — automation, local analytics, scripted checks.

Enable IOX and the container

show iox-service
configure terminal
 iox
 ip nat inside source list NAT_ACL interface vlan 1 overload
 ip access-list standard NAT_ACL
  permit 192.168.0.0 0.0.255.255
 exit
 vlan 4094
 exit
 interface vlan 4094
  ip address 192.168.2.1 255.255.255.0
  ip nat inside
 ip routing
 ip route 0.0.0.0 0.0.0.0 10.1.1.3
 app-hosting appid guestshell
  app-vnic AppGigabitEthernet trunk
   vlan 4094 guest-interface 0
   guest-ipaddress 192.168.2.2 netmask 255.255.255.0
  exit
  app-default-gateway 192.168.2.1 guest-interface 0
  name-server0 192.0.2.53
 exit
 interface AppGigabitEthernet1/0/1
  switchport mode trunk
end
guestshell enable

The IOX infrastructure services must be running before any of this — show iox-service lists them, and if something is not running, a no iox followed by iox restarts the stack. The container connects through an internal virtual interface (AppGigabitEthernet) on a dedicated VLAN, and it needs its own gateway and DNS. If NAT is not configured, or the guest VLAN has no route out, everything inside the shell works except the network — which is exactly the symptom people misdiagnose as a broken container. NAT also generally requires an appropriate license level on platforms where features are licensed.

Working inside the shell

guestshell
[guestshell@guestshell ~]$ python3 --version
[guestshell@guestshell ~]$ python3 --version | cut -d' ' -f2
[guestshell@guestshell ~]$ exit

! or run a single command without entering the shell
Device# guestshell run python3 --version
Device# guestshell run bash -c "uname -a"
Device# guestshell run bash /flash/scripts/check_bgp.py

Enable can take up to a minute; the CLI prints the state transitions (DEPLOYED, ACTIVATED, RUNNING) as they happen. Note the Python version bundled with your IOS-XE release — it is often older than what you develop against locally, so avoid f-strings and other newer syntax if the container reports 3.6.

What to automate with it

# /flash/scripts/check_interfaces.py
import subprocess, json, re

out = subprocess.run(["show interfaces", "|", "include packets input"],
                     capture_output=True, text=True, shell=True).stdout
drops = [l for l in out.splitlines() if "drop" in l.lower()]
print(json.dumps({"drop_lines": drops, "count": len(drops)}))

Three patterns justify the container. First, local validation after a change: verify that the interfaces you configured are up, that the routes you expected are present, that the intended VLANs exist — and fail the pipeline if not. Second, device-local data collection for a central system, so the device pushes rather than being polled. Third, lightweight remediation triggers, though for event-driven logic the on-box applet framework may be a better fit; the two are often combined, with an applet calling a shell script, as described in IOS-XE EEM applet configuration.

Talking to the device from inside

Because the shell is local, it can reach the device's own NETCONF interface without traversing the network. A script can open a session to the device's management address, read the hostname from the native YANG model, or push a configuration with the same XML payloads a central controller would use.

<rpc-reply message-id="...1">
  <data>
    <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
      <hostname>C9300</hostname>
    </native>
  </data>
</rpc-reply>

For continuous metric streams rather than on-demand polls, model-driven telemetry is the right mechanism, and the subscription setup is described in gNMI streaming telemetry on IOS-XE.

Operational cautions

• Treat the container as a persistent service: scripts should be idempotent, log to a known location, and handle the case where the shell restarts.
• Store scripts in version control and deploy them with automation, not by copy-pasting into a console.
• Keep the container's package footprint small; installing large dependencies into a switch's limited flash is a self-inflicted outage.
• Do not put anything critical only inside the container — an image upgrade or a guestshell disable takes it away. Central tooling built on the patterns in Netmiko network automation remains the system of record.

原文链接：https://cisco.com/c/en/us/td/docs/switches/lan/cisco_ie9300/software/17_8/cisco-iox-ie93xx-switches/m-iox-guest-shell.pdf