Cisco Nexus 3000 Series Switches User guide

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release

10.1(x)

First Published: 2019-12-23

Last Modified: 2020-07-21

Americas Headquarters

Cisco Systems, Inc.

170 West Tasman Drive

San Jose, CA 95134-1706

USA

http://www.cisco.com

Tel: 408 526-4000

800 553-NETS (6387)

Fax: 408 527-0883

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS REFERENCED IN THIS DOCUMENTATION ARE SUBJECT TO CHANGE WITHOUT NOTICE.

EXCEPT AS MAY OTHERWISE BE AGREED BY CISCO IN WRITING, ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS DOCUMENTATION ARE

PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

The Cisco End User License Agreement and any supplemental license terms govern your use of any Cisco software, including this product documentation, and are located at:

http://www.cisco.com/go/softwareterms.Cisco product warranty information is available at http://www.cisco.com/go/warranty. US Federal Communications Commission Notices are found

here http://www.cisco.com/c/en/us/products/us-fcc-notice.html.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT

LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS

HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any products and features described herein as in development or available at a future date remain in varying stages of development and will be offered on a when-and if-available basis. Any

such product or feature roadmaps are subject to change at the sole discretion of Cisco and Cisco will have no liability for delay in the delivery or failure to deliver any products or feature

roadmap items that may be set forth in this document.

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, network

topology 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 unintentional

and coincidental.

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based

on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language

that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product.

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: 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 relationship between Cisco and any

other company. (1721R)

CONTENTS

Preface xv

PREFACE

Audience xv

Document Conventions xv

Related Documentation for Cisco Nexus 3000 Series Switches xvi

Documentation Feedback xvi

Communications, Services, and Additional Information xvi

New and Changed Information 1

CHAPTER 1

New and Changed Information 1

Overview 3

CHAPTER 2

Programmability Overview 3

Standard Network Manageability Features 4

Advanced Automation Feature 4

Power on Auto Provisioning Support 4

Programmability Support 4

NX-API Support 4

Python Scripting 5

Tcl Scripting 5

Bash 5

Bash Shell Access and Linux Container Support 5

Guest Shell 5

Container Tracker Support 5

Perl Modules 6

Shells and Scripting 9

PART I

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

iii

Bash 11

CHAPTER 3

About Bash 11

Guidelines and Limitations 11

Accessing Bash 12

Escalate Privileges to Root 13

Examples of Bash Commands 14

Displaying System Statistics 14

Running Bash from CLI 15

Managing Feature RPMs 16

RPM Installation Prerequisites 16

Installing Feature RPMs from Bash 16

Upgrading Feature RPMs 17

Downgrading a Feature RPM 18

Erasing a Feature RPM 18

Managing Patch RPMs 18

RPM Installation Prerequisites 18

Adding Patch RPMs from Bash 19

Activating a Patch RPM 21

Committing a Patch RPM 22

Deactivating a Patch RPM 23

Removing a Patch RPM 24

Persistently Daemonizing an SDK- or ISO-Built Third-Party Process 25

Persistently Starting Your Application from the Native Bash Shell 26

Synchronize Files from Active Bootflash to Standby Bootflash 27

An Example Application in the Native Bash Shell 28

Guest Shell 31

CHAPTER 4

About the Guest Shell 31

Guidelines and Limitations 32

Accessing the Guest Shell 36

Resources Used for the Guest Shell 36

Capabilities in the Guest Shell 37

NX-OS CLI in the Guest Shell 37

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

iv

Contents

Network Access in Guest Shell 38

Access to Bootflash in Guest Shell 40

Python in Guest Shell 40

Python 3 in Guest Shell versions up to 2.10 (CentOS 7) 41

Installing RPMs in the Guest Shell 44

Security Posture for Guest Shell 45

Kernel Vulnerability Patches 45

ASLR and X-Space Support 45

Namespace Isolation 45

Root-User Restrictions 46

Resource Management 47

Guest File System Access Restrictions 47

Managing the Guest Shell 48

Disabling the Guest Shell 51

Destroying the Guest Shell 51

Enabling the Guest Shell 52

Replicating the Guest Shell 53

Exporting Guest Shell rootfs 53

