Guest Shell 2.2
• About the Guest Shell, page 1
• Accessing the Guest Shell, page 2
• Capabilities in the Guest Shell, page 2
• Resources Used for the Guest Shell, page 7
• Security Posture for Virtual Services , page 8
• Guest File System Access Restrictions , page 10
• Guidelines and Limitations, page 10
• Managing the Guest Shell, page 14
• Verifying Virtual Service and Guest Shell Information, page 19
• Persistently Starting Your Application From the Guest Shell, page 20
• Procedure for Persistently Starting Your Application from the Guest Shell, page 21
• An Example Application in the Guest Shell, page 21
About the Guest Shell
In addition to the NX-OS CLI and Bash access on the underlying Linux environment, the Cisco Nexus 9000
Series devices support access to a decoupled execution space running within a Linux Container (LXC) called
the “Guest Shell”.
From within the Guest Shell the network-admin has the following capabilities:
• Access to the network over Linux network interfaces.
• Access to Cisco Nexus 9000 bootflash.
• Access to Cisco Nexus 9000 volatile tmpfs.
• Access to Cisco Nexus 9000 CLI.
• Access to Cisco NX-API REST.
• The ability to install and run python scripts.
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
1
Guest Shell 2.2
Accessing the Guest Shell
• The ability to install and run 32-bit and 64-bit Linux applications.
Decoupling the execution space from the native host system allows customization of the Linux environment
to suit the needs of the applications without impacting the host system or applications running in other Linux
Containers.
On NX-OS devices, Linux Containers are installed and managed with the virtual-service commands. The
Guest Shell will appear in the virtual-service show command output.
Note
By default, the Guest Shell occupies approximately 5 MB of RAM and 200 MB of bootflash when enabled.
Beginning with Cisco NX-OS Release 7.0(3)I2(1) the Guest Shell occupies approximately 35 MB of
RAM. Use the guestshell destroy command to reclaim resources if the Guest Shell is not used.
Accessing the Guest Shell
In Cisco NX-OS, the Guest Shell is accessible to the network-admin. It is automatically enabled in the system
and can be accessed using the run guestshell command. Consistent with the run bash command, these
commands can be issued within the Guest Shell with the run guestshell command form of the NX-OS CLI
command.
Note
The Guest Shell is automatically enabled on the Cisco Nexus 9000, but not on the Cisco Nexus 3000.
switch# run guestshell ls -al /bootflash/*.ova
-rw-rw-rw- 1 2002 503 117616640 Aug 21 18:04 /bootflash/chef.ova
-rw-rw-rw- 1 2002 503 83814400 Aug 21 18:04 /bootflash/pup.ova
-rw-rw-rw- 1 2002 503 40724480 Apr 15 2012 /bootflash/red.ova
Note
When running in the Guest Shell, you have network-admin level privileges.
Note
The Guest Shell starting in 2.2(0.2) will dynamically create user accounts with the same as the user logged
into switch. However, all other information is NOT shared between the switch and the Guest Shell user
accounts.
In addition, the Guest Shell accounts are not automatically removed, and must be removed by the network
administrator when no longer needed.
Capabilities in the Guest Shell
The Guest Shell has a number of utilities and capabilities available by default.
The Guest Shell is populated with CentOS 7 Linux which provides the ability to Yum install software packages
built for this distribution. The Guest Shell is pre-populated with many of the common tools that would naturally
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
2
Guest Shell 2.2
NX-OS CLI in the Guest Shell
be expected on a networking device including net-tools, iproute, tcpdump and OpenSSH. Python 2.7.5 is
included by default as is the PIP for installing additional python packages.
By default the Guest Shell is a 64-bit execution space. If 32-bit support is needed, the glibc.i686 package can
be Yum installed.
The Guest Shell has access to the Linux network interfaces used to represent the management and data ports
of the switch. Typical Linux methods and utilities like ifconfig and ethtool can be used to collect counters.
When an interface is placed into a VRF in the NX-OS CLI, the Linux network interface is placed into a
network namespace for that VRF. The name spaces can be seen at /var/run/netns and the ip netns
utility can be used to run in the context of different namespaces. A couple of utilities, chvrf and vrfinfo, are
provided as a convenience for running in a different namespace and getting information about which
namespace/vrf a process is running in.
systemd is used to manage services in CentOS 7 environments, including the Guest Shell.
NX-OS CLI in the Guest Shell
The Guest Shell provides an application to allow the user to issue NX-OS commands from the guest shell
environment to the host network element. The dohost application accepts any valid NX-OS configuration or
exec commands and issues them to the host network element.
When invoking the dohost command each NX-OS command may be in single or double quotes:
dohost "<NXOS CLI>"
The NX-OS CLI can be chained together:
[guestshell@guestshell ~]$ dohost "sh lldp time | in Hold" "show cdp global"
Holdtime in seconds: 120
Global CDP information:
CDP enabled globally
Refresh time is 21 seconds
Hold time is 180 seconds
CDPv2 advertisements is enabled
DeviceID TLV in System-Name(Default) Format
[guestshell@guestshell ~]$
The NX-OS CLI can also be chained together using the NX-OS style command chaining technique by adding
a semicolon between each command. (A space on either side of the semicolon is required.):
[guestshell@guestshell ~]$ dohost "conf t ; cdp timer 13 ; show run | inc cdp"
Enter configuration commands, one per line. End with CNTL/Z.
cdp timer 13
[guestshell@guestshell ~]$
Note
For release 7.0(3)I5(2) using Guest Shell 2.2 (0.2), commands issued on the host through the dohost
command are run with privileges based on the effective role of the Guest Shell user.
Prior versions of Guest Shell will run command with network-admin level privileges.
The dohost command fails when the number of UDS connections to NX-API are at the maximum allowed.
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
3
Guest Shell 2.2
Network Access in Guest Shell
Network Access in Guest Shell
The NX-OS switch ports are represented in the Guest Shell as Linux network interfaces. Typical Linux methods
like view stats in /proc/net/dev, through ifconfig or ethtool are all supported:
The Guest Shell has a number of typical network utilities included by default and they can be used on different
VRFs using the chvrf vrf command command.
[guestshell@guestshell bootflash]$ ifconfig Eth1-47
Eth1-47: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet 13.0.0.47 netmask 255.255.255.0 broadcast 13.0.0.255
ether 54:7f:ee:8e:27:bc txqueuelen 100 (Ethernet)
RX packets 311442 bytes 21703008 (20.6 MiB)
RX errors 0 dropped 185 overruns 0 frame 0
TX packets 12967 bytes 3023575 (2.8 MiB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
Within the Guest Shell, the networking state can be monitored, but may not be changed. To change networking
state, use the NX-OS CLI or the appropriate Linux utilities in the host bash shell.
The tcpdump command is packaged with the Guest Shell to allow packet tracing of punted traffic on the
management or switch ports.
The sudo ip netns exec management ping utility is a common method for running a command in the context
of a specified network namespace. This can be done within the Guest Shell:
[guestshell@guestshell bootflash]$ sudo ip netns exec management ping 10.28.38.48
PING 10.28.38.48 (10.28.38.48) 56(84) bytes of data.
64 bytes from 10.28.38.48: icmp_seq=1 ttl=48 time=76.5 ms
The chvrf utility is provided as a convenience:
guestshell@guestshell bootflash]$ chvrf management ping 10.28.38.48
PING 10.28.38.48 (10.28.38.48) 56(84) bytes of data.
64 bytes from 10.28.38.48: icmp_seq=1 ttl=48 time=76.5 ms
Note
Commands that are run without the chvrf command are run in the current VRF/network namespace.
For example, to ping IP address 10.0.0.1 over the management VRF, the command is “chvrf management
ping 10.0.0.1”. Other utilities such as scp or ssh would be similar.
Example:
switch# guestshell
[guestshell@guestshell ~]$ cd /bootflash
[guestshell@guestshell bootflash]$ chvrf management scp [email protected]:/foo/index.html
index.html
[email protected]'s password:
index.html 100% 1804 1.8KB/s 00:00
[guestshell@guestshell bootflash]$ ls -al index.html
-rw-r--r-- 1 guestshe users 1804 Sep 13 20:28 index.html
[guestshell@guestshell bootflash]$
[guestshell@guestshell bootflash]$ chvrf management curl cisco.com
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>301 Moved Permanently</title>
</head><body>
<h1>Moved Permanently</h1>
<p>The document has moved <a href="http://www.cisco.com/">here</a>.</p>
</body></html>
[guestshell@guestshell bootflash]$
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
4
Guest Shell 2.2
Access to Bootflash in Guest Shell
To obtain a list of VRFs on the system, use the show vrf command natively from NX-OS or through the
dohost command:
Example:
[guestshell@guestshell bootflash]$ dohost 'sh vrf'
VRF-Name
VRF-ID State
Reason
default
1
Up
-management 2
Up
-red
6
Up
--
Within the Guest Shell, the network namespaces associated with the VRFs are what is actually used. It can
be more convenient to just see which network namespaces are present:
[guestshell@guestshell bootflash]$ ls /var/run/netns
default management red
[guestshell@guestshell bootflash]$
To resolve domain names from within the Guest Shell, the resolver needs to be configured. Edit the
/etc/resolv.conf file in the Guest Shell to include a DNS nameserver and domain as appropriate for the network.
Example:
nameserver 10.1.1.1
domain cisco.com
The nameserver and domain information should match what is configured through the NX-OS configuration.
Example:
switch(config)# ip domain-name cisco.com
switch(config)# ip name-server 10.1.1.1
switch(config)# vrf context management
switch(config-vrf)# ip domain-name cisco.com
switch(config-vrf)# ip name-server 10.1.1.1
If the Cisco Nexus 9000 device is in a network that uses an HTTP proxy server, the http_proxy and
https_proxy environment variables must be set up within the Guest Shell also.
Example:
export http_proxy=http://proxy.esl.cisco.com:8080
export https_proxy=http://proxy.esl.cisco.com:8080
These environment variables should be set in the .bashrc file or in an appropriate script to ensure that they
are persistent.
Access to Bootflash in Guest Shell
Network administrators can manage files with Linux commands and utilities in addition to using NX-OS CLI
commands. By mounting the system bootflash at /bootflash in the Guest Shell environment, the network-admin
can operate on these files with Linux commands.
Example:
find . –name “foo.txt”
rm “/bootflash/junk/foo.txt”
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
5
Guest Shell 2.2
Python in Guest Shell
Python in Guest Shell
Python can be used interactively or python scripts can be run in the Guest Shell.
Example:
guestshell:~$ python
Python 2.7.5 (default, Jun 24 2015, 00:41:19)
[GCC 4.8.3 20140911 (Red Hat 4.8.3-9)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
guestshell:~$
The pip python package manager is included in the Guest Shell to allow the network-admin to install new
python packages.
Example:
[guestshell@guestshell ~]$ sudo su
[root@guestshell guestshell]# pip install Markdown
Collecting Markdown
Downloading Markdown-2.6.2-py2.py3-none-any.whl (157kB)
100% |################################| 159kB 1.8MB/s
Installing collected packages: Markdown
Successfully installed Markdown-2.6.2
[root@guestshell guestshell]# pip list | grep Markdown
Markdown (2.6.2)
[root@guestshell guestshell]#
Note
You must enter the sudo su command before entering the pip install command.
Installing RPMs in the Guest Shell
The /etc/yum.repos.d/CentOS-Base.repo file is set up to use the CentOS mirror list by default. Follow
instructions in that file if changes are needed.
Yum can be pointed to one or more repositories at any time by modifying the yumrepo_x86_64.repo
file or by adding a new .repo file in the repos.d directory.
For applications to be installed inside Guest Shell, go to the CentOS 7 repo at http://mirror.centos.org/centos/
7/os/x86_64/Packages/.
Yum resolves the dependancies and installs all the required packages.
[guestshell@guestshell ~]$ sudo chvrf management yum -y install glibc.i686
Loaded plugins: fastestmirror
Loading mirror speeds from cached hostfile
* base: bay.uchicago.edu
* extras: pubmirrors.dal.corespace.com
* updates: mirrors.cmich.edu
Resolving Dependencies
"-->" Running transaction check
"--->" Package glibc.i686 0:2.17-78.el7 will be installed
"-->" Processing Dependency: libfreebl3.so(NSSRAWHASH_3.12.3) for package:
glibc-2.17-78.el7.i686
"-->" Processing Dependency: libfreebl3.so for package: glibc-2.17-78.el7.i686
"-->" Running transaction check
"--->" Package nss-softokn-freebl.i686 0:3.16.2.3-9.el7 will be installed
"-->" Finished Dependency Resolution
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
6
Guest Shell 2.2
Resources Used for the Guest Shell
Dependencies Resolved
============================================================================================================================================================================
Package Arch Version Repository Size
============================================================================================================================================================================
Installing:
glibc i686 2.17-78.el7 base 4.2 M
Installing for dependencies:
nss-softokn-freebl i686 3.16.2.3-9.el7 base 187 k
Transaction Summary
============================================================================================================================================================================
Install 1 Package (+1 Dependent package)
Total download size: 4.4 M
Installed size: 15 M
Downloading packages:
Delta RPMs disabled because /usr/bin/applydeltarpm not installed.
(1/2): nss-softokn-freebl-3.16.2.3-9.el7.i686.rpm | 187 kB 00:00:25
(2/2): glibc-2.17-78.el7.i686.rpm | 4.2 MB 00:00:30
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------Total 145 kB/s | 4.4 MB 00:00:30
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
Installing : nss-softokn-freebl-3.16.2.3-9.el7.i686 1/2
Installing : glibc-2.17-78.el7.i686 2/2
error: lua script failed: [string "%triggerin(glibc-common-2.17-78.el7.x86_64)"]:1: attempt
to compare number with nil
Non-fatal "<"unknown">" scriptlet failure in rpm package glibc-2.17-78.el7.i686
Verifying : glibc-2.17-78.el7.i686 1/2
Verifying : nss-softokn-freebl-3.16.2.3-9.el7.i686 2/2
Installed:
glibc.i686 0:2.17-78.el7
Dependency Installed:
nss-softokn-freebl.i686 0:3.16.2.3-9.el7
Complete!
Note
When more space is needed in the Guest Shell root file system for installing or running packages, the
guestshell resize roofs size-in-MB command is used to increase the size of the file system.
Note
Some open source software packages from the repository might not install or run as expected in the Guest
Shell as a result of restrictions that have been put into place to protect the integrity of the host system.
Resources Used for the Guest Shell
By default, the resources for the Guest Shell have a small impact on resources available for normal switch
operations. If the network-admin requires additional resources for the Guest Shell, the guestshell resize {cpu
| memory | rootfs} command changes these limits.
Resource
Default
Minimum/Maximum
CPU
1%
1/20%
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
7
Guest Shell 2.2
Security Posture for Virtual Services
Resource
Default
Minimum/Maximum
Memory
256MB
256/3840MB
Storage
200MB
200/2000MB
The CPU limit is the percentage of the system compute capacity that tasks running within the Guest Shell are
given when there is contention with other compute loads in the system. When there is no contention for CPU
resources, the tasks within the Guest Shell are not limited.
Note
A Guest Shell reboot is required after changing the resource allocations. This can be accomplished with
the guestshell reboot command.
Security Posture for Virtual Services
Use of the Guest Shell and virtual services in Cisco Nexus 9000 series devices are only two of the many ways
that the network-admin can manage or extend the functionality of the system. These options are geared towards
providing an execution environment that is decoupled from the native host context. This separation allows
the introduction of software into the system that may not be compatible with the native execution environment.
It also allows the software to run in an environment that does not interfere with the behavior, performance,
or scale of the system.
Digitally Signed Application Packages
By default, Cisco network elements require applications to provide a valid Cisco digital signature at runtime.
The Cisco digital signature ensures the integrity of Cisco-developed packages and applications.
The Cisco Nexus 9000 Series switches support the configuration of a signing level policy to allow for unsigned
OVA software packages. To allow unsigned and Cisco-signed packages for creating virtual-services, the
network-admin can configure the following:
virtual-service
signing level unsigned
Note
The Guest Shell software package has a Cisco signature and does not require this configuration.
Kernel Vulnerability Patches
Cisco responds to pertinent Common Vulnerabilities and Exposures (CVEs) with platform updates that address
known vulnerabilities.
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
8
Guest Shell 2.2
ASLR and X-Space Support
ASLR and X-Space Support
Cisco Nexus 9000 NX-OS supports the use of Address Space Layout Randomization (ASLR) and Executable
Space Protection (X-Space) for runtime defense. The software in Cisco-signed packages make use of this
capability. If other software is installed on the system, it is recommended that it be built using a host OS and
development toolchain that supports these technologies. Doing so reduces the potential attack surface that the
software presents to potential intruders.
Root-User Restrictions
As a best practice for developing secure code, it is recommend running applications with the least privilege
needed to accomplish the assigned task. To help prevent unintended accesses, software added into the guest
shell should follow this best practice.
All processes within a virtual service are subject to restrictions imposed by reduced Linux capabilities. If your
application must perform operations that require root privileges, restrict the use of the root account to the
smallest set of operations that absolutely requires root access, and impose other controls such as a hard limit
on the amount of time that the application can run in that mode.
The set of Linux capabilities that are dropped for root within virtual services follow:
CAP_SYS_BOOT
CAP_MKNOD
CAP_SYS_PACCT
CAP_SYS_MODULE
CAP_MAC_OVERRIDE
CAP_SYS_RESOURCE
CAP_SYS_TIME
CAP_SYS_RAWIO
CAP_AUDIT_WRITE
CAP_AUDIT_CONTROL
CAP_SYS_NICE
CAP_NET_ADMIN
CAP_MAC_ADMIN
CAP_SYS_PTRACE
As root within a virtual-service, bind mounts may be used as well as tmpfs and ramfs mounts. Other mounts
are prevented.
Namespace Isolation
The host and virtual service are separated into separate namespaces. This provides the basis of separating the
execution spaces of the virtual services from the host. Namespace isolation helps to protect against data loss
and data corruption due to accidental or intentional data overwrites between trust boundaries. It also helps to
ensure the integrity of confidential data by preventing data leakage between trust boundaries: an application
in one virtual service cannot access data in another virtual service
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
9
Guest Shell 2.2
Guest File System Access Restrictions
Guest File System Access Restrictions
To preserve the integrity of the files within the virtual services, the file systems of the virtual services are not
accessible from the NX-OS CLI. If a given virtual-service allows files to be modified, it needs to provide an
alternate means by which this can be done (i.e. yum install, scp, ftp, etc).
The Guest Shell mounts the bootflash of the host system at /bootflash. The network-admin can access
the file using an NX-OS CLI or Linux command from within the Guest Shell.
Resource Management
A Denial-of-Service (DoS) attack attempts to make a machine or network resource unavailable to its intended
users. Misbehaving or malicious application code can cause DoS as the result of over-consumption of connection
bandwidth, disk space, memory, and other resources. The host provides resource-management features that
ensure fair allocation of resources among all virtual services on the host.
Guidelines and Limitations
The Guest Shell has the following guideline and limitations:
Common Guidelines Across All Releases
Important
If you have performed custom work inside your installation of the Guest Shell, save your changes to
bootflash, off-box storage, or elsewhere outside the Guest Shell root file system before performing an
upgrade.
The guestshell
in succession.
• Use the run
upgrade command essentially performs a guestshell destroy and guestshell enable
CLI command to access the Guest Shell on the Cisco Nexus device: The run
command parallels the run bash command used to access the host shell. This command
allows you to access the Guest Shell and get a bash prompt or run a command within the context of the
Guest Shell. The command uses password-less SSH to an available port on the localhost in the default
network namespace.
guestshell
guestshell
• sshd utility can secure the pre-configured SSH access into the Guest Shell by listening on localhost
to avoid connection attempts from ouside the network. sshd has the following features
◦It is configured for key-based authentication without fallback to passwords.
◦Only root can read keys use to access the Guest Shell after Guest Shell restarts.
◦Only root can read the file that contains the key on the host to prevent a non-privileged user with
host bash access from being able to use the key to connect to the Guest Shell. Network-admin users
may start another instance of sshd in the Guest Shell to allow remote access directly into the Guest
Shell, but any user that logs into the Guest Shell is also given network-admin privilege
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
10
Guest Shell 2.2
Guidelines and Limitations
Note
Introduced in Guest Shell 2.2 (0.2), the key file is readable for whom the user account
was created for.
In addition, the Guest Shell accounts are not automatically removed, and must be removed
by the network administrator when no longer needed.
Guest Shell installations prior to 2.2 (0.2) with Cisco Nexus release 7.0(3)I5(2) will not
dynamically create individual user accounts.
• Installing the Cisco Nexus series switch software release on a fresh out-of-the-box Cisco Nexus switch
will automatically enable the Guest Shell. Subsequent upgrades to the Cisco Nexus series switch software
will NOT automatically upgrade Guest Shell.
• Guest Shell releases increment the major number when distributions or distribution versions change.
• Guest Shell releases increment the minor number when CVEs have been addressed. The Guest Shell
will update CVEs only when CentOS makes them publically available.
Upgrading from Guest Shell 1.0 to Guest Shell 2.x
Guest Shell 2.x is based upon a CentOS 7 root file system. If you have an off-box repository of .conf files
and/or utilities that pulled the content down into Guest Shell 1.0, you will need to repeat the same deployment
steps in Guest Shell 2.x. Your deployment script may need to be adjusted to account for the CentOS 7
differences.
Guest Shell 2.x
The Cisco NX-OS automatically installs and enables the Guest Shell by default on systems with . However,
if the device is reloaded with a Cisco NX-OS image that does not provide Guest Shell support, the installer
will automatically remove the existing Guest Shell and issue a %VMAN-2-INVALID_PACKAGE.
Note
Systems with 4GB of RAM will not enable Guest Shell by default. Use the guestshell enable command
to install and enable Guest Shell.
The install all command validates the compatibility between the current Cisco NX-OS image against the
target Cisco NX-OS image.
The following is an example output from installing an incompatible image:
switch#
Installer will perform compatibility check first. Please wait.
uri is: /
2014 Aug 29 20:08:51 switch %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE:
Successfully activated virtual service 'guestshell+'
Verifying image bootflash:/n9kpregs.bin for boot variable "nxos".
[####################] 100% -- SUCCESS
Verifying image type.
[####################] 100% -- SUCCESS
Preparing "" version info using image bootflash:/.
[####################] 100% -- SUCCESS
Preparing "bios" version info using image bootflash:/.
[####################] 100% -- SUCCESS
Preparing "" version info using image bootflash:/.
[####################] 100% -- SUCCESS
Preparing "" version info using image bootflash:/.
[####################] 100% -- SUCCESS
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
11
Guest Shell 2.2
Guidelines and Limitations
Preparing "nxos" version info using image bootflash:/.
[####################] 100% -- SUCCESS
Preparing "" version info using image bootflash:/.
[####################] 100% -- SUCCESS
Preparing "" version info using image bootflash:/.
[####################] 100% -- SUCCESS
"Running-config contains configuration that is incompatible with the new image (strict
incompatibility).
Please run 'show incompatibility-all nxos <image>' command to find out which feature
needs to be disabled.".
Performing module support checks.
[####################] 100% -- SUCCESS
Notifying services about system upgrade.
[# ] 0% -- FAIL.
Return code 0x42DD0006 ((null)).
"Running-config contains configuration that is incompatible with the new image (strict
incompatibility).
Please run 'show incompatibility-all nxos <image>' command to find out
which feature needs to be disabled."
Service "vman" in vdc 1: Guest shell not supported, do 'guestshell destroy' to remove
it and then retry ISSU
Pre-upgrade check failed. Return code 0x42DD0006 ((null)).
switch#
Note
As a best practice, remove the Guest Shell with the guestshell destroy command before reloading an
older Cisco Nexos image that does not support the Guest Shell.
Pre-Configured SSHD Service
The Guest Shell starts an OpenSSH server upon boot up. The server listens on a randomly generated port on
the localhost IP address interface 127.0.0.1 only. This provides the password-less connectivity into the Guest
Shell from the NX-OS vegas-shell when the guestshell keyword is entered. If this server is killed or its
configuration (residing in /etc/ssh/sshd_config-cisco) is altered, access to the Guest Shell from
the NX-OS CLI might not work.
The following steps instantiate an OpenSSh server within the Guest Shell as root:
1 Determine which network namespace or VRF you want to establish your SSH connections through.
2 Determine port you want OpenSSH to listen on. Use the NX-OS command show socket connection to
view ports already in use.
Note
The Guest Shell sshd service for password-less access uses a randomized port starting at 17680 through
49150. To avoid port conflict choose a port outside this range.
The following steps start the OpenSSH server. The examples start the OpenSSH server for management netns
on IP address 10.122.84.34:2222:
1 Create the following files: /usr/lib/systemd/systm/sshd-mgmt.service and
/etc/ssh/sshd-mgmt_config. The files should have the following configurations:
-rw-r--r-- 1 root root 394 Apr 7 14:21 /usr/lib/systemd/system/sshd-mgmt.service
-rw------- 1 root root 4478 Apr 7 14:22 /etc/ssh/sshd-mgmt_config
2 Copy the Unit and Service contents from the /usr/lib/systemd/syste/ssh.service file to
sshd-mgmt.service.
[Unit]
Description=OpenSSH server daemon
After=network.target sshd-keygen.service
Wants=sshd-keygen.service
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
12
Guest Shell 2.2
Guidelines and Limitations
[Service]
EnvironmentFile=/etc/sysconfig/sshd
ExecStartPre=/usr/sbin/sshd-keygen
ExecStart=/sbin/ip netns exec management /usr/sbin/sshd -f /etc/ssh/sshd-mgmt_config -D
$OPTIONS
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
Restart=on-failure
RestartSec=42s
[Install]
WantedBy=multi-user.target
3 Copy the contents of /etc/ssh/sshd-config to /etc/ssh/sshd-mgmt_config. Modify the
ListenAddress IP and port as necessary.
Port 2222
ListenAddress 10.122.84.34
4 Start the systemctl daemon using the following commands:
sudo systemctl daemon-reload
sudo systemctl start sshd-mgmt.service
sudo systemctl status sshd-mgmt.service -l
5 (optional) Check the configuration.
ss -tnldp | grep 2222
6 SSH into Guest Shell:
ssh -p 2222 [email protected]
7 Save the configuration across multiple Guess Shell or switch reboots.
sudo systemctl enable sshd-mgmt.service
8 For passwordless SSH/SCP and remote execution, genearte the public and private keys for the user ID
you want to user for SSH/SCP using the ssh-keygen -t dsa command.
The key is then stored in the id_rsa and id_rsa.pub files in the /.ssh directory:
[root@node01 ~]# cd ~/.ssh
[root@node02 .ssh]# ls -l
total 8
-rw-------. 1 root root 1675 May 5 15:01 id_rsa
-rw-r--r--. 1 root root 406 May 5 15:01 id_rsa.pub
9 Copy the public key into the machine you want to SSH into and fix permissions:
cat id_rsa.pub >> /root/.ssh/authorized_keys
chmod 700 /root/.ssh
chmod 600 /root/.ssh/*
10 SSH or SCP into the remote switch without a password:
ssh -p <port#> userid@hostname [<remote command>]
scp -P <port#> userid@hostname/filepath /destination
localtime
The Guest Shell shares /etc/localtime with the host system.
Note
If you do not want to share the same localtime with the host, this symlink can be broken and a Guest Shell
specific /etc/localtime can be created.
switch(config)# clock timezone PDT -7 0
switch(config)# clock set 10:00:00 27 Jan 2017
Fri Jan 27 10:00:00 PDT 2017
switch(config)# show clock
10:00:07.554 PDT Fri Jan 27 2017
switch(config)# run guestshell
guestshell:~$ date
Fri Jan 27 10:00:12 PDT 2017
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
13
Guest Shell 2.2
Testing for Common Vulnerabilities and Exposures in the Guest Shell
Testing for Common Vulnerabilities and Exposures in the Guest Shell
The following steps can help determine and address the impacts by a Common Vulnerabilities and Exposures
(CVEs) in the Guest Shell.
Procedure
Step 1
Locate the CVE identifier, for example, CVE-2014-9112, the affected package(s), cpio, and the affected
version(s) of that package, 2.11.
This information is publicly available on the web.
Step 2
Verify an affected package version is installed, inside the Guest Shell.
[root@guestshell guestshell]# rpm -qa | grep cpio
cpio -2.11-22.el7.x86_64
Step 3
If installed, query the package's changelog to determine if the CVE has already been addressed.
[root@guestshell guestshell]# rpm -q -changelog cpio | grep CVE
-CVE-2010-0624 fix heap-based buffer overflow by expanding
-upstream patch for -2007-4476(stack crashing in safer_name_suffix)
Step 4
If no fix has been applied for the CVE in this package version, there may be an updated version containing
the fix. This can be verified before installing the update by using the yum-changelog plugin.
[root@guestshell guestshell]# yum install yum-changelog
...
Loaded plugins:fastestmirror
Complete!
Step 5
Running yum update with the --changelog parameter will display the changelog for the available updated
versions, including any resolved CVEs. The update may be installed normally.
[root@guestshell guestshell]# yum update cpio --changelog
Loaded plugins: changelog, fastestmirror
...
ChangeLog for: cpio-2.11-24.el7.x86_64
* Wed Jul 8 12:00:00 2015 Username <[email protected]> -2.11-24
-fix for CVE-2014-9112
...
Total download size: 210 k
Is this ok[y/d/N]:
...
Complete!
Managing the Guest Shell
The following are commands to manage the Guest Shell:
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
14
Guest Shell 2.2
Managing the Guest Shell
Table 1: Guest Shell CLI Commands
Commands
Description
guestshell enable [package guest shell OVA file]
Installs and activates the Guest Shell using the OVA
that is embedded in the system image.
Installs and activates the Guest Shell using the
specified software package (OVA file) or the
embedded package from the system image (when no
package is specified). Initially, Guest Shell packages
are only available by being embedded in the system
image.
When the Guest Shell is already installed, this
command enables the installed Guest Shell. Typically
this is used after a guestshell disable command.
guestshell disable
Shuts down and disables the Guest Shell.
guestshell upgrade [package guest shell OVA file]
Deactivates and upgrades the Guest Shell using the
specified software package (OVA file) or the
embedded package from the system image (if no
package is specified). Initially Guest Shell packages
are only available by being embedded in the system
image.
The current rootfs for the Guest Shell is replaced with
the rootfs in the software package. The Guest Shell
does not make use of secondary filesystems that
persist across an upgrade. Without persistent
secondary filesystems, a guestshell destroy command
followed by a guestshell enable command could also
be used to replace the rootfs. When an upgrade is
successful, the Guest Shell is activated.
You are prompted for a confirmation prior to carrying
out the upgrade command.
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
15
Guest Shell 2.2
Managing the Guest Shell
Commands
Description
guestshell reboot
Deactivates the Guest Shell and then reactivates it.
You are prompted for a confirmation prior to carrying
out the reboot command.
Note
This is the equivalent of a guestshell disable
command followed by a guestshell enable
command in exec mode.
This is useful when processes inside the
Guest Shell have been stopped and need to
be restarted. The run guestshell command
relies on sshd running in the Guest Shell.
If the command does not work, the sshd
process may have been inadvertently
stopped. Performing a reboot of the Guest
Shell from the NX-OS CLI allows it to restart
and restore the command.
guestshell destroy
Deactivates and uninstalls the Guest Shell. All
resources associated with the Guest Shell are returned
to the system. The show virtual-service global
command indicates when these resources become
available.
Issuing this command results in a prompt for a
confirmation prior to carrying out the destroy
command.
guestshell
run guestshell
guestshell run command
run guestshell command
Connects to the Guest Shell that is already running
with a shell prompt. No username/password is
required.
Executes a Linux/UNIX command within the context
of the Guest Shell environment.
After execution of the command you are returned to
the switch prompt.
guestshell resize [cpu | memory | rootfs]
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
16
Changes the allotted resources available for the Guest
Shell. The changes take effect the next time the Guest
Shell is enabled or rebooted.
Guest Shell 2.2
Disabling the Guest Shell
Commands
Description
guestshell sync
On systems that have active and standby supervisors,
this command synchronizes the Guest Shell contents
from the active supervisor to the standby supervisor.
The network-admin issues this command when the
Guest Shell rootfs has been set up to a point that they
would want the same rootfs used on the standby
supervisor when it becomes the active supervisor. If
this command is not used, the Guest Shell is freshly
installed when the standby supervisor transitions to
an active role using the Guest Shell package available
on that supervisor.
virtual-service reset force
In the event that the guestshell or virtual-services
cannot be managed, even after a system reload, the
reset command is used to force the removal of the
Guest Shell and all virtual-services. The system needs
to be reloaded for the cleanup to happen. No Guest
Shell or additional virtual-services can be installed
or enabled after issuing this command until after the
system has been reloaded.
You are prompted for a confirmation prior to initiating
the reset.
Note
Administrative privileges are necessary to enable/disable and to gain access to the Guest Shell environment.
Note
The Guest Shell is implemented as a Linux container (LXC) on the host system. On NX-OS devices,
LXCs are installed and managed with the virtual-service commands. The Guest Shell appears in the
virtual-service commands as a virtual service named guestshell+.
Disabling the Guest Shell
The guestshell disable command shuts down and disables the Guest Shell.
When the Guest Shell is disabled and the system is reloaded, the Guest Shell remains disabled.
Example:
switch# show virtual-service list
Virtual Service List:
Name
Status
Package Name
----------------------------------------------------------guestshell+
Activated
guestshe11.ova
switch# guestshell disable
You will not be able to access your guest shell if it is disabled. Are you sure you want
to disable the guest shell? (y/n) [n) y
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
17
Guest Shell 2.2
Destroying the Guest Shell
2014 Jul 30 19:47:23 switch %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE: Deactivating virtual
service 'guestshell+'
2014 Jul 30 18:47:29 switch %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE: Successfully deactivated
virtual service 'guestshell+'
switch# show virtual-service list
Virtual Service List:
Name
Status
Package Name
guestshell+
Deactivated
guestshell.ova
Note
The Guest Shell is reactivated with the guestshell enable command.
Destroying the Guest Shell
The guestshell destroy command uninstalls the Guest Shell and its artifacts. The command does not remove
the Guest Shell OVA.
When the Guest Shell is destroyed and the system is reloaded, the Guest Shell remains destroyed.
switch# show virtual-service list
Virtual Service List:
Name
Status
Package Name
------------------------------------------------guestshell+
Deactivated
guestshell.ova
switch# guestshell destroy
You are about to destroy the guest shell and all of its contents. Be sure to save your work.
Are you sure you want to continue? (y/n) [n] y
2014 Jul 30 18:49:10 switch %$ VDC-1 %$ %VMAN-2-INSTALL_STATE: Destroying virtual service
'guestshell+'
2014 Jul 30 18:49:10 switch %$ VDC-1 %$ %VMAN-2-INSTALL_STATE: Successfully destroyed
virtual service 'guestshell +'
switch# show virtual-service list
Virtual Service List:
Note
The Guest Shell can be re-enabled with the guestshell enable command.
Note
If you do not want to use the Guest Shell, you can remove it with the guestshell destroy command. Once
the Guest Shell has been removed, it remains removed for subsequent reloads. This means that when the
Guest Shell container has been removed and the switch is reloaded, the Guest Shell container is not
automatically started.
Enabling the Guest Shell
The guestshell enable command installs the Guest Shell from a Guest Shell software package. By default,
the package embedded in the system image is used for the installation. The command is also used to reactivate
the Guest Shell if it has been disabled.
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
18
Guest Shell 2.2
Verifying Virtual Service and Guest Shell Information
When the Guest Shell is enabled and the system is reloaded, the Guest Shell remains enabled.
Example:
switch# show virtual-service list
Virtual Service List:
switch# guestshell enable
2014 Jul 30 18:50:27 switch %$ VDC-1 %$ %VMAN-2-INSTALL_STATE: Installing virtual service
'guestshell+'
2014 Jul 30 18;50;42 switch %$ VDC-1 %$ %VMAN-2-INSTALL_STATE: Install success virtual
service 'guestshell+'; Activating
2014 Jul 30 18:50:42 switch %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE: Activating virtual service
'guestshell+'
2014 Jul 30 18:51:16 switch %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE: Successfully activated
virtual service 'guestshell+'
switch# show virtual-service list
Virtual Service List:
Name
Status
guestshell+
Activated
Package Name
guestshell.ova
Verifying Virtual Service and Guest Shell Information
You can verify virtual service and Guest Shell information with the following commands:
Command
Description
show virtual-service global
Displays the global state and
limits for virtual services.
switch# show virtual-service global
Virtual Service Global State and Virtualization Limits:
Infrastructure version : 1.9
Total virtual services installed : 1
Total virtual services activated : 1
Machine types supported : LXC
Machine types disabled : KVM
Maximum VCPUs per virtual service : 1
Resource virtualization limits:
Name Quota Committed Available
----------------------------------------------------------------------system CPU (%) 20 1 19
memory (MB) 3840 256 3584
bootflash (MB) 8192 200 7992
switch#
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
19
Guest Shell 2.2
Persistently Starting Your Application From the Guest Shell
Command
Description
show virtual-service list
Displays a summary of the
virtual services, the status of
the virtual services, and
installed software packages.
switch# show virtual-service list *
Virtual Service List:
Name
Status
Package Name
-----------------------------------------------------------------guestshell+
Activated
guestshell.ova
chef
Installed
chef-0.8.1-n9000-spa-k9.ova
show guestshell detail
switch# show guestshell detail
Virtual service guestshell+ detail
State
: Activated
Package information
Name
: guestshell.ova
Path
: /isan/bin/guestshell.ova
Application
Name
: GuestShell
Installed version : 2.2(0.2)
Description
: Cisco Systems Guest Shell
Signing
Key type
: Cisco key
Method
: SHA-1
Licensing
Name
: None
Version
: None
Resource reservation
Disk
: 250 MB
Memory
: 256 MB
CPU
: 1% system CPU
Displays details about the
guestshell package (such as
version, signing resources,
and devices).
Attached devices
Type
Name
Alias
--------------------------------------------Disk
_rootfs
Disk
/cisco/core
Serial/shell
Serial/aux
Serial/Syslog
serial2
Serial/Trace
serial3
Persistently Starting Your Application From the Guest Shell
Your application should have a systemd / systemctl service file that gets installed in
/usr/lib/systemd/system/application_name.service. This service file should have the following
general format:
[Unit]
Description=Put a short description of your application here
[Service]
ExecStart=Put the command to start your application here
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
20
Guest Shell 2.2
Procedure for Persistently Starting Your Application from the Guest Shell
Restart=always
RestartSec=10s
[Install]
WantedBy=multi-user.target
Note
To run systemd as a specific user, add User=<username> to the [Service] section of your service.
Procedure for Persistently Starting Your Application from the
Guest Shell
Procedure
Step 1
Install your application service file that you created above into
/usr/lib/systemd/system/application_name.service
Step 2
Start your application with systemctl start application_name
Step 3
Verify that your application is running with systemctl status -l application_name
Step 4
Enable your application to be restarted on reload with systemctl enable application_name
Step 5
Verify that your application is running with systemctl status -l application_name
An Example Application in the Guest Shell
The following example demonstrates an application in the Guest Shell:
root@guestshell guestshell]# cat /etc/init.d/hello.sh
#!/bin/bash
OUTPUTFILE=/tmp/hello
rm -f $OUTPUTFILE
while true
do
echo $(date) >> $OUTPUTFILE
echo 'Hello World' >> $OUTPUTFILE
sleep 10
done
[root@guestshell guestshell]#
[root@guestshell guestshell]#
[root@guestshell system]# cat /usr/lib/systemd/system/hello.service
[Unit]
Description=Trivial "hello world" example daemon
[Service]
ExecStart=/etc/init.d/hello.sh &
Restart=always
RestartSec=10s
[Install]
WantedBy=multi-user.target
[root@guestshell system]#
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
21
Guest Shell 2.2
An Example Application in the Guest Shell
[root@guestshell system]# systemctl start hello
[root@guestshell system]# systemctl enable hello
[root@guestshell system]# systemctl status -l hello
hello.service - Trivial "hello world" example daemon
Loaded: loaded (/usr/lib/systemd/system/hello.service; enabled)
Active: active (running) since Sun 2015-09-27 18:31:51 UTC; 10s ago
Main PID: 355 (hello.sh)
CGroup: /system.slice/hello.service
##355 /bin/bash /etc/init.d/hello.sh &
##367 sleep 10
Sep 27 18:31:51 guestshell hello.sh[355]: Executing: /etc/init.d/hello.sh &
[root@guestshell system]#
[root@guestshell guestshell]# exit
exit
[guestshell@guestshell ~]$ exit
logout
switch# reload
This command will reboot the system. (y/n)? [n] y
After reload
[root@guestshell guestshell]#
root
20
1 0 18:37
root
123
108 0 18:38
[root@guestshell guestshell]#
[root@guestshell guestshell]#
Sun Sep 27 18:38:03 UTC 2015
Hello World
Sun Sep 27 18:38:13 UTC 2015
Hello World
Sun Sep 27 18:38:23 UTC 2015
Hello World
Sun Sep 27 18:38:33 UTC 2015
Hello World
Sun Sep 27 18:38:43 UTC 2015
Hello World
[root@guestshell guestshell]#
ps -ef | grep hello
?
00:00:00 /bin/bash /etc/init.d/hello.sh &
pts/4
00:00:00 grep --color=auto hello
cat /tmp/hello
Running under systemd / systemctl, your application is automatically restarted if it dies (or if you
kill it). The Process ID is originally 226. After killing the application, it is automatically restarted with a
Process ID of 257.
[root@guestshell
root
226
root
254
[root@guestshell
[root@guestshell
[root@guestshell
[root@guestshell
root
257
root
264
[root@guestshell
guestshell]#
1 0 19:02
116 0 19:03
guestshell]#
guestshell]#
guestshell]#
guestshell]#
1 0 19:03
116 0 19:03
guestshell]#
ps -ef | grep hello
?
00:00:00 /bin/bash /etc/init.d/hello.sh &
pts/4
00:00:00 grep --color=auto hello
kill -9 226
ps -ef | grep hello
?
00:00:00 /bin/bash /etc/init.d/hello.sh &
pts/4
00:00:00 grep --color=auto hello
Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 7.x
22