Enable the Guest Shell

Enabling the Guest Shell

To enable the guest shell on Cisco Catalyst 8000V running on AWS, create an IAM instance role and establish trust with an EC2 service. You have a choice of either assigning the IAM instance role to a preexisting Cisco Catalyst 8000V instance or assigning the IAM instance role to a new Cisco Catalyst 8000V instance.

For more information on how to perform these tasks, see Assign an IAM Instance Role to a Cisco Catalyst 8000V and Assign an IAM Instance Role to a New Cisco Catalyst 8000V.

Then, perform further configuration steps on Cisco Catalyst 8000V and enter the guest shell.

Create an IAM Instance Role

  1. Sign into AWS, as an administrator with permissions to create an IAM Role

  2. Click EC2 to enter the EC2 console.

  3. Click IAM to enter the IAM console.

  4. Click Roles.

    Figure 1. IAM Instance Roles

  5. Click Create new Role.

  6. Enter a name for your app's role.

  7. Click Continue.

  8. Select a Role Type.

    Figure 2. IAM Instance Role Types

  9. For the Amazon EC2 role type, click Select.

    This establishes trust with an EC2 service.

  10. From Set Permissions, click Select Policy Template.

  11. Select a template (for example, "Amazon S3 Full Access") by clicking Select. You can select multiple services. Use this option to specify the access in further detail. For example, you can allow an IAM instance role to read from an S3 bucket but not write to an S3 bucket.

  12. Enter the role name.

  13. Click Create Role.

Assign an IAM Instance Role to a Cisco Catalyst 8000V Instance

Specifying an IAM instance role is not a mandatory for accessing the guest shell. However, it will later allow you to access specific entities in the AWS account using a key or a password that eliminates the need to save account information on the Cisco Catalyst 8000V instance.

Procedure

Step 1

Click EC2 to enter the EC2 dashboard.

Step 2

Select one of your listed Cisco Catalyst 8000V instances, right-click and select Instance Setup. Then, select Attach/Replace IAM Role.

Step 3

From the drop-down list, select an IAM instance role that you created previously.

Step 4

Enter the following CLI configuration commands on Cisco Catalyst 8000V and relaunch Cisco Catalyst 8000V. 


Router(config)# interface GigabitEthernet1
Router(config-if)# ip address dhcp
Router(config-if)# ip nat outside
Router(config-if)# exit
Router(config)# interface VirtualPortGroup0
Router(config-if)# ip address 192.168.35.1 255.255.255.0
Router(config-if)# ip nat inside
Router(config-if)# exit
Router(config)# ip nat inside source list GS_NAT_ACL interface GigabitEthernet1 overload
Router(config)# ip access-list standard GS_NAT_ACL
Router(config)# permit 192.168.0.0 0.0.255.255
Router(config)# app-hosting appid guestshell
Router(config-app-hosting)# vnic gateway1 virtualportgroup 0 guest-interface 0 guest-ipaddress 192.168.35.2 netmask 255.255.255.0 gateway 192.168.35.1 name-server 8.8.8.8 default
Router(config-app-hosting)# resource profile custom cpu 1500 memory 512
Router(config-app-hosting)# exit
Router(config)# exit
Router# guestshell enable
Router# guestshell run python

Assign an IAM Instance Role to a New Instance

The following procedure shows how to assign an IAM Instance Role to Cisco Catalyst 8000V during the creation of a new Cisco Catalyst 8000V instance.

Procedure

Step 1

Launch a new Cisco Catalyst 8000V as an EC2 instance, and choose an instance type.

Step 2

Click Next: Configure Instance Details.

Step 3

Perform one of the following two steps:

  1. Click the IAM role text box to select an existing IAM instance role from the dropdown list.

  2. Click Create new IAM role to create a new IAM instance role.

Step 4

Enter the following CLI configuration commands on the Cisco Catalyst 8000V instance and relaunch the instance. 