Importing Guest Shell rootfs 53

Importing YAML File 55

show guestshell Command 58

Verifying Virtual Service and Guest Shell Information 59

Persistently Starting Your Application from the Guest Shell 60

Procedure for Persistently Starting Your Application from the Guest Shell 61

An Example Application in the Guest Shell 61

Troubleshooting Guest Shell Issues 62

Innovium Shell 65

CHAPTER 5

About the Innovium Shell 65

Guidelines and Limitations 65

Accessing the Innovium Shell Through CLI API 66

Passing Commands to the Innovium Shell 68

Python API 69

CHAPTER 6

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

v

Contents

About the Python API 69

Using Python 69

Cisco Python Package 69

Using the CLI Command APIs 71

Invoking the Python Interpreter from the CLI 72

Display Formats 73

Non-Interactive Python 74

Running Scripts with Embedded Event Manager 75

Python Integration with Cisco NX-OS Network Interfaces 76

Cisco NX-OS Security with Python 76

Examples of Security and User Authority 77

Example of Running Script with Schedular 78

Scripting with TCL 79

CHAPTER 7

About Tcl 79

Guidelines and Limitations 79

Tclsh Command Help 79

Tclsh Command History 80

Tclsh Tab Completion 80

Tclsh CLI Command 80

Tclsh Command Separation 81

Tcl Variables 81

Tclquit 81

Tclsh Security 81

Running the Tclsh Command 82

Navigating Cisco NX-OS Modes from the Tclsh Command 82

Tcl References 83

Kernel Stack 85

CHAPTER 8

About Kernel Stack 85

Guidelines and Limitations 85

Changing the Port Range 86

Netdevice Property Changes 87

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

vi

Contents

Applications 89

PART II

Cisco Nexus Application Development - SDK 91

CHAPTER 9

About the Cisco SDK 91

Installing the SDK 91

Procedure for Installation and Environment Initialization 92

Using the SDK to Build Applications 93

Using RPM to Package an Application 94

Creating an RPM Build Environment 95

Using General RPM Build Procedure 95

Example to Build RPM for collectd with No Optional Plug-Ins 96

Example to Build RPM for collectd with Optional Curl Plug-In 97

NX-SDK 99

CHAPTER 10

About the NX-SDK 99

Install the NX-SDK 100

Building and Packaging C++ Applications 101

Installing and Running Custom Applications 103

NX-API 107

PART III

NX-API CLI 109

CHAPTER 11

About NX-API CLI 109

Transport 109

Message Format 109

Security 110

Using NX-API CLI 110

Escalate Privileges to Root on NX-API 112

Sample NX-API Scripts 113

NX-API Management Commands 114

Working with Interactive Commands Using NX-API 115

NX-API Request Elements 116

NX-API Response Elements 119

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

vii

Contents

Restricting Access to NX-API 120

Updating an iptable 121

Making an Iptable Persistent Across Reloads 122

Table of NX-API Response Codes 123

JSON and XML Structured Output 124

About JSON (JavaScript Object Notation) 125

Examples of XML and JSON Output 125

NX-API REST 129

CHAPTER 12

About NX-API REST 129

NX-API Developer Sandbox 131

CHAPTER 13

About the NX-API Developer Sandbox 131

Guidelines and Limitations 132

Enabling and Accessing the Developer Sandbox 133

Configuring the Message Format and Input Type 133

Using the Developer Sandbox 135

Using the Developer Sandbox to Convert CLI Commands to Payloads 136

Using the Developer Sandbox to Convert from REST Payloads to CLI Commands 139

Using the Developer Sandbox to Convert from RESTCONF to json or XML 143

Model-Driven Programmability 147

PART IV

Infrastructure Overview 149

CHAPTER 14

About Model-Driven Programmability 149

About the Programmable Interface Infrastructure 149

Managing Components 153

CHAPTER 15

About the Component RPM Packages 153

Preparing for Installation 155

Downloading Components from the Cisco Artifactory 156

Installing RPM Packages 156

Installing the Programmable Interface Base and Common Model Component RPM Packages 156

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

viii

Contents

OpenConfig YANG 159

CHAPTER 16

