Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6€¦ · CiscoNexus9000SeriesNX-OSProgrammabilityGuide,Release6.x FirstPublished:2013-11-20 LastModified:2019-09-21 AmericasHeadquarters

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xFirst Published: 2013-11-20

Last Modified: 2019-09-21

Americas HeadquartersCisco Systems, Inc.170 West Tasman DriveSan Jose, CA 95134-1706USAhttp://www.cisco.comTel: 408 526-4000

800 553-NETS (6387)Fax: 408 527-0883

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITHTHE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version ofthe UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHERWARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS.CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUTLIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERSHAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, networktopology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentionaland coincidental.

This product includes cryptographic software written by Eric Young ([email protected]).

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)

This product includes software written by Tim Hudson ([email protected]).

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL:http://www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationshipbetween Cisco and any other company. (1110R)

© 2014–2019 Cisco Systems, Inc. All rights reserved.

http://www.openssl.org/

http://www.cisco.com/go/trademarks

C O N T E N T S

Preface viiP R E F A C E

Audience vii

Document Conventions vii

Related Documentation for Cisco Nexus 9000 Series Switches viii

Documentation Feedback viii

Communications, Services, and Additional Information viii

New and Changed Information 1C H A P T E R 1

New and Changed Information 1

Overview 3C H A P T E R 2

Programmability Overview 3

Standard Network Manageability Features 4

Advanced Automation Feature 4

PowerOn Auto Provisioning Support 4

OpenStack Integration 4

Programmability Support 5

NX-API Support 6

Python Scripting 6

Tcl Scripting 6

Broadcom Shell 6

Bash 6

Guest Shell 6

NX-API 9C H A P T E R 3

About NX-API 9

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xiii

Transport 9

Message Format 9

Security 10

Using NX-API 10

Sample NX-API Scripts 12

NX-API Sandbox 12

NX-API Management Commands 13

NX-API Request Elements 14

NX-API Response Elements 17

Python API 19C H A P T E R 4

About the Python API 19

Using Python 19

Cisco Python Package 19

Using the CLI Command APIs 20

Invoking the Python Interpreter from the CLI 22

Display Formats 22

Non-interactive Python 23

Running Scripts with Embedded Event Manager 25

Python Integration with Cisco NX-OS Network Interfaces 25

Cisco NX-OS Security with Python 26

Examples of Security and User Authority 26

Example of Running Script with Scheduler 27

Broadcom Shell 29C H A P T E R 5

About the Broadcom Shell 29

Guidelines and Limitations 29

Accessing the Broadcom Shell (bcm-shell) 29

Accessing bcm-shell with the CLI API 29

Accessing the Native bcm-shell on the Fabric Module 30

Accessing the bcm-shell on the Line Card 31

Bash 33C H A P T E R 6

About Bash 33

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xiv

Contents

Accessing Bash 33

Escalate Privileges to Root 34

Examples of Bash Commands 35

Displaying System Statistics 35

Running Bash from CLI 35

Running Python from Bash 36

Guest Shell 37C H A P T E R 7

About the Guest Shell 37

Accessing the Guest Shell 38

Capabilities in the Guest Shell 38

NX-OS CLI in the Guest Shell 38

Network Access in Guest Shell 39

Access to Bootflash in Guest Shell 40

Python in Guest Shell 40

Installing RPMs in the Guest Shell 41

Resources Used for the Guest Shell 42

Security Posture for Virtual Services 43

Digitally Signed Application Packages 43

Kernel Vulnerability Patches 43

ASLR and X-Space Support 43

Root-User Restrictions 43

Namespace Isolation 44

Guest File System Access Restrictions 44

Resource Management 44

Secure IPC 44

Guidelines and Limitations 45

Managing the Guest Shell 46

Disabling the Guest Shell 49

Destroying the Guest Shell 50

Enabling the Guest Shell 51

Verifying Virtual Service and Guest Shell Information 51

Scripting with Tcl 55C H A P T E R 8

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xv

Contents

About Tcl 55

Tclsh Command Help 55

Tclsh Command History 56

Tclsh Tab Completion 56

Tclsh CLI Command 56

Tclsh Command Separation 56

Tcl Variables 57

Tclquit 57

Tclsh Security 57

Running the tclsh Command 57

Navigating Cisco NX-OS Modes from the tclsh Command 58

Tcl References 60

NX-API Response Codes 61A P P E N D I X A

Table of NX-API Response Codes 61

Troubleshooting 63A P P E N D I X B

About Troubleshooting 63

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xvi

Contents

Preface

This preface includes the following sections:

• Audience, on page vii• Document Conventions, on page vii• Related Documentation for Cisco Nexus 9000 Series Switches, on page viii• Documentation Feedback, on page viii• Communications, Services, and Additional Information, on page viii

AudienceThis publication is for network administrators who install, configure, and maintain Cisco Nexus switches.

Document ConventionsCommand descriptions use the following conventions:

DescriptionConventionBold text indicates the commands and keywords that you enter literallyas shown.

bold

Italic text indicates arguments for which you supply the values.Italic

Square brackets enclose an optional element (keyword or argument).[x]

Square brackets enclosing keywords or arguments that are separated bya vertical bar indicate an optional choice.

[x | y]

Braces enclosing keywords or arguments that are separated by a verticalbar indicate a required choice.

{x | y}

Nested set of square brackets or braces indicate optional or requiredchoices within optional or required elements. Braces and a vertical barwithin square brackets indicate a required choice within an optionalelement.

[x {y | z}]

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xvii

DescriptionConvention

Indicates a variable for which you supply values, in context where italicscannot be used.

variable

A nonquoted set of characters. Do not use quotation marks around thestring or the string includes the quotation marks.

string

Examples use the following conventions:

DescriptionConventionTerminal sessions and information the switch displays are in screen font.screen font

Information that you must enter is in boldface screen font.boldface screen font

Arguments for which you supply values are in italic screen font.italic screen font

Nonprinting characters, such as passwords, are in angle brackets.< >

Default responses to system prompts are in square brackets.[ ]