Router(config)# interface GigabitEthernet1
Router(config-if)# ip address dhcp
Router(config-if)# ip nat outside
Router(config-if)# exit
Router(config)# interface VirtualPortGroup0
Router(config-if)# ip address 192.168.35.1 255.255.255.0
Router(config-if)# ip nat inside
Router(config-if)# exit
Router(config)# ip nat inside source list GS_NAT_ACL interface GigabitEthernet1 overload
Router(config)# ip access-list standard GS_NAT_ACL
Router(config)# permit 192.168.0.0 0.0.255.255
Router(config)# app-hosting appid guestshell
Router(config-app-hosting)# vnic gateway1 virtualportgroup 0 guest-interface 0 guest-ipaddress 192.168.35.2 netmask 255.255.255.0 gateway 192.168.35.1 name-server 8.8.8.8 default
Router(config-app-hosting)# resource profile custom cpu 1500 memory 512
Router(config-app-hosting)# exit
Router(config)# exit
Router# guestshell enable
Router# guestshell run python

Examples of Guest Shell

The following examples show how to download packages in the Guest Shell on a Cisco Catalyst 8000V instance, and a few other useful guest shell commands.

  1. Install packages using the yum or pip3 commands. For example, enter the [guestshell@guestshell ~] sudo pip3 install awscli command to install the AWS CLI and Amazon SDK. 

    [guestshell@guestshell ~]$ sudo pip3 install awscli 
WARNING: Running pip install with root privileges is generally not a good idea. Try `pip3 install --user` instead.
Collecting awscli
  Downloading https://files.pythonhosted.org/packages/ce/38/6f2b06f0f00e6b381ad4741d0bf97eb2e3faa23238a2dfe31577154a207c/awscli-1.18.157-py2.py3-none-any.whl (3.4MB)
    100% |################################| 3.4MB 369kB/s 
Collecting colorama<0.4.4,>=0.2.5; python_version != "3.4" (from awscli)
  Downloading https://files.pythonhosted.org/packages/c9/dc/45cdef1b4d119eb96316b3117e6d5708a08029992b2fee2c143c7a0a5cc5/colorama-0.4.3-py2.py3-none-any.whl
Collecting s3transfer<0.4.0,>=0.3.0 (from awscli)
  Downloading https://files.pythonhosted.org/packages/69/79/e6afb3d8b0b4e96cefbdc690f741d7dd24547ff1f94240c997a26fa908d3/s3transfer-0.3.3-py2.py3-none-any.whl (69kB)
    100% |################################| 71kB 7.3MB/s 
Collecting docutils<0.16,>=0.10 (from awscli)
  Downloading https://files.pythonhosted.org/packages/22/cd/a6aa959dca619918ccb55023b4cb151949c64d4d5d55b3f4ffd7eee0c6e8/docutils-0.15.2-py3-none-any.whl (547kB)
    100% |################################| 552kB 2.1MB/s 
Collecting PyYAML<5.4,>=3.10; python_version != "3.4" (from awscli)
  Downloading https://files.pythonhosted.org/packages/64/c2/b80047c7ac2478f9501676c988a5411ed5572f35d1beff9cae07d321512c/PyYAML-5.3.1.tar.gz (269kB)
    100% |################################| 276kB 3.6MB/s 
Collecting rsa<=4.5.0,>=3.1.2; python_version != "3.4" (from awscli)
  Downloading https://files.pythonhosted.org/packages/26/f8/8127fdda0294f044121d20aac7785feb810e159098447967a6103dedfb96/rsa-4.5-py2.py3-none-any.whl
Collecting botocore==1.18.16 (from awscli)
  Downloading https://files.pythonhosted.org/packages/2d/9e/afa41db0cd911869305bb783b9b021be67ea23c8b7b317caa46632dbf3cf/botocore-1.18.16-py2.py3-none-any.whl (6.7MB)
    100% |################################| 6.7MB 173kB/s 
Collecting pyasn1>=0.1.3 (from rsa<=4.5.0,>=3.1.2; python_version != "3.4"->awscli)
  Downloading https://files.pythonhosted.org/packages/62/1e/a94a8d635fa3ce4cfc7f506003548d0a2447ae76fd5ca53932970fe3053f/pyasn1-0.4.8-py2.py3-none-any.whl (77kB)
    100% |################################| 81kB 7.5MB/s 
Collecting urllib3<1.26,>=1.20; python_version != "3.4" (from botocore==1.18.16->awscli)
  Downloading https://files.pythonhosted.org/packages/9f/f0/a391d1463ebb1b233795cabfc0ef38d3db4442339de68f847026199e69d7/urllib3-1.25.10-py2.py3-none-any.whl (127kB)
    100% |################################| 133kB 6.1MB/s 
