IOx Guest Shell

Overview of Guest Shell

Guest Shell is a built-in, Linux-based container environment on Cisco IOS XE, managed by IOx on the Cisco Catalyst IE9300 Rugged Series Switch. It is designed for operational automation and manageability, such as running Python scripts that interact with Cisco IOS XE. Guest-Shell cannot be used for Data-plane forwarding. The key characteristics include

  • Guest Shell is bundled with the Cisco IOS XE system image on supported releases.

  • Guest Shell runs as an IOx-hosted Linux container (LXC), sharing the kernel with IOS XE.

  • You can install scripts and software packages inside the container.

  • Guest Shell does not modify the host IOS XE file system or processes.

Prerequisites


Note

Day-0 ZTP-based device provisioning uses Guest Shell and does not require an SD card.

Before you enable Guest Shell on IE9300, verify these prerequisites.

  • Cisco IOS XE release on your IE9300 SKU supports Guest Shell and IOx.

  • You have privileged EXEC (enable) access to the switch.

  • Enable IOx (iox in global configuration mode) and verify that IOx services are healthy.

  • IOx uses SD card storage when you configure it.You must have at least 4GB of available storage on the SD card.

  • Format the SD card with the EXT4 file system.

  • Network connectivity for Guest Shell is configured if external access is required (for example, management interface using the app-vnic management command).


Note

The initial enablement of Guest Shell may take several minutes as the container needs to be provisioned.

Enable Guest Shell

Enable Guest Shell on IOS XE devices so you can run Linux tools and scripts in a secure container environment.

Guest Shell is a built-in, containerized Linux environment on Cisco IOS XE platforms. When enabled, network administrators can use Guest Shell to run custom scripts, conduct local analytics, and improve operational workflows directly on the device.

Before you begin

Ensure you have administrative access to the device.

Verify your device supports IOx and Guest Shell.

Procedure

Step 1

Use the enable command to enter privileged EXEC mode.

Example:

Device> enable

Step 2

Use the configure terminal command to enter global configuration mode.

Example:

Device# configure terminal

Step 3

Use the iox command to enable IOx services.

Example:

Device(config)# iox
Device(config)# end
Device# write memory
Device# show iox-service

Verify that IOx infrastructure services show as running.

Example:

Device# show iox

IOx Infrastructure Summary:
---------------------------
IOx service (CAF)              : Running
IOx service (HA)               : Running 
IOx service (IOxman)           : Running 
IOx service (Sec storage)      : Running 
Libvirtd 5.5.0                 : Running
Dockerd v19.03.13-ce           : Running
Redundancy Status              : Non-Redundant

Step 4

Use the app-hosting appid guestshell command to configure application hosting for Guest Shell.

Example:

Device# configure terminal
Device(config)# app-hosting appid guestshell
Device(config-app-hosting)# app-vnic management guest-interface 0
Device(config-app-hosting)# end
Device# write memory

Step 5

Use the guest shell enable command to enter the Guest Shell.

Example:

Device# guestshell enable
Interface will be selected if configured in app-hosting
Please wait for completion
guestshell installed successfully
Current state is: DEPLOYED
guestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

Use the guestshell disable command to disable the Guest Shell.

Example:

Device# guestshell disable 
Guestshell disabled successfully

Step 6

Use the show app-hosting list command for viewing the list of IOx applications and their states.

Example:

Device# show app-hosting list
App id                                   State
---------------------------------------------------------
guestshell                               RUNNING

Additionally, you can use the show app-hosting detail appid guestshell command to get more information about the guestshell application.

Note

 

To run commands from IOS XE without entering the shell, use the guestshell run command.

Example:

Device# guestshell run python3 --version
Python 3.6.8

Device# guestshell run bash -c "uname -a"
Linux guestshell 5.15.178 #1 SMP Mon May 12 10:05:06 UTC 2025 aarch64 aarch64 aarch64 GNU/Linux

Note

 

Use the same method to run any automation scripts you have by executing: guestshell run bash <myscript.py>

Step 7

Use the guestshell run bash command to enter the bash environment and run commands from within the shell.

Example:

Device# guestshell run bash 
[guestshell@guestshell ~]$ cat /etc/os-release

Step 8

Use the exit command to exit out of the shell and return to the IOS-XE.

Example:

[guestshell@guestshell ~]$ exit

Show commands

Use these show commands to verify IOx and Guest Shell (GS) status on IE9300.

Table 1. Guest Shell status on IE9300

Command

Description

show iox-service

Displays the status of the IOx infrastructure service.

show app-hosting list

Lists the IOx applications and their states.

show app-hosting detail appid guestshell

Displays detailed information about the Guest Shell application.

show guestshell detail

Displays the status and configuration specific to the Guest Shell.

show app-hosting resource

Displays the available CPU, memory, and storage for IOx applications.

show app-hosting infra

Displays IOx infrastructure settings (for example, signature verification).