An exclamation point (!) or a pound sign (#) at the beginning of a lineof code indicates a comment line.

!, #

Related Documentation for Cisco Nexus 9000 Series SwitchesThe entire Cisco Nexus 9000 Series switch documentation set is available at the following URL:

http://www.cisco.com/en/US/products/ps13386/tsd_products_support_series_home.html

Documentation FeedbackTo provide technical feedback on this document, or to report an error or omission, please send your commentsto [email protected]. We appreciate your feedback.

Communications, Services, and Additional Information• To receive timely, relevant information from Cisco, sign up at Cisco Profile Manager.

• To get the business impact you’re looking for with the technologies that matter, visit Cisco Services.

• To submit a service request, visit Cisco Support.

• To discover and browse secure, validated enterprise-class apps, products, solutions and services, visitCisco Marketplace.

• To obtain general networking, training, and certification titles, visit Cisco Press.

• To find warranty information for a specific product or product family, access Cisco Warranty Finder.

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xviii

PrefaceRelated Documentation for Cisco Nexus 9000 Series Switches

http://www.cisco.com/en/US/products/ps13386/tsd_products_support_series_home.html

https://www.cisco.com/offer/subscribe

https://www.cisco.com/go/services

https://www.cisco.com/c/en/us/support/index.html

https://www.cisco.com/go/marketplace/

https://www.cisco.com/go/marketplace/

http://www.ciscopress.com

http://www.cisco-warrantyfinder.com

Cisco Bug Search Tool

Cisco Bug Search Tool (BST) is a web-based tool that acts as a gateway to the Cisco bug tracking systemthat maintains a comprehensive list of defects and vulnerabilities in Cisco products and software. BST providesyou with detailed defect information about your products and software.

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xix

PrefacePreface

https://www.cisco.com/c/en/us/support/web/tools/bst/bsthelp/index.html

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.xx

PrefacePreface

C H A P T E R 1New and Changed Information

This chapter provides release-specific information for each new and changed feature in the Cisco Nexus 9000Series NX-OS Programmability Guide, Release 6.x.

• New and Changed Information, on page 1

New and Changed InformationThis chapter provides release-specific information for each new and changed feature in the Cisco Nexus 9000Series NX-OS Programmability Guide, Release 6.x.

Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 6.x1


New and Changed InformationNew and Changed Information

C H A P T E R 2Overview

• Programmability Overview, on page 3• Standard Network Manageability Features, on page 4• Advanced Automation Feature, on page 4• Programmability Support, on page 5

Programmability OverviewThe Cisco NX-OS software running on the Cisco Nexus 9000 Series devices is as follows:

• Resilient

Provides critical business-class availability.

• Modular

Has extensions that accommodate business needs.

• Highly Programmatic

Allows for rapid automation and orchestration through Application Programming Interfaces (APIs).

• Secure

Protects and preserves data and operations.

• Flexible

Integrates and enables new technologies.

• Scalable

Accommodates and grows with the business and its requirements.

• Easy to use

Reduces the amount of learning required, simplifies deployment, and provides ease of manageability.

With the Cisco NX-OS operating system, the device functions in the unified fabric mode to provide networkconnectivity with programmatic automation functions.

Cisco NX-OS contains Open Source Software (OSS) and commercial technologies that provide automation,orchestration, programmability, monitoring and compliance support.


Standard Network Manageability Features• SNMP (V1, V2, V3)

• Syslog

• RMON

• NETCONF

• CLI and CLI scripting

Advanced Automation FeatureThe enhanced Cisco NX-OS on the device supports automation. The platform includes support for PowerOnAuto Provisioning (POAP).

PowerOn Auto Provisioning SupportPowerOn Auto Provisioning (POAP) automates the process of installing/upgrading software images andinstalling configuration files on Cisco Nexus devices that are being deployed in the network for the first time.It reduces the manual tasks required to scale the network capacity.

When a Cisco Nexus device with the POAP feature boots and does not find the startup configuration, thedevice enters POAPmode. It locates a DHCP server and bootstraps itself with its interface IP address, gateway,and DNS server IP addresses. The device obtains the IP address of a TFTP server or the URL of an HTTPserver and downloads a configuration script that enables the device to download and install the appropriatesoftware image and configuration file.

For more details about POAP, see the Cisco Nexus 9000 Series NX-OS Fundamentals Configuration Guide.

OpenStack IntegrationThe Cisco Nexus 9000 Series devices support the Cisco Nexus plugin for OpenStack Networking, also knownas Neutron (http://www.cisco.com/web/solutions/openstack/index.html). The plugin allows you to build aninfrastructure as a service (IaaS) network and to deploy a cloud network. With OpenStack, you can build anon-demand, self-service, multitenant computing infrastructure. However, implementing OpenStack's VLANnetworking model across virtual and physical infrastructures can be difficult.

The OpenStack Networking extensible architecture supports plugins to configure networks directly. However,when you choose a network plugin, only that plugin's target technology is configured. When you are runningOpenStack clusters across multiple hosts with VLANs, a typical plugin configures either the virtual networkinfrastructure or the physical network, but not both.

The Cisco Nexus plugin solves this difficult problem by including support for configuring both the physicaland virtual networking infrastructure.

The CiscoNexus plugin accepts OpenStackNetworkingAPI calls and uses the Network Configuration Protocol(NETCONF) to configure Cisco Nexus devices as well as Open vSwitch (OVS) that runs on the hypervisor.The Cisco Nexus plugin configures VLANs on both the physical and virtual network. It also allocates scarce


OverviewStandard Network Manageability Features

VLAN IDs by deprovisioning them when they are no longer needed and reassigning them to new tenantswhenever possible. VLANs are configured so that virtual machines that run on different virtualization (compute)hosts that belong to the same tenant network transparently communicate through the physical network. Inaddition, connectivity from the compute hosts to the physical network is trunked to allow traffic only fromthe VLANs that are configured on the host by the virtual switch.

The following table lists the features of the Cisco Nexus plugin for OpenStack Networking:

Table 1: Summary of Cisco Nexus Plugin features for OpenStack Networking (Neutron)

Cisco Nexus PluginDescriptionConsiderations

Accepts networking API calls andconfigures both physical and virtualswitches.

VLANsmust be configured on bothphysical and virtual networks.OpenStack Networking supportsonly a single plugin at a time. Youmust choose which parts of thenetworks to manually configure.

Extension of tenant VLANs acrossvirtualization hosts

Efficiently uses limited VLAN IDsby provisioning and deprovisioningVLANs across switches as tenantnetworks are created and destroyed.

Static provisioning of VLAN IDson every switch rapidly consumesall available VLAN IDs, whichlimits scalability and makes thenetwork vulnerable to broadcaststorms.

Efficient use of scarce VLAN IDs

Dynamically provisionstenant-network-specific VLANs onswitch ports connected tovirtualization hosts through theNexus plugin driver.

You must statically provision allavailable VLANs on all physicalswitches. This process is manualand error prone.

Easy configuration of tenantVLANs in a top-of-rack (ToR)switch

Configures switch ports connectedto virtualization hosts only for theVLANs that correspond to thenetworks configured on the host.This feature enables accurate portand VLAN associations.

Switch ports connected tovirtualization hosts are configuredto handle all VLANs. Hardwarelimits are reached quickly.

Intelligent assignment of VLANIDs

Supports Cisco Nexus 2000 SeriesFabric Extenders to enable large,multirack deployments andeliminates the need for anaggregation switch VLANconfiguration.

When compute hosts run in severalracks, you must fully meshtop-of-rack switches or manuallytrunk aggregation switches.

Aggregation switch VLANconfiguration for large multirackdeployments.

Programmability SupportCisco NX-OS on Cisco Nexus 9000 Series devices support the following capabilities to aid programmability:

• NX-API support


OverviewProgrammability Support

• Python scripting

• Tcl scripting

• Broadcom Shell

• Bash

• Guest Shell

NX-API SupportCisco NX-API allows for HTTP-based programmatic access to the Cisco Nexus 9000 Series platform. Thissupport is delivered byNX-API, an open sourcewebserver. NX-API provides the configuration andmanagementcapabilities of the Cisco NX-OS CLI with web-based APIs. The device can be set to publish the output of theAPI calls in XML or JSON format. This API enables rapid development on the Cisco Nexus 9000 Seriesplatform.

Python ScriptingCisco Nexus 9000 Series devices support Python v2.7.5 in both interactive and non-interactive (script) modes.

The Python scripting capability on the devices provide programmatic access to the switch CLI to performvarious tasks, and to Power-On Auto Provisioning (POAP) and Embedded Event Manager (EEM) actions.Responses to Python calls that invoke the Cisco NX-OS CLI return text or JSON output.

The Python interpreter is included in the Cisco NX-OS software.

Tcl ScriptingCisco Nexus 9000 Series devices support tcl (Tool Command Language). Tcl is a scripting language thatenables greater flexibility with CLI commands on the switch. You can use tcl to extract certain values in theoutput of a show command, perform switch configurations, run Cisco NX-OS commands in a loop, or defineEEM policies in a script.

Broadcom ShellThe Cisco Nexus 9000 Series device front panel and fabric module line cards contain Broadcom NetworkForwarding Engine (NFE). You can access the Broadcom command line shell (bcm-shell) from these NFEs.

BashCisco Nexus 9000 Series devices support direct Bourne-Again SHell (Bash) access.With Bash, you can accessthe underlying Linux system on the device and manage the system.

Guest ShellThe Cisco Nexus 9000 Series devices support a guest shell that provides Bash access into a 64-bit Linuxexecution space on the host system that is decoupled from the host Cisco Nexus 9000 NX-OS software. With


OverviewNX-API Support

the guest shell you can add software packages and update libraries as needed without impacting the hostsystem software.


OverviewGuest Shell


OverviewGuest Shell

C H A P T E R 3NX-API

• About NX-API, on page 9• Using NX-API, on page 10

About NX-APIOn Cisco Nexus devices, command-line interfaces (CLIs) are run only on the device. NX-API improves theaccessibility of these CLIs by making them available outside of the switch by using HTTP/HTTPS. You canuse this extension to the existing Cisco Nexus CLI system on the Cisco Nexus 9000 Series devices. NX-APIsupports show commands, configurations, and Linux Bash.

NX-API supports JSON-RPC.

TransportNX-API uses HTTP/HTTPS as its transport. CLIs are encoded into the HTTP/HTTPS POST body.

The NX-API backend uses the Nginx HTTP server. The Nginx process, and all of its children processes, areunder Linux cgroup protection where the CPU and memory usage is capped. If the Nginx memory usageexceeds the cgroup limitations, the Nginx process is restarted and restored.

Message FormatNX-API is an enhancement to the Cisco Nexus 9000 Series CLI system, which supports XML output. NX-APIalso supports JSON output format for specific commands.

• NX-API XML output presents information in a user-friendly format.

• NX-API XML does not map directly to the Cisco NX-OS NETCONF implementation.

• NX-API XML output can be converted into JSON.

Note


SecurityNX-API supports HTTPS. All communication to the device is encrypted when you use HTTPS.

NX-API is integrated into the authentication system on the device. Users must have appropriate accounts toaccess the device through NX-API. NX-API uses HTTP basic authentication. All requests must contain theusername and password in the HTTP header.

You should consider using HTTPS to secure your user's login credentials.Note

You can enable NX-API by using the feature manager CLI command. NX-API is disabled by default.

NX-API provides a session-based cookie, nxapi_auth when users first successfully authenticate. With thesession cookie, the username and password are included in all subsequent NX-API requests that are sent tothe device. The username and password are used with the session cookie to bypass performing the fullauthentication process again. If the session cookie is not included with subsequent requests, another sessioncookie is required and is provided by the authentication process. Avoiding unnecessary use of the authenticationprocess helps to reduce the workload on the device.

A nxapi_auth cookie expires in 600 seconds (10 minutes). This value is a fixed and cannot be adjusted.Note

NX-API performs authentication through a programmable authentication module (PAM) on the switch. Usecookies to reduce the number of PAM authentications, which reduces the load on the PAM.

Note

Using NX-APIThe commands, command type, and output type for the Cisco Nexus 9000 Series devices are entered usingNX-API by encoding the CLIs into the body of a HTTP/HTTPs POST. The response to the request is returnedin XML or JSON output format.

For more details about NX-API response codes, see Table of NX-API Response Codes, on page 61.Note

You must enable NX-API with the feature manager CLI command on the device. By default, NX-API isdisabled.

The following example shows how to configure and launch the NX-API Sandbox:

• Enable the management interface.switch# conf tswitch(config)# interface mgmt 0switch(config)# ip address 198.51.100.1/24switch(config)# vrf context managmentswitch(config)# ip route 203.0.113.1/0 1.2.3.1


NX-APISecurity

• Enable the NX-API nxapi feature.switch# conf tswitch(config)# feature nxapi

The following example shows a request and its response in XML format:

Request:<?xml version="1.0" encoding="ISO-8859-1"?><ins_api><version>0.1</version><type>cli_show</type><chunk>0</chunk><sid>session1</sid><input>show switchname</input><output_format>xml</output_format>

</ins_api>

Response:<?xml version="1.0"?><ins_api><type>cli_show</type><version>0.1</version><sid>eoc</sid><outputs><output><body><hostname>switch</hostname>

</body><input>show switchname</input><msg>Success</msg><code>200</code>

</output></outputs>

</ins_api>

The following example shows a request and its response in JSON format:

Request:{

"ins_api": {"version": "0.1","type": "cli_show","chunk": "0","sid": "session1","input": "show switchname","output_format": "json"

}}

Response:{

"ins_api": {"type": "cli_show","version": "0.1","sid": "eoc","outputs": {

"output": {"body": {


NX-APIUsing NX-API

"hostname": "switch"},"input": "show switchname","msg": "Success","code": "200"

}}

}}

Sample NX-API ScriptsThe sample scripts demonstrate how a script is used with NX-API. The scripts are available athttps://github.com/datacenter/nexus9000/tree/master/nx-os/nxapi/check_cable.

• Cable Checker (check_cable.py)

• Cable Checker Blueprint (connectivity.json)

NX-API SandboxThe NX-API Sandbox is the web-based user interface that you use to enter the commands, command type,and output type for the Cisco Nexus 9000 Series device using HTTP/HTTPS. After posting the request, theoutput response is displayed.

By default, NX-API is disabled. Begin enabling NX-API with the feature manager CLI command on theswitch. Then enable NX-API with the nxapi sandbox command.

Use a browser to access the NX-API Sandbox.

When using the NX-API Sandbox, Cisco recommends that you use the Firefox browser, release 24.0 or later.Note

The following example shows how to configure and launch the NX-API Sandbox:

• Enable the management interface.switch# conf tswitch(config)# interface mgmt 0switch(config)# ip address 198.51.100.1/24switch(config)# vrf context managmentswitch(config)# ip route 203.0.113.1/0 1.2.3.1

• Enable the NX-API nxapi feature.switch# conf tswitch(config)# feature nxapiswitch(config)# nxapi sandbox

• Open a browser and enter http://mgmt-ip to launch the NX-API Sandbox. The following figure is anexample of a request and output response.


NX-APISample NX-API Scripts

https://github.com/datacenter/nexus9000/tree/master/nx-os/nxapi/check_cable

https://github.com/datacenter/nexus9000/tree/master/nx-os/nxapi/check_cable

Figure 1: NX-API Sandbox with Example Request and Output Response

In the NX-API Sandbox, you specify the commands, command type, and output type in the top pane. Clickthe POST Request button above the left pane to post the request. Brief descriptions of the request elementsare displayed below the left pane.

After the request is posted, the output response is displayed in the right pane.

The following sections describe the commands to manage NX-API and descriptions of the elements of therequest and the output response.

NX-API Management CommandsYou can enable and manage NX-API with the CLI commands listed in the following table.

Table 2: NX-API Management Commands

DescriptionNX-API Management Command

Enables NX-API.feature nxapi

Disables NX-API.no feature nxapi

Specifies a port.nxapi {http|https} port port

Disables HTTP/HTTPS.no nxapi {http|https}

Displays port information.show nxapi


NX-APINX-API Management Commands

DescriptionNX-API Management Command

Specifies the upload of the following:

• HTTPS certificate when httpscrt is specified.

• HTTPS key when httpskey is specified.

nxapi certificate {httpscrt |httpskey}

Enables a certificate.nxapi certificate enable

NX-API Request ElementsNX-API request elements are sent to the device in XML format or JSON format. The HTTP header of therequest must identify the content type of the request.

You use the NX-API elements that are listed in the following table to specify a CLI command:

Table 3: NX-API Request Elements

DescriptionNX-API Request Element

Specifies the NX-API version.version


NX-APINX-API Request Elements


Specifies the type of command to be executed.

The following types of commands are supported:

• cli_show

CLI show commands that expect structured output. If thecommand does not support XML output, an error message isreturned.

• cli_show_ascii

CLI show commands that expect ASCII output. This alignswith existing scripts that parse ASCII output. Users are ableto use existing scripts with minimal changes.

• cli_conf

CLI configuration commands.

• bash

Bash commands. Most non-interactive Bash commands aresupported by NX-API.

Note • Each command is only executable with the currentuser's authority.

• The pipe operation is supported in the output whenthe message type is ASCII. If the output is in XMLformat, the pipe operation is not supported.

• A maximum of 10 consecutive show commandsare supported. If the number of show commandsexceeds 10, the 11th and subsequent commandsare ignored.

• No interactive commands are supported.

type




Some show commands can return a large amount of output. Forthe NX-API client to start processing the output before the entirecommand completes, NX-API supports output chunking for showcommands.

Enable or disable chunk with the following settings:

Do not chunk output.0

Chunk output.1

Only show commands support chunking.When a seriesof show commands are entered, only the first commandis chunked and returned.

The output message format is XML. (XML is thedefault.) Special characters, such as < or >, are convertedto form a valid XML message (< is converted into <> is converted into &gt).

You can use XML SAX to parse the chunked output.

Note

When chunking is enabled, themessage format is limitedto XML. JSON output format is not supported whenchunking is enabled.

Note

chunk

The session ID element is valid only when the response messageis chunked. To retrieve the next chunk of the message, you mustspecify a sid to match the sid of the previous response message.

sid

Input can be one command or multiple commands. However,commands that belong to different message types should not bemixed. For example, show commands are cli_show message typeand are not supported in cli_conf mode.

Except for bash, multiple commands are separated with" ; ". (The ; must be surrounded with single blankcharacters.)

For bash, multiple commands are separated with ";".(The ; is not surrounded with single blank characters.)

Note

The following are examples of multiple commands:

show version ; show interface brief ; showvlan

cli_show

interface Eth4/1 ; no shut ; switchportcli_conf

cd /bootflash;mkdir new_dirbash

input




The available output message formats are the following:

Specifies output in XML format.xml

Specifies output in JSON format.json

The CiscoNexus 9000 Series CLI supports XMLoutput,which means that the JSON output is converted fromXML. The conversion is processed on the switch.

To manage the computational overhead, the JSONoutput is determined by the amount of output. If theoutput exceeds 1 MB, the output is returned in XMLformat. When the output is chunked, only XML outputis supported.

The content-type header in the HTTP/HTTPS headersindicate the type of response format (XML or JSON).

Note

output_format

NX-API Response ElementsThe NX-API elements that respond to a CLI command are listed in the following table:

Table 4: NX-API Response Elements

DescriptionNX-API Response Element

NX-API version.version

Type of command to be executed.type

Session ID of the response. This element is valid only when the responsemessage is chunked.

sid

Tag that encloses all command outputs.

Whenmultiple commands are in cli_show or cli_show_ascii, each commandoutput is enclosed by a single output tag.

When the message type is cli_conf or bash, there is a single output tag forall the commands because cli_conf and bash commands require context.

outputs

Tag that encloses the output of a single command output.

For cli_conf and bash message types, this element contains the outputs ofall the commands.

output

Tag that encloses a single command that was specified in the request. Thiselement helps associate a request input element with the appropriateresponse output element.

input

Body of the command response.body


NX-APINX-API Response Elements

DescriptionNX-API Response Element

Error code returned from the command execution.

NX-API uses standard HTTP error codes as described by the HypertextTransfer Protocol (HTTP) Status Code Registry(http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

code

Error message associated with the returned error code.msg


NX-APINX-API Response Elements

C H A P T E R 4Python API

• About the Python API , on page 19• Using Python, on page 19

About the Python APIPython is an easy to learn, powerful programming language. It has efficient high-level data structures and asimple but effective approach to object-oriented programming. Python's elegant syntax and dynamic typing,together with its interpreted nature, make it an ideal language for scripting and rapid application developmentin many areas on most platforms.

The Python interpreter and the extensive standard library are freely available in source or binary form for allmajor platforms from the Python website:

http://www.python.org/

The same site also contains distributions of and pointers to many free third-party Python modules, programsand tools, and additional documentation.

The Cisco Nexus 9000 Series devices support Python v2.7.5 in both interactive and non-interactive (script)modes.

The Python scripting capability gives programmatic access to the device's command-line interface (CLI) toperform various tasks and PowerOn Auto Provisioning (POAP) or Embedded Event Manager (EEM) actions.Python can also be accessed from the Bash shell.

The Python interpreter is available in the Cisco NX-OS software.

Using PythonThis section describes how to write and execute Python scripts.

Cisco Python PackageCisco NX-OS provides a Cisco Python package that enables access to many core network device modules,such as interfaces, VLANs, VRFs, ACLs and routes. You can display the details of the Cisco Python packageby entering the help() command. To obtain additional information about the classes and methods in a module,


you can run the help command for a specific module. For example, help(cisco.interface) displays the propertiesof the cisco.interface module.

The following is an example of how to display information about the Cisco python package:>>> import cisco>>> help(cisco)Help on package cisco:

NAMEcisco

FILE/isan/python/scripts/cisco/__init__.py

PACKAGE CONTENTSaclbgpcisco_secretcisco_socketfeatureinterfacekeyline_parsermd5sumnxcliospfroutemaproutessection_parsersshsystemtacacsvrf

CLASSES__builtin__.object

cisco.cisco_secret.CiscoSecretcisco.interface.Interfacecisco.key.Key

Using the CLI Command APIsThe Python programming language uses three APIs that can execute CLI commands. The APIs are availablefrom the Python CLI module.

These APIs are listed in the following table. You need to enable the APIs with the from cli import * command.The arguments for these APIs are strings of CLI commands. To execute a CLI command through the Pythoninterpreter, you enter the CLI command as an argument string of one of the following APIs:


Python APIUsing the CLI Command APIs

Table 5: CLI Command APIs

DescriptionAPI

Returns the raw output of CLI commands, includingcontrol/special characters.

The interactive Python interpreter printscontrol/special characters 'escaped'. Acarriage return is printed as '\n' and givesresults that might be difficult to read. Theclip() API gives results that are morereadable.

Note

cli()

Example:string = cli (“cli-command”)

Returns JSON output for cli-command, if XMLsupport exists for the command, otherwise anexception is thrown.

This API can be useful when searching theoutput of show commands.

Note

clid()

Example:json_string = clid (“cli-command”)

Prints the output of the CLI command directly tostdout and returns nothing to Python.

clip (“cli-command”)

is equivalent tor=cli(“cli-command”)print r

Note

clip()

Example:clip (“cli-command”)

When two or more commands are run individually, the state is not persistent from one command to subsequentcommands.

In the following example, the second command fails because the state from the first command does not persistfor the second command:>>> cli("conf t")>>> cli("interface eth4/1")

When two or more commands are run together, the state is persistent from one command to subsequentcommands.

In the following example, the second command is successful because the state persists for the second andthird commands:>>> cli("conf t ; interface eth4/1 ; shut")

Commands are separated with " ; " as shown in the example. (The ; must be surrounded with single blankcharacters.)

Note


Python APIUsing the CLI Command APIs

Invoking the Python Interpreter from the CLIThe following example shows how to invoke Python from the CLI:

The Python interpreter is designated with the ">>>" or "…" prompt.Note

switch# pythonPython 2.7.5 (default, Oct 8 2013, 23:59:43)[GCC 4.6.3] on linux2Type "help", "copyright", "credits" or "license" for more information.>>> from cli import *>>> import json>>> cli('configure terminal ; interface loopback 5 ; no shut')''>>> intflist=json.loads(clid('show interface brief'))>>> i=0>>> while i < len(intflist['TABLE_interface']['ROW_interface']):... intf=intflist['TABLE_interface']['ROW_interface'][i]... i=i+1... if intf['state'] == 'up':... print intf['interface']...mgmt0Ethernet2/7Ethernet4/7loopback0loopback5>>>

Display FormatsThe following examples show various display formats using the Python APIs:

Example 1:>>> from cli import *>>> cli("conf ; interface loopback 1")''>>> clip('where detail')mode:username: adminvdc: switchrouting-context vrf: default

Example 2:>>> from cli import *>>> cli("conf ; interface loopback 1")''>>> cli('where detail')' mode: \n username: admin\n vdc:switch\n routing-context vrf: default\n'>>>

Example 3:>>> from cli import *>>> cli("conf ; interface loopback 1")


Python APIInvoking the Python Interpreter from the CLI

''>>> r = cli('where detail') ; print rmode:username: adminvdc: EOR-1routing-context vrf: default

>>>

Example 4:>>> from cli import *>>> import json>>> out=json.loads(clid('show version'))>>> for k in out.keys():... print "%30s = %s" % (k, out[k])...

kern_uptm_secs = 6kick_file_name = bootflash:///n9000-dk9.6.1.2.I1.1.bin

rr_service = Nonemodule_id = Supervisor Module

kick_tmstmp = 10/21/2013 00:06:10bios_cmpl_time = 08/17/2013bootflash_size = 20971520

kickstart_ver_str = 6.1(2)I1(2) [build 6.1(2)I1(2)] [gdb]kick_cmpl_time = 10/20/2013 4:00:00

chassis_id = Nexus9000 C9508 (8 Slot) Chassisproc_board_id = SAL171211LX

memory = 16077872manufacturer = Cisco Systems, Inc.

kern_uptm_mins = 26bios_ver_str = 06.14

cpu_name = Intel(R) Xeon(R) CPU E5-2403kern_uptm_hrs = 2

rr_usecs = 816550rr_sys_ver = Nonerr_reason = Reset Requested by CLI command reloadrr_ctime = Mon Oct 21 00:10:24 2013

header_str = Cisco Nexus Operating System (NX-OS) SoftwareTAC support: http://www.cisco.com/tacDocuments: http://www.cisco.com/en/US/products/ps9372/tsd_products_support_series_home.htmlCopyright (c) 2002-2013, Cisco Systems, Inc. All rights reserved.The copyrights to certain works contained herein are owned byother third parties and are used and distributed under license.Some parts of this software are covered under the GNU PublicLicense. A copy of the license is available athttp://www.gnu.org/licenses/gpl.html.

host_name = switchmem_type = kB

kern_uptm_days = 0>>>

Non-interactive PythonA Python script can run in non-interactive mode by providing the Python script name as an argument to thePython CLI command. Python scripts must be placed under the bootflash or volatile scheme. A maximum of32 command line arguments for the Python script are allowed with the Python CLI command.

The Cisco Nexus 9000 Series device also supports the source CLI command for running Python scripts. Thebootflash:scripts directory is the default script directory for the source CLI command.

The following example shows a script and how to run it:


Python APINon-interactive Python

switch# show file bootflash:deltaCounters.py#!/isan/bin/python

from cli import *import sys, time

ifName = sys.argv[1]delay = float(sys.argv[2])count = int(sys.argv[3])cmd = 'show interface ' + ifName + ' counters'

out = json.loads(clid(cmd))rxuc = int(out['TABLE_rx_counters']['ROW_rx_counters'][0]['eth_inucast'])rxmc = int(out['TABLE_rx_counters']['ROW_rx_counters'][1]['eth_inmcast'])rxbc = int(out['TABLE_rx_counters']['ROW_rx_counters'][1]['eth_inbcast'])txuc = int(out['TABLE_tx_counters']['ROW_tx_counters'][0]['eth_outucast'])txmc = int(out['TABLE_tx_counters']['ROW_tx_counters'][1]['eth_outmcast'])txbc = int(out['TABLE_tx_counters']['ROW_tx_counters'][1]['eth_outbcast'])print 'row rx_ucast rx_mcast rx_bcast tx_ucast tx_mcast tx_bcast'print '========================================================='print ' %8d %8d %8d %8d %8d %8d' % (rxuc, rxmc, rxbc, txuc, txmc, txbc)print '========================================================='

i = 0while (i < count):time.sleep(delay)out = json.loads(clid(cmd))rxucNew = int(out['TABLE_rx_counters']['ROW_rx_counters'][0]['eth_inucast'])rxmcNew = int(out['TABLE_rx_counters']['ROW_rx_counters'][1]['eth_inmcast'])rxbcNew = int(out['TABLE_rx_counters']['ROW_rx_counters'][1]['eth_inbcast'])txucNew = int(out['TABLE_tx_counters']['ROW_tx_counters'][0]['eth_outucast'])txmcNew = int(out['TABLE_tx_counters']['ROW_tx_counters'][1]['eth_outmcast'])txbcNew = int(out['TABLE_tx_counters']['ROW_tx_counters'][1]['eth_outbcast'])i += 1print '%-3d %8d %8d %8d %8d %8d %8d' % \(i, rxucNew - rxuc, rxmcNew - rxmc, rxbcNew - rxbc, txucNew - txuc, txmcNew - txmc,

txbcNew - txbc)

switch# python bootflash:deltaCounters.py Ethernet1/1 1 5row rx_ucast rx_mcast rx_bcast tx_ucast tx_mcast tx_bcast=========================================================

0 791 1 0 212739 0=========================================================1 0 0 0 0 26 02 0 0 0 0 27 03 0 1 0 0 54 04 0 1 0 0 55 05 0 1 0 0 81 0switch#

The following example shows how a source command specifies command-line arguments. In the example,policy-map is an argument to the cgrep python script. The example also shows that a source command canfollow after the pipe operator ("|").switch# show running-config | source sys/cgrep policy-map

policy-map type network-qos nw-pfcpolicy-map type network-qos no-drop-2policy-map type network-qos wred-policypolicy-map type network-qos pause-policypolicy-map type qos foopolicy-map type qos classifypolicy-map type qos cos-based


Python APINon-interactive Python

policy-map type qos no-drop-2policy-map type qos pfc-tor-port

Running Scripts with Embedded Event ManagerOn Cisco Nexus 9000 Series devices, embedded event manager (EEM) policies support Python scripts.

The following example shows how to run a Python script as an EEM action:

• An EEM applet can include a Python script with an action command.switch# show running-config eem

!Command: show running-config eem!Time: Sun May 1 14:40:07 2011

version 6.1(2)I2(1)event manager applet a1event cli match "show clock"action 1 cli python bootflash:pydate.pyaction 2 event-default

• You can search for the action triggered by the event in the log file by running the show filelogflash:event_archive_1 command.switch# show file logflash:event_archive_1 | last 33

eem_event_time:05/01/2011,19:40:28 event_type:cli event_id:8 slot:active(1)vdc:1 severity:minor applets:a1eem_param_info:command = "exshow clock"Starting with policy a1Python

2011-05-01 19:40:28.644891Executing the following commands succeeded:

python bootflash:pydate.py

PC_VSH_CMD_TLV(7679) with q

Python Integration with Cisco NX-OS Network InterfacesOnCiscoNexus 9000 Series devices, Python is integratedwith the underlying CiscoNX-OS network interfaces.You can switch from one virtual routing context to another by setting up a context through thecisco.vrf.set_global_vrf() API.

The following example shows how to retrieve an HTML document over themanagement interface of a device.You can also establish a connection to an external entity over the inband interface by switching to a desiredvirtual routing context.switch# pythonPython 2.7.5 (default, Oct 8 2013, 23:59:43)[GCC 4.6.3] on linux2Type "help", "copyright", "credits" or "license" for more information.>>> import urllib2>>> from cisco.vrf import *>>> set_global_vrf('management')>>> page=urllib2.urlopen('http://172.23.40.211:8000/welcome.html')>>> print page.read()Hello Cisco Nexus 9000


Python APIRunning Scripts with Embedded Event Manager

>>>>>> import cisco>>> help(cisco.vrf.set_global_vrf)Help on function set global vrf in module cisco.vrf:

set global vrf(vrf)Sets the global vrf. Any new sockets that are created (using socket.socket)will automatically get set to this vrf (including sockets used by otherpython libraries).

Arguments:vrf: VRF name (string) or the VRF ID (int).

Returns: Nothing

>>>

Cisco NX-OS Security with PythonCiscoNX-OS resources are protected by the CiscoNX-OS Sandbox layer of software and by the CLI role-basedaccess control (RBAC).

All users associated with a Cisco NX-OS network-admin or dev-ops role are privileged users. Users who aregranted access to Python with a custom role are regarded as non-privileged users. Non-privileged users havea limited access to Cisco NX-OS resources, such as file system, guest shell, and Bash commands. Privilegedusers have greater access to all the resources of Cisco NX-OS.

Examples of Security and User AuthorityThe following example shows how a privileged user runs commands:switch# pythonPython 2.7.5 (default, Oct 8 2013, 23:59:43)[GCC 4.6.3] on linux2Type "help", "copyright", "credits" or "license" for more information.>>> import os>>> os.system('whoami')admin0>>> f=open('/tmp/test','w')>>> f.write('hello from python')>>> f.close()>>> r=open('/tmp/test','r')>>> print r.read()hello from python>>> r.close()

The following example shows a non-privileged user being denied access:switch# pythonPython 2.7.5 (default, Oct 8 2013, 23:59:43)[GCC 4.6.3] on linux2Type "help", "copyright", "credits" or "license" for more information.>>> import os>>> os.system('whoami')system(whoami): rejected!-1>>> f=open('/tmp/test','r')Permission denied. Traceback (most recent call last):File "<stdin>", line 1, in <module>


Python APICisco NX-OS Security with Python

IOError: [Errno 13] Permission denied: '/tmp/test'>>>

RBAC controls CLI access based on the login user privileges. A login user's identity is given to Python thatis invoked from the CLI shell or from Bash. Python passes the login user's identity to any subprocess that isinvoked from Python.

The following is an example for a privileged user:>>> from cli import *>>> cli('show clock')'11:28:53.845 AM UTC Sun May 08 2011\n'>>> cli('configure terminal ; vrf context myvrf')''>>> clip('show running-config l3vm')

!Command: show running-config l3vm!Time: Sun May 8 11:29:40 2011

version 6.1(2)I2(1)

interface Ethernet1/48vrf member blue

interface mgmt0vrf member management

vrf context bluevrf context managementvrf context myvrf

The following is an example for a non-privileged user:>>> from cli import *>>> cli('show clock')'11:18:47.482 AM UTC Sun May 08 2011\n'>>> cli('configure terminal ; vrf context myvrf2')Traceback (most recent call last):File "<stdin>", line 1, in <module>File "/isan/python/scripts/cli.py", line 20, in cliraise cmd_exec_error(msg)

errors.cmd_exec_error: '% Permission denied for the role\n\nCmd exec error.\n'

The following example shows an RBAC configuration:switch# show user-accountuser:admin

this user account has no expiry dateroles:network-admin

user:pyuserthis user account has no expiry dateroles:network-operator python-role

switch# show role name python-role

Example of Running Script with SchedulerThe following example shows a Python script that is running the script with the scheduler feature:#!/bin/env pythonfrom cli import *from nxos import *import os


Python APIExample of Running Script with Scheduler

switchname = cli("show switchname")try:

user = os.environ['USER']except:

user = "No user"pass

msg = user + " ran " + __file__ + " on : " + switchnameprint msgpy_syslog(1, msg)# Save this script in bootflash:///scripts

switch# conf tEnter configuration commands, one per line. End with CNTL/Z.switch(config)# feature schedulerswitch(config)# scheduler job name testplanswitch(config-job)# python bootflash:///scripts/testplan.pyswitch(config-job)# exitswitch(config)# scheduler schedule name testplanswitch(config-schedule)# job name testplanswitch(config-schedule)# time start now repeat 0:0:4Schedule starts from Mon Mar 14 16:40:03 2011switch(config-schedule)# endswitch# term mon2011 Mar 14 16:38:03 switch %VSHD-5-VSHD_SYSLOG_CONFIG_I: Configured from vty by admin on10.19.68.246@pts/2switch# show scheduler scheduleSchedule Name : testplan------------------------------User Name : adminSchedule Type : Run every 0 Days 0 Hrs 4 MinsStart Time : Mon Mar 14 16:40:03 2011Last Execution Time : Yet to be executed-----------------------------------------------

Job Name Last Execution Status-----------------------------------------------

testplan -NA-==============================================================================switch#switch# 2011 Mar 14 16:40:04 switch %USER-1-SYSTEM_MSG: No user ran/bootflash/scripts/testplan.py on : switch - nxpython2011 Mar 14 16:44:04 switch last message repeated 1 timeswitch#


Python APIExample of Running Script with Scheduler

C H A P T E R 5Broadcom Shell

• About the Broadcom Shell, on page 29• Accessing the Broadcom Shell (bcm-shell), on page 29

About the Broadcom ShellThe Cisco Nexus 9000 Series device front panel and fabric module line cards contain Broadcom NetworkForwarding Engines (NFE). The number of NFEs varies depending upon the specific model of the front panelline card (LC) or the fabric module (FM).

The following sections describe how you can access the command-line shell (bcm-shell) and how to readfrom these NFEs.

Guidelines and LimitationsUsing the Broadcom Shell has the following guideline and limitation:

• You can access and read information from the T2 ASICs without any limitations. However, Cisco doesnot recommend that you change the settings of the T2 configuration. Use caution when accessing theBroadcom Shell.

Accessing the Broadcom Shell (bcm-shell)The following sections describe approaches to access the Broadcom Shell (bcm-shell).

Accessing bcm-shell with the CLI APIThe bcm-shell commands are passed directly from the Cisco Nexus 9000 Series CLI to the specific T2 ASICinstance. The T2 ASIC instance can be on the fabric module or on the front panel line card.

The command syntax is as follows:

bcm-shell module module_number [instance_number:command]

where

Module number in the chassis.module_number


T2 instance number

• When not specified, the T2 instance number defaults to 0.

• When a wildcard ('*') is specified, all T2 instances are processed.

instance_number

Broadcom commandcommand

Cisco NX-OS command extensions such as ‘pipe include’ or ‘redirect output to file’ can be used to managecommand output.

Note

Entering commands with the CLI API are recorded in the system accounting log for auditing purposes.Commands entered directly from the bcm-shell are not recorded in the accounting log.

Note

Accessing the Native bcm-shell on the Fabric ModuleAn eight-slot line card (LC) chassis can host a maximum of six fabric modules (FMs). These slots are numbered21 through 26.You must specify the FM that you wish to access the bcm-shell on.

The following example shows how to access the bcm-shell on the FM in slot 24, access context help, and exitthe bcm-shell.

• Use the show module command to display the FMs.n9k-spine1# show moduleMod Ports Module-Type Model Status--- ----- ----------------------------------- ------------------ ----------3 36 36p 40G Ethernet Module N9k-X9636PQ ok4 36 36p 40G Ethernet Module N9k-X9636PQ ok21 0 Fabric Module N9K-C9508-FM ok22 0 Fabric Module N9K-C9508-FM ok23 0 Fabric Module N9K-C9508-FM ok24 0 Fabric Module N9K-C9508-FM ok25 0 Fabric Module N9K-C9508-FM ok26 0 Fabric Module N9K-C9508-FM ok27 0 Supervisor Module N9K-SUP-A active *29 0 System Controller N9K-SC-A active

• Attach to module 24 to gain access to the command line for the FM in slot 24.n9k-spine1# attach module 24Attaching to module 24 ...To exit type 'exit', to abort type '$.'

• Enter the command to gain root access to the fabric module software.module-24# test hardware internal bcm-usd bcm-diag-shellAvailable Unit Numbers: 0 1bcm-shell.0> 1

At this point, you are at the Broadcom shell for the fabric module in slot 24, T2 ASIC instance 1. Anycommands entered are specific to this specific ASIC instance.

• Use the exit command to exit the bcm-shell and to detach from the FM.


Broadcom ShellAccessing the Native bcm-shell on the Fabric Module

bcm-shell.1> exitmodule-24# exitrlogin: connection closed.

Accessing the bcm-shell on the Line CardWhen connecting to the T2 ASIC on the line card (LC), you first attach to the module, enter root mode, runthe shell access exec, and select the ASIC instance that you want to attach to. The number of available ASICsdepends on the model of the line card you are attached to.

The following example shows how to access the bcm-shell of ASIC instance 1 on the LC in slot 2 and exitthe bcm-shell on a LC that contains three T2 instances.

• Attach to module 2 to gain access to the command line for the LC in slot 2.n9k-spine1# attach module 2Attaching to module 2 ...To exit type 'exit', to abort type '$.'Last login: Wed Aug 7 14:13:15 UTC 2013 from sup27 on ttyp0

• Enter the command to gain root access to the line card software.module-2# test hardware internal bcm-usd bcm-diag-shellAvailable Unit Numbers: 0 1 2bcm-shell.0> 1bcm-shell.1>

At this point you are at the Broadcom shell for the line card module in slot 2, T2 ASIC instance 1.

• Use the exit command to exit the bcm-shell and detach from the FM.bcm-shell.1> exitmodule-2# exitrlogin: connection closed.


Broadcom ShellAccessing the bcm-shell on the Line Card


Broadcom ShellAccessing the bcm-shell on the Line Card

C H A P T E R 6Bash

• About Bash, on page 33• Accessing Bash, on page 33• Escalate Privileges to Root, on page 34• Examples of Bash Commands, on page 35

About BashIn addition to the NX-OS CLI, Cisco Nexus 9000 Series devices support access to the Bourne-Again SHell(Bash). Bash interprets commands that you enter or commands that are read from a shell script. Using Bashenables access to the underlying Linux system on the device and to manage the system.

Accessing BashIn Cisco NX-OS, Bash is accessible from user accounts that are associated with the Cisco NX-OS dev-opsrole or the Cisco NX-OS network-admin role.

The following example shows the authority of the dev-ops role and the network-admin role:switch# show role name dev-ops

Role: dev-opsDescription: Predefined system role for devops access. This rolecannot be modified.Vlan policy: permit (default)Interface policy: permit (default)Vrf policy: permit (default)-------------------------------------------------------------------Rule Perm Type Scope Entity-------------------------------------------------------------------4 permit command conf t ; username *3 permit command bcm module *2 permit command run bash *1 permit command python *

switch# show role name network-admin

Role: network-adminDescription: Predefined network admin role has access to all commandson the switch-------------------------------------------------------------------


Rule Perm Type Scope Entity-------------------------------------------------------------------1 permit read-write

switch#

Bash is enabled by running the feature bash-shell command.

The run bash command loads Bash and begins at the home directory for the user.

The following examples show how to enable the Bash shell feature and how to run Bash.switch# config tswitch(config)# feature bash-shell

switch# run?run Execute/run programrun-script Run shell scripts

switch# run bash?bash Linux-bash

switch# run bashbash-4.2$ whoamiadminbash-4.2$ pwd/bootflash/home/adminbash-4.2$

You can also execute Bash commands with the run bash command command.

The following is an example of the run bash command command.run bash whoami

Note

Escalate Privileges to RootThe privileges of an admin user can escalate their privileges for root access.

The following are guidelines for escalating privileges:

• admin privilege user (network-admin / vdc-admin) is equivalent of Linux root privilege user in NX-OS

• Only an authenticated admin user can escalate privileges to root, and password is not required for andauthenticated admin privilege user.

• Bash must be enabled before escalating privileges.

The following example shows how to escalate privileges to root and how to verify the escalation:switch# run bashbash-4.2$ sudo su root

We trust you have received the usual lecture from the local SystemAdministrator. It usually boils down to these three things:

#1) Respect the privacy of others.#2) Think before you type.


BashEscalate Privileges to Root

#3) With great power comes great responsibility.

Password:

bash-4.2# whoamirootbash-4.2# exitexit

Examples of Bash CommandsThis section contains examples of Bash commands and output.

Displaying System StatisticsThe following example shows how to display system statistics:switch# run bashbash-4.2$ cat /proc/meminfo<snip>MemTotal: 16402560 kBMemFree: 14098136 kBBuffers: 11492 kBCached: 1287880 kBSwapCached: 0 kBActive: 1109448 kBInactive: 717036 kBActive(anon): 817856 kBInactive(anon): 702880 kBActive(file): 291592 kBInactive(file): 14156 kBUnevictable: 0 kBMlocked: 0 kBSwapTotal: 0 kBSwapFree: 0 kBDirty: 32 kBWriteback: 0 kBAnonPages: 527088 kBMapped: 97832 kB<\snip>

Running Bash from CLIThe following example shows how to run a bash command from the CLIwith the run bash command command:switch# run bash ps -elF S UID PID PPID C PRI NI ADDR SZ WCHAN TTY TIME CMD4 S 0 1 0 0 80 0 - 528 poll_s ? 00:00:03 init1 S 0 2 0 0 80 0 - 0 kthrea ? 00:00:00 kthreadd1 S 0 3 2 0 80 0 - 0 run_ks ? 00:00:56 ksoftirqd/01 S 0 6 2 0 -40 - - 0 cpu_st ? 00:00:00 migration/01 S 0 7 2 0 -40 - - 0 watchd ? 00:00:00 watchdog/01 S 0 8 2 0 -40 - - 0 cpu_st ? 00:00:00 migration/11 S 0 9 2 0 80 0 - 0 worker ? 00:00:00 kworker/1:01 S 0 10 2 0 80 0 - 0 run_ks ? 00:00:00 ksoftirqd/1


BashExamples of Bash Commands

Running Python from BashThe following example shows how to load Python and configure a switch using Python objects:switch# run bashbash-4.2$ pythonPython 2.7.5 (default, Oct 8 2013, 23:59:43)[GCC 4.6.3] on linux2Type "help", "copyright", "credits" or "license" for more information.>>> from cisco import *>>> from cisco.vrf import *>>> from cisco.interface import *>>> vrfobj=VRF('myvrf')>>> vrfobj.get_name()'myvrf'>>> vrfobj.add_interface('Ethernet1/3')True>>> intf=Interface('Ethernet1/3')>>> print intf.config()

!Command: show running-config interface Ethernet1/3!Time: Mon Nov 4 13:17:56 2013

version 6.1(2)I2(1)

interface Ethernet1/3vrf member myvrf

>>>


BashRunning Python from Bash

C H A P T E R 7Guest Shell

• About the Guest Shell, on page 37• Accessing the Guest Shell, on page 38• Capabilities in the Guest Shell, on page 38• Resources Used for the Guest Shell, on page 42• Security Posture for Virtual Services , on page 43• Guest File System Access Restrictions , on page 44• Guidelines and Limitations, on page 45• Managing the Guest Shell, on page 46• Verifying Virtual Service and Guest Shell Information, on page 51

About the Guest ShellIn addition to the NX-OS CLI and Bash access on the underlying Linux environment, the Cisco Nexus 9000Series devices support access to a decoupled execution space running within a Linux Container (LXC) calledthe “guest shell”.

From within the guest shell the network-admin has the following capabilities:

• Access to the network.

• Access to Cisco Nexus 9000 bootflash.

• Access to Cisco Nexus 9000 CLI.

• Access to Cisco onePK APIs.

• The ability to install and run python scripts.

• The ability to install and run 64-bit Linux applications.

Decoupling the execution space from the native host system allows customization of the Linux environmentto suit the needs of the applications without impacting the host system or applications running in other LinuxContainers.

On NX-OS devices, Linux Containers are installed and managed with the virtual-service commands. Theguest shell will appear in the virtual-service show command output.


By default the guest shell occupies approximately 5 MB of RAM and 200 MB of bootflash when enabled.Use the guestshell destroy command to reclaim resources if the guest shell is not used.

Note

Accessing the Guest ShellIn Cisco NX-OS, the guest shell is accessible to the network-admin. It is automatically enabled in the systemand can be accessed using the run guestshell command. Consistent with the run bash command, thesecommands can be issued within the guest shell with the run guestshell command form of the NX-OS CLIcommand.

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

When running in the guest shell, you have network-admin level privileges.Note

Capabilities in the Guest ShellThe guest shell has a number of utilities and capabilities available by default.

NX-OS CLI in the Guest ShellThe guest shell provides an application to allow the user to issue NX-OS commands from the guest shellenvironment to the host network element. The dohost application accepts any valid NX-OS configuration orexec commands and issues them to the host network element.

When invoking the dohost command each NX-OS command must be in double quotes:

dohost "<NXOS CLI>"

The NX-OS CLI can be chained together:

guestshell:~$ dohost "conf t ; cdp timer 20"{0}{}{0}{}guestshell:~$ dohost "show run | inc cdp"{0}{cdp timer 20}

The value between the first set of brackets is the result code from the NXOS parser. The value between thesecond set of brackets is the output result from the command issued.

The NX-OS CLI can also be chained together using the NX-OS style command chaining technique by addinga semicolon between each command. (A space on either side of the semicolon is required.):


Guest ShellAccessing the Guest Shell

guestshell:~$ dohost "conf t ; cdp timer 13 ; show run | inc cdp"{0}{cdp timer 13}

In this example, the dohost command received only one quoted command string. It returns one result stringback from the NX-OS parser.

Commands issued on the host through the dohost command are run with network-admin level privileges.Note

Network Access in Guest ShellThe guest shell has a number of typical network utilities included by default and they can be used on differentVRFs using the chvrf vrf command command.

Commands that are run without the chvrf command are run within the context of the default VRF.Note

For example, to ping IP address 10.0.0.1 over the management VRF, the command is “chvrf managementping 10.0.0.1”. Other utilities such as scp or ssh would be similar.

Example:

switch# guestshellguestshell:~$ cd /bootflashguestshell:/bootflash$ chvrf management scp [email protected]:/foo/index.html [email protected]'s password:index.html 100% 1804 1.8KB/s 00:00guestshell:/bootflash$ ls -al index.html-rw-r--r-- 1 guestshe users 1804 Sep 13 20:28 index.htmlguestshell:/bootflash$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:/bootflash$

To obtain a list of VRFs on the system, use the show vrf command. The command can be run natively fromthe NX-OS CLI or by with the dohost show vrf command in the guest shell.

Example:

guestshell:/bootflash$ dohost "show vrf"{0}{VRF-Name VRF-ID State Reasondefault 1 Up --management 2 Up --}

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.


Guest ShellNetwork Access in Guest Shell

Example:

nameserver 10.1.1.1domain cisco.com

The nameserver and domain information should match what is configured through the NX-OS configuration.

Example:

switch(config)# ip domain-name cisco.comswitch(config)# ip name-server 10.1.1.1switch(config)# vrf context managementswitch(config-vrf)# ip domain-name cisco.comswitch(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 andhttps_proxy environment variables must be set up within the guest shell also.

Example:

export http_proxy=http://proxy.esl.cisco.com:8080export 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 theyare persistent.

Access to Bootflash in Guest ShellNetwork administrators can manage files with Linux commands and utilities in addition to using NX-OS CLIcommands. Bymounting the system bootflash at /bootflash in the guest shell environment, the network-admincan operate on these files with Linux commands.

Example:

find . –name “foo.txt”rm “/bootflash/junk/foo.txt”

Python in Guest ShellPython can be used interactively or python scripts can be run in the guest shell.

Example:

guestshell:~$ pythonPython 2.7.3 (default, Aug 22 2014, 12:09:58)[GCC 4.8.1] on linux2Type "help", "copyright", "credits" or "license" for more information.>>> quit()guestshell:~$

The pip python package manager is included in the guest shell to allow the network-admin to install newpython packages.


Guest ShellAccess to Bootflash in Guest Shell

Example:

guestshell:~$ pip listargparse (1.2.1)async (0.6.1)iniparse (0.3.2)ipaddress (branches-3144)pexpect (2.3)pip (1.5.6)pycurl (7.19.0)setuptools (0.6c11)smart (1.4.1)urlgrabber (3.9.1)yum-metadata-parser (1.1.4)

Installing RPMs in the Guest ShellBy default, the Yum RPM package manager is included in the guest shell for the installation of softwarepackages. Yum is pointed to the yocto repository.

guestshell:~$ cat /etc/yum/repos.d/yumrepo_x86_64.repo[poky_1_5_1_x86_64]baseurl=http://downloads.yoctoproject.org/releases/yocto/yocto-1.5.1/rpm/x86_64/name=Poky 1.5.1 repository (x86_64)enabled=1

Yum can be pointed to one or more repositories at any time by modifying the yumrepo_x86_64.repofile or by adding a new .repo file in the repos.d directory.

Yum resolves the dependancies and installs all the required packages.

guestshell:~$ sudo chvrf management yum install perlSetting up Install ProcessResolving Dependencies--> Running transaction check---> Package perl.x86_64 0:5.14.3-r1 set to be updated--> Processing Dependency: libperl5 >= 5.14.3 for package: perl-5.14.3-r1.x86_64--> Processing Dependency: libperl.so.5()(64bit) for package: perl-5.14.3-r1.x86_64--> Running transaction check---> Package libperl5.x86_64 0:5.14.3-r1 set to be updated--> Finished Dependency Resolution

Dependencies Resolved

================================================================================Package Arch Version Repository Size================================================================================Installing:perl x86_64 5.14.3-r1 poky_1_5_1_x86_64 16 kInstalling for dependencies:libperl5 x86_64 5.14.3-r1 poky_1_5_1_x86_64 712 k

Transaction Summary================================================================================Install 2 Package(s)Upgrade 0 Package(s)

Total size: 728 kInstalled size: 1.6 M


Guest ShellInstalling RPMs in the Guest Shell

Is this ok [y/N]: yDownloading Packages:Running rpm_check_debugRunning Transaction TestTransaction Test SucceededRunning TransactionInstalling : libperl5-5.14.3-r1.x86_64 1/2Installing : perl-5.14.3-r1.x86_64 2/2

Installed:perl.x86_64 0:5.14.3-r1

Dependency Installed:libperl5.x86_64 0:5.14.3-r1

Complete!guestshell:~$

Whenmore space is needed in the guest shell root file system for installing or running packages, the guestshellresize 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 guestshell as a result of restrictions that have been put into place to protect the integrity of the host system.

Note

Resources Used for the Guest ShellBy default, the resources for the guest shell have a small impact on resources available for normal switchoperations. If the network-admin requires additional resources for the guest shell, the guestshell resize {cpu| memory | rootfs} command changes these limits.

Minimum/MaximumDefaultResource

1/20%1%CPU

256/3840MB256MBMemory

204/1024MB204MBStorage

The CPU limit is the percentage of the system compute capacity that tasks running within the guest shell aregiven when there is contention with other compute loads in the system. When there is no contention for CPUresources, the tasks within the guest shell are not limited.

A guest shell reboot is required after changing the resource allocations. This can be accomplished with theguestshell reboot command.

Note


Guest ShellResources Used for the Guest Shell

Security Posture for Virtual ServicesUse of the guest shell and virtual services in Cisco Nexus 9000 series devices are only two of the many waysthat the network-admin canmanage or extend the functionality of the system. These options are geared towardsproviding an execution environment that is decoupled from the native host context. This separation allowsthe 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 PackagesBy 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 unsignedOVA software packages. To allow unsigned and Cisco-signed packages for creating virtual-services, thenetwork-admin can configure the following:

virtual-servicesigning level unsigned

The guest shell software package has a Cisco signature and does not require this configuration.Note

Kernel Vulnerability PatchesCisco responds to pertinent CommonVulnerabilities and Exposures (CVEs) with platform updates that addressknown vulnerabilities.

ASLR and X-Space SupportCisco Nexus 9000 NX-OS supports the use of Address Space Layout Randomization (ASLR) and ExecutableSpace Protection (X-Space) for runtime defense. The software in Cisco-signed packages make use of thiscapability. If other software is installed on the system, it is recommended that it be built using a host OS anddevelopment toolchain that supports these technologies. Doing so reduces the potential attack surface that thesoftware presents to potential intruders.

Root-User RestrictionsAs a best practice for developing secure code, it is recommend running applications with the least privilegeneeded to accomplish the assigned task. To help prevent unintended accesses, software added into the guestshell should follow this best practice.

All processes within a virtual service are subject to restrictions imposed by reduced Linux capabilities. If yourapplication must perform operations that require root privileges, restrict the use of the root account to thesmallest set of operations that absolutely requires root access, and impose other controls such as a hard limiton the amount of time that the application can run in that mode.


Guest ShellSecurity Posture for Virtual Services

The set of Linux capabilities that are dropped for root within virtual services follow:

CAP_SYS_PACCTCAP_MKNODCAP_SYS_BOOT

CAP_SYS_RESOURCECAP_MAC_OVERRIDECAP_SYS_MODULE

CAP_AUDIT_WRITECAP_SYS_RAWIOCAP_SYS_TIME

CAP_SETFCAPCAP_SYS_NICECAP_AUDIT_CONTROL

CAP_SETPCAPCAP_SYS_PTRACECAP_MAC_ADMIN

As root within a virtual-service, bind mounts may be used as well as tmpfs and ramfs mounts. Other mountsare prevented.

Namespace IsolationThe host and virtual service are separated into separate namespaces. This provides the basis of separating theexecution spaces of the virtual services from the host. Namespace isolation helps to protect against data lossand data corruption due to accidental or intentional data overwrites between trust boundaries. It also helps toensure the integrity of confidential data by preventing data leakage between trust boundaries: an applicationin one virtual service cannot access data in another virtual service

Guest File System Access RestrictionsTo preserve the integrity of the files within the virtual services, the file systems of the virtual services are notaccessible from the NX-OS CLI. If a given virtual-service allows files to be modified, it needs to provide analternate 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 accessthe file using an NX-OS CLI or Linux command from within the guest shell.

Resource ManagementADenial-of-Service (DoS) attack attempts to make a machine or network resource unavailable to its intendedusers.Misbehaving ormalicious application code can causeDoS as the result of over-consumption of connectionbandwidth, disk space, memory, and other resources. The host provides resource-management features thatensure fair allocation of resources among all virtual services on the host.

Secure IPCApplications in a guest shell or virtual service can be made more integrated with the host by using CiscoonePK services. The applications communicate with the host network element over TIPC. Applications withinvarious containers are not allowed to communicate with each other over TIPC, they are only allowed to talkto the host. This prevents issues of one container from spoofing that it is where the Cisco onePK services arerunning. Applications in containers are also not allowed to listen on TIPC ports.

To ensure that only know virtual services can communicate with the host, a unique identifier for each virtualservice is created when it is enabled and verified at the time when the onePK communication channel isestablished.


Guest ShellNamespace Isolation

The system also limits the rate at which an application in an individual virtual service can send messages tothe host. This behavior prevents a misbehaving application from sending messages frequently enough toprevent normal operation of the host or to block other virtual services on the same host from communicatingwith the host.

Guidelines and LimitationsThe guest shell has the following guidelines and limitations:

• By default, the guest shell starts an Open-SSH v6.2p2 server upon boot up. The server listens on port4022 on the localhost ip address interface 127.0.0.1 only. This provides the password-less connectivityinto the guest shell from the NX-OS vegas-shell when the guestshell keyword is entered. If this serveris killed or its configuration (residing in /etc/ssh/sshd_config) is altered, access to the guestshell from the NX-OS CLI may not work. When this happens, you should navigate back into the guestshell with the virtual-service connect name guestshell+ console command. The username/passwordfor this access is guestshell/guestshell.

To instantiate your own Open-SSH server within the guest shell use the following steps as root:

• Determine which VRF you want to establish your ssh connections through.

• Determine which port you want your Open-SSH server to listen for connections. Use the NX-OSCLI show socket connection command to view which ports that are already in use.

Do not select port 4022.Note

• Start your Open-SSH server with the following command:

chvrf vrf_name /usr/sbin/sshd -p port_number

• The time zone within the guest shell is not updated when the clock timezone command is configured.

Use the Linux TZ environment variable to change the timezone within the guest shell.

The following is an example that configures the time zone in the guest shell:

switch(config)# clock timezone PDT -7 0switch(config)# clock set 11:01:15 12 Sep 2014Fri Sep 12 11:01:15 PDT 2014switch(config)# show clock11:01:26.421 PDT Fri Sep 12 2014switch(config)# run guestshellguestshell:~$ export TZ='PDT7'guestshell:~$ dateFri Sep 12 11:01:59 PDT 2014

• Cisco Nexus 9000 NX-OS automatically installs and enables the guest shell by default. However, if thedevice is reloaded with a Cisco NX-OS image that does not provide guest shell support, the existingguest shell is automatically removed and a%VMAN-2-INVALID_PACKAGE message is issued.

As a best practice, remove the guest shell with the guestshell destroy command before reloading theolder Cisco NX-OS image.


Guest ShellGuidelines and Limitations

Use the install all command to validate the compatibility between the current Cisco NX-OS image andthe target Cisco NX-OS image.

The following is an example of incompatible images:

switch# install all nxos n9kpregs.binInstaller will perform compatibility check first. Please wait.uri is: /n9kpregs.bin2014 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% -- SUCCESSVerifying image type.[####################] 100% -- SUCCESSPreparing "lcn9k" version info using image bootflash:/n9kpregs.bin.[####################] 100% -- SUCCESSPreparing "bios" version info using image bootflash:/n9kpregs.bin.[####################] 100% -- SUCCESSPreparing "lcn9k" version info using image bootflash:/n9kpregs.bin.[####################] 100% -- SUCCESSPreparing "lcn9k" version info using image bootflash:/n9kpregs.bin.[####################] 100% -- SUCCESSPreparing "nxos" version info using image bootflash:/n9kpregs.bin.[####################] 100% -- SUCCESSPreparing "lcn9k" version info using image bootflash:/n9kpregs.bin.[####################] 100% -- SUCCESSPreparing "lcn9k" version info using image bootflash:/n9kpregs.bin.[####################] 100% -- SUCCESS"Running-config contains configuration that is incompatible with the new image (strictincompatibility).Please run 'show incompatibility-all nxos <image>' command to find out which featureneeds to be disabled.".Performing module support checks.[####################] 100% -- SUCCESSNotifying services about system upgrade.[# ] 0% -- FAIL.Return code 0x42DD0006 ((null))."Running-config contains configuration that is incompatible with the new image (strictincompatibility).Please run 'show incompatibility-all nxos <image>' command to find outwhich feature needs to be disabled."Service "vman" in vdc 1: Guest shell not supported, do 'guestshell destroy' to removeit and then retry ISSUPre-upgrade check failed. Return code 0x42DD0006 ((null)).switch#

Managing the Guest ShellThe following are commands to manage the guest shell:


Guest ShellManaging the Guest Shell

Table 6: Guest Shell CLI Commands

DescriptionCommands

Installs and activates the guest shell using the OVAthat is embedded in the system image.

Installs and activates the guest shell using the specifiedsoftware package (OVA file) or the embeddedpackage from the system image (when no package isspecified). Initially, guest shell packages are onlyavailable by being embedded in the system image.

When the guest shell is already installed, thiscommand enables the installed guest shell. Typicallythis is used after a guestshell disable command.

guestshell enable [package guest shell OVA file]

Shuts down and disables the guest shell.guestshell disable

Deactivates and upgrades the guest shell using thespecified software package (OVA file) or theembedded package from the system image (if nopackage is specified). Initially guest shell packagesare only available by being embedded in the systemimage.

The current rootfs for the guest shell is replaced withthe rootfs in the software package. The guest shelldoes not make use of secondary filesystems thatpersist across an upgrade. Without persistentsecondary filesystems, a guestshell destroy commandfollowed by a guestshell enable command could alsobe used to replace the rootfs. When an upgrade issuccessful, the guest shell is activated.

You are prompted for a confirmation prior to carryingout the upgrade command.

guestshell upgrade [package guest shell OVA file]



DescriptionCommands

Deactivates the guest shell and then reactivates it.

You are prompted for a confirmation prior to carryingout the reboot command.

This is the equivalent of a guestshelldisable command followed by a guestshellenable command in exec mode.

This is useful when processes inside theguest shell have been stopped and need tobe restarted. The run guestshell commandrelies on sshd running in the guest shell.

If the command does not work, the sshdprocess may have been inadvertentlystopped. Performing a reboot of the guestshell from the NX-OS CLI allows it torestart and restore the command.

Note

guestshell reboot

Deactivates and uninstalls the guest shell. Allresources associated with the guest shell are returnedto the system. The show virtual-service globalcommand indicates when these resources becomeavailable.

Issuing this command results in a prompt for aconfirmation prior to carrying out the destroycommand.

guestshell destroy

Connects to the guest shell that is already runningwith a shell prompt. No username/password isrequired.

guestshell

run guestshell

Executes a Linux/UNIX commandwithin the contextof the guest shell environment.

After execution of the command you are returned tothe switch prompt.

guestshell run command

run guestshell command

Changes the allotted resources available for the guestshell. The changes take effect the next time the guestshell is enabled or rebooted.

guestshell resize [cpu |memory | rootfs]



DescriptionCommands

On systems that have active and standby supervisors,this command synchronizes the guest shell contentsfrom the active supervisor to the standby supervisor.The network-admin issues this command when theguest shell rootfs has been set up to a point that theywould want the same rootfs used on the standbysupervisor when it becomes the active supervisor. Ifthis command is not used, the guest shell is freshlyinstalled when the standby supervisor transitions toan active role using the guest shell package availableon that supervisor.

guestshell sync

In the event that the guestshell or virtual-servicescannot be managed, even after a system reload, thereset command is used to force the removal of theguest shell and all virtual-services. The system needsto be reloaded for the cleanup to happen. No guestshell or additional virtual-services can be installed orenabled after issuing this command until after thesystem has been reloaded.

You are prompted for a confirmation prior to initiatingthe reset.

virtual-service reset force

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, LXCsare installed and managed with the virtual-service commands. The guest shell appears in the virtual-servicecommands as a virtual service named guestshell+.

Note

Disabling the Guest ShellThe 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 listVirtual Service List:Name Status Package Name-----------------------------------------------------------guestshell+ Activated guestshe11.ovaswitch# guestshell disableYou will not be able to access your guest shell if it is disabled. Are you sure you wantto disable the guest shell? (y/n) [n) y


Guest ShellDisabling the Guest Shell

2014 Jul 30 19:47:23 switch %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE: Deactivating virtualservice 'guestshell+'2014 Jul 30 18:47:29 switch %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE: Successfully deactivatedvirtual service 'guestshell+'switch# show virtual-service listVirtual Service List:Name Status Package Nameguestshell+ Deactivated guestshell.ova

The guest shell is reactivated with the guestshell enable command.Note

Destroying the Guest ShellThe guestshell destroy command uninstalls the guest shell and its artifacts. The command does not removethe guest shell OVA.

When the guest shell is destroyed and the system is reloaded, the guest shell remains destroyed.

switch# show virtual-service listVirtual 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] y2014 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 destroyedvirtual service 'guestshell +'

switch# show virtual-service listVirtual Service List:

The guest shell can be re-enabled with the guestshell enable command.Note

In the Cisco NX-OS software, the oneP feature is automatically enabled for local access when a container isinstalled. Since the guest shell is a container, the oneP feature is automatically started.

If you do not want to use the guest shell, you can remove it with the guestshell destroy command. Once theguest shell has been removed, it remains removed for subsequent reloads. This means that when the guestshell container has been removed and the switch is reloaded, the guest shell container and the oneP featureare not automatically started.

Note


Guest ShellDestroying the Guest Shell

Enabling the Guest ShellThe guestshell enable command installs the guest shell from a guest shell software package. By default, thepackage embedded in the system image is used for the installation. The command is also used to reactivatethe guest shell if it has been disabled.

When the guest shell is enabled and the system is reloaded, the guest shell remains enabled.

Example:

switch# show virtual-service listVirtual Service List:switch# guestshell enable2014 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 virtualservice '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 activatedvirtual service 'guestshell+'

switch# show virtual-service listVirtual Service List:Name Status Package Nameguestshell+ Activated guestshell.ova

Verifying Virtual Service and Guest Shell InformationYou can verify virtual service and guest shell information with the following commands:


Guest ShellEnabling the Guest Shell

DescriptionCommand

Displays the global state andlimits for virtual services.

show virtual-service global

switch# show virtual-service global

Virtual Service Global State and Virtualization Limits:

Infrastructure version : 1.8Total virtual services installed : 1Total virtual services activated : 1

Machine types supported : LXCMachine types disabled : KVM

Maximum VCPUs per virtual service : 1

Resource virtualization limits:

Name Quota Committed Available------------------------------------------------------------------system CPU (%) 6 1 5memory (MB) 2304 256 2048bootflash (MB) 8192 2483710

Displays a summary of thevirtual services, the status ofthe virtual services, andinstalled software packages.

show virtual-service list

switch# show virtual-service list *

Virtual Service List:

Name Status Package Name------------------------------------------------------------------guestshell+ Activated guestshell.ovachef Installed chef-0.8.1-n9000-spa-k9.ova


Guest ShellVerifying Virtual Service and Guest Shell Information

DescriptionCommand

Displays details about theguestshell package (such asversion, signing resources, anddevices).

show guestshell detail

switch# show guestshell detailVirtual service guestshell+ detailState : ActivatedPackage informationName : guestshell.ovaPath : /isan/bin/guestshell.ovaApplicationName : GuestShellInstalled version : 1.0(0.1)Description : Cisco Systems Guest Shell

SigningKey type : Cisco keyMethod : SHA-1

LicensingName : NoneVersion : None

Resource reservationDisk : 204 MBMemory : 256 MBCPU : 1% system CPU

Attached devicesType Name Alias---------------------------------------------Disk _rootfsDisk /cisco/coreSerial/shellSerial/auxSerial/Syslog serial2Serial/Trace serial3





C H A P T E R 8Scripting with Tcl

• About Tcl, on page 55• Running the tclsh Command, on page 57• Navigating Cisco NX-OS Modes from the tclsh Command, on page 58• Tcl References, on page 60

About TclTcl (Tool Command Language) is a scripting language. With tcl, you gain more flexibility in your use of theCLI commands on the device. You can use tcl to extract certain values in the output of a show command,perform switch configurations, run Cisco NX-OS commands in a loop, or define Embedded Event Manager(EEM) policies in a script.

This section describes how to run tcl scripts or run tcl interactively on Cisco NX-OS devices.

Tclsh Command HelpCommand help is not available for tcl commands. You can still access the help functions of Cisco NX-OScommands from within an interactive tcl shell.

This example shows the lack of tcl command help in an interactive tcl shell:switch# tclshswitch-tcl# set x 1switch-tcl# puts ?

^% Invalid command at '^' marker.switch-tcl# configure ?<CR>session Configure the system in a sessionterminal Configure the system from terminal input

switch-tcl#

In the above example, the Cisco NX-OS command help function is still available but the tcl puts commandreturns an error from the help function.

Note


Tclsh Command HistoryYou can use the arrow keys on your terminal to access commands you previously entered in the interactivetcl shell.

The tclsh command history is not saved when you exit the interactive tcl shell.Note

Tclsh Tab CompletionYou can use tab completion for Cisco NX-OS commands when you are running an interactive tcl shell. Tabcompletion is not available for tcl commands.

Tclsh CLI CommandAlthough you can directly access Cisco NX-OS commands from within an interactive tcl shell, you can onlyexecute Cisco NX-OS commands in a tcl script if they are prepended with the tcl cli command.

In an interactive tcl shell, the following commands are identical and will execute properly:switch-tcl# cli show module 1 | incl Modswitch-tcl# cli "show module 1 | incl Mod"switch-tcl# show module 1 | incl Mod

In a tcl script, you must prepend Cisco NX-OS commands with the tcl cli command as shown in the followingexample:set x 1cli show module $x | incl Modcli "show module $x | incl Mod"

If you use the following commands in your script, the script will fail and the tcl shell will display an error:show module $x | incl Mod"show module $x | incl Mod"

Tclsh Command SeparationThe semicolon (;) is the command separator in both Cisco NX-OS and tcl. To execute multiple Cisco NX-OScommands in a tcl command, you must enclose the Cisco NX-OS commands in quotes ("").

In an interactive tcl shell, the following commands are identical and will execute properly:switch-tcl# cli "configure terminal ; interface loopback 10 ; description loop10"switch-tcl# cli configure terminal ; cli interface loopback 10 ; cli description loop10switch-tcl# cli configure terminalEnter configuration commands, one per line. End with CNTL/Z.

switch(config-tcl)# cli interface loopback 10switch(config-if-tcl)# cli description loop10switch(config-if-tcl)#


Scripting with TclTclsh Command History

In an interactive tcl shell, you can also execute Cisco NX-OS commands directly without prepending the tclcli command:switch-tcl# configure terminalEnter configuration commands, one per line. End with CNTL/Z.

switch(config-tcl)# interface loopback 10switch(config-if-tcl)# description loop10switch(config-if-tcl)#

Tcl VariablesYou can use tcl variables as arguments to the Cisco NX-OS commands. You can also pass arguments into tclscripts. Tcl variables are not persistent.

The following example shows how to use a tcl variable as an argument to a Cisco NX-OS command:switch# tclshswitch-tcl# set x loop10switch-tcl# cli "configure terminal ; interface loopback 10 ; description $x"switch(config-if-tcl)#

TclquitThe tclquit command exits the tcl shell regardless of which Cisco NX-OS command mode is currently active.You can also press Ctrl-C to exit the tcl shell. The exit and end commands change Cisco NX-OS commandmodes. The exit command will terminate the tcl shell only from the EXEC command mode.

Tclsh SecurityThe tcl shell is executed in a sandbox to prevent unauthorized access to certain parts of the Cisco NX-OSsystem. The system monitors CPU, memory, and file system resources being used by the tcl shell to detectevents such as infinite loops, excessive memory utilization, and so on.

You configure the intial tcl environment with the scripting tcl init init-file command.

You can define the looping limits for the tcl environment with the scripting tcl recursion-limit iterationscommand. The default recursion limit is 1000 interations.

Running the tclsh CommandYou can run tcl commands from either a script or on the command line using the tclsh command.

You cannot create a tcl script file at the CLI prompt. You can create the script file on a remote device andcopy it to the bootflash: directory on the Cisco NX-OS device.

Note

SUMMARY STEPS

1. tclsh [bootflash:filename [argument ... ]]


Scripting with TclTcl Variables

DETAILED STEPS

PurposeCommand or Action

Starts a tcl shell.tclsh [bootflash:filename [argument ... ]]Step 1

Example: If you run the tclsh command with no arguments, the shellruns interactively, reading tcl commands from standardswitch# tclsh ?

<CR>bootflash: The file to run

input and printing command results and error messages tothe standard output. You exit from the interactive tcl shellby typing tclquit or Ctrl-C.

If you run the tclsh command with arguments, the firstargument is the name of a script file containing tclcommands and any additional arguments are made availableto the script as variables.

Example

The following example shows an interactive tcl shell:switch# tclshswitch-tcl# set x 1switch-tcl# cli show module $x | incl ModMod Ports Module-Type Model Status1 36 36p 40G Ethernet Module N9k-X9636PQ okMod Sw HwMod MAC-Address(es) Serial-Num

switch-tcl# exitswitch#

The following example shows how to run a tcl script:switch# show file bootflash:showmodule.tclset x 1while {$x < 19} {cli show module $x | incl Modset x [expr {$x + 1}]}

switch# tclsh bootflash:showmodule.tclMod Ports Module-Type Model Status1 36 36p 40G Ethernet Module N9k-X9636PQ okMod Sw HwMod MAC-Address(es) Serial-Num

switch#

Navigating Cisco NX-OS Modes from the tclsh CommandYou can change modes in Cisco NX-OS while you are running an interactive tcl shell.


Scripting with TclNavigating Cisco NX-OS Modes from the tclsh Command

SUMMARY STEPS

1. tclsh2. configure terminal3. tclquit

DETAILED STEPS

PurposeCommand or Action

Starts an interactive tcl shell.tclsh

Example:

Step 1

switch# tclshswitch-tcl#

Runs a Cisco NX-OS command in the tcl shell, changingmodes.

configure terminal

Example:

Step 2

The tcl prompt changes to indicate the CiscoNX-OS command mode.

Noteswitch-tcl# configure terminalswitch(config-tcl)#

Terminates the tcl shell, returning to the starting mode.tclquit

Example:

Step 3

switch-tcl# tclquitswitch#

Example

The following example shows how to change Cisco NX-OS modes from an interactive tcl shell:switch# tclshswitch-tcl# configure terminalEnter configuration commands, one per line. End with CNTL/Z.switch(config-tcl)# interface loopback 10switch(config-if-tcl)# ?description Enter description of maximum 80 charactersinherit Inherit a port-profileip Configure IP featuresipv6 Configure IPv6 featureslogging Configure logging for interfaceno Negate a command or set its defaultsrate-limit Set packet per second rate limitshutdown Enable/disable an interfacethis Shows info about current object (mode's instance)vrf Configure VRF parametersend Go to exec modeexit Exit from command interpreterpop Pop mode from stack or restore from namepush Push current mode to stack or save it under namewhere Shows the cli context you are in

switch(config-if-tcl)# description loop10switch(config-if-tcl)# tclquit


Scripting with TclNavigating Cisco NX-OS Modes from the tclsh Command

Exiting Tclswitch#

Tcl ReferencesThe following titles are provided for your reference:

• Mark Harrison (ed), Tcl/Tk Tools, O'Reilly Media, ISBN 1-56592-218-2, 1997

• Mark Harrison and Michael McLennan, Effective Tcl/Tk Programming, Addison-Wesley, Reading, MA,USA, ISBN 0-201-63474-0, 1998

• John K. Ousterhout, Tcl and the Tk Toolkit, Addison-Wesley, Reading, MA, USA, ISBN 0-201-63337-X,1994.

• Brent B. Welch, Practical Programming in Tcl and Tk, Prentice Hall, Upper Saddle River, NJ, USA,ISBN 0-13-038560-3, 2003.

• J Adrian Zimmer, Tcl/Tk for Programmers, IEEE Computer Society, distributed by JohnWiley and Sons,ISBN 0-8186-8515-8, 1998.


Scripting with TclTcl References

A P P E N D I X ANX-API Response Codes

• Table of NX-API Response Codes, on page 61

Table of NX-API Response CodesThe following are the possible NX-API errors, error codes, and messages of an NX-API response.

The following are the possible NX-API errors, error codes, and messages of an NX-API response.

The standard HTTP error codes are at the Hypertext Transfer Protocol (HTTP) Status Code Registry(http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

Note

Table 7: NX-API Response Codes

MessageCodeNX-API Response

Success.200SUCCESS

Output is piped elsewhere due to request.204CUST_OUTPUT_PIPED

Input Bash command error.400BASH_CMD_ERR

Chunking only allowed to one command.400CHUNK_ALLOW_ONE_CMD_ERR

CLI execution error.400CLI_CLIENT_ERR

Input CLI command error.400CLI_CMD_ERR

Request message is invalid.400IN_MSG_ERR

No input command.400NO_INPUT_CMD_ERR

Permission denied.401PERM_DENY_ERR

Configuration mode does not allow show .405CONF_NOT_ALLOW_SHOW_ERR

Show mode does not allow configuration.405SHOW_NOT_ALLOW_CONF_ERR


Maximum number of consecutive showcommands exceeded. The maximum is 10.

413EXCEED_MAX_SHOW_ERR

Response size too large.413MSG_SIZE_LARGE_ERR

Backend processing error.500BACKEND_ERR

System internal file operation error.500FILE_OPER_ERR

System internal LIBXML NS error.500LIBXML_NS_ERR

System internal LIBXML parse error.500LIBXML_PARSE_ERR

System internal LIBXML path context error.500LIBXML_PATH_CTX_ERR

System internal memory allocation error.500MEM_ALLOC_ERR

User not found from input or cache.500USER_NOT_FOUND_ERR

XML to JSON conversion error.500XML_TO_JSON_CONVERT_ERR

Bash command not supported.501BASH_CMD_NOT_SUPPORTED_ERR

Chunking allows only XML output.501CHUNK_ALLOW_XML_ONLY_ERR

JSON not supported due to large amount ofoutput.

501JSON_NOT_SUPPORTED_ERR

Message type not supported.501MSG_TYPE_UNSUPPORTED_ERR

Pipe operation not supported.501PIPE_OUTPUT_NOT_SUPPORTED_ERR

Pipe XML is not allowed in input.501PIPE_XML_NOT_ALLOWED_IN_INPUT

Response has large amount of output. JSON notsupported.

501RESP_BIG_JSON_NOT_ALLOWED_ERR

Structured output unsupported.501STRUCT_NOT_SUPPORTED_ERR

Undefined.600ERR_UNDEFINED


NX-API Response CodesNX-API Response Codes

A P P E N D I X BTroubleshooting

• About Troubleshooting, on page 63

About TroubleshootingTroubleshooting information for Cisco NX-OS programmability is documented in the Cisco Nexus 9000Series NX-OS Troubleshooting Guide.



TroubleshootingTroubleshooting