About OpenConfig YANG 159

Guidelines and Limitations for OpenConfig YANG 159

Understanding Deletion of BGP Routing Instance 164

NETCONF Agent 167

CHAPTER 17

About the NETCONF Agent 167

Guidelines and Limitations 169

Configuring the NETCONF Agent 169

Using the NETCONF Agent 170

Error Messages 173

Troubleshooting the NETCONF Agent 174

Converting CLI Commands to Network Configuration 175

CHAPTER 18

Information About XMLIN 175

Licensing Requirements for XMLIN 175

Installing and Using the XMLIN Tool 176

Converting Show Command Output to XML 176

Configuration Examples for XMLIN 177

RESTCONF Agent 181

CHAPTER 19

About the RESTConf Agent 181

Guidelines and Limitations 182

Configuring the RESTConf Agent 182

Using the RESTConf Agent 182

Troubleshooting the RESTConf Agent 183

gRPC Agent 185

CHAPTER 20

About the gRPC Agent 185

Guidelines and Limitations 186

Configuring the gRPC Agent 187

Using the gRPC Agent 188

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

ix

Contents

Troubleshooting the gRPC Agent 189

gRPC Protobuf File 189

gNMI - gRPC Network Management Interface 197

CHAPTER 21

About gNMI 197

gNMI RPC and SUBSCRIBE 198

Guidelines and Limitations for gNMI 199

Configuring gNMI 200

Configuring Server Certificate 201

Generating Key/Certificate Examples 202

Verifying gNMI 206

Clients 206

Sample DME Subscription - JSON Encoding 206

Sample DME Subscription - PROTO Encoding 207

Subscribe 209

Guidelines and Limitations for Subscribe 209

gNMI Payload 210

Capabilities 212

About Capabilities 212

Guidelines and Limitations for Capabilities 212

Example Client Output for Capabilities 213

Troubleshooting 216

Gathering TM-Trace Logs 216

Gathering MTX-Internal Logs 216

Innovium Path Telemetry 219

About Innovium Path Telemetry 219

Guidelines and Limitations for Innovium Path Telemetry 219

Configuring Flow of Interest ACL for IPT 220

Configuring the TCAM Region for Innovium Path Telemetry 221

Configuring the Source Node 221

Configuring the Transit Node 223

Configuring the Sink Node 224

Verifying Innovium Path Telemetry 226

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

x

Contents

Dynamic Logger 231

CHAPTER 22

Prerequisites 231

Reference 231

Model-Driven Telemetry 239

CHAPTER 23

About Telemetry 239

Telemetry Components and Process 239

High Availability of the Telemetry Process 241

Licensing Requirements for Telemetry 241

Installing and Upgrading Telemetry 241

Guidelines and Limitations 242

Configuring Telemetry Using the CLI 247

Configuring Telemetry Using the NX-OS CLI 247

Configuration Examples for Telemetry Using the CLI 252

Displaying Telemetry Configuration and Statistics 255

Displaying Telemetry Log and Trace Information 261

Configuring Telemetry Using the NX-API 262

Configuration Example for Telemetry Using the NX-API 271

Telemetry Model in the DME 274

Hardware Telemetry 277

CHAPTER 24

Guidelines and Limitations 277

Telemetry RPM Installation Example 277

About Streaming Statistics Export 280

SSX Supported Types 280

SSX gRPC Filter Types 281

SSX Examples 281

About Port Counters 285

Port Counter Exports 286

Port Counter Sample Output 286

Guidelines and Limitations for Buffer Drop Capture and Buffer Latency Capture 287

Configuring Software Telemetry 288

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xi

Contents

FTE drop and Latency Capture 289

About Flow Table Events (FTE) 289

Guidelines and Limitations 290

Configuring FTE 290

FTE show Commands 294

FTE Drop and Latency Filter Types 296

Innovium Path Telemetry 296

About Innovium Path Telemetry 296

Guidelines and Limitations for Innovium Path Telemetry 297

Configuring Flow of Interest ACL for IPT 297

Configuring TCAM for Innovium Path Telemetry 298

Configuring Ingress TCAM Carving 298

Configuring Egress TCAM Carving 298

Configuring the Source Node 299