Collecting python-dateutil<3.0.0,>=2.1 (from botocore==1.18.16->awscli)
  Downloading https://files.pythonhosted.org/packages/d4/70/d60450c3dd48ef87586924207ae8907090de0b306af2bce5d134d78615cb/python_dateutil-2.8.1-py2.py3-none-any.whl (227kB)
    100% |################################| 235kB 4.0MB/s 
Collecting jmespath<1.0.0,>=0.7.1 (from botocore==1.18.16->awscli)
  Downloading https://files.pythonhosted.org/packages/07/cb/5f001272b6faeb23c1c9e0acc04d48eaaf5c862c17709d20e3469c6e0139/jmespath-0.10.0-py2.py3-none-any.whl
Collecting six>=1.5 (from python-dateutil<3.0.0,>=2.1->botocore==1.18.16->awscli)
  Downloading https://files.pythonhosted.org/packages/ee/ff/48bde5c0f013094d729fe4b0316ba2a24774b3ff1c52d924a8a4cb04078a/six-1.15.0-py2.py3-none-any.whl
Installing collected packages: colorama, urllib3, six, python-dateutil, jmespath, botocore, s3transfer, docutils, PyYAML, pyasn1, rsa, awscli
  Running setup.py install for PyYAML ... done
Successfully installed PyYAML-5.3.1 awscli-1.18.157 botocore-1.18.16 colorama-0.4.3 docutils-0.15.2 jmespath-0.10.0 pyasn1-0.4.8 python-dateutil-2.8.1 rsa-4.5 s3transfer-0.3.3 six-1.15.0 urllib3-1.25.10
[guestshell@guestshell ~]$ aws s3 ls c8kv
Unable to locate credentials. You can configure credentials by running "aws configure"
  2. Having installed the AWS CLI, enter the aws s3 command such as aws s3 ls.
    [guestshell@guestshell ~]$ aws s3 ls c8kv
2020-10-14 19:44:08  433546509 upgrade.bin
[guestshell@guestshell ~]$

  3. You can download a Cisco Catalyst 8000V AWS package containing sample scripts using the sudo pip3 install csr_aws_guestshell command.

    Example:

    [guestshell@guestshell ~]$ sudo pip3 install csr_aws_guestshell