Configuring the Transit Node 301

Configuring the Sink Node 301

Verifying Innovium Path Telemetry 303

XML Mangement Interface 309

PART V

XML Management Interface 311

CHAPTER 25

About the XML Management Interface 311

Information About the XML Management Interface 311

NETCONF Layers 311

SSH xmlagent 312

Licensing Requirements for the XML Management Interface 312

Prerequisites to Using the XML Management Interface 312

Using the XML Management Interface 313

Configuring the SSH and the XML Server Options Through the CLI 313

Starting an SSHv2 Session 314

Sending a Hello Message 315

Obtaining XML Schema Definition (XSD) Files 315

Sending an XML Document to the XML Server 316

Creating NETCONF XML Instances 316

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xii

Contents

Information About Example XML Instances 326

Example XML Instances 326

NETCONF Close Session Instance 326

NETCONF Kill Session Instance 327

NETCONF Copy Config Instance 327

NETCONF Edit Config Instance 328

NETCONF Get Config Instance 329

NETCONF Lock Instance 330

NETCONF Unlock Instance 331

NETCONF Commit Instance: Candidate Configuration Capability 331

NETCONF Confirmed Commit Instance 331

NETCONF Rollback-On-Error Instance 332

NETCONF Validate Capability Instance 332

Additional References 333

Streaming Telemetry Sources 335

APPENDIX A

About Streaming Telemetry 335

Guidelines and Limitations 335

Data Available for Telemetry 335

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xiii

Contents

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xiv

Contents

Preface

This preface includes the following sections:

•Audience, on page xv

•Document Conventions, on page xv

•Related Documentation for Cisco Nexus 3000 Series Switches, on page xvi

•Documentation Feedback, on page xvi

•Communications, Services, and Additional Information, on page xvi

Audience

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

Document Conventions

Command descriptions use the following conventions:

DescriptionConvention

Bold text indicates the commands and keywords that you enter literally

as shown.

bold

Italic text indicates arguments for which the user supplies the values.Italic

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

Square brackets enclosing keywords or arguments separated by a vertical

bar indicate an optional choice.

[x | y]

Braces enclosing keywords or arguments separated by a vertical bar

indicate a required choice.

{x | y}

Nested set of square brackets or braces indicate optional or required

choices within optional or required elements. Braces and a vertical bar

within square brackets indicate a required choice within an optional

element.

[x {y | z}]

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xv

DescriptionConvention

Indicates a variable for which you supply values, in context where italics

cannot be used.

variable

A nonquoted set of characters. Do not use quotation marks around the

string or the string will include the quotation marks.

string

Examples use the following conventions:

DescriptionConvention

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

Information 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 line

of code indicates a comment line.

!, #

Related Documentation for Cisco Nexus 3000 Series Switches

The entire Cisco Nexus 3000 Series switch documentation set is available at the following URL:

https://www.cisco.com/c/en/us/support/switches/nexus-3000-series-switches/

tsd-products-support-series-home.html

Documentation Feedback

To provide technical feedback on this document, or to report an error or omission, please send your comments

to [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, visit

Cisco 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 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xvi

Preface

Related Documentation for Cisco Nexus 3000 Series Switches

Cisco Bug Search Tool

Cisco Bug Search Tool (BST) is a web-based tool that acts as a gateway to the Cisco bug tracking system

that maintains a comprehensive list of defects and vulnerabilities in Cisco products and software. BST provides

you with detailed defect information about your products and software.

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xvii

Preface

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

xviii

Preface

CHAPTER 1

New and Changed Information

This chapter contains the following topics:

•New and Changed Information, on page 1

New and Changed Information

Table 1: New and Changed Features

Where DocumentedChanged

in

Release

DescriptionFeature

Python API, on page 699.3(5)Added support for Python 3.Python 3 for NX-OS

9.3(3)Initial releaseSupport for the Cisco Nexus

3400-S

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

1

Cisco Nexus 3400-S Series NX-OS Programmability Guide, Release 10.1(x)

2

New and Changed Information

Page is loading ...

Cisco Nexus 3000 Series Switches User guide

Cisco Nexus 3000 Series Switches User guide

Related papers

Other documents