WARNING: Running pip install with root privileges is generally not a good idea. Try `pip3 install --user` instead.
Collecting csr_aws_guestshell
Downloading https://files.pythonhosted.org/packages/42/a7/c772726166f809d9223ef448f5d7fa2cfb8a809525a11991612d81dd080a/csr_aws_guestshell-0.0.17.dev.tar.gz
Collecting awscli (from csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/23/1b/2b65ddc4e18ab8b232d413b75591ccd22021233fb3c3fd1ddd099d0170ce/awscli-1.18.162-py2.py3-none-any.whl (3.4MB)
100% |################################| 3.4MB 352kB/s
Collecting boto (from csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/23/10/c0b78c27298029e4454a472a1919bde20cb182dab1662cec7f2ca1dcc523/boto-2.49.0-py2.py3-none-any.whl (1.4MB)
100% |################################| 1.4MB 794kB/s
Collecting boto3 (from csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/30/3c/c9b65c398de6589c93b3c65aa27a695a6cdf7588c50a7934ad3ac6599a8a/boto3-1.16.2-py2.py3-none-any.whl (129kB)
100% |################################| 133kB 7.2MB/s
Collecting rsa<=4.5.0,>=3.1.2; python_version != "3.4" (from awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/26/f8/8127fdda0294f044121d20aac7785feb810e159098447967a6103dedfb96/rsa-4.5-py2.py3-none-any.whl
Collecting botocore==1.19.2 (from awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/1f/96/35fa364675cf17e3a190ae08716ac4b078ca86a62ef071d32cd8b86d52bc/botocore-1.19.2-py2.py3-none-any.whl (6.7MB)
100% |################################| 6.7MB 164kB/s
Collecting PyYAML<5.4,>=3.10; python_version != "3.4" (from awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/64/c2/b80047c7ac2478f9501676c988a5411ed5572f35d1beff9cae07d321512c/PyYAML-5.3.1.tar.gz (269kB)
100% |################################| 276kB 3.6MB/s
Collecting s3transfer<0.4.0,>=0.3.0 (from awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/69/79/e6afb3d8b0b4e96cefbdc690f741d7dd24547ff1f94240c997a26fa908d3/s3transfer-0.3.3-py2.py3-none-any.whl (69kB)
100% |################################| 71kB 7.6MB/s
Collecting docutils<0.16,>=0.10 (from awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/22/cd/a6aa959dca619918ccb55023b4cb151949c64d4d5d55b3f4ffd7eee0c6e8/docutils-0.15.2-py3-none-any.whl (547kB)
100% |################################| 552kB 1.9MB/s
Collecting colorama<0.4.4,>=0.2.5; python_version != "3.4" (from awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/c9/dc/45cdef1b4d119eb96316b3117e6d5708a08029992b2fee2c143c7a0a5cc5/colorama-0.4.3-py2.py3-none-any.whl
Collecting jmespath<1.0.0,>=0.7.1 (from boto3->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/07/cb/5f001272b6faeb23c1c9e0acc04d48eaaf5c862c17709d20e3469c6e0139/jmespath-0.10.0-py2.py3-none-any.whl
Collecting pyasn1>=0.1.3 (from rsa<=4.5.0,>=3.1.2; python_version != "3.4"->awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/62/1e/a94a8d635fa3ce4cfc7f506003548d0a2447ae76fd5ca53932970fe3053f/pyasn1-0.4.8-py2.py3-none-any.whl (77kB)
100% |################################| 81kB 9.4MB/s
Collecting urllib3<1.26,>=1.25.4; python_version != "3.4" (from botocore==1.19.2->awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/56/aa/4ef5aa67a9a62505db124a5cb5262332d1d4153462eb8fd89c9fa41e5d92/urllib3-1.25.11-py2.py3-none-any.whl (127kB)
100% |################################| 133kB 6.5MB/s
Collecting python-dateutil<3.0.0,>=2.1 (from botocore==1.19.2->awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/d4/70/d60450c3dd48ef87586924207ae8907090de0b306af2bce5d134d78615cb/python_dateutil-2.8.1-py2.py3-none-any.whl (227kB)
100% |################################| 235kB 4.6MB/s
Collecting six>=1.5 (from python-dateutil<3.0.0,>=2.1->botocore==1.19.2->awscli->csr_aws_guestshell)
Downloading https://files.pythonhosted.org/packages/ee/ff/48bde5c0f013094d729fe4b0316ba2a24774b3ff1c52d924a8a4cb04078a/six-1.15.0-py2.py3-none-any.whl
Installing collected packages: pyasn1, rsa, urllib3, six, python-dateutil, jmespath, botocore, PyYAML, s3transfer, docutils, colorama, awscli, boto, boto3, csr-aws-guestshell
Running setup.py install for PyYAML ... done
Running setup.py install for csr-aws-guestshell ... done
Successfully installed PyYAML-5.3.1 awscli-1.18.162 boto-2.49.0 boto3-1.16.2 botocore-1.19.2 colorama-0.4.3 csr-aws-guestshell-0.0.17.dev0 docutils-0.15.2 jmespath-0.10.0 pyasn1-0.4.8 python-dateutil-2.8.1 rsa-4.5 s3transfer-0.3.3 six-1.15.0 urllib3-1.25.11
    The following scripts are included in the csr_aws_guestshell package:

    get-metadata.py - retrieves and prints instance metadata from AWS.

    get-route-table.py - retrieves instances in VPC along with routes, route tables, and associations.

    save-config-to-s3.py - saves the Cisco IOS XE CLI commands to an S3 bucket.

    save-tech-support-to-s3.py - saves the tech support output to an S3 bucket.

    load-bin-from-s3.py - downloads a .bin file for Cisco Catalyst 8000V and reloads.

    get-stat-drop.py - retrieves the CLI statistics and pushes them to cloudwatch.

    capture-interface.py - sets the Cisco IOS XE CLI commands to monitor and captures packets for a period of time, then uploads the file to S3.

  4. In the following example, the load-bin-from-s3.py script loads a binary from S3 and boots a Cisco Catalyst 8000V image: 

    [guestshell@guestshell ~]$ load-bin-from-s3.py csr1kv ultra_167.bin
/bootflash/ultra_167.bin  446866343 / 446866343  (100.00%)
Download Complete

Note

The csr_aws_guestshell package will continue to work with Cisco Catalyst 8000V.