Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.

x
First Published: 2022-11-30

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 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 WITH
THE 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 of
the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY 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 OF
MERCHANTABILITY, 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, 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 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.

All printed copies and duplicate soft copies of this document are considered uncontrolled. See the current online version for the latest version.

Cisco has more than 200 offices worldwide. Addresses and phone numbers are listed on the Cisco website at www.cisco.com/go/offices.

The documentation set for this product strives to use bias-free language. For 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 standards 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:
https://www.cisco.com/c/en/us/about/legal/trademarks.html. 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)
© 2022 Cisco Systems, Inc. All rights reserved.
 Preface
This preface describes the conventions of this document and information on how to obtain other documentation.
It also provides information on what's new in Cisco product documentation.
• Document Conventions , on page iii
• Related Documentation, on page v
• Obtaining Documentation and Submitting a Service Request, on page v

Document Conventions
This document uses the following conventions:

Convention Description
^ or Ctrl Both the ^ symbol and Ctrl represent the Control (Ctrl) key on a keyboard. For
example, the key combination ^D or Ctrl-D means that you hold down the Control
key while you press the D key. (Keys are indicated in capital letters but are not
case sensitive.)

bold font Commands and keywords and user-entered text appear in bold font.

Italic font Document titles, new or emphasized terms, and arguments for which you supply
values are in italic font.

Courier font Terminal sessions and information the system displays appear in courier font.

Bold Courier font Bold Courier font indicates text that the user must enter.
[x] Elements in square brackets are optional.

... An ellipsis (three consecutive nonbolded periods without spaces) after a syntax
element indicates that the element can be repeated.

| A vertical line, called a pipe, indicates a choice within a set of keywords or

arguments.

[x | y] Optional alternative keywords are grouped in brackets and separated by vertical

bars.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

iii
 Preface
Preface

Convention Description
{x | y} Required alternative keywords are grouped in braces and separated by vertical
bars.

[x {y | z}] 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.

string A nonquoted set of characters. Do not use quotation marks around the string or
the string will include the quotation marks.

<> 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.

Reader Alert Conventions

This document may use the following conventions for reader alerts:

Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the
manual.

Tip Means the following information will help you solve a problem.

Caution Means reader be careful. In this situation, you might do something that could result in equipment damage
or loss of data.

Timesaver Means the described action saves time. You can save time by performing the action described in the
paragraph.

Warning IMPORTANT SAFETY INSTRUCTIONS

Before you work on any equipment, be aware of the hazards involved with electrical circuitry and be
familiar with standard practices for preventing accidents. Read the installation instructions before using,
installing, or connecting the system to the power source. Use the statement number provided at the end
of each warning statement to locate its translation in the translated safety warnings for this device.
Statement 1071
SAVE THESE INSTRUCTIONS

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

iv
 Preface
Related Documentation

Related Documentation

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, submitting a service request, and gathering additional information,
see the monthly What's New in Cisco Product Documentation, which also lists all new and revised Cisco
technical documentation, at:
http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html
Subscribe to the What's New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed
and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free
service and Cisco currently supports RSS version 2.0.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

v
 Preface
Obtaining Documentation and Submitting a Service Request

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

vi
 CONTENTS

Full Cisco Trademarks with Software License ?

PREFACE Preface iii

Document Conventions iii

Related Documentation v
Obtaining Documentation and Submitting a Service Request v

CHAPTER 1 New and Changed Information 1

New and Changed Information 1

PART I Provisioning 33

CHAPTER 2 Zero-Touch Provisioning 35

Restrictions for Zero-Touch Provisioning 35

Information About Zero-Touch Provisioning 35
Zero-Touch Provisioning Overview 35
DHCP Server Configuration for Zero-Touch Provisioning 36
DHCPv6 Support 36

Sample Zero-Touch Provisioning Configurations 37

Sample DHCP Server Configuration on a Management Port Using TFTP Copy 37
Sample DHCP Server Configuration on a Management Port Using HTTP Copy 37
Sample DHCP Server Configuration on an In-Band Port Using TFTP Copy 38
Sample DHCP Server Configuration on an In-Band Port Using HTTP Copy 38
Sample DHCP Server Configuration on a Linux Ubuntu Device 38
Sample DHCPv6 Server Configuration on a Management Port Using TFTP Copy 39
Sample Python Provisioning Script 39

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

vii
 Contents

Boot Log for Cisco 4000 Series Integrated Services Routers 40

Boot Log for Cisco Catalyst 9000 Series Switches 41

Feature Information for Zero-Touch Provisioning 65

CHAPTER 3 iPXE 71

Information About iPXE 71

About iPXE 71
iPXE Overview 72
IPv6 iPXE Network Boot 74
IPv6 Address Assignment in Rommon Mode 76
Supported ROMMON Variables 77
iPXE-Supported DHCP Options 77
DHCPv6 Unique Identifiers 79
How to Configure iPXE 79
Configuring iPXE 79
Configuring Device Boot 80
Configuration Examples for iPXE 81
Example: iPXE Configuration 81
Sample iPXE Boot Logs 82
Sample DHCPv6 Server Configuration for iPXE 82
Troubleshooting Tips for iPXE 84
Additional References for iPXE 85
Feature Information for iPXE 85

PART II Shells and Scripting 87

CHAPTER 4 Guest Shell 89

Restrictions for Guest Shell 89

Information About the Guest Shell 89
Guest Shell Overview 89
Guest Shell Software Requirements 90
Guest Shell Security 91
Hardware Requirements for the Guest Shell 91
Guest Shell Storage Requirements 91

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

viii
 Contents

Enabling and Running the Guest Shell 92

Disabling and Destroying the Guest Shell 93
Accessing Guest Shell on a Device 93
Accessing Guest Shell Through the Management Port 93
Day Zero Guest Shell Provisioning Using Front-Panel Port or Fiber Uplink 93
Stacking with Guest Shell 94
Cisco IOx Overview 94
IOx Tracing and Logging Overview 94
IOXMAN Structure 95
NETCONF Access from Guest Shell 95
Logging and Tracing System Flow 96
Logging and Tracing of Messages 98
How to Enable the Guest Shell 99
Managing IOx 99
Managing the Guest Shell 100
Managing the Guest Shell Using Application Hosting 102
Configuring the AppGigabitEthernet Interface for Guest Shell 103
Enabling Guest Shell on the Management Interface 106
Enabling and Disabling NETCONF Access from Guest Shell 107
Accessing the Python Interpreter 108
Configuration Examples for the Guest Shell 109
Example: Managing the Guest Shell 109
Sample VirtualPortGroup Configuration 110
Example: Configuring the AppGigabitEthernet Interface for Guest Shell 111
Example: Enabling Guest Shell on the Management Interface 112
Example: Guest Shell Usage 112
Example: Guest Shell Networking Configuration 112
Sample DNS Configuration for Guest Shell 112
Example: Configuring Proxy Environment Variables 113
Example: Configuring Yum and PIP for Proxy Settings 113
Additional References for Guest Shell 114
Feature Information for Guest Shell 114

CHAPTER 5 Python API 119

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

ix
 Contents

About Python 119

Cisco Python Module 119

Cisco Python Module to Execute IOS CLI Commands 121
Python Scripts Overview 123
Interactive Python Prompt 123
Python Script 124
Supported Python Versions 125
Updating the Cisco CLI Python Module 126
Additional References for Python API 127
Feature Information for Python API 127

CHAPTER 6 EEM Python Module 129

Prerequisites for the EEM Python Module 129

Information About EEM Python Module 129
Python Scripting in EEM 129
EEM Python Package 129
Python-Supported EEM Actions 130
EEM Variables 131
EEM CLI Library Command Extensions 131
How to Configure the EEM Python Policy 132
Registering a Python Policy 132
Running Python Scripts as Part of EEM Applet Actions 133
Adding a Python Script in an EEM Applet 135
Additional References EEM Python Module 137
Feature Information for EEM Python Module 138

PART III Model-Driven Programmability 141

CHAPTER 7 NETCONF Protocol 143

Information About the NETCONF Protocol 143
Introduction to Data Models - Programmatic and Standards-Based Configuration 143
NETCONF 144
Restrictions for the NETCONF Protocol 144
YANG Model Version 1.1 144

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

x
 Contents

NETCONF RESTCONF IPv6 Support 146

Converting IOS Commands to XML 146
NETCONF Global Session Lock 159
NETCONF Kill Session 160
NETCONF-YANG SSH Server Support 160
Candidate Configuration Support 160
NETCONF Operations on Candidate 161
Confirmed Candidate Configuration Commit 162
Candidate Support Configuration 164
Side-Effect Synchronization of the Configuration Database 164

How to Configure the NETCONF Protocol 165

Providing Privilege Access to Use NETCONF 165
Configuring NETCONF-YANG 166
Configuring NETCONF Options 167
Configuring SNMP 167
Configuring the SSH Server to Perform RSA-Based User Authentication 169
Verifying the NETCONF Protocol Configuration Through the CLI 170
Displaying NETCONF-YANG Diagnostics Through RPCs 173
Additional References for NETCONF Protocol 176
Feature Information for the NETCONF Protocol 177

CHAPTER 8 RESTCONF Protocol 187

Prerequisites for the RESTCONF Protocol 187
Restrictions for the RESTCONF Protocol 187
Information About the RESTCONF Protocol 188
Overview of RESTCONF 188
HTTPs Methods 188
RESTCONF Root Resource 188
Displaying Version Information 189
RESTCONF API Resource 191
Methods 191
RESTCONF YANG-Patch Support 191
NETCONF RESTCONF IPv6 Support 195
Converting IOS Commands to XML 195

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xi
 Contents

How to Configure the RESTCONF Protocol 208

Authentication of NETCONF/RESTCONF Using AAA 208
Enabling Cisco IOS HTTP Services for RESTCONF 210
Verifying RESTCONF Configuration 211
Configuration Examples for the RESTCONF Protocol 213
Example: Configuring the RESTCONF Protocol 213
Additional References for the RESTCONF Protocol 216
Feature Information for the RESTCONF Protocol 217

CHAPTER 9 NETCONF and RESTCONF Service-Level ACLs 223

Information About NETCONF and RESTCONF Service-Level ACLs 223
Overview of NETCONF and RESTCONF Service-Level ACLs 223
How to Configure NETCONF and RESTCONF Service-Level ACLs 223
Configuring an ACL for a NETCONF-YANG Session 223
Configuring an ACL for a RESTCONF Session 225
Configuration Examples for NETCONF and RESTCONF Service-Level ACLs 226
Example: Configuring an ACL for a NETCONF Session 226
Example: Configuring an ACL for a RESTCONF Session 226
Additional References for NETCONF and RESTCONF Service-Level ACLs 227
Feature Information for NETCONF and RESTCONF Service-Level ACLs 227

CHAPTER 10 gNMI Protocol 229

Restrictions for the gNMI Protocol 229
Information About the gNMI Protocol 230
About GNMI 230
JSON IETF Encoding for YANG Data Trees 230
gNMI GET Request 231
gNMI SetRequest 234
gNMI Namespace 235
gNMI Wildcards 237
gNMI Configuration Persistence 240
gNMI Username and Password Authentication 240
gNMI Error Messages 240
How to Enable the gNMI Protocol 240

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xii
 Contents

Creating Certs with OpenSSL on Linux 241

Installing Certs on a Device Through the CLI 241
Enabling gNMI in Insecure Mode 242
Enabling gNMI in Secure Mode 243
Connecting the gNMI Client 245

Configuration Examples for the gNMI Protocol 246

Example: Enabling gNMI in Insecure Mode 246
Example: Enabling gNMI in Secure Mode 246
Additional References for the gNMI Protocol 247
Feature Information for the gNMI Protocol 247

CHAPTER 11 gRPC Network Operations Interface 253

Information About the gRPC Network Operations Interface 253

gNOI Protocol 253
Certificate Management Service 253
Install RPC 254
Rotate RPC 256
Revoke RPC 257
GetCertificate RPC 258
CanGenerateCSR RPC 259
Mutual Authentication 260
Bootstrapping with Certificate Service 260
OS Installation Service 260
OS Install RPC 262
OS Activate RPC 263
OS Verify RPC 267
GNOI Factory-Reset Services 267
gNOI Factory-Reset Error Messages 267
Additional References for the gRPC Network Operations Interface 268
Feature Information for the gRPC Network Operations Interface 269

CHAPTER 12 Model Based AAA 273

Model Based AAA 273

Prerequisites for Model Based AAA 273

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xiii
 Contents

Initial Operation 273

Group Membership 274
NACM Privilege Level Dependencies 275
NACM Configuration Management and Persistance 275
Resetting the NACM Configuration 275
Sample NACM Configuration 275
Additional References for Model Based AAA 279
Feature Information for Model-Based AAA 279

CHAPTER 13 Model-Driven Telemetry 281

Model-Driven Telemetry 281

Prerequisites for Model-Driven Telemetry 281
Restrictions for Model-Driven Telemetry 284
Information About Model-Driven Telemetry 284
Model-Driven Telemetry Overview 284
Telemetry Roles 285
Subscription Overview 285
Subscription Monitoring 307
Streams 309
TLDP On-Change Notifications 316
Transport Protocol 316
High Availability in Telemetry 317
Pubd Restartability 318
Sample Model-Driven Telemetry RPCs 318
Managing Configured Subscriptions 318
Receiving a Response Code 321
Receiving Subscription Push Updates for NETCONF Dial-In 321
Retrieving Subscription Details 322
Configuring Named Protocol Receiver Using the CLI 324

Subscription Configuration Using Named Receivers Using CLI 325

Additional References for Model-Driven Telemetry 326
Feature Information for Model-Driven Telemetry 327

CHAPTER 14 In-Service Model Update 341

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xiv
 Contents

Restrictions for In-Service Model Update 341

Information About In-Service Model Update 341
Overview of In-Service Model Updates 341
Compatibility of In-Service Model Update Packages 341
Update Package Naming Conventions 342
Installing the Update Package 342
Deactivating the Update Package 343
Rollback of the Update Package 343
How to Manage In-Service Model Update 344
Managing the Update Package 344
Configuration Examples for In-Service Model Updates 345
Example: Managing an Update Package 345

Feature Information for In-Service Model Update 349

PART IV Application Hosting 351

CHAPTER 15 Application Hosting 353

Restrictions for Application Hosting 353

Information About Application Hosting 354
Need for Application Hosting 354
Cisco IOx Overview 354
Application Hosting Overview 354
Application Hosting on Front-Panel Trunk and VLAN Ports 355

Application Hosting on Cisco Catalyst 9300 Series Switches 356

Front-Panel App Hosting on Cisco Catalyst 9300X Series Switches 356
High Availability on Cisco Catalyst 9300X Series Switches 357
Application Hosting on Cisco Catalyst 9400 Series Switches 359
Application Hosting on Cisco Catalyst 9410 Series Switches 359
Application Hosting on Cisco Catalyst 9500 Series Switches 361
Application Hosting on Cisco Catalyst 9600 Series Switches 361
Autotransfer and Auto-Install of Apps from Internal Flash to SSD 361
Native Docker Container: Application Auto-Restart 362
Application Auto-Restart Scenarios 362
Application Auto-Restart on Cisco Catalyst 9300 Series Switches 363

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xv
Contents

Supported Network Types 364

Virtual Network Interface Card 365
ERSPAN Support on the AppGigabitEthernet Port 365
How to Configure Application Hosting 365
Enabling Cisco IOx 365
Configuring Application Hosting on Front-Panel VLAN Ports 366
Configuring Application Hosting on Front-Panel Trunk Ports 368
Starting an Application in Configuration Mode 370
Lifecycle of an Application 371
Configuring Docker Run Time Options 372
Configuring a Static IP Address in a Container 373
Configuring Application Hosting on the Management Port 374
Manually Configuring the IP Address for an Application 376
Overriding App Resource Configuration 376
Configuring ERSPAN Support on the AppGigabitEthernet Port 377
Configuring an ERSPAN Source Session 378

Configuring the AppGigabitEthernet Interface for ERSPAN 379

Verifying the Application-Hosting Configuration 381
Configuration Examples for Application Hosting 384
Example: Enabling Cisco IOx 384
Example: Configuring Application Hosting on Front-Panel VLAN Ports 385
Example: Configuring Application Hosting on Front-Panel Trunk Ports 385

Example: Installing an Application from disk0: 385

Example: Starting an Application 386

Example: Lifecycle for an Application 386
Example: Configuring Docker Run Time Options 386
Example: Configuring a Static IP Address in a Container 387
Example: Configuring Application Hosting on the Management Port 387
Example: Overriding App Resource Configuration 387
Example: Configuring ERSPAN Support on the AppGigabitEthernet Port 387
Example: Configuring an ERSPAN Source Session 388
Examples: Configuring ERSPAN Through the AppGigabitEthernet Interface 388
Additional References 388
Feature Information for Application Hosting 389

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xvi
 Contents

CHAPTER 16 ThousandEyes Enterprise Agent 393

Prerequisites for the ThousandEyes Enterprise Agent 393
Information About ThousandEyes Enterprise Agent 394
ThousandEyes Enterprise Agent Overview 394
Resources Required for the ThousandEyes Enterprise Agent 394
ThousandEyes Enterprise Agent Download 395
ThousandEyes BrowserBot 396
ThousandEyes Agent Upgrade and Downgrade 397
How to Install the ThousandEyes Enterprise Agent 397
Configuring AppHosting for the ThousandEyes Enterprise Agent 398
Configuring AppGigabitEthernet Interface for the ThousandEyes Enterprise Agent 400
Installing the ThousandEyes Enterprise Agent 401
Configuration Examples for ThousandEyes Enterprise Agent 402
Example: Installing ThousandEyes Enterprise Agent 402
Sample Configuration for ThousandEyes Enterprise Agent 403
Additional References 406
Feature Information for ThousandEyes Enterprise Agent 406

PART V OpenFlow 409

CHAPTER 17 OpenFlow 411

Prerequisites for OpenFlow 411

Restrictions for OpenFlow 411
Information About OpenFlow 411
OpenFlow Overview 412
OpenFlow Controller 412
Flow Management 412
OpenFlow Pipeline 413
Supported Match Fields and Actions 413
Rewrite Fields 415
OpenFlow Scale Information 415
Flow Operations 416
OpenFlow Table Pipeline 416

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xvii
 Contents

Breakout Port Support 416

OpenFlow Power over Ethernet 416
How to Configure OpenFlow 417
Enabling OpenFlow Mode on a Device 417
Configuring OpenFlow 418
Configuring an Interface in OpenFlow Mode 420
Verifying OpenFlow 421
Configuration Examples for OpenFlow 424
Example: Enabling OpenFlow on a Device 424
Example: Configuring OpenFlow 424
Additional References 424
Feature Information for OpenFlow 425

CHAPTER 18 High Availability in OpenFlow Mode 427

Restrictions for High Availability in OpenFlow Mode 427

Information About OpenFlow 427

High Availability in OpenFlow Mode 427
Stateful Switchover 428
Symmetric High Availability 428
Asymmetric High Availability 428
Probe Interval 429
How to Configure High Availability in OpenFlow Mode 429
Configuring High Availability in OpenFlow Mode 429
Configuration Examples for High Availability in OpenFlow Mode 430
Examples: Configuring High Availability in OpenFlow Mode 430
Feature Information for High Availability in OpenFlow Mode 431

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

xviii
 CHAPTER 1
New and Changed Information
This chapter provides release-specific information about all features.
• New and Changed Information, on page 1

New and Changed Information

This table summarizes the new and changed features, the supported platforms, and links to features.

Table 1: New and Changed Feature Information

Feature Release & Platform

Provisioning

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

1
 New and Changed Information
New and Changed Information

Feature Release & Platform

Zero-Touch Provisioning

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

2
New and Changed Information
New and Changed Information

Feature Release & Platform

Cisco IOS XE Everest 16.5.1a
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.5.1b

• Cisco 4000 Series Integrated Services Routers

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco ASR 1000 Aggregation Services Routers (ASR1001-X,
ASR1001-HX, ASR1002-X, ASR1002-HX)

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches

Cisco IOS XE Fuji 16.8.2

• Cisco ASR 1000 Series Aggregation Services Routers
(ASR1004, ASR1006, ASR1006-X, ASR1009-X, ASR1013)

Cisco IOS XE Gibraltar 16.12.1

• Cisco Catalyst 9200 Series Switches
Note This feature is not supported on C9200L SKUs.

• Cisco Catalyst 9300L SKUs

• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers

Cisco IOS XE Amsterdam 17.2.1

• Cisco Cloud Services Router 1000V Series
• Cisco C1100 Terminal Services Gateway (Supported only on
C1100TGX-1N24P32A)

Cisco IOS XE Amsterdam 17.3.1

• Cisco Catalyst 8200 Series Edge Platforms

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

3
 New and Changed Information
New and Changed Information

Feature Release & Platform

• Cisco Catalyst 8300 Series Edge Platforms

Cisco IOS XE Bengaluru 17.4.1

• Cisco Catalyst 8000V Edge Software

Cisco IOS XE Cupertino 17.8.1

• Cisco Catalyst 9800-L Wireless Controllers

C9800L
Zero Touch Provisioning: HTTP Cisco IOS XE Fuji 16.8.1
Download
• Cisco 4000 Series Integrated Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches

DHCPv6 Support for Zero-Touch Cisco IOS XE Fuji 16.9.1

Provisioning
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Amsterdam 17.3.2a

• Cisco Catalyst 9800-40 Series Wireless Controllers
• Cisco Catalyst 9800-80 Series Wireless Controllers

Zero-Touch Provisioning Through Cisco IOS XE Cupertino 17.7.1

YANG Models
• This feature is supported on all platforms that support
NETCONF-YANG.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

4
New and Changed Information
New and Changed Information

Feature Release & Platform

iPXE Cisco IOS XE Denali 16.3.2 and Cisco IOS XE Everest 16.5.1a
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3650 Series Switches

Cisco IOS XE Everest 16.6.1

• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches

Cisco IOS XE Fuji 16.9.2

• Cisco Catalyst 9200 Series Switches

Cisco IOS XE Gibraltar 16.11.1

• Cisco Catalyst 9600 Series Switches

Shells and Scripting

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

5
 New and Changed Information
New and Changed Information

Feature Release & Platform

Guest Shell Cisco IOS XE Everest 16.5.1a

• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.5.1b

• Cisco 4000 Series Integrated Services Routers

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco ASR 1000 Aggregation Services Routers (ASR1001-X,
ASR1001-HX, ASR1002-X, ASR1002-HX)
• Cisco Cloud Services Router 1000V Series

Cisco IOS XE Fuji 16.8.1

• Cisco Catalyst 9500-High Performance Series Switches

Cisco IOS XE Fuji 16.9.1

• Cisco 1000 Series Integrated Services Routers

Cisco IOS XE Gibraltar 16.11.1b

• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers

Cisco IOS XE Gibraltar 16.12.1

• Cisco Catalyst 9200 Series Switches
Note This feature is not supported on C9200L SKUs.

• Cisco Catalyst 9300L SKUs

• Cisco Catalyst 9600 Series Switches

Cisco IOS XE Amsterdam 17.3.1

• Cisco Catalyst 8200 Series Edge Platforms
• Cisco Catalyst 8300 Series Edge Platforms

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

6
New and Changed Information
New and Changed Information

Feature Release & Platform

Python 3 Support in Guest Shell Cisco IOS XE Amsterdam 17.1.1

• Cisco 1000 Series Integrated Services Routers
• Cisco ASR 1000 Aggregation Services Routers
(ASR1000-RP1, ASR1000-RP2, ASR1000-RP3, ASR1001-X,
ASR1001-HX, ASR1002-X, ASR1002-HX)
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches
• Cisco ISR 4000 Series Integrated Services Routers

NETCONF Access from Guest Shell Cisco IOS XE Bengaluru 17.6.1

• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 and 9300L Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

7
 New and Changed Information
New and Changed Information

Feature Release & Platform

Python APIs Cisco IOS XE Everest 16.5.1a

• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.5.1b

• Cisco 4000 Series Integrated Services Routers

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco ASR 1000 Aggregation Services Routers (ASR1001-X,
ASR1001-HX, ASR1002-X, ASR1002-HX)
• Cisco Cloud Services Router 1000V Series

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

8
New and Changed Information
New and Changed Information

Feature Release & Platform

Python CLI Module Cisco IOS XE Everest 16.5.1a

• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.5.1b

• Cisco 4000 Series Integrated Services Routers

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco ASR 1000 Aggregation Services Routers (ASR1001-X,
ASR1001-HX, ASR1002-X, ASR1002-HX)
• Cisco Cloud Services Router 1000V Series

Cisco IOS XE Fuji 16.8.1

• Cisco 4000 Series Integrated Services Router models with a
minimum of 4 GB RAM.
• Cisco ASR 1000 Series Aggregation Services Routers
(ASR1004, ASR1006, ASR1006-X, ASR1009-X, ASR1013)

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

9
 New and Changed Information
New and Changed Information

Feature Release & Platform

EEM Python Module Cisco IOS XE Everest 16.5.1a

• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.5.1b

• Cisco 4000 Series Integrated Services Routers

Cisco IOS XE Everest 16.6.2.

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco ASR 1000 Aggregation Services Routers (ASR1001-X,
ASR1001-HX, ASR1002-X, ASR1002-HX)
• Cisco Cloud Services Router 1000V Series

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches

Model-Driven Programmability

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

10
New and Changed Information
New and Changed Information

Feature Release & Platform

NETCONF Protocol Cisco IOS XE Denali 16.3.1

• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco 4000 Series Integrated Services Routers

Cisco IOS XE Everest 16.5.1a

• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco ASR 900 Series Aggregation Services Routers
• Cisco Network Convergence System 4200 Series

Cisco IOS XE Fuji 16.9.2

• Cisco Catalyst 9200 Series Switches

Cisco IOS XE Gibraltar 16.10.1

• Cisco Catalyst 9800 Series Wireless Controllers
• Cisco Network Convergence System 520 Series
• Cisco IR1101 Integrated Services Router Rugged

Cisco IOS XE Gibraltar 16.11.1

• Cisco Catalyst IE 3200, 3300, 3400 Rugged Series
• Cisco Embedded Service 3300 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

11
 New and Changed Information
New and Changed Information

Feature Release & Platform

NETCONF and RESTCONF IPv6 Cisco IOS XE Fuji 16.8.1a

Support
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 1000 Series Aggregation Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series

Cisco IOS XE Gibraltar 16.11.1

• Cisco Catalyst 9500-High Performance Series Switches

NETCONF Global Lock and Kill Cisco IOS XE Fuji 16.8.1a

Session
• Cisco 1100 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 1000 Series Aggregation Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000v Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

12
New and Changed Information
New and Changed Information

Feature Release & Platform

NETCONF-YANG SSH Server Support Cisco IOS XE Gibraltar 16.12.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregation Services Routers
• Cisco ASR 1000 Aggregation Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800 Series Wireless Controllers
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Side-Effect Synchronization of the Cisco IOS XE Bengaluru 17.4.1

Configuration Database
• Cisco ASR 1000 Series Aggregated Services Routers
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

13
 New and Changed Information
New and Changed Information

Feature Release & Platform

YANG Model Version 1.1 Cisco IOS XE Cupertino 17.7.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 900 Aggregation Services Routers
• Cisco ASR 920 Aggregation Services Routers
• Cisco ASR 1000 Aggregation Services Routers
• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300 and 9300L Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

14
New and Changed Information
New and Changed Information

Feature Release & Platform

Upgrade YANG Models to YANG 1.1 Cisco IOS XE Dublin 17.10.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 900 Aggregation Services Routers
• Cisco ASR 920 Aggregation Services Routers
• Cisco ASR 1000 Aggregation Services Routers
• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300 and 9300L Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Converting IOS Commands to XML Cisco IOS XE Cupertino 17.7.1

• This feature is supported on all platforms that support
NETCONF-YANG.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

15
 New and Changed Information
New and Changed Information

Feature Release & Platform

RESTCONF Protocol

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

16
New and Changed Information
New and Changed Information

Feature Release & Platform

Cisco IOS XE Everest 16.6.1
• Cisco 4000 Series Integrated Services Router
• Cisco ASR 1000 Aggregation Services Routers
• Cisco Cloud Services Router 1000V Series

Cisco IOS XE Fuji 16.8.1a

• Cisco 1000 Series Integrated Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregation Services Router
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Network Convergence System 4200 Series

Cisco IOS XE Fuji 16.9.2

• Cisco Catalyst 9200 Series Switches

Cisco IOS XE Gibraltar 16.11.1

• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-CL Wireless Controllers
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers
• Cisco Network Convergence System 520 Series

Cisco IOS XE Gibraltar 16.12.1

• Cisco Catalyst 9800-L Wireless Controllers

Cisco IOS XE Amsterdam 17.3.1

• Cisco Catalyst 8200 Series Edge Platforms
• Cisco Catalyst 8300 Series Edge Platforms

Cisco IOS XE Bengaluru 17.4.1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

17
 New and Changed Information
New and Changed Information

Feature Release & Platform

• Cisco Catalyst 8000V Edge Software

RESTCONF YANG-Patch Support Cisco IOS XE Amsterdam 17.1.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 1000 Aggregation Services Routers
(ASR1000-RP2, ASR1000-RP3, ASR1001-HX, ASR1001-X,
ASR1002-HX, ASR1002-X)
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Catalyst IE3200 Rugged Series
• Cisco Catalyst IE3300 Rugged Series
• Cisco Catalyst IE3400 Rugged Series
• Cisco IR1101 Integrated Services Router Rugged
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

18
New and Changed Information
New and Changed Information

Feature Release & Platform

NETCONF and RESTCONF Cisco IOS XE Gibraltar 16.11.1

Service-Level ACLs
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregated Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst IE3200 Rugged Series
• Cisco Catalyst IE3300 Rugged Series
• Cisco Catalyst IE3400 Rugged Series
• Cisco Embedded Services 3300 Series Switches
• Cisco IR1101 Integrated Services Router Rugged
• Cisco Network Convergence System 4200 Series
• Cisco Network Convergence System 520 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

19
 New and Changed Information
New and Changed Information

Feature Release & Platform

gNMI Protocol Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Gibraltar 16.10.1

• Cisco Catalyst 9500-High Performance Series Switches

Cisco IOS XE Gibraltar 16.11.1

• Cisco Catalyst 9600 Series Switches

Cisco IOS XE Gibraltar 16.12.1

• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300L SKUs
• Cisco cBR-8 Converged Broadband Router

Cisco IOS XE Amsterdam 17.1.1

• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregation Services Router
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Cisco IOS XE Amsterdam 17.2.1r

• Cisco ASR 1000 Series Aggregation Services Routers

Cisco IOS XE Cupertino 17.8.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco Catalyst 8000V Edge Software
• Cisco Catalyst 8200 Series Edge Platforms
• Cisco Catalyst 8300 Series Edge Platforms
• Cisco Catalyst 9800-CL Wireless Controllers
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

20
New and Changed Information
New and Changed Information

Feature Release & Platform

gNMI IPv6 support Cisco IOS XE Dublin 17.10.1

• Cisco Catalyst 9200, 9200L Series Switches
• Cisco Catalyst 9300, 9300L, 9300X Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches

gNMI Username and Password Cisco IOS XE Gibraltar 16.12.1

Authentication
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst IE3200 Rugged Series
• Cisco Catalyst IE3200 Rugged Series
• Cisco Catalyst IE3300 Rugged Series
• Cisco Catalyst IE3400 Rugged Series
• Cisco Embedded Service 3300 Series Switches

gRPC Network Operations Interface: Cisco IOS XE Amsterdam 17.3.1

gNOI Certificate Management & gNOI
• Cisco Catalyst 9200 Series Switches
Bootstrapping with Certificate Service
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

gNOI OS Installation Service Cisco IOS XE Bengaluru 17.5.1

• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

21
 New and Changed Information
New and Changed Information

Feature Release & Platform

gNOI Factory Reset Service Cisco IOS XE Cupertino 17.7.1

• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers

Model-Based AAA Cisco IOS XE Fuji 16.8.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 1000 Series Aggregation Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregation Services Routers
• Cisco Cloud Services Router 1000v Series
• Cisco Network Convergence System 4200

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

22
New and Changed Information
New and Changed Information

Feature Release & Platform

Model-Driven Telemetry NETCONF

Dial-In

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

23
 New and Changed Information
New and Changed Information

Feature Release & Platform

Cisco IOS XE Everest 16.6.1
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 1000 Aggregation Services Routers (ASR1001-HX,
ASR1001-X, ASR1002-HX, ASR1002-X

Cisco IOS XE Fuji 16.8.1

• Cisco 1000 Series Integrated Services Routers
• Cisco ASR 1000 RP2 and RP3 Series Aggregation Services
Routers

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches

Cisco IOS XE Fuji 16.9.1

• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregation Services Router
• Cisco cBR-8 Converged Broadband Router
• Cisco Network Convergence System 4200 Series

Cisco IOS XE Fuji 16.9.2

• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300L SKUs

Cisco IOS XE Gibraltar 16.10.1

• Cisco Cloud Services Router 1000v
• Cisco Network Convergence System 520 Series

Cisco IOS XE Gibraltar 16.11.1

• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

24
New and Changed Information
New and Changed Information

Feature Release & Platform

Cisco IOS XE Amsterdam 17.3.1
• Cisco Catalyst 8200 Series Edge Platforms
• Cisco Catalyst 8300 Series Edge Platforms

Cisco IOS XE Bengaluru 17.4.1

• Cisco Catalyst 8000V Edge Software

Model-Driven Telemetry gRPC Cisco IOS XE Gibraltar 16.10.1

Dial-out
• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 1000 Series Aggregation Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregated Services Router
• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300 and 9300L Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Cisco IOS XE Gibraltar 16.11.1

• Cisco Catalyst 9600 Series Switches

Cisco IOS XE Amsterdam 17.3.1

• Cisco Catalyst 8200 Series Edge Platforms
• Cisco Catalyst 8300 Series Edge Platforms

Cisco IOS XE Bengaluru 17.4.1

• Cisco Catalyst 8000V Edge Software

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

25
 New and Changed Information
New and Changed Information

Feature Release & Platform

Model-Driven Telemetry gNMI Dial-In Cisco IOS XE Gibraltar 16.12.1

• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300 and 9300L Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches
• Cisco cBR-8 Converged Broadband Router

Cisco IOS XE Amsterdam 17.1.1

• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregated Services Router
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Cisco IOS XE Amsterdam 17.2.1

• Cisco ASR 1000 Series Aggregation Services Routers

Cisco IOS XE Amsterdam 17.3.1

• Cisco ASR 1000 Series Aggregation Services Routers

Cisco IOS XE Cupertino 17.8.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco Catalyst 8200 Series Edge Platforms
• Cisco Catalyst 8300 Series Edge Platforms

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

26
New and Changed Information
New and Changed Information

Feature Release & Platform

TLS for gRPC Dial-Out Cisco IOS XE Amsterdam 17.1.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 1000 Series Aggregation Services Routers
ASR1000-RP1, ASR1000-RP2, ASR1000-RP3, ASR1001-HX,
ASR1001-X, ASR1002-HX, ASR1002-X)
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Catalyst IE3200 Rugged Series
• Cisco Catalyst IE3300 Rugged Series
• Cisco Catalyst IE3400 Rugged Series
• Cisco IR1101 Integrated Services Router Rugged
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

TLDP On-Change Notifications Cisco IOS XE Amsterdam 17.2.1

• Cisco 4000 Series Integrated Services Routers
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

27
 New and Changed Information
New and Changed Information

Feature Release & Platform

Kill Telemetry Subscription Cisco IOS XE Gibraltar 16.11.1

• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregated Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco IR1101 Integrated Services Router Rugged
• Cisco Network Convergence System 4200 Series
• Cisco Network Convergence System 520 Series

Cisco IOS XE Gibraltar 16.11.1a

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 1000 Series Aggregation Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregation Services Routers
• Cisco Cloud Services Router 1000V Series

FQDN Support for gRPC Subscriptions Cisco IOS XE Bengaluru 17.6.1

• Cisco ASR 900 Series Aggregation Services Routers (RSP2)
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers

Leaf-Level Filtering Cisco IOS XE Cupertino 17.7.1

• Cisco Catalyst 9300 and 9300L Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

28
New and Changed Information
New and Changed Information

Feature Release & Platform

Mutual Authentication for gRPC Cisco IOS XE Cupertino 17.9.1

Telemetry
• Cisco Catalyst 9800-CL Series Wireless Controller
• Cisco Catalyst 9800-40 Series Wireless Controller
• Cisco Catalyst 9800-80 Series Wireless Controller

Pubd Restartability Cisco IOS XE Cupertino 17.9.1

• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 1000 Series Aggregation Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregated Services Router
• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300 and 9300L Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-CL Series Wireless Controller
• Cisco Catalyst 9800-40 Series Wireless Controller
• Cisco Catalyst 9800-80 Series Wireless Controller
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

29
 New and Changed Information
New and Changed Information

Feature Release & Platform

In-Service Model Updates Cisco IOS XE Everest 16.5.1a

• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.5.1b

• Cisco 4000 Series Integrated Services Routers

Cisco IOS XE Everest 16.6.1

• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches

Cisco IOS XE Everest 16.6.2

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Fuji 16.7.1

• Cisco ASR 1000 Aggregation Services Routers

Cisco IOS XE Fuji 16.8.1a

• Cisco Catalyst 9500-High Performance Series Switches.

Application Hosting

Application Hosting Cisco IOS XE Gibraltar 16.12.1

• Cisco Catalyst 9300 Series Switches

Cisco IOS XE Amsterdam 17.1.1

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Amsterdam 17.2.1

• Cisco Catalyst 9500-High Performance Series Switches
• Cisco Catalyst 9600 Series Switches

Cisco IOS XE Bengaluru 17.5.1

• Cisco Catalyst 9410 Series Switches

Cisco IOS XE Cupertino 17.7.1

• Cisco Catalyst 9500-X Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

30
New and Changed Information
New and Changed Information

Feature Release & Platform

Application Hosting: Front-Panel Cisco IOS XE Gibraltar 16.12.1

Network Port Access
• Cisco Catalyst 9300 Series Switches

Cisco IOS XE Amsterdam 17.1.1

• Cisco Catalyst 9400 Series Switches
Note Cisco Catalyst 9410R Switch does not support
front-panel application-hosting.

Application Hosting: Front-Panel USB Cisco IOS XE Gibraltar 16.12.1

Port Access
• Cisco Catalyst 9300 Series Switches

Cisco IOS XE Amsterdam 17.1.1

• Cisco Catalyst 9400 Series Switches
Note Cisco Catalyst 9410R Switch does not support
front-panel application-hosting.

Native Docker Container: Application Cisco IOS XE Amsterdam 17.2.1

Auto-Restart
• Cisco Catalyst 9300 Series Switches

Cisco IOS XE Bengaluru 17.5.1

• Cisco Catalyst 9410 Series Switches

Application Hosting: ERSPAN Support Cisco IOS XE Dublin 17.10.1

on the AppGigabitEthernet Port
• Cisco Catalyst 9300, 9300L, 9300X Series Switches
• Cisco Catalyst 9400 Series Switches

Application Hosting: ThousandEyes Cisco IOS XE Amsterdam 17.3.3

Integration
• Cisco Catalyst 9300 and 9300L Series Switches

Cisco IOS XE Bengaluru 17.5.1

• Cisco Catalyst 9400 Series Switches

Cisco IOS XE Bengaluru 17.6.1

• Cisco Catalyst 9300X Series Switches

ThousandEyes BrowserBot Cisco IOS XE Bengaluru 17.6.1

• Cisco Catalyst 9300, 9300L, and 9300X Series Switches
• Cisco Catalyst 9400 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

31
 New and Changed Information
New and Changed Information

Feature Release & Platform

OpenFlow
OpenFlow Cisco IOS XE Fuji 16.9.1
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches and Cisco Catalyst
9500-High Performance Series Switches

OpenFlow Power over Ethernet Cisco IOS XE Gibraltar 16.12.1

• Catalyst 9300 Series Switches
• Catalyst 9400 Series Switches

OpenFlow Rewrite Fields Cisco IOS XE Bengaluru 17.4.1

• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches and Cisco Catalyst
9500-High Performance Series Switches

High Availability in OpenFlow Mode Cisco IOS XE Bengaluru 17.5.1

• Cisco Catalyst 9400 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

32
PA R T I
Provisioning
• Zero-Touch Provisioning, on page 35
• iPXE, on page 71
 CHAPTER 2
Zero-Touch Provisioning
To address network provisioning challenges, Cisco introduces a zero-touch provisioning model. This module
describes the Zero-Touch Provisioning feature.

Note The Zero-Touch Provisioning feature is enabled automatically; no configuration is required.

• Restrictions for Zero-Touch Provisioning, on page 35

• Information About Zero-Touch Provisioning, on page 35
• Sample Zero-Touch Provisioning Configurations, on page 37
• Feature Information for Zero-Touch Provisioning, on page 65

Restrictions for Zero-Touch Provisioning

• Zero-Touch Provisioning is not supported on Cisco Catalyst 9200L SKUs.
• On Cisco Catalyst 9800-L Wireless Controller, if both the service port as well as one of the data ports
are enabled and connected, then AutoInstall will reach out to the service port by default.
• The Cisco Catalyst 9800-L Wireless Controller does not support virtual port group (VPG) and network
address translation (NAT). Hence, applications or scripts cannot communicate from the Guest Shell to
the network through data ports. On the Cisco Catalyst 9800-L Wireless Controller, the ZTP scripts
downloaded through the data port or the service port will not be able to communicate externally.

Information About Zero-Touch Provisioning

Zero-Touch Provisioning Overview
Zero-Touch Provisioning provides open bootstrap interfaces to automate network device provisioning in
heterogeneous network environments.
When a device that supports Zero-Touch Provisioning boots up, and does not find the startup configuration
(during initial installation), the device enters the Zero-Touch Provisioning mode. The device searches for a
Dynamic Host Control Protocol (DHCP) server, bootstraps itself with its interface IP address, gateway, and

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

35
 Provisioning
DHCP Server Configuration for Zero-Touch Provisioning

Domain Name System (DNS) server IP address, and enables Guest Shell. The device then obtains the IP
address or URL of an HTTP/TFTP server, and downloads the Python script from an HTTP/TFTP server to
configure the device.
Guest Shell provides the environment for the Python script to run. Guest Shell executes the downloaded
Python script and applies an initial configuration to the device.
After initial provisioning is complete, Guest Shell remains enabled. For more information, see the Guest Shell
chapter.

Note In case Zero-Touch Provisioning fails, the device falls back to AutoInstall to load configuration files.
For more information, see Using AutoInstall and Setup.

DHCP Server Configuration for Zero-Touch Provisioning

In Zero-Touch Provisioning, a DHCP server must be running on the same network as the new device that is
being provisioned. Zero-Touch Provisioning is supported on both management ports and in-band ports.
When the new device is switched on, it retrieves the IP address information of the HTTP/TFTP server where
the Python script resides, and the folder path of the Python script from the DHCP server. For more information
on Python Scripts, see the Python API and Python CLI Module chapters.
The DHCP server responds to DHCP discovery events with the following options:
• Option 150—(Optional) Contains a list of IP addresses that points to the HTTP/TFTP server on the
management network that hosts the Python scripts to be run.
• Option 67—Contains the Python script file path on the HTTP/TFTP server.

After receiving these DHCP options, the device connects to the HTTP/TFTP server, and downloads the Python
script. The device, at this point does not have any route to reach the HTTP/TFTP server, so it uses the default
route provided by the DHCP server.

DHCPv6 Support
In Cisco IOS XE Fuji 16.9.1, Dynamic Host Control Protocol Version 6 (DHCPv6) support is added to the
Zero-touch provisioning feature. DHCPv6 is enabled by default, and will work on any device that boots
without a startup configuration.

Note DHCPv6 is only supported on Catalyst 9300 and 9500 Series Switches.

DHCPv6 is supported by both TFTP and HTTP download of Python scripts. If the HTTP or TFTP download
of Python scripts fail, the device will revert to the start (without any configuration). For both DHCPv4, and
DHCPv6 to work, the correct HTTP file path must be available in the DHCP configuration.
There can be scenarios where the same interface can have both IPv4 and IPv6 addresses, or two different
interfaces in the network - one can receive IPv4 traffic and the other IPv6 traffic. We recommend that you
use either the DHCPv4 or DHCPv6 option in your deployment.
The following is a sample DHCPv4: /etc/dhcp/dhcpd.conf:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

36
 Provisioning
Sample Zero-Touch Provisioning Configurations

host <hostname> {
hardware ethernet xx:xx:xx:xx:xx:xx;
option dhcp-client-identifier "xxxxxxxxxxxxxx";
option host-name "<hostname>".
option log-servers x.x.x.x;
fixed-address x.x.x.x;
if option vendor-class-identifier = "..." {
option vendor-class-identifier "...";
if exists user-class and option user-class = "iPXE" {
filename "http://x.x.x.x/…/<image>";
} else {
filename "http://x.x.x.x/…/<script-name>";
}
}
}

The following is a sample ISC DHCPv6 server configuration:

option dhcp6.bootfile-url "http://[2001:DB8::21]/sample_day0_script.py";

Sample Zero-Touch Provisioning Configurations

Sample DHCP Server Configuration on a Management Port Using TFTP Copy
The following is a sample DHCP server configuration using TFTP copy, when connected via the management
port on a device:

Device> enable
Device# configure terminal
Device(config)# ip dhcp excluded-address 10.1.1.1
Device(config)# ip dhcp excluded-address vrf Mgmt-vrf 10.1.1.1 10.1.1.10
Device(config)# ip dhcp pool pnp_device_pool
Device(config-dhcp)# vrf Mgmt-vrf
Device(config-dhcp)# network 10.1.1.0 255.255.255.0
Device(config-dhcp)# default-router 10.1.1.1
Device(config-dhcp)# option 150 ip 203.0.113.254
Device(config-dhcp)# option 67 ascii /sample_python_dir/python_script.py
Device(config-dhcp)# exit
Device(config)# interface gigabitethernet 1/0/2
Device(config-if)# no ip dhcp client request tftp-server-address
Device(config-if)# end

Sample DHCP Server Configuration on a Management Port Using HTTP Copy

The following is a sample DHCP server configuration using HTTP copy, when connected via the
management port on a device:

Device> enable
Device# configure terminal
Device(config)# ip dhcp pool pnp_device_pool
Device(config-dhcp)# vrf Mgmt-vrf
Device(config-dhcp)# network 10.1.1.0 255.255.255.0

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

37
 Provisioning
Sample DHCP Server Configuration on an In-Band Port Using TFTP Copy

Device(config-dhcp)# default-router 10.1.1.1

Device(config-dhcp)# option 67 ascii http://198.51.100.1:8000/sample_python_2.py
Device(config-dhcp)# end

Sample DHCP Server Configuration on an In-Band Port Using TFTP Copy

The following is a sample DHCP server configuration using TFTP copy, when connected via the in-band port
on a device:

Device> enable
Device# configure terminal
Device(config)# ip dhcp excluded-address 10.1.1.1
Device(config)# ip dhcp pool pnp_device_pool
Device(config-dhcp)# network 10.1.1.0 255.255.255.0
Device(config-dhcp)# default-router 10.1.1.1
Device(config-dhcp)# option 150 ip 203.0.113.254
Device(config-dhcp)# option 67 ascii /sample_python_dir/python_script.py
Device(config-dhcp)# exit
Device(config)# interface gigabitethernet 1/0/2
Device(config-if)# no ip dhcp client request tftp-server-address
Device(config-if)# end

Sample DHCP Server Configuration on an In-Band Port Using HTTP Copy

The following is a sample DHCP server configuration using HTTP copy, when connected via the
in-band port on a device:

Device> enable
Device# configure terminal
Device(config)# ip dhcp excluded-address 10.1.1.1
Device(config)# ip dhcp pool pnp_device_pool
Device(config-dhcp)# network 10.1.1.0 255.255.255.0
Device(config-dhcp)# default-router 10.1.1.1
Device(config-dhcp)# option 67 ascii http://192.0.2.1:8000/sample_python_2.py
Device(config-dhcp)# end

Sample DHCP Server Configuration on a Linux Ubuntu Device

The following sample DHCP server configuration displays that the server is either connected to the management
port or in-band port on a device, and a Python script is copied from a TFTP server.

root@ubuntu-server:/etc/dhcp# more dhcpd.conf

subnet 10.1.1.0 netmask 255.255.255.0 {
range 10.1.1.2 10.1.1.255;
host 3850 {
fixed-address 10.1.1.246 ;
hardware ethernet CC:D8:C1:85:6F:00;
option bootfile-name !<opt 67> " /python_dir/python_script.py";
option tftp-server-name !<opt 150> "203.0.113.254";

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

38
 Provisioning
Sample DHCPv6 Server Configuration on a Management Port Using TFTP Copy

}
}

The following sample DHCP configuration shows that a Python script is copied from an HTTP server to the
device:

Day0_with_mgmt_port_http
-------------------------
subnet 192.168.1.0 netmask 255.255.255.0 {
range 192.168.1.2 192.168.1.255;
host C2-3850 {
fixed-address 192.168.1.246 ;
hardware ethernet CC:D8:C1:85:6F:00;
option bootfile-name "http://192.168.1.46/sample_python_2.py";
}
}

Once the DHCP server is running, boot a management-network connected device, and the rest of the
configuration is automatic.

Sample DHCPv6 Server Configuration on a Management Port Using TFTP Copy

The following is a sample DHCPv6 server configuration using TFTP copy, when connected via the
management port on a device:

Device> enable
Device# configure terminal
Device(config)# ipv6 dhcp pool ztp
Device(config-dhcpv6)# address prefix 2001:DB8::1/64
Device(config-dhcpv6)# domain-name cisco.com
Device(config-dhcpv6)# bootfile-url tftp://[2001:db8::46]/sample_day0_script.py
Device(config-dhcpv6)# exit
Device(config)# interface vlan 20
Device(config-if)# ipv6 dhcp server ztp
Device(config-if)# end

Sample Python Provisioning Script

The following is a sample Python script can be used from either an HTTP or a TFTP server:

print "\n\n *** Sample ZTP Day0 Python Script *** \n\n"

# Importing cli module

import cli

print "\n\n *** Executing show platform *** \n\n"

cli_command = "show platform"
cli.executep(cli_command)

print "\n\n *** Executing show version *** \n\n"

cli_command = "show version"

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

39
 Provisioning
Boot Log for Cisco 4000 Series Integrated Services Routers

cli.executep(cli_command)

print "\n\n *** Configuring a Loopback Interface *** \n\n"

cli.configurep(["interface loop 100", "ip address 10.10.10.10 255.255.255.255", "end"])

print "\n\n *** Executing show ip interface brief *** \n\n"

cli_command = "sh ip int brief"
cli.executep(cli_command)

print "\n\n *** ZTP Day0 Python Script Execution Complete *** \n\n"

Boot Log for Cisco 4000 Series Integrated Services Routers

The following sample Zero-Touch Provisioning boot log displays that Guest Shell is successfully enabled,
the Python script is downloaded to the Guest Shell, and the Guest Shell executes the downloaded Python
script and configures the device for Day Zero.

% failed to initialize nvram

! <This message indicates that the startup configuration
is absent on the device. This is the first indication that the Day Zero work flow is
going to start.>

This product contains cryptographic features and is subject to United

States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.

A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html

If you require further assistance please contact us by sending email to

[email protected].

cisco ISR4451-X/K9 (2RU) processor with 7941237K/6147K bytes of memory.

Processor board ID FJC1950D091
4 Gigabit Ethernet interfaces
32768K bytes of non-volatile configuration memory.
16777216K bytes of physical memory.
7341807K bytes of flash memory at bootflash:.
0K bytes of WebUI ODM Files at webui:.

%INIT: waited 0 seconds for NVRAM to be available

--- System Configuration Dialog ---

Would you like to enter the initial configuration dialog? [yes/no]: %

!!<DO NOT TOUCH. This is Zero-Touch Provisioning>>
Generating 2048 bit RSA keys, keys will be non-exportable...
[OK] (elapsed time was 1 seconds)
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

40
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

The process for the command is not responding or is otherwise unavailable

The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
Guestshell enabled successfully

*** Sample ZTP Day0 Python Script ***

*** Configuring a Loopback Interface ***

Line 1 SUCCESS: interface loop 100

Line 2 SUCCESS: ip address 10.10.10.10 255.255.255.255
Line 3 SUCCESS: end

*** Executing show ip interface brief ***

Interface IP-Address OK? Method Status Protocol

GigabitEthernet0/0/0 unassigned YES unset down down
GigabitEthernet0/0/1 unassigned YES unset down down
GigabitEthernet0/0/2 unassigned YES unset down down
GigabitEthernet0/0/3 192.168.1.246 YES DHCP up up
GigabitEthernet0 192.168.1.246 YES DHCP up up
Loopback100 10.10.10.10 YES TFTP up up

*** ZTP Day0 Python Script Execution Complete ***

Press RETURN to get started!

The Day Zero provisioning is complete, and the IOS prompt is accessible.

Boot Log for Cisco Catalyst 9000 Series Switches

The following sections displays sample Zero-Touch Provisioning boot logs. These logs shows that Guest
Shell is successfully enabled, the Python script is downloaded to the Guest Shell, and the Guest Shell executes
the downloaded Python script and configures the device for Day Zero.

% Checking backup nvram

% No config present. Using default config

FIPS: Flash Key Check : Begin

FIPS: Flash Key Check : End, Not Found, FIPS Mode Not Enabled

! <This message indicates that the startup configuration

is absent on the device. This is the first indication that the Day Zero
work flow is

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

41
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

going to start.>

Cisco IOS XE Everest 16.6.x to Cisco IOS XE Fuji 16.8.x

This section displays the sample boot logs before the .py script is run:

Press RETURN to get started!

The process for the command is not responding or is otherwise unavailable

The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable

*** Sample ZTP Day0 Python Script ***

...

*** ZTP Day0 Python Script Execution Complete ***

The section shows how to configure the device for Day Zero provisioning:
Initializing Hardware...

System Bootstrap, Version 17.2.1r[FC1], RELEASE SOFTWARE (P)

Compiled Thu 02/20/2020 23:47:51.50 by rel

Current ROMMON image : Primary

Last reset cause : SoftwareReload
C9300-48UXM platform with 8388608 Kbytes of main memory

Preparing to autoboot. [Press Ctrl-C to interrupt] 0

boot: attempting to boot from [flash:cat9k_iosxe.16.06.05.SPA.bin]
boot: reading file cat9k_iosxe.16.06.05.SPA.bin
##################################################################################################

Both links down, not waiting for other switches

Switch number is 1

Restricted Rights Legend

Use, duplication, or disclosure by the Government is

subject to restrictions as set forth in subparagraph
(c) of the Commercial Computer Software - Restricted
Rights clause at FAR sec. 52.227-19 and subparagraph
(c) (1) (ii) of the Rights in Technical Data and Computer
Software clause at DFARS sec. 252.227-7013.

cisco Systems, Inc.

170 West Tasman Drive
San Jose, California 95134-1706

Cisco IOS Software [Everest], Catalyst L3 Switch Software (CAT9K_IOSXE),

Version 16.6.5, RELEASE SOFTWARE (fc3)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2018 by Cisco Systems, Inc.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

42
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Compiled Mon 10-Dec-18 12:52 by mcpre

Cisco IOS-XE software, Copyright (c) 2005-2018 by cisco Systems, Inc.

All rights reserved. Certain components of Cisco IOS-XE software are
licensed under the GNU General Public License ("GPL") Version 2.0. The
software code licensed under GPL Version 2.0 is free software that comes
with ABSOLUTELY NO WARRANTY. You can redistribute and/or modify such
GPL code under the terms of GPL Version 2.0. For more details, see the
documentation or "License Notice" file accompanying the IOS-XE software,
or the applicable URL provided on the flyer accompanying the IOS-XE
software.

% Checking backup nvram

% No config present. Using default config

FIPS: Flash Key Check : Begin

FIPS: Flash Key Check : End, Not Found, FIPS Mode Not Enabled

This product contains cryptographic features and is subject to United

States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.

A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html

If you require further assistance please contact us by sending email to

[email protected].

cisco C9300-48UXM (X86) processor with 1392780K/6147K bytes of memory.

Processor board ID FCW2144L045
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.
0K bytes of WebUI ODM Files at webui:.

Base Ethernet MAC Address : ec:1d:8b:0a:68:00

Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0
Model Number : C9300-48UXM
System Serial Number : FCW2144L045

%INIT: waited 0 seconds for NVRAM to be available

SETUP: new interface Vlan1 placed in "shutdown" state

Press RETURN to get started!

*Sep 4 20:35:07.330: %SMART_LIC-6-AGENT_READY: Smart Agent for Licensing is initialized

*Sep 4 20:35:07.493: %IOSXE_RP_NV-3-NV_ACCESS_FAIL: Initial read of NVRAM contents failed

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

43
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

*Sep 4 20:35:07.551: %IOSXE_RP_NV-3-BACKUP_NV_ACCESS_FAIL: Initial read of backup NVRAM

contents failed
*Sep 4 20:35:10.932: dev_pluggable_optics_selftest attribute table internally inconsistent
@ 0x1D4

*Sep 4 20:35:13.406: %CRYPTO-4-AUDITWARN: Encryption audit check could not be performed

*Sep 4 20:35:13.480: %SPANTREE-5-EXTENDED_SYSID: Extended SysId enabled for type vlan
*Sep 4 20:35:13.715: %LINK-3-UPDOWN: Interface Lsmpi18/3, changed state to up
*Sep 4 20:35:13.724: %LINK-3-UPDOWN: Interface EOBC18/1, changed state to up
*Sep 4 20:35:13.724: %LINEPROTO-5-UPDOWN: Line protocol on Interface LI-Null0, changed
state to up
*Sep 4 20:35:13.724: %LINK-3-UPDOWN: Interface GigabitEthernet0/0, changed state to down
*Sep 4 20:35:13.725: %LINK-3-UPDOWN: Interface LIIN18/2, changed state to up
*Sep 4 20:35:13.749: WCM-PKI-SHIM: buffer allocation failed for SUDI support check
*Sep 4 20:35:13.749: PKI/SSL unable to send Sudi support to WCM
*Sep 4 20:35:14.622: %IOSXE_MGMTVRF-6-CREATE_SUCCESS_INFO: Management vrf Mgmt-vrf created
with ID 1,
ipv4 table-id 0x1, ipv6 table-id 0x1E000001
*Sep 4 20:34:42.022: %STACKMGR-6-STACK_LINK_CHANGE: Switch 1 R0/0: stack_mgr: Stack port
1 on Switch 1 is nocable
*Sep 4 20:34:42.022: %STACKMGR-6-STACK_LINK_CHANGE: Switch 1 R0/0: stack_mgr: Stack port
2 on Switch 1 is down
*Sep 4 20:34:42.022: %STACKMGR-6-STACK_LINK_CHANGE: Switch 1 R0/0: stack_mgr: Stack port
2 on Switch 1 is nocable
*Sep 4 20:34:42.022: %STACKMGR-6-SWITCH_ADDED: Switch 1 R0/0: stack_mgr: Switch 1 has
been added to the stack.
*Sep 4 20:34:42.022: %STACKMGR-6-SWITCH_ADDED: Switch 1 R0/0: stack_mgr: Switch 1 has
been added to the stack.
*Sep 4 20:34:42.022: %STACKMGR-6-SWITCH_ADDED: Switch 1 R0/0: stack_mgr: Switch 1 has
been added to the stack.
*Sep 4 20:34:42.022: %STACKMGR-6-ACTIVE_ELECTED: Switch 1 R0/0: stack_mgr: Switch 1 has
been elected ACTIVE.
*Sep 4 20:35:14.728: %LINEPROTO-5-UPDOWN: Line protocol on Interface Lsmpi18/3, changed
state to up
*Sep 4 20:35:14.728: %LINEPROTO-5-UPDOWN: Line protocol on Interface EOBC18/1, changed
state to up
*Sep 4 20:35:15.506: %HMANRP-6-HMAN_IOS_CHANNEL_INFO: HMAN-IOS channel event for switch
1: EMP_RELAY: Channel UP!
*Sep 4 20:35:15.510: %LINEPROTO-5-UPDOWN: Line protocol on Interface Vlan1, changed state
to down
*Sep 4 20:35:34.501: %LINK-5-CHANGED: Interface Vlan1, changed state to administratively
down
*Sep 4 20:35:34.717: %SYS-5-RESTART: System restarted --
Cisco IOS Software [Everest], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 16.6.5,
RELEASE SOFTWARE (fc3)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2018 by Cisco Systems, Inc.
Compiled Mon 10-Dec-18 12:52 by mcpre
*Sep 4 20:35:34.796: %LINK-3-UPDOWN: Interface GigabitEthernet0/0, changed state to up
*Sep 4 20:35:35.266: %SYS-6-BOOTTIME: Time taken to reboot after reload = 283 seconds
*Sep 4 20:35:35.796: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet0/0,
changed state to up
*Sep 4 20:35:36.607: %LINK-3-UPDOWN: Interface GigabitEthernet1/1/1, changed state to down
*Sep 4 20:35:36.607: %LINK-3-UPDOWN: Interface GigabitEthernet1/1/2, changed state to down
*Sep 4 20:35:36.607: %LINK-3-UPDOWN: Interface GigabitEthernet1/1/3, changed state to down
*Sep 4 20:35:36.608: %LINK-3-UPDOWN: Interface GigabitEthernet1/1/4, changed state to down
*Sep 4 20:35:36.608: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/1, changed state to
down
*Sep 4 20:35:36.608: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/2, changed state to
down
*Sep 4 20:35:36.608: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/3, changed state to
down
*Sep 4 20:35:36.608: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/4, changed state to
down

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

44
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

*Sep 4 20:35:36.608: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/5, changed state to

down
*Sep 4 20:35:36.609: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/6, changed state to
down
*Sep 4 20:35:36.609: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/7, changed state to
down
*Sep 4 20:35:36.609: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/1/8, changed state to
down
*Sep 4 20:35:36.609: %LINK-3-UPDOWN: Interface FortyGigabitEthernet1/1/1, changed state
to down
*Sep 4 20:35:36.609: %LINK-3-UPDOWN: Interface FortyGigabitEthernet1/1/2, changed state
to down
*Sep 4 20:35:37.607: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet1/1/1,
changed state to down
*Sep 4 20:35:37.608: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet1/1/2,
changed state to down
*Sep 4 20:35:37.608: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet1/1/3,
changed state to down
*Sep 4 20:35:37.609: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet1/1/4,
changed state to down
*Sep 4 20:35:37.609: %LINEPROTO-5-UPDOWN: Line protocol on Interface TenGigabitEthernet1/1/1,
changed state to down
*Sep 4 20:35:37.609: %LINEPROTO-5-UPDOWN: Line protocol on Interface TenGigabitEthernet1/1/2,
changed state to down
*Sep 4 20:35:37.609: %LINEPROTO-5-UPDOWN: Line protocol on Interface TenGigabitEthernet1/1/3,
changed state to down
*Sep 4 20:35:37.609: %LINEPROTO-5-UPDOWN: Line protocol on Interface TenGigabitEthernet1/1/4,
changed state to down
*Sep 4 20:35:37.609: %LINEPROTO-5-UPDOWN: Line protocol on Interface TenGigabitEthernet1/1/5,
changed state to down
*Sep 4 20:35:37.609: %LINEPROTO-5-UPDOWN: Line protocol on Interface TenGigabitEthernet1/1/6,
changed state to down
*Sep 4 20:35:43.511: AUTOINSTALL: Obtain tftp server address (opt 150) 159.14.27.2
*Sep 4 20:35:43.511: PNPA: Setting autoinstall complete to true for 159.14.27.2
*Sep 4 20:35:57.673: %PLATFORM_PM-6-FRULINK_INSERTED: 8x10G uplink module inserted in the
switch 1 slot 1
*Sep 4 20:36:19.562: [IOX DEBUG] Guestshell start API is being invoked

*Sep 4 20:36:19.562: [IOX DEBUG] provided idb is mgmt interface

*Sep 4 20:36:19.562: [IOX DEBUG] Setting up guestshell to use mgmt-intf

*Sep 4 20:36:19.562: [IOX DEBUG] Setting up chasfs for iox related activity

*Sep 4 20:36:19.562: [IOX DEBUG] Setting up for iox pre-clean activity if needed

*Sep 4 20:36:19.562: [IOX DEBUG] Waiting for iox pre-clean setup to take affect

*Sep 4 20:36:19.562: [IOX DEBUG] Waited for 1 sec(s) for iox pre-clean setup to take affect

*Sep 4 20:36:19.562: [IOX DEBUG] Auto-configuring iox feature

*Sep 4 20:36:19.563: [IOX DEBUG] Waiting for CAF and ioxman to be up, in that order

*Sep 4 20:36:20.076: %UICFGEXP-6-SERVER_NOTIFIED_START: Switch 1 R0/0: psd: Server iox

has been notified to start
*Sep 4 20:36:23.564: [IOX DEBUG] Waiting for another 5 secs

*Sep 4 20:36:28.564: [IOX DEBUG] Waiting for another 5 secs

The process for the command is not responding or is otherwise unavailable

*Sep 4 20:36:33.564: [IOX DEBUG] Waiting for another 5 secs

The process for the command is not responding or is otherwise unavailable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

45
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

*Sep 4 20:36:34.564: [IOX DEBUG] Waited for 16 sec(s) for CAF and ioxman to come up

*Sep 4 20:36:34.564: [IOX DEBUG] Validating if CAF and ioxman are running

*Sep 4 20:36:34.564: [IOX DEBUG] CAF and ioxman are up and running

*Sep 4 20:36:34.564: [IOX DEBUG] Building the simple mgmt-intf enable command string

*Sep 4 20:36:34.564: [IOX DEBUG] Enable command is: request platform software iox-manager

app-hosting guestshell enable

*Sep 4 20:36:34.564: [IOX DEBUG] Issuing guestshell enable command and waiting for it to
be up
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable

*Sep 4 20:36:38.578: [IOX DEBUG] Waiting for another 5 secs

The process for the command is not responding or is otherwise unavailable

*Sep 4 20:36:39.416: %LINK-3-UPDOWN: Interface TenGigabitEthernet1/0/48, changed state to

up
*Sep 4 20:36:40.416: %LINEPROTO-5-UPDOWN: Line protocol on Interface
TenGigabitEthernet1/0/48,
changed state to upThe process for the command is not responding or is otherwise
unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable

*Sep 4 20:36:43.586: [IOX DEBUG] Waiting for another 5 secs

Guestshell enabled successfully

*Sep 4 20:37:45.321: [IOX DEBUG] Checking for guestshell mount path

*Sep 4 20:37:45.321: [IOX DEBUG] Validating if guestshell is ready for use

*Sep 4 20:37:45.321: [IOX DEBUG] Guestshell enabled successfully

*** Sample ZTP Day0 Python Script ***

*** Executing show platform ***

Switch Ports Model Serial No. MAC address Hw Ver. Sw Ver.

------ ----- --------- ----------- -------------- ------- --------
1 62 C9300-48UXM FCW2144L045 ec1d.8b0a.6800 V01 16.6.5

Switch/Stack Mac Address : ec1d.8b0a.6800 - Local Mac Address

Mac persistency wait time: Indefinite
Current
Switch# Role Priority State
-------------------------------------------
*1 Active 1 Ready

*** Executing show version ***

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

46
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Cisco IOS XE Software, Version 16.06.05

Cisco IOS Software [Everest], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 16.6.5,
RELEASE SOFTWARE (fc3)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2018 by Cisco Systems, Inc.
Compiled Mon 10-Dec-18 12:52 by mcpre
Cisco IOS-XE software, Copyright (c) 2005-2018 by cisco Systems, Inc.
All rights reserved. Certain components of Cisco IOS-XE software are
licensed under the GNU General Public License ("GPL") Version 2.0. The
software code licensed under GPL Version 2.0 is free software that comes
with ABSOLUTELY NO WARRANTY. You can redistribute and/or modify such
GPL code under the terms of GPL Version 2.0. For more details, see the
documentation or "License Notice" file accompanying the IOS-XE software,
or the applicable URL provided on the flyer accompanying the IOS-XE
software.
ROM: IOS-XE ROMMON
BOOTLDR: System Bootstrap, Version 17.2.1r[FC1], RELEASE SOFTWARE (P)
Switch uptime is 2 minutes
Uptime for this control processor is 4 minutes
System returned to ROM by Reload Command
System image file is "flash:cat9k_iosxe.16.06.05.SPA.bin"
Last reload reason: Reload Command
This product contains cryptographic features and is subject to United
States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.
A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html
If you require further assistance please contact us by sending email to
[email protected].
Technology Package License Information:
-----------------------------------------------------------------
Technology-package Technology-package
Current Type Next reboot
------------------------------------------------------------------
network-advantage Permanent network-advantage
cisco C9300-48UXM (X86) processor with 1392780K/6147K bytes of memory.
Processor board ID FCW2144L045
36 Ethernet interfaces
1 Virtual Ethernet interface
4 Gigabit Ethernet interfaces
20 Ten Gigabit Ethernet interfaces
2 Forty Gigabit Ethernet interfaces
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.
0K bytes of WebUI ODM Files at webui:.
Base Ethernet MAC Address : ec:1d:8b:0a:68:00
Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0
Model Number : C9300-48UXM
System Serial Number : FCW2144L045
Switch Ports Model SW Version SW Image Mode
------ ----- ----- ---------- ---------- ----
* 1 62 C9300-48UXM 16.6.5 CAT9K_IOSXE BUNDLE
Configuration register is 0x102

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

47
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

*** Configuring a Loopback Interface ***

Line 1 SUCCESS: interface loop 100

Line 2 SUCCESS: ip address 10.10.10.10 255.255.255.255
Line 3 SUCCESS: end

*** Executing show ip interface brief ***

Interface IP-Address OK? Method Status Protocol

Vlan1 unassigned YES unset administratively down down
GigabitEthernet0/0 10.127.128.3 YES DHCP up up
Tw1/0/1 unassigned YES unset down down
Tw1/0/2 unassigned YES unset down down
Tw1/0/3 unassigned YES unset down down
Tw1/0/4 unassigned YES unset down down
Tw1/0/5 unassigned YES unset down down
Tw1/0/6 unassigned YES unset down down
Tw1/0/7 unassigned YES unset down down
Tw1/0/8 unassigned YES unset down down
Tw1/0/9 unassigned YES unset down down
Tw1/0/10 unassigned YES unset down down
Tw1/0/11 unassigned YES unset down down
Tw1/0/12 unassigned YES unset down down
Tw1/0/13 unassigned YES unset down down
Tw1/0/14 unassigned YES unset down down
Tw1/0/15 unassigned YES unset down down
Tw1/0/16 unassigned YES unset down down
Tw1/0/17 unassigned YES unset down down
Tw1/0/18 unassigned YES unset down down
Tw1/0/19 unassigned YES unset down down
Tw1/0/20 unassigned YES unset down down
Tw1/0/21 unassigned YES unset down down
Tw1/0/22 unassigned YES unset down down
Tw1/0/23 unassigned YES unset down down
Tw1/0/24 unassigned YES unset down down
Tw1/0/25 unassigned YES unset down down
Tw1/0/26 unassigned YES unset down down
Tw1/0/27 unassigned YES unset down down
Tw1/0/28 unassigned YES unset down down
Tw1/0/29 unassigned YES unset down down
Tw1/0/30 unassigned YES unset down down
Tw1/0/31 unassigned YES unset down down
Tw1/0/32 unassigned YES unset down down
Tw1/0/33 unassigned YES unset down down
Tw1/0/34 unassigned YES unset down down
Tw1/0/35 unassigned YES unset down down
Tw1/0/36 unassigned YES unset down down
Te1/0/37 unassigned YES unset down down
Te1/0/38 unassigned YES unset down down
Te1/0/39 unassigned YES unset down down
Te1/0/40 unassigned YES unset down down
Te1/0/41 unassigned YES unset down down
Te1/0/42 unassigned YES unset down down
Te1/0/43 unassigned YES unset down down
Te1/0/44 unassigned YES unset down down
Te1/0/45 unassigned YES unset down down
Te1/0/46 unassigned YES unset down down
Te1/0/47 unassigned YES unset down down
Te1/0/48 unassigned YES unset up up
GigabitEthernet1/1/1 unassigned YES unset down down

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

48
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

GigabitEthernet1/1/2 unassigned YES unset down down

GigabitEthernet1/1/3 unassigned YES unset down down
GigabitEthernet1/1/4 unassigned YES unset down down
Te1/1/1 unassigned YES unset down down
Te1/1/2 unassigned YES unset down down
Te1/1/3 unassigned YES unset down down
Te1/1/4 unassigned YES unset down down
Te1/1/5 unassigned YES unset down down
Te1/1/6 unassigned YES unset down down
Te1/1/7 unassigned YES unset down down
Te1/1/8 unassigned YES unset down down
Fo1/1/1 unassigned YES unset down down
Fo1/1/2 unassigned YES unset down down
Loopback100 10.10.10.10 YES TFTP up up

*** Configuring username, password, SSH ***

Line 1 SUCCESS: username cisco privilege 15 password cisco

Line 2 SUCCESS: ip domain name domain
Line 3 SUCCESS: line vty 0 15
Line 4 SUCCESS: login local
Line 5 SUCCESS: transport input all
Line 6 SUCCESS: end

*** ZTP Day0 Python Script Execution Complete ***

Cisco IOS XE Fuji 16.9.x to Cisco IOS XE Gibraltar 16.11.x

This section displays the sample boot logs before the .py script is run:

--- System Configuration Dialog ---

Would you like to enter the initial configuration dialog? [yes/no]: The process for the
command is not
responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
guestshell installed successfully
Current state is: DEPLOYED
guestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

The section shows how to configure the device for Day Zero provisioning:

Both links down, not waiting for other switches

Switch number is 1

Restricted Rights Legend

Use, duplication, or disclosure by the Government is

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

49
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

subject to restrictions as set forth in subparagraph

(c) of the Commercial Computer Software - Restricted
Rights clause at FAR sec. 52.227-19 and subparagraph
(c) (1) (ii) of the Rights in Technical Data and Computer
Software clause at DFARS sec. 252.227-7013.

Cisco Systems, Inc.

170 West Tasman Drive
San Jose, California 95134-1706

Cisco IOS Software [Fuji], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 16.9.4, RELEASE
SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2019 by Cisco Systems, Inc.
Compiled Thu 22-Aug-19 18:14 by mcpre

PLEASE READ THE FOLLOWING TERMS CAREFULLY. INSTALLING THE LICENSE OR

LICENSE KEY PROVIDED FOR ANY CISCO SOFTWARE PRODUCT, PRODUCT FEATURE,
AND/OR SUBSEQUENTLY PROVIDED SOFTWARE FEATURES (COLLECTIVELY, THE
"SOFTWARE"), AND/OR USING SUCH SOFTWARE CONSTITUTES YOUR FULL
ACCEPTANCE OF THE FOLLOWING TERMS. YOU MUST NOT PROCEED FURTHER IF YOU
ARE NOT WILLING TO BE BOUND BY ALL THE TERMS SET FORTH HEREIN.

Your use of the Software is subject to the Cisco End User License Agreement
(EULA) and any relevant supplemental terms (SEULA) found at
http://www.cisco.com/c/en/us/about/legal/cloud-and-software/software-terms.html.

You hereby acknowledge and agree that certain Software and/or features are
licensed for a particular term, that the license to such Software and/or
features is valid only for the applicable term and that such Software and/or
features may be shut down or otherwise terminated by Cisco after expiration
of the applicable license term (e.g., 90-day trial period). Cisco reserves
the right to terminate any such Software feature electronically or by any
other means available. While Cisco may provide alerts, it is your sole
responsibility to monitor your usage of any such term Software feature to
ensure that your systems and networks are prepared for a shutdown of the
Software feature.

% Checking backup nvram

% No config present. Using default config

FIPS: Flash Key Check : Key Not Found, FIPS Mode Not Enabled
cisco C9300-48UXM (X86) processor with 1419044K/6147K bytes of memory.
Processor board ID FCW2144L045
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.
0K bytes of WebUI ODM Files at webui:.

Base Ethernet MAC Address : ec:1d:8b:0a:68:00

Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0
Model Number : C9300-48UXM
System Serial Number : FCW2144L045

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

50
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

%INIT: waited 0 seconds for NVRAM to be available

--- System Configuration Dialog ---

Would you like to enter the initial configuration dialog? [yes/no]: The process for the
command is not
responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
The process for the command is not responding or is otherwise unavailable
guestshell installed successfully

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

51
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Current state is: DEPLOYED

guestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

HTTP server statistics:

Accepted connections total: 0

*** Sample ZTP Day0 Python Script ***

*** Executing show platform ***

Switch Ports Model Serial No. MAC address Hw Ver. Sw Ver.

------ ----- --------- ----------- -------------- ------- --------
1 64 C9300-48UXM FCW2144L045 ec1d.8b0a.6800 V01 16.9.4

Switch/Stack Mac Address : ec1d.8b0a.6800 - Local Mac Address

Mac persistency wait time: Indefinite
Current
Switch# Role Priority State
-------------------------------------------
*1 Active 1 Ready

*** Executing show version ***

Cisco IOS XE Software, Version 16.09.04

Cisco IOS Software [Fuji], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 16.9.4, RELEASE
SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2019 by Cisco Systems, Inc.
Compiled Thu 22-Aug-19 18:14 by mcpre
Cisco IOS-XE software, Copyright (c) 2005-2019 by cisco Systems, Inc.
All rights reserved. Certain components of Cisco IOS-XE software are
licensed under the GNU General Public License ("GPL") Version 2.0. The
software code licensed under GPL Version 2.0 is free software that comes
with ABSOLUTELY NO WARRANTY. You can redistribute and/or modify such
GPL code under the terms of GPL Version 2.0. For more details, see the
documentation or "License Notice" file accompanying the IOS-XE software,
or the applicable URL provided on the flyer accompanying the IOS-XE
software.
ROM: IOS-XE ROMMON
BOOTLDR: System Bootstrap, Version 17.2.1r[FC1], RELEASE SOFTWARE (P)
Switch uptime is 4 minutes
Uptime for this control processor is 5 minutes
System returned to ROM by Reload Command
System image file is "flash:cat9k_iosxe.16.09.04.SPA.bin"
Last reload reason: Reload Command
This product contains cryptographic features and is subject to United
States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

52
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html
If you require further assistance please contact us by sending email to
[email protected].
Technology Package License Information:
------------------------------------------------------------------------------
Technology-package Technology-package
Current Type Next reboot
------------------------------------------------------------------------------
network-advantage Smart License network-advantage
None Subscription Smart License None
Smart Licensing Status: UNREGISTERED/EVAL EXPIRED
cisco C9300-48UXM (X86) processor with 1419044K/6147K bytes of memory.
Processor board ID FCW2144L045
36 Ethernet interfaces
1 Virtual Ethernet interface
4 Gigabit Ethernet interfaces
20 Ten Gigabit Ethernet interfaces
2 TwentyFive Gigabit Ethernet interfaces
2 Forty Gigabit Ethernet interfaces
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.
0K bytes of WebUI ODM Files at webui:.
Base Ethernet MAC Address : ec:1d:8b:0a:68:00
Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0
Model Number : C9300-48UXM
System Serial Number : FCW2144L045
Switch Ports Model SW Version SW Image Mode
------ ----- ----- ---------- ---------- ----
* 1 64 C9300-48UXM 16.9.4 CAT9K_IOSXE BUNDLE
Configuration register is 0x102

*** Configuring a Loopback Interface ***

Line 1 SUCCESS: interface loop 100

Line 2 SUCCESS: ip address 10.10.10.10 255.255.255.255
Line 3 SUCCESS: end

*** Executing show ip interface brief ***

Any interface listed with OK? value "NO" does not have a valid configuration
Interface IP-Address OK? Method Status Protocol
Vlan1 unassigned NO unset up up
GigabitEthernet0/0 10.127.128.5 YES DHCP up up
Tw1/0/1 unassigned YES unset down down
Tw1/0/2 unassigned YES unset down down
Tw1/0/3 unassigned YES unset down down
Tw1/0/4 unassigned YES unset down down
Tw1/0/5 unassigned YES unset down down
Tw1/0/6 unassigned YES unset down down
Tw1/0/7 unassigned YES unset down down
Tw1/0/8 unassigned YES unset down down
Tw1/0/9 unassigned YES unset down down
Tw1/0/10 unassigned YES unset down down
Tw1/0/11 unassigned YES unset down down

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

53
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Tw1/0/12 unassigned YES unset down down

Tw1/0/13 unassigned YES unset down down
Tw1/0/14 unassigned YES unset down down
Tw1/0/15 unassigned YES unset down down
Tw1/0/16 unassigned YES unset down down
Tw1/0/17 unassigned YES unset down down
Tw1/0/18 unassigned YES unset down down
Tw1/0/19 unassigned YES unset down down
Tw1/0/20 unassigned YES unset down down
Tw1/0/21 unassigned YES unset down down
Tw1/0/22 unassigned YES unset down down
Tw1/0/23 unassigned YES unset down down
Tw1/0/24 unassigned YES unset down down
Tw1/0/25 unassigned YES unset down down
Tw1/0/26 unassigned YES unset down down
Tw1/0/27 unassigned YES unset down down
Tw1/0/28 unassigned YES unset down down
Tw1/0/29 unassigned YES unset down down
Tw1/0/30 unassigned YES unset down down
Tw1/0/31 unassigned YES unset down down
Tw1/0/32 unassigned YES unset down down
Tw1/0/33 unassigned YES unset down down
Tw1/0/34 unassigned YES unset down down
Tw1/0/35 unassigned YES unset down down
Tw1/0/36 unassigned YES unset down down
Te1/0/37 unassigned YES unset down down
Te1/0/38 unassigned YES unset down down
Te1/0/39 unassigned YES unset down down
Te1/0/40 unassigned YES unset down down
Te1/0/41 unassigned YES unset down down
Te1/0/42 unassigned YES unset down down
Te1/0/43 unassigned YES unset down down
Te1/0/44 unassigned YES unset down down
Te1/0/45 unassigned YES unset down down
Te1/0/46 unassigned YES unset down down
Te1/0/47 unassigned YES unset down down
Te1/0/48 unassigned YES unset up up
GigabitEthernet1/1/1 unassigned YES unset down down
GigabitEthernet1/1/2 unassigned YES unset down down
GigabitEthernet1/1/3 unassigned YES unset down down
GigabitEthernet1/1/4 unassigned YES unset down down
Te1/1/1 unassigned YES unset down down
Te1/1/2 unassigned YES unset down down
Te1/1/3 unassigned YES unset down down
Te1/1/4 unassigned YES unset down down
Te1/1/5 unassigned YES unset down down
Te1/1/6 unassigned YES unset down down
Te1/1/7 unassigned YES unset down down
Te1/1/8 unassigned YES unset down down
Fo1/1/1 unassigned YES unset down down
Fo1/1/2 unassigned YES unset down down
TwentyFiveGigE1/1/1 unassigned YES unset down down
TwentyFiveGigE1/1/2 unassigned YES unset down down
Loopback100 10.10.10.10 YES TFTP up up

*** Configuring username, password, SSH ***

Line 1 SUCCESS: username cisco privilege 15 password cisco

**CLI Line # 1: WARNING: Command has been added to the configuration using a type 0 password.

However, type 0 passwords will soon be deprecated. Migrate to a supported password type
Line 2 SUCCESS: ip domain name domain

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

54
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Line 3 SUCCESS: line vty 0 15

Line 4 SUCCESS: login local
Line 5 SUCCESS: transport input all
Line 6 SUCCESS: end

*** ZTP Day0 Python Script Execution Complete ***

Press RETURN to get started!

Cisco IOS XE Gibraltar 16.12.x to Cisco IOS XE Amsterdam 17.1.x

This section displays the sample boot logs before the .py script is run:

--- System Configuration Dialog ---

Would you like to enter the initial configuration dialog? [yes/no]: day0guestshell installed
successfully
Current state is: DEPLOYED
day0guestshell activated successfully
Current state is: ACTIVATED
day0guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

*** Sample ZTP Day0 Python Script ***

...

*** ZTP Day0 Python Script Execution Complete ***

Guestshell destroyed successfully

The section shows how to configure the device for Day Zero provisioning:

Both links down, not waiting for other switches

Switch number is 1

Restricted Rights Legend

Use, duplication, or disclosure by the Government is

subject to restrictions as set forth in subparagraph
(c) of the Commercial Computer Software - Restricted
Rights clause at FAR sec. 52.227-19 and subparagraph
(c) (1) (ii) of the Rights in Technical Data and Computer
Software clause at DFARS sec. 252.227-7013.

Cisco Systems, Inc.

170 West Tasman Drive
San Jose, California 95134-1706

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

55
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Cisco IOS Software [Gibraltar], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 16.12.3a,

RELEASE SOFTWARE (fc1)

Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2020 by Cisco Systems, Inc.
Compiled Tue 28-Apr-20 09:37 by mcpre

This software version supports only Smart Licensing as the software licensing mechanism.

PLEASE READ THE FOLLOWING TERMS CAREFULLY. INSTALLING THE LICENSE OR

LICENSE KEY PROVIDED FOR ANY CISCO SOFTWARE PRODUCT, PRODUCT FEATURE,
AND/OR SUBSEQUENTLY PROVIDED SOFTWARE FEATURES (COLLECTIVELY, THE
"SOFTWARE"), AND/OR USING SUCH SOFTWARE CONSTITUTES YOUR FULL
ACCEPTANCE OF THE FOLLOWING TERMS. YOU MUST NOT PROCEED FURTHER IF YOU
ARE NOT WILLING TO BE BOUND BY ALL THE TERMS SET FORTH HEREIN.

Your use of the Software is subject to the Cisco End User License Agreement
(EULA) and any relevant supplemental terms (SEULA) found at
http://www.cisco.com/c/en/us/about/legal/cloud-and-software/software-terms.html.

You hereby acknowledge and agree that certain Software and/or features are
licensed for a particular term, that the license to such Software and/or
features is valid only for the applicable term and that such Software and/or
features may be shut down or otherwise terminated by Cisco after expiration
of the applicable license term (e.g., 90-day trial period). Cisco reserves
the right to terminate any such Software feature electronically or by any
other means available. While Cisco may provide alerts, it is your sole
responsibility to monitor your usage of any such term Software feature to
ensure that your systems and networks are prepared for a shutdown of the
Software feature.

% Checking backup nvram

% No config present. Using default config

FIPS: Flash Key Check : Key Not Found, FIPS Mode Not Enabled

All TCP AO KDF Tests Pass

cisco C9300-48UXM (X86) processor with 1343703K/6147K bytes of memory.
Processor board ID FCW2144L045
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.
0K bytes of WebUI ODM Files at webui:.

Base Ethernet MAC Address : ec:1d:8b:0a:68:00

Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0
Model Number : C9300-48UXM
System Serial Number : FCW2144L045

--- System Configuration Dialog ---

Would you like to enter the initial configuration dialog? [yes/no]: day0guestshell installed
successfully
Current state is: DEPLOYED

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

56
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

day0guestshell activated successfully

Current state is: ACTIVATED
day0guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

HTTP server statistics:

Accepted connections total: 0

*** Sample ZTP Day0 Python Script ***

*** Executing show platform ***

Switch Ports Model Serial No. MAC address Hw Ver. Sw Ver.

------ ----- --------- ----------- -------------- ------- --------
1 65 C9300-48UXM FCW2144L045 ec1d.8b0a.6800 V01 16.12.3a

Switch/Stack Mac Address : ec1d.8b0a.6800 - Local Mac Address

Mac persistency wait time: Indefinite
Current
Switch# Role Priority State
-------------------------------------------
*1 Active 1 Ready

*** Executing show version ***

Cisco IOS XE Software, Version 16.12.03a

Cisco IOS Software [Gibraltar], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 16.12.3a,

RELEASE SOFTWARE (fc1)

Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2020 by Cisco Systems, Inc.
Compiled Tue 28-Apr-20 09:37 by mcpre
Cisco IOS-XE software, Copyright (c) 2005-2020 by cisco Systems, Inc.
All rights reserved. Certain components of Cisco IOS-XE software are
licensed under the GNU General Public License ("GPL") Version 2.0. The
software code licensed under GPL Version 2.0 is free software that comes
with ABSOLUTELY NO WARRANTY. You can redistribute and/or modify such
GPL code under the terms of GPL Version 2.0. For more details, see the
documentation or "License Notice" file accompanying the IOS-XE software,
or the applicable URL provided on the flyer accompanying the IOS-XE
software.
ROM: IOS-XE ROMMON
BOOTLDR: System Bootstrap, Version 17.2.1r[FC1], RELEASE SOFTWARE (P)
Switch uptime is 4 minutes
Uptime for this control processor is 9 minutes
System returned to ROM by Reload Command
System image file is "flash:cat9k_iosxe.16.12.03a.SPA.bin"
Last reload reason: Reload Command
This product contains cryptographic features and is subject to United
States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

57
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html
If you require further assistance please contact us by sending email to
[email protected].
Technology Package License Information:
------------------------------------------------------------------------------
Technology-package Technology-package
Current Type Next reboot
------------------------------------------------------------------------------
network-advantage Smart License network-advantage
None Subscription Smart License None
AIR License Level: AIR DNA Advantage
Next reload AIR license Level: AIR DNA Advantage
Smart Licensing Status: UNREGISTERED/EVAL EXPIRED
cisco C9300-48UXM (X86) processor with 1343703K/6147K bytes of memory.
Processor board ID FCW2144L045
1 Virtual Ethernet interface
4 Gigabit Ethernet interfaces
36 2.5 Gigabit Ethernet interfaces
20 Ten Gigabit Ethernet interfaces
2 TwentyFive Gigabit Ethernet interfaces
2 Forty Gigabit Ethernet interfaces
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.
0K bytes of WebUI ODM Files at webui:.
Base Ethernet MAC Address : ec:1d:8b:0a:68:00
Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0
Model Number : C9300-48UXM
System Serial Number : FCW2144L045
Switch Ports Model SW Version SW Image Mode
------ ----- ----- ---------- ---------- ----
* 1 65 C9300-48UXM 16.12.3a CAT9K_IOSXE BUNDLE
Configuration register is 0x102

*** Configuring a Loopback Interface ***

Line 1 SUCCESS: interface loop 100

Line 2 SUCCESS: ip address 10.10.10.10 255.255.255.255
Line 3 SUCCESS: end

*** Executing show ip interface brief ***

Interface IP-Address OK? Method Status Protocol

Vlan1 unassigned YES unset up up
GigabitEthernet0/0 10.127.128.10 YES DHCP up up
Tw1/0/1 unassigned YES unset down down
Tw1/0/2 unassigned YES unset down down
Tw1/0/3 unassigned YES unset down down
Tw1/0/4 unassigned YES unset down down
Tw1/0/5 unassigned YES unset down down
Tw1/0/6 unassigned YES unset down down
Tw1/0/7 unassigned YES unset down down
Tw1/0/8 unassigned YES unset down down
Tw1/0/9 unassigned YES unset down down
Tw1/0/10 unassigned YES unset down down

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

58
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Tw1/0/11 unassigned YES unset down down

Tw1/0/12 unassigned YES unset down down
Tw1/0/13 unassigned YES unset down down
Tw1/0/14 unassigned YES unset down down
Tw1/0/15 unassigned YES unset down down
Tw1/0/16 unassigned YES unset down down
Tw1/0/17 unassigned YES unset down down
Tw1/0/18 unassigned YES unset down down
Tw1/0/19 unassigned YES unset down down
Tw1/0/20 unassigned YES unset down down
Tw1/0/21 unassigned YES unset down down
Tw1/0/22 unassigned YES unset down down
Tw1/0/23 unassigned YES unset down down
Tw1/0/24 unassigned YES unset down down
Tw1/0/25 unassigned YES unset down down
Tw1/0/26 unassigned YES unset down down
Tw1/0/27 unassigned YES unset down down
Tw1/0/28 unassigned YES unset down down
Tw1/0/29 unassigned YES unset down down
Tw1/0/30 unassigned YES unset down down
Tw1/0/31 unassigned YES unset down down
Tw1/0/32 unassigned YES unset down down
Tw1/0/33 unassigned YES unset down down
Tw1/0/34 unassigned YES unset down down
Tw1/0/35 unassigned YES unset down down
Tw1/0/36 unassigned YES unset down down
Te1/0/37 unassigned YES unset down down
Te1/0/38 unassigned YES unset down down
Te1/0/39 unassigned YES unset down down
Te1/0/40 unassigned YES unset down down
Te1/0/41 unassigned YES unset down down
Te1/0/42 unassigned YES unset down down
Te1/0/43 unassigned YES unset down down
Te1/0/44 unassigned YES unset down down
Te1/0/45 unassigned YES unset down down
Te1/0/46 unassigned YES unset down down
Te1/0/47 unassigned YES unset down down
Te1/0/48 unassigned YES unset up up
GigabitEthernet1/1/1 unassigned YES unset down down
GigabitEthernet1/1/2 unassigned YES unset down down
GigabitEthernet1/1/3 unassigned YES unset down down
GigabitEthernet1/1/4 unassigned YES unset down down
Te1/1/1 unassigned YES unset down down
Te1/1/2 unassigned YES unset down down
Te1/1/3 unassigned YES unset down down
Te1/1/4 unassigned YES unset down down
Te1/1/5 unassigned YES unset down down
Te1/1/6 unassigned YES unset down down
Te1/1/7 unassigned YES unset down down
Te1/1/8 unassigned YES unset down down
Fo1/1/1 unassigned YES unset down down
Fo1/1/2 unassigned YES unset down down
TwentyFiveGigE1/1/1 unassigned YES unset down down
TwentyFiveGigE1/1/2 unassigned YES unset down down
Ap1/0/1 unassigned YES unset up up
Loopback100 10.10.10.10 YES TFTP up up

*** Configuring username, password, SSH ***

Line 1 SUCCESS: username cisco privilege 15 password cisco

**CLI Line # 1: WARNING: Command has been added to the configuration using a type 0 password.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

59
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

However, type 0 passwords will soon be deprecated. Migrate to a supported password type
Line 2 SUCCESS: ip domain name domain
Line 3 SUCCESS: line vty 0 15
Line 4 SUCCESS: login local
Line 5 SUCCESS: transport input all
Line 6 SUCCESS: end

*** ZTP Day0 Python Script Execution Complete ***

Guestshell destroyed successfully

Press RETURN to get started!

Cisco IOS XE Amsterdam 17.2.x and Later Releases

This section displays the sample boot logs before the .py script is run:

--- System Configuration Dialog ---

Would you like to enter the initial configuration dialog? [yes/no]:

Acquired IPv4 address 10.127.128.8 on Interface GigabitEthernet0/0
Received following DHCPv4 options:
bootfile : test.py
tftp-server-ip : 159.14.27.2

OK to enter CLI now...

pnp-discovery can be monitored without entering enable mode

Entering enable mode will stop pnp-discovery

Attempting bootfile tftp://159.14.27.2/test.py

day0guestshell activated successfully
Current state is: ACTIVATED
day0guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

*** Sample ZTP Day0 Python Script ***

...

*** ZTP Day0 Python Script Execution Complete ***

Guestshell destroyed successfully

The section shows how to configure the device for Day Zero provisioning:

Both links down, not waiting for other switches

Switch number is 1

Restricted Rights Legend

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

60
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Use, duplication, or disclosure by the Government is

subject to restrictions as set forth in subparagraph
(c) of the Commercial Computer Software - Restricted
Rights clause at FAR sec. 52.227-19 and subparagraph
(c) (1) (ii) of the Rights in Technical Data and Computer
Software clause at DFARS sec. 252.227-7013.

Cisco Systems, Inc.

170 West Tasman Drive
San Jose, California 95134-1706

Cisco IOS Software [Amsterdam], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 17.2.1,
RELEASE SOFTWARE (fc4)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2020 by Cisco Systems, Inc.
Compiled Thu 26-Mar-20 03:29 by mcpre

This software version supports only Smart Licensing as the software licensing mechanism.

PLEASE READ THE FOLLOWING TERMS CAREFULLY. INSTALLING THE LICENSE OR

LICENSE KEY PROVIDED FOR ANY CISCO SOFTWARE PRODUCT, PRODUCT FEATURE,
AND/OR SUBSEQUENTLY PROVIDED SOFTWARE FEATURES (COLLECTIVELY, THE
"SOFTWARE"), AND/OR USING SUCH SOFTWARE CONSTITUTES YOUR FULL
ACCEPTANCE OF THE FOLLOWING TERMS. YOU MUST NOT PROCEED FURTHER IF YOU
ARE NOT WILLING TO BE BOUND BY ALL THE TERMS SET FORTH HEREIN.

Your use of the Software is subject to the Cisco End User License Agreement
(EULA) and any relevant supplemental terms (SEULA) found at
http://www.cisco.com/c/en/us/about/legal/cloud-and-software/software-terms.html.

You hereby acknowledge and agree that certain Software and/or features are
licensed for a particular term, that the license to such Software and/or
features is valid only for the applicable term and that such Software and/or
features may be shut down or otherwise terminated by Cisco after expiration
of the applicable license term (e.g., 90-day trial period). Cisco reserves
the right to terminate any such Software feature electronically or by any
other means available. While Cisco may provide alerts, it is your sole
responsibility to monitor your usage of any such term Software feature to
ensure that your systems and networks are prepared for a shutdown of the
Software feature.

% Checking backup nvram

% No config present. Using default config

FIPS: Flash Key Check : Key Not Found, FIPS Mode Not Enabled

All TCP AO KDF Tests Pass

cisco C9300-48UXM (X86) processor with 1338934K/6147K bytes of memory.
Processor board ID FCW2144L045
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.

Base Ethernet MAC Address : ec:1d:8b:0a:68:00

Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

61
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Model Number : C9300-48UXM

System Serial Number : FCW2144L045
CLEI Code Number :

No startup-config, starting autoinstall/pnp/ztp...

Autoinstall will terminate if any input is detected on console

Autoinstall trying DHCPv4 on GigabitEthernet0/0

Autoinstall trying DHCPv6 on GigabitEthernet0/0

--- System Configuration Dialog ---

Would you like to enter the initial configuration dialog? [yes/no]:

Acquired IPv4 address 10.127.128.8 on Interface GigabitEthernet0/0
Received following DHCPv4 options:
bootfile : test.py
tftp-server-ip : 159.14.27.2

OK to enter CLI now...

pnp-discovery can be monitored without entering enable mode

Entering enable mode will stop pnp-discovery

Attempting bootfile tftp://159.14.27.2/test.py

day0guestshell activated successfully
Current state is: ACTIVATED
day0guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

*** Sample ZTP Day0 Python Script ***

*** Executing show platform ***

Switch Ports Model Serial No. MAC address Hw Ver. Sw Ver.

------ ----- --------- ----------- -------------- ------- --------
1 65 C9300-48UXM FCW2144L045 ec1d.8b0a.6800 V01 17.02.01

Switch/Stack Mac Address : ec1d.8b0a.6800 - Local Mac Address

Mac persistency wait time: Indefinite
Current
Switch# Role Priority State
-------------------------------------------
*1 Active 1 Ready

*** Executing show version ***

Cisco IOS XE Software, Version 17.02.01

Cisco IOS Software [Amsterdam], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 17.2.1,
RELEASE SOFTWARE (fc4)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2020 by Cisco Systems, Inc.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

62
Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

Compiled Thu 26-Mar-20 03:29 by mcpre

Cisco IOS-XE software, Copyright (c) 2005-2020 by cisco Systems, Inc.
All rights reserved. Certain components of Cisco IOS-XE software are
licensed under the GNU General Public License ("GPL") Version 2.0. The
software code licensed under GPL Version 2.0 is free software that comes
with ABSOLUTELY NO WARRANTY. You can redistribute and/or modify such
GPL code under the terms of GPL Version 2.0. For more details, see the
documentation or "License Notice" file accompanying the IOS-XE software,
or the applicable URL provided on the flyer accompanying the IOS-XE
software.
ROM: IOS-XE ROMMON
BOOTLDR: System Bootstrap, Version 17.2.1r[FC1], RELEASE SOFTWARE (P)
Switch uptime is 2 minutes
Uptime for this control processor is 8 minutes
System returned to ROM by Reload Command
System image file is "flash:cat9k_iosxe.17.02.01.SPA.bin"
Last reload reason: Reload Command
This product contains cryptographic features and is subject to United
States and local country laws governing import, export, transfer and
use. Delivery of Cisco cryptographic products does not imply
third-party authority to import, export, distribute or use encryption.
Importers, exporters, distributors and users are responsible for
compliance with U.S. and local country laws. By using this product you
agree to comply with applicable laws and regulations. If you are unable
to comply with U.S. and local laws, return this product immediately.
A summary of U.S. laws governing Cisco cryptographic products may be found at:
http://www.cisco.com/wwl/export/crypto/tool/stqrg.html
If you require further assistance please contact us by sending email to
[email protected].
Technology Package License Information:
------------------------------------------------------------------------------
Technology-package Technology-package
Current Type Next reboot
------------------------------------------------------------------------------
network-advantage Smart License network-advantage
None Subscription Smart License None
AIR License Level: AIR DNA Advantage
Next reload AIR license Level: AIR DNA Advantage
Smart Licensing Status: UNREGISTERED/EVAL EXPIRED
cisco C9300-48UXM (X86) processor with 1338934K/6147K bytes of memory.
Processor board ID FCW2144L045
1 Virtual Ethernet interface
4 Gigabit Ethernet interfaces
36 2.5 Gigabit Ethernet interfaces
20 Ten Gigabit Ethernet interfaces
2 TwentyFive Gigabit Ethernet interfaces
2 Forty Gigabit Ethernet interfaces
2048K bytes of non-volatile configuration memory.
8388608K bytes of physical memory.
1638400K bytes of Crash Files at crashinfo:.
11264000K bytes of Flash at flash:.
Base Ethernet MAC Address : ec:1d:8b:0a:68:00
Motherboard Assembly Number : 73-17959-06
Motherboard Serial Number : FOC21418FPQ
Model Revision Number : B0
Motherboard Revision Number : A0
Model Number : C9300-48UXM
System Serial Number : FCW2144L045
CLEI Code Number :
Switch Ports Model SW Version SW Image Mode
------ ----- ----- ---------- ---------- ----
* 1 65 C9300-48UXM 17.02.01 CAT9K_IOSXE BUNDLE
Configuration register is 0x102

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

63
 Provisioning
Boot Log for Cisco Catalyst 9000 Series Switches

*** Configuring a Loopback Interface ***

Line 1 SUCCESS: interface loop 100

Line 2 SUCCESS: ip address 10.10.10.10 255.255.255.255
Line 3 SUCCESS: end

*** Executing show ip interface brief ***

Interface IP-Address OK? Method Status Protocol

Vlan1 unassigned YES unset up up
GigabitEthernet0/0 10.127.128.8 YES DHCP up up
Tw1/0/1 unassigned YES unset down down
Tw1/0/2 unassigned YES unset down down
Tw1/0/3 unassigned YES unset down down
Tw1/0/4 unassigned YES unset down down
Tw1/0/5 unassigned YES unset down down
Tw1/0/6 unassigned YES unset down down
Tw1/0/7 unassigned YES unset down down
Tw1/0/8 unassigned YES unset down down
Tw1/0/9 unassigned YES unset down down
Tw1/0/10 unassigned YES unset down down
Tw1/0/11 unassigned YES unset down down
Tw1/0/12 unassigned YES unset down down
Tw1/0/13 unassigned YES unset down down
Tw1/0/14 unassigned YES unset down down
Tw1/0/15 unassigned YES unset down down
Tw1/0/16 unassigned YES unset down down
Tw1/0/17 unassigned YES unset down down
Tw1/0/18 unassigned YES unset down down
Tw1/0/19 unassigned YES unset down down
Tw1/0/20 unassigned YES unset down down
Tw1/0/21 unassigned YES unset down down
Tw1/0/22 unassigned YES unset down down
Tw1/0/23 unassigned YES unset down down
Tw1/0/24 unassigned YES unset down down
Tw1/0/25 unassigned YES unset down down
Tw1/0/26 unassigned YES unset down down
Tw1/0/27 unassigned YES unset down down
Tw1/0/28 unassigned YES unset down down
Tw1/0/29 unassigned YES unset down down
Tw1/0/30 unassigned YES unset down down
Tw1/0/31 unassigned YES unset down down
Tw1/0/32 unassigned YES unset down down
Tw1/0/33 unassigned YES unset down down
Tw1/0/34 unassigned YES unset down down
Tw1/0/35 unassigned YES unset down down
Tw1/0/36 unassigned YES unset down down
Te1/0/37 unassigned YES unset down down
Te1/0/38 unassigned YES unset down down
Te1/0/39 unassigned YES unset down down
Te1/0/40 unassigned YES unset down down
Te1/0/41 unassigned YES unset down down
Te1/0/42 unassigned YES unset down down
Te1/0/43 unassigned YES unset down down
Te1/0/44 unassigned YES unset down down
Te1/0/45 unassigned YES unset down down
Te1/0/46 unassigned YES unset down down
Te1/0/47 unassigned YES unset down down
Te1/0/48 unassigned YES unset up up
GigabitEthernet1/1/1 unassigned YES unset down down

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

64
 Provisioning
Feature Information for Zero-Touch Provisioning

GigabitEthernet1/1/2 unassigned YES unset down down

GigabitEthernet1/1/3 unassigned YES unset down down
GigabitEthernet1/1/4 unassigned YES unset down down
Te1/1/1 unassigned YES unset down down
Te1/1/2 unassigned YES unset down down
Te1/1/3 unassigned YES unset down down
Te1/1/4 unassigned YES unset down down
Te1/1/5 unassigned YES unset down down
Te1/1/6 unassigned YES unset down down
Te1/1/7 unassigned YES unset down down
Te1/1/8 unassigned YES unset down down
Fo1/1/1 unassigned YES unset down down
Fo1/1/2 unassigned YES unset down down
TwentyFiveGigE1/1/1 unassigned YES unset down down
TwentyFiveGigE1/1/2 unassigned YES unset down down
Ap1/0/1 unassigned YES unset up up
Loopback100 10.10.10.10 YES TFTP up up

*** Configuring username, password, SSH ***

Line 1 SUCCESS: username cisco privilege 15 password cisco

**CLI Line # 1: WARNING: Command has been added to the configuration using a type 0 password.

However, type 0 passwords will soon be deprecated. Migrate to a supported password type
Line 2 SUCCESS: ip domain name domain
Line 3 SUCCESS: line vty 0 15
Line 4 SUCCESS: login local
Line 5 SUCCESS: transport input all
Line 6 SUCCESS: end

*** ZTP Day0 Python Script Execution Complete ***

Guestshell destroyed successfully

Script execution success!

Press RETURN to get started!

Feature Information for Zero-Touch Provisioning

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

65
 Provisioning
Feature Information for Zero-Touch Provisioning

Table 2: Feature Information for Zero-Touch Provisioning

Feature Name Release Feature Information

Zero-Touch Provisioning Cisco IOS XE Everest

16.5.1a
Cisco IOS XE Everest
16.5.1b
Cisco IOS XE Fuji 16.7.1
Cisco IOS XE Fuji 16.8.2
Cisco IOS XE Gibraltar
16.12.1
Cisco IOS XE Amsterdam
17.2.1
Cisco IOS XE Amsterdam
17.3.1
Cisco IOS XE Cupertino
17.8.1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

66
Provisioning
Feature Information for Zero-Touch Provisioning

Feature Name Release Feature Information

To address network provisioning challenges,
Cisco introduces a zero-touch provisioning
model.
In Cisco IOS XE Everest 16.5.1a, this feature
was implemented on the following platforms:
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

In Cisco IOS XE Everest 16.5.1b, this feature

was implemented on the following platform:
• Cisco 4000 Series Integrated Services
Router models with a minimum of 8 GB
RAM to support Guest Shell.

In Cisco IOS XE Fuji 16.7.1, this feature was

implemented on the following platform:
• Cisco ASR 1000 Aggregation Services
Routers (ASR1001-X, ASR1001-HX,
ASR1002-X, ASR1002-HX)

In Cisco IOS XE Fuji 16.8.2, this feature was

implemented on the following platform:
• Cisco ASR 1000 Series Aggregation
Services Routers (ASR1004, ASR1006,
ASR1006-X, ASR1009-X, ASR1013)

In Cisco IOS XE Gibraltar 16.12.1, this feature

was implemented on the following platforms:
• Cisco Catalyst 9200 Series Switches
Note This feature is not supported
on C9200L SKUs.

• Cisco Catalyst 9300L SKUs

• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-40 Wireless
Controllers
• Cisco Catalyst 9800-80 Wireless
Controllers

In Cisco IOS XE Amsterdam 17.2.1, this

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

67
 Provisioning
Feature Information for Zero-Touch Provisioning

Feature Name Release Feature Information

feature was implemented on the following
platforms:
• Cisco Cloud Services Router 1000V
Series
• Cisco C1100 Terminal Services Gateway
(Supported only on
C1100TGX-1N24P32A)

In Cisco IOS XE Amsterdam 17.3.1, this

feature was implemented on the following
platforms:
• Cisco Catalyst 8200 Series Edge
Platforms
• Cisco Catalyst 8300 Series Edge
Platforms
• Cisco Catalyst 8500 and 8500L Series
Edge Platforms

In Cisco IOS XE Bengaluru 17.4.1, this

feature was implemented on the following
platform:
• Cisco Catalyst 8000V Edge Software

In Cisco IOS XE Cupertino 17.8.1, this feature

was implemented on the following platform:
• Cisco Catalyst 9800-L Wireless
Controller

Zero-Touch Provisioning: Cisco IOS XE Fuji 16.8.1 Zero-Touch Provisioning supports HTTP and
HTTP Download TFTP file download.
Cisco IOS XE Fuji 16.8.1a
In Cisco IOS XE Everest 16.8.1, this feature
was implemented on the following platforms:
• Cisco 4000 Series Integrated Services
Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

In Cisco IOS XE Fuji 16.8.1a, this feature was

implemented on Cisco Catalyst 9500-High
Performance Series Switches.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

68
Provisioning
Feature Information for Zero-Touch Provisioning

Feature Name Release Feature Information

DHCPv6 Support for Cisco IOS XE Fuji 16.9.1 In Cisco IOS XE Fuji 16.9.1, this feature was
Zero-Touch Provisioning implemented on the following platforms:
Cisco IOS XE Amsterdam
17.3.2a • Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

In Cisco IOS XE Amsterdam 17.3.2a, this

feature was implemented on the following
platforms:
• Cisco Catalyst 9800-40 Wireless
Controllers
• Cisco Catalyst 9800-80 Wireless
Controllers

Side-Effect Synchronization Cisco IOS XE Bengaluru During configuration changes in the DMI, a
of the Configuration Database 17.4.1 partial synchronization of the changes that are
triggered when a command or RPC is
configured happens. This is called the
side-effect synchronization, and it reduces the
synchronization time and NETCONF
downtime.
This feature was implemented on the
following platforms:
• Cisco ASR 1000 Aggregation Services
Routers
• Cisco Catalyst 8500 and 8500L Series
Edge Platforms
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

Zero-Touch Provisioning Cisco IOS XE Cupertino ZTP is enabled through YANG models when
Through YANG Models 17.7.1 NETCONF is enabled.
This feature is supported on all platforms that
support NETCONF-YANG.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

69
 Provisioning
Feature Information for Zero-Touch Provisioning

Feature Name Release Feature Information

Zero-Touch Provisioning Cisco IOS XE Cupertino ZTP is supported on data port for both IPv4
Support on Data Port 17.7.1 and IPv6.
This feature is implemented on the following
platform:
• Cisco Catalyst 9800-L Wireless
Controller

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

70
 CHAPTER 3
iPXE
iPXE is an enhanced version of the Pre-boot eXecution Environment (PXE), which is an open standard for
network booting. This module describes the iPXE feature and how to configure it.
• Information About iPXE, on page 71
• How to Configure iPXE, on page 79
• Configuration Examples for iPXE, on page 81
• Troubleshooting Tips for iPXE, on page 84
• Additional References for iPXE, on page 85
• Feature Information for iPXE, on page 85

Information About iPXE

About iPXE
iPXE is an enhanced version of the Pre-boot eXecution Environment (PXE), which is an open standard for
network booting.
iPXE netboot provides:
• IPv4 and IPv6 protocols
• FTP/HTTP/TFTP boot image download
• Embedded scripts into the image
• Stateless and stateful address auto-configuration (SLAAC) using Dynamic Host Configuration Protocol
Version 4 (DHCPv4) and/or DHCPv6, boot URI, and parameters for DHCPv6 options depending on the
IPv6 router advertisement.

Netboot Requirements
The following are the primary requirements for netbooting:
• DHCP server with proper configuration.
• Boot image available on the FTP/HTTP/TFTP server.
• Device configured to boot from a network-based source.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

71
 Provisioning
iPXE Overview

iPXE Overview
Network bootloaders support booting from a network-based source. The bootloaders boot an image located
on an HTTP, FTP, or TFTP server. A network boot source is detected automatically by using an iPXE-like
solution.
iPXE enables network boot for a device that is offline. The following are the three types of boot modes:
• iPXE Timeout—Boots through iPXE network boot. Configures a timeout in seconds for iPXE network
boot by using the IPXE_TIMEOUT rommon variable. Use the boot ipxe timeout command to configure
iPXE timeout. When the timeout expires, device boot is activated.
• iPXE Forever—Boots through iPXE network boot. The device sends DHCP requests forever, when the
boot ipxe forever command is configured. This is an iPXE-only boot (which means that the bootloader
will not fall back to a device boot or a command prompt, because it will send DHCP requests forever
until it receives a valid DHCP response.)
• Device—Boots using the local device BOOT line configured on it. When device boot is configured, the
configured IPXE_TIMEOUT rommon variable is ignored. You can activate device boot as specified
below:
• If BOOTMODE=ipxe-forever, device boot is not activated without user intervention (this is possible
only if ENABLE_BREAK=yes).
• If BOOTMODE=ipxe-timeout, device boot is activated when the specified IPXE_TIMEOUT variable
(in seconds) has elapsed.
• If BOOTMODE=device, device boot is activated. This is the default active mode.
• Device boot can also be activated through the CLI.

Note Device boot is the default boot mode.

Note Manual boot is another term used in this document. Manual boot is a flag that determines whether to do
a rommon reload or not. When the device is in rommon mode, you have to manually issue the boot
command.
If manual boot is set to YES, the rommon or device prompt is activated. If manual boot is set to NO,
the autoboot variable is executed; this means that the value set in the BOOT variable is followed.

The following section describes how an iPXE bootloader works:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

72
Provisioning
iPXE Overview

Figure 1: iPXE Bootloader Workflow

1. Bootloader sends a DHCP discover message, and when the server replies, the Bootloader sends a DHCP
request.
2. The DHCP response includes the IP address and boot file name. The boot file name indicates that the boot
image is to be retrieved from a TFTP server (tftp://server/filename), FTP server
(ftp://userid:password@server/filename), or an HTTP server (http://server/filename).
3. Bootloader downloads and boots the image from the network source.
4. If no DHCP response is received, the bootloader keeps sending DHCP requests forever or for a specified
period of time, based on the boot mode configured. When a timeout occurs, the bootloader reverts to a
device-based boot. The device sends DHCP requests forever only if the configured boot mode is
ipxe-forever. If the ipxe-timeout boot mode command is configured, DHCP requests are sent for the
specified amount of time, and when the timeout expires, device boot mode is activated.

Note Because the current iPXE implementation works only via the management port (GigabitEthernet0/0),
DHCP requests sent through the front panel ports are not supported.

When using a static network configuration to network boot, ROMMON uses the following environment
variables (and all of them are required):
• BOOT—URLs separated by semicolon (;) to boot from.
• IP_ADDRESS—Statically assigned IP address of a device.
• DEFAULT_GATEWAY—Default gateway of the device.
• IP_SUBNET_MASK—IPv4 or IPv6 prefix information.
IPv4—Subnet mask of the device in the format WWW.XXX.YYY.ZZZ eg. 255.255.255.0.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

73
 Provisioning
IPv6 iPXE Network Boot

IPv6—Subnet prefix length of the device in the format NNN eg. 64 or 112.

When manual boot is disabled, the bootloader determines whether to execute a device boot or a network boot
based on the configured value of the rommon iPXE variable. Irrespective of whether manual boot is enabled
or disabled, the bootloader uses the BOOTMODE variable to determine whether to do a device boot or a
network boot. Manual boot means that the user has configured the boot manual switch command. When
manual boot is disabled, and when the device reloads, the boot process starts automatically.
When iPXE is disabled, the contents of the existing BOOT variable are used to determine how to boot the
device. The BOOT variable may contain a network-based uniform resource identifier (URI) (for example,
http://, ftp://, tftp://), and a network boot is initiated; however DHCP is not used to get the network image
path. The static network configuration is taken from the IP_ADDRESS, DEFAULT_GATEWAY, and
IP_SUBNET_MASK variables. The BOOT variable may also contain a device filesystem-based path, in
which case, a device filesystem-based boot is initiated.
The DHCP server used for booting can identify a device through the Product ID (PID) (available in DHCP
Option 60), chassis serial number (available in DHCP option 61), or the MAC address of the device. The
show inventory and show switch commands also display these values on the device.
The following is sample output from the show inventory command:
Device# show inventory

NAME:“c38xx Stack”, DESCR:“c38xx Stack”

PID:WS-3850-12X-48U-L, VID:V01 , SN: F0C1911V01A

NAME:“Switch 1”, DESCR:“WS-C3850-12X48U-L”

PID:WS-C3850-12X48U-L, VID:V01 , SN:F0C1911V01A

NAME:”Switch1 -Power Supply B”, DESCR:“Switch1 -Power Supply B”

PID:PWR-C1-1100WAC, VID:V01, SN:LIT1847146Q

The following is sample output from the show switch command:

Device# show switch

Switch/Stack Mac Address : 046c.9d01.7d80 - Local Mac Address

Mac persistency wait time: Indefinite
H/W Current
Switch# Role Mac Address Priority Version State
-------------------------------------------------------------------------------------
1 Member 046c.9d1e.1a00 1 Ready
2 Standby 046c.9d01.7d80 1 Ready
*3 Active f8b7.e24e.9a00 1 P2B Ready

The following rommon variables should be configured for iPXE:

• BOOTMODE = ipxe-forever | ipxe-timeout | device
• IPXE_TIMEOUT = seconds

IPv6 iPXE Network Boot

This illustration displays how IPv6 iPXE network boot works on a Cisco device:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

74
Provisioning
IPv6 iPXE Network Boot

The four elements in the above illustration are described below:

• IPv6 Booting Device—The device that is booting through iPXE boot.
• Supporting Device—A Cisco device that is configured with an IPv6 address to generate Router
Advertisement (RA) messages.

Note In this illustration, the IPv6 booting device, the supporting device, and the
DHCP server are on the same subnet. However; if the supporting device
and the DHCP server are on different subnets, then there must be a relay
agent in the network.

• DHCP server—Any DHCP server.

• Web server—Any web server.

This section describes the IPv6 iPXE boot process:

1. The device sends a router solicitation Internet Control Message Protocol IPv6 (ICMPv6) type 133 packet
to the IPv6 device on the local subnet.
2. The IPv6 device on the local subnet replies with a router advertisement (RA) message, ICMPv6 type 134
packet. The device that sent the router solicitation message, gets the default router and prefix information
for Stateless Address AutoConfiguration (SLAAC) address completion from the RA packet.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

75
 Provisioning
IPv6 Address Assignment in Rommon Mode

3. The device sends a DHCPv6 solicit message to the multicast group address of ff02::1:2 for all DHCP
agents.
The following sample displays the fields in a DHCPv6 solicit packet during iPXE boot:

DHCPv6
Message type: Solicit (1)
Transaction ID: 0x36f5f1
Client Identifier
Vendor Class
Identity Association for Non-Temporary Address
Option Request
User Class
Vendor-specific Information

The DHCPv6 solicit message contains the following information:

• DHCP Unique Identifier (DUID)—Identifies the client. iPXE supports DUID-EN. EN stands for
Enterprise Number, and this DUID is based on the vendor-assigned unique identifier.
• DHCP and DHCPv6 Options

4. If the DHCPv6 server is configured, it responds with a DHCPv6 advertise packet that contains the 128
Bit IPv6 address, the boot file Uniform Resource Identifier (URI), the Domain Name System (DNS) server
and domain search list, and the client and server IDs. The client ID contains the DUID of the client (In
this illustration, the IPv6 Booting Device), and the Server ID contains the DUID of the DHCPv6 server.
5. The client then sends a DHCPv6 request packet to the multicast group address ff02::1:2, requesting for
advertised parameters.
6. The server responds with a unicast DHCPv6 reply to the Link Local (FE80::) IPv6 address of the client.
The following sample displays the fields in a DHCPv6 reply packet:

DHCPv6
Message type: Reply (7)
Transaction ID: 0x790950
Identity Association for Non-Temporary Address
Client Identifier
Server Identifier
DNS recursive name server
Boot File URL
Domain Search List

7. The device then sends an HTTP GET request to the web server.
8. If the requested image is available at the specified path, the web server responds with an OK for the HTTP
GET request.
9. The TCP image transfer copies the image, and the device boots up.

IPv6 Address Assignment in Rommon Mode

The DHCP client uses the following order-of-precedence to decide which IPv6 address to use in rommon
mode:
1. DHCP Server-assigned address

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

76
 Provisioning
Supported ROMMON Variables

2. Stateless Address Auto-Configuration (SLAAC) address

3. Link-local address
4. Site-local address

The device uses the DHCP server-assigned address to boot an image. If the DHCPv6 server fails to assign an
address, the device tries to use the SLAAC address. If both the DHCP server-assigned address and the SLAAC
address are not available, the device uses the link-local address. However, the remote FTP/HTTP/TFTP servers
must be on the same local subnet as that of the device for the image copy to succeed.
If the first three addresses are not available, the device uses the automatically generated site-local address.

Supported ROMMON Variables

The following ROMMON variables are supported in Cisco IOS XE Fuji 16.8.1:
• BAUD: Changes the device console BAUD rate to one of the Cisco standard baud rate; such as 1200,
2400, 4800, 9600, 19200, 38400, 57600, and 115200). Any invalid value will be rejected. If the BAUD
variable is not set, the default will be 9600. The corresponding CLI command is
• ENABLE_BREAK: Enables a rommon break. The default value is NO.
• MANUAL_BOOT: If manual boot is set to 1, the rommon or device prompt is activated. If manual boot
is set to 0, the device is reloaded; but rommon mode is not activated.
• SWITCH_IGNORE_STARTUP_CFG: If the value is 1, it causes the device to ignore the startup
configuration. If the value is not set, the value is treated as zero. This is a read-only variable, and can
only be modified by IOS.

iPXE-Supported DHCP Options

iPXE boot supports the following DHCPv4 and DHCPv6 options in rommon mode.

Note Catalyst 9000 Series Switches support DHCP Option 60, Option 77, DHCPv6 Options 1, Option 15,
and Option 16. DHCP Option 61 is only supported on Catalyst 9300 and 9500 Series Switches.

• DHCP Option 60—Vendor Class Identifier. This option is populated with the value of the ROMMON
environment variable MODEL_NUM.
• DHCP Option 61—Client Identifier. This option is populated with the value of theROMMON environment
variable SYSTEM_SERIAL_NUM.

Note This option is not supported on Catalyst 9400 Series Switches.

• DHCP Option 77—User Class Option. This option is added to a DHCP Discover packet, and contains
the value equal to the string iPXE. This option helps to isolate iPXE DHCP clients looking for an image
to boot from a DHCP server.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

77
 Provisioning
iPXE-Supported DHCP Options

The following is sample DHCPv4 configuration from the ISC DHCP Server that displays the use of
Option 77. The if condition in this sample implies that if Option 77 exists, and is equal to the string iPXE,
then advertise the Boot File URI for the image.

host Switch2 {
fixed-address 192.168.1.20 ;
hardware ethernet CC:D8:C1:85:6F:11 ;
#user-class = length of string + ASCII code for iPXE
if exists user-class and option user-class = 04:68:50:58:45 {
filename "http://192.168.1.146/test-image.bin"
}
}

• DHCPv6 Option 1—Client Identifier Option. This option is populated with the value of the ROMMON
environment variable SYSTEM_SERIAL_NUM as specified in RFC 3315. The recommended format
for the ROMMON environment variable is MAC_ADDR.
• DHCPv6 Option 15—User Class Option. This option is the IPv6 User Class option in a DHCPv6 solicit
message, and is populated with the string, iPXE. The following sample shows Option 15 defined in the
ISC DHCP server:

option dhcp6.user-class code 15 = string ;

The following is a sample DHCP Server configuration that uses the DHCPv6 Option 15:

#Client-specific parameters
host switch1 {
#assigning a fixed IPv6 address
fixed-address6 2001:DB8::CAFE ;
#Client DUID in hexadecimal format contains: DUID-type"2" + "EN=9" + "Chassis
serial number"
host-identifier option dhcp6.client-id 00:02:00:00:00:09:46:4F:43:31:38:33:
31:58:31:41:53;
#User class 00:04:69:50:58:45 is len 4 + "iPXE"
if option dhcp6.user-class = 00:04:69:50:58:45 {
option dhcp6.bootfile-url
"http://[2001:DB8::461/platform-pxe/edi46/test-image.bin";
}
}

• DHCPv6 Option 16—Vendor Class Option. Contains the device product ID (PID). The PID can be
determined from the output of the show inventory command or from the MODEL_NUM rommon
variable. Option 16 is not a default option in the ISC DHCP Server and can be defined as follows:

option dhcp6.vendor-class-data code 16 = string;

The following sample configuration illustrates the use of DHCPv6 Option 16:

# Source: dhcpd6ConfigPD

host host1-ipxe6-auto-host1 {
fixed-address6 2001:DB8::1234;
host-identifier option dhcp6.client-id 00:02:00:00:00:09:46:4F:
43:31:38:33:31:58:31:41:53;
if option dhcp6.vendor-class-data = 00:00:00:09:00:0E:57:53:2D:
43:33:38:35:30:2D:32:34:50:2D:4D {
option dhcp6.bootfile-url

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

78
 Provisioning
DHCPv6 Unique Identifiers

"http://[2001:DB8::46]/platform-pxe/host1/17jan-polaris.bin";

The table below describes the significant fields shown in the display.

Table 3: Sample Output Field Descriptions

Field Description

dhcp6.client-id DHCP Unique Identifier (DUID) to identify the

client.

dhcp6.user-class DHCPv6 Option 15, the User Class option

dhcp6.vendor-class-data DHCPv6 Option 16, the Vendor Class option that

contains the switch Product ID (PID).

dhcp6.bootfile-url DHCPv6 Option 6 to request for the Boot File URI

DHCPv6 Unique Identifiers

There are three types of DHCPv6 Identifiers (DUIDs) defined by RFC 3315; these are:
• DUID-LLT—DUID Link Layer address plus time, this is the link layer address of the network interface
connected to the DHCP device plus the time stamp at which it is generated.
• DUID-EN—EN stands for Enterprise Number, this DUID is based on vendor-assigned unique ID.
• DUID-LL—DUID formed using the Link Layer address of any network interface that is permanently
connected to the DHCP (client/server) device.

Cisco devices that support this feature use the DUID-EN (DUID Type 2) to identify the DHCP client (that is
the device in the DHCPv6 Solicit packet). Catalyst 9000 Series Switches support not only DUID-EN, but also
DUID-LL (DUID Type 3). DUID-EN is the preferred type; however, if switches are unable to create it, then
DUID-LL is constructed and used.

How to Configure iPXE

Configuring iPXE
SUMMARY STEPS
1. enable
2. configure terminal
3. • boot ipxe forever [switch number]
• boot ipxe timeout seconds [switch number]
4. boot system {switch switch-number | all} {flash: | ftp: | http: | usbflash0 | tftp:}
5. end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

79
 Provisioning
Configuring Device Boot

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 • boot ipxe forever [switch number] Configures the BOOTMODE rommon variable.
• boot ipxe timeout seconds [switch number] • The forever keyword configures the BOOTMODE
Example: rommon variable as IPXE-FOREVER.
Device(config)# boot ipxe forever switch 2 • The timeout keyword configures the BOOTMODE
Example: rommon variable as IPXE-TIMEOUT.
Device(config)# boot ipxe timeout 30 switch 2

Step 4 boot system {switch switch-number | all} {flash: | ftp: | Boots an image from the specified location.
http: | usbflash0 | tftp:}
• You can either use an IPv4 or an IPv6 address for the
Example: remote FTP/HTTP/TFTP servers.
Device(config)# boot system switch 1
http://192.0.2.42/image-filename
• You must enter the IPv6 address inside the square
brackets (as per RFC 2732); if not the device will not
or boot.
Device(config)# boot system switch 1
http://[2001:db8::1]/image-filename

Step 5 end Exits global configuration mode and returns to privileged

EXEC mode.
Example:
Device(config)# end

Configuring Device Boot

You can either use the no boot ipxe or the default boot ipxe command to configure device boot.

SUMMARY STEPS
1. enable
2. configure terminal
3. • no boot ipxe
• default boot ipxe
4. end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

80
 Provisioning
Configuration Examples for iPXE

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 • no boot ipxe Configures device boot. The default bot mode is device
• default boot ipxe boot.
Example: Enables default configuration on the device.
Device(config)# no boot ipxe

Example:
Device(config)# default boot ipxe

Step 4 end Exits global configuration mode and returns to privileged

EXEC mode.
Example:
Device(config)# end

Configuration Examples for iPXE

Example: iPXE Configuration
The following example shows that iPXE is configured to send DHCP requests forever until the device
boots with an image:
Device# configure terminal
Device(config)# boot ipxe forever switch 2
Device(config)# end

The following example shows how to configure the boot mode to ipxe-timeout. The configured
timeout is 200 seconds. If an iPXE boot failure occurs after the configured timeout expires, the
configured device boot is activated. In this example, the configured device boot is
http://[2001:db8::1]/image-filename.
Device# configure terminal
Device(config)# boot ipxe timeout 200 switch 2
Device(config)# boot system http://[2001:db8::1]/image-filename
Device(config)# end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

81
 Provisioning
Sample iPXE Boot Logs

Sample iPXE Boot Logs

The following are sample boot logs from a device in rommon mode. Here, manual boot using the
ipxe-timeout command is configured:
switch: boot

pxemode:(ipxe-timeout) 60s timeout

00267.887 ipxe_get_booturl: Get URL from DHCP; timeout 60s
00267.953 ipxe_get_booturl: trying DHCPv6 (#1) for 10s
IPv4:
ip addr 192.168.1.246
netmask 255.255.255.0
gateway 192.168.1.46
IPv6:
link-local addr fe80::ced8:c1ff:fe85:6f00
site-local addr fec0::ced8:c1ff:fe85:6f00
DHCP addr 2001:db8::cafe
router addr fe80::f29e:63ff:fe42:4756
SLAAC addr 2001:db8::ced8:c1ff:fe85:6f00 /64
Common:
macaddr cc:d8:c1:85:6f:00
dns 2001:db8::46
bootfile
http://[2001:DB8::461/platform-pxe/edi46/17jan-dev.bin--13103--2017-Feb28--13-54-50
domain cisco.com
00269.321 ipxe_get_booturl: got URL
(http://[2001:DB8::461/platform-pxe/edi46/17jan-dev.bin--13103--2017-Feb-28--13-54-50)
Reading full image into memory ….….….….….….….….….….….….….….….….….….….….…...
Bundle Image
––––––––––––––––––––––––––––––––––––––––––––––-
Kernel Address : 0x5377a7e4
Kernel Size : 0x365e3c/3563068
Initramfs Address : 0x53ae0620
Initramfs Size : 0x13a76f0/20608752
Compression Format: mzip

Sample DHCPv6 Server Configuration for iPXE

The following is a sample DHCPv6 server configuration taken from an Internet Systems Consortium
(ISC) DHCP Server for reference. The lines preceded by the character #, are comments that explain
the configuration that follows.

Default-least-time 600;
max-lease-time-7200;
log-facility local7;

#Global configuration
#domain search list
option dhcp6.domain-search "cisco.com" ;
#User-defined options:new-name code new-code = definition ;
option dhcp6.user-class code 15 = string ;
option dhcp6.vendor-class-data code 16 = string;

subnet6 2001:db8::/64 {
#subnet range for clients requiring an address
range6 2001:db8:0000:0000::/64;

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

82
Provisioning
Sample DHCPv6 Server Configuration for iPXE

#DNS server options

option dhcp6.name-servers 2001:db8::46;

}
#Client-specific parameters
host switch1 {
#assigning a fixed IPv6 address
fixed-address6 2001:DB8::CAFE ;
#Client DUID in hexadecimal that contains: DUID-type "2" + "EN=9" + "Chassis serial
number"
host-identifier option dhcp6.client-id 00:02:00:00:00:09:46:4F:43:31:38:33:
31:58:31:41:53;
option dhcp6.bootfile-url "http://[2001:DB8::461/platform-pxe/edi46/test-image.bin";
}

For more information on DHCP server commands, see the ISC DHCP Server website.
In this sample configuration, the dhcp6.client-id option identifies the switch, and it is followed by
the Enterprise Client DUID. The client DUID can be broken down for understanding as 00:02 +
00:00:00:09 + chassis serial number in hexadecimal format, where 2 refers to the Enterprise Client
DUID Type, 9 refers to the reserved code for Cisco’s Enterprise DUID, followed by the ASCII code
for the Chassis serial number in hexadecimal format. The chassis serial number for the switch in this
sample is FOC1831X1AS.
The Boot File URI is advertised to the switch only using the specified DUID.
The DHCPv6 Vendor Class Option 16 can also be used to identify the switch on the DHCP Server.
To define Option 16 as a user-defined option, configure the following:

option dhcp6.vendor-class-data code 16 = string;

The following is a sample DHCP server configuration that identifies the switch based on the DHCPv6
Vendor Class Option 16 that is formed by using the switch Product ID:

# Source: dhcp6ConfigPID

host edi-46-ipxe6-auto-edi46 {
fixed-address6 2001:DB8::1234;
host-identifier option dhcp6.client-id 00:02:00:00:00:09:
46:4F:43:31:38:33:31:58:31:58:31:41:53;
if option dhcp6.vendor-class-data = 00:00:00:09:00:0E:57:
53:2D:43:33:38:35:30:2D:32:34:50:2D:4C {
option dhcp6.bootfile-url "http://[2001:DB8::461/platform-pxe/edi46/17jan-dev.bin";
}
}

In this sample configuration, the dhcp6.vendor-class-data option refers to the DHCPv6 Option 16.
In the dhcp6.vendor-class-data, 00:00:00:09 is Cisco’s Enterprise DUID, 0E is the length of the PID,
and the rest is the PID in hexadecimal format. The PID can also be found from the output of the
show inventory command or from the CFG_MODEL_NUM rommon variable. The PID used in
this sample configuration is WS-C3850-24P-L.
DHCPv6 options and DUIDs in the server configuration must be specified in the hexadecimal format,
as per the ISC DHCP server guidelines.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

83
 Provisioning
Troubleshooting Tips for iPXE

Troubleshooting Tips for iPXE

This section provides troubleshooting tips.
• When iPXE boot is enabled on power up, the device first attempts to send a DHCPv6 Solicit message,
followed by a DHCPv4 Discover message. If boot mode is ipxe-forever the device keeps iterating
between the two forever.
• If the boot-mode is iPXE timeout, the device first sends a DHCPv6 Solicit message, and then a DHCPv4
Discover message, and the device falls back to device boot after the timeout expires.
• To interrupt iPXE boot, send a serial break to the console.
When using a UNIX telnet client, type CTRL-] and then send break. When you are using a different
TELNET client, or you are directly attached to a serial port, sending a break may be triggered by a
different keystroke or command.
• If the DHCP server responds with an image, but the DNS server cannot resolve the hostname, enable
DNS debugs.

Note We recommend the use of ISC DHCP server. This feature has not been
verified on IOS DHCP.

• To test the HTTP server connectivity, use HTTP copy to copy a small sample file from your HTTP server
to your device. For example, at the rommon prompt, enter copy http://192.168.1.1/test null: (the flash
is normally locked and you need to use the null device for testing) or http://[2001:db8::99]/test.
• When manual boot is enabled, and boot mode is ipxe-timeout, the device will not automatically boot on
power up. Issue the boot command in rommon mode. To automate the boot process on power up, disable
manual boot.
• Use the net6-show command to display the current IPv6 parameters, including IPv6 addresses and the
default router in rommon mode

Note On Catalyst 9000 Series Switches, use the net-show show command.

• Use the net-dhcp or the net6-dhcp commands based on your configuration, The net-dhcp command is
a test command for DHCPv4 and the net6-dhcp command is for DHCPv6.

Note On Catalyst 9000 Series Switches, use the net-dhcp -6 command for
DHCPv6.

• Use the dig command to resolve names.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

84
 Provisioning
Additional References for iPXE

Note On Catalyst 9000 Series Switches, use the dns-lookup commmand to resolve
names.

• Enable HTTP debug logs to view the HTTP response code from the web server.
• If Stateless Address Auto-Configuration (SLAAC) addresses are not generated, there is no router that is
providing IPv6 RA messages. iPXE boot for IPv6 can still work but only with link or site-local addresses.

Additional References for iPXE

Related Documents

Related Topic Document Title

Programmability commands Programmability Command Reference, Cisco IOS XE Everest
16.6.1

Standards and RFCs

Standard/RFC Title
RFC 3315 Dynamic Host Configuration Protocol for IPv6 (DHCPv6)

RFC 3986 Uniform Resource Identifier (URI): Generic Syntax

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for iPXE

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

85
 Provisioning
Feature Information for iPXE

Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Table 4: Feature Information for iPXE

Feature Name Release Feature Information

iPXE Cisco IOS XE Denali 16.5.1a Network Bootloaders support booting from an
IPv4/IPv6 device-based or network-based
source. A network boot source must be
detected automatically by using an iPXE-like
solution.
This feature was implemented on the following
platforms:
• Catalyst 3650 Series Switches
• Catalyst 3850 Series Switches

Cisco IOS XE Denali 16.6.1 In Cisco IOS XE Denali 16.6.1, this feature
was implemented on the following platforms:
• Catalyst 9300 Series Switches
• Catalyst 9500 Series Switches

Cisco IOS XE Everest 16.6.2 In Cisco IOS XE Everest 16.6.2, this feature
was implemented on Cisco Catalyst 9400
Series Switches.

Cisco IOS XE Fuji 16.9.2 In Cisco IOS XE Fuji 16.9.2, this feature was
implemented on the following platforms.
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300L SKUs

Cisco IOS XE Gibraltar 16.11.1 In Cisco IOS XE Gibraltar 16.11.1, this feature
was implemented on Cisco Catalyst 9600
Series Switches.

IPXE IPv6 Support Cisco IOS XE 16.8.1a IPXE supports the IPv6 protocol.
This feature was implemented on the following
platforms:
• Catalyst 9300 Series Switches
• Catalyst 9400 Series Switches
• Catalyst 9500 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

86
PA R T II
Shells and Scripting
• Guest Shell, on page 89
• Python API, on page 119
• EEM Python Module, on page 129
 CHAPTER 4
Guest Shell
Guestshell is a virtualized Linux-based environment, designed to run custom Linux applications, including
Python for automated control and management of Cisco devices. It also includes the automated provisioning
(Day zero) of systems. This container shell provides a secure environment, decoupled from the host device,
in which users can install scripts or software packages and run them.
This module describes Guest Shell and how to enable it.
• Restrictions for Guest Shell, on page 89
• Information About the Guest Shell, on page 89
• How to Enable the Guest Shell, on page 99
• Configuration Examples for the Guest Shell, on page 109
• Additional References for Guest Shell, on page 114
• Feature Information for Guest Shell, on page 114

Restrictions for Guest Shell

• Guest Shell is not supported on Cisco Catalyst 9200L SKUs.
• NETCONF sessions cannot be established on the standby Route Processor (RP).
• Python scripts fail when running commands like the show tech-support wireless command, when the
scale is set to 2000Aps, and clients are set to 10000.
The output of commands like show tech-support wireless is huge and can cause memory exhaustion
inside the Guest Shell. When using commands with huge output, redirect the output to a file. The IOS
CLI can write the output to a file in the /bootflash/guest-share directory, and it can be accessed from the
Guest Shell.

Information About the Guest Shell

Guest Shell Overview
The Guest Shell is a virtualized Linux-based environment, designed to run custom Linux applications, including
Python, for automated control and management of Cisco devices. Using the Guest Shell, you can also install,

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

89
 Shells and Scripting
Guest Shell Software Requirements

update, and operate third-party Linux applications. The Guest Shell is bundled with the system image and
can be installed using the guestshell enable Cisco IOS command.
The Guest Shell environment is intended for tools, Linux utilities, and manageability rather than networking.
Guest Shell shares the kernel with the host (Cisco switches and routers) system. Users can access the Linux
shell of Guest Shell and update scripts and software packages in the container root filesystem. However, users
within the Guest Shell cannot modify the host file system and processes.
Guest Shell container is managed using IOx. IOx is Cisco's Application Hosting Infrastructure for Cisco IOS
XE devices. IOx enables hosting of applications and services developed by Cisco, partners, and third-party
developers in network edge devices, seamlessly across diverse and disparate hardware platforms.

Guest Shell Software Requirements

The Guest Shell container allows users to run their scripts and apps on the system. The Guest Shell container
on Intel x86 platforms will be a Linux container (LXC) with a CentOS 8.0 minimal rootfs. You can install
other Python libraries such as, Python Version 3.0 during runtime using the Yum utility in CentOS 8.0. You
can also install or update python packages using PIP.

Table 5: Guest Shell Software Requirements

Guest Shell (LXC Container)

Operating System Cisco IOS XE

Platform All supported Cisco IOS XE platforms

Guest Shell Environment • CentOS 7 supported in Cisco IOS XE Amsterdam 17.2.1

and previous releases.
• CentOS 8 supported in Cisco IOS XE Amsterdam 17.3.1
and later releases.
Note CentOS supports only Python 3.6.

Python 2.7 Supported till Cisco IOS XE Amsterdam 17.3.1

Python 3.6 Supported in Cisco IOS XE Amsterdam 17.1.1 and later

releases.
In Cisco IOS XE Amsterdam 17.1.1 and Cisco IOS XE
Amsterdam 17.2.1, Python V2 is the default. However, in
Cisco IOS XE Amsterdam 17.3.1 and later releases, Python
V3 is the default.
Note Cisco Catalyst 9200 Series Switches support
Python version 3 in Cisco IOS XE Amsterdam
17.3.1 and later releases.

Pre-installed Custom Python Libraries • Cisco Embedded Event Manager

• Cisco IOS XE CLIs
• NCCLIENT library for the NETCONF API

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

90
 Shells and Scripting
Guest Shell Security

Guest Shell (LXC Container)

Supported Rootfs SSH, Yum install, and Python PIP install

GNU C Compiler Not supported

RPM Install Supported

Architecture x86 and ARM

Guest Shell Security

Cisco provides security to ensure that users or apps in the Guest Shell do not compromise the host system.
Guest Shell is isolated from the host kernel, and it runs as an unprivileged container.

Hardware Requirements for the Guest Shell

This section provides information about the hardware requirements for supported platforms which have
variable memory configurations.

Table 6: Guest Shell Resource Requirements

Platforms Minimum Memory

Cisco 1000 Series Integrated Services Routers 4 GB

Cisco Cloud Services Router 1000V Series 4 GB

Cisco ISR 4000 Series Integrated Services Routers 8 GB DRAM (In Cisco IOS XE Fuji 16.8.1 and
previous releases.)
4GB DRAM (In Cisco IOS XE Fuji 16.8.1 and later
releases.)

All other platforms are shipped with sufficient resources to support Guest Shell.

Note Virtual-service installed applications and the Guest Shell container cannot co-exist.

Guest Shell Storage Requirements

Cisco Catalyst 9300 Series Switches and Cisco Catalyst 9500 Series Switches require 1100 MB free hard disk
space for Guest Shell to install successfully.
On Cisco 4000 Series Integrated Services Routers, the Guest Shell is installed on the Network Interface
Module (NIM)-Solid State Drive (SSD) (hard disk), if available. If the hard disk drive is available, there is
no option to select bootflash to install Guest Shell. Cisco 4000 Series Integrated Services Routers require
1100 MB free hard disk (NIM-SSD) space for Guest Shell to install successfully.
For Cisco 4000 Series Integrated Services Routers and Cisco ASR 1000 Series Aggregation Services Routers
(when an optional hard disk has been added to that router) you can only do resource resizing if you have
installed the Guest Shell on the hard disk and inserted the hard disk into the router.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

91
 Shells and Scripting
Enabling and Running the Guest Shell

Note A Guest Shell installed via bootflash does not allow you to do resource resizing using application hosting
configuration commands.

During Guest Shell installation, if enough hard disk space is not available, an error message is displayed.
The following is a sample error message on an Cisco ISR 4000 Series Integrated Services Router

% Error:guestshell_setup.sh returned error:255, message:

Not enough storage for installing guestshell. Need 1100 MB free space.

Bootflash or hard disk space can be used to store additional data by Guest Shell. On Cisco 4000 Series
Integrated Services Routers, Guest Shell has 800 MB of storage space available. Because Guest Shell accesses
the bootflash, it can use the entire space available.

Table 7: Resources Available to Guest Shell and Guest Shell Lite

Resource Default Minimum/Maximum

CPU 1% 1/100%
Note 1% is not standard; 800
CPU units/ total system
CPU units.

Memory 256 MB 256/256 MB

512 MB (Cisco Cloud Services 512/512 MB (Cisco Cloud Services
Router 1000V Series) Router 1000V Series)

Enabling and Running the Guest Shell

The guestshell enable command installs Guest Shell. This command is also used to reactivate Guest Shell,
if it is disabled.
When Guest Shell is enabled and the system is reloaded, Guest Shell remains enabled.

Note IOx must be configured before the guestshell enable command is used.

The guestshell run bash command opens the Guest Shell bash prompt. Guest Shell must already be enabled
for this command to work.

Note If the following message is displayed on the console, it means that IOx is not enabled; check the output
of the show iox-service command to view the status of IOx.

The process for the command is not responding or is otherwise unavailable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

92
 Shells and Scripting
Disabling and Destroying the Guest Shell

For more information on how to enable Guest Shell, see the "Configuring the AppGigabitEthernet Interface
for Guest Shell" and "Enabling Guest Shell on the Management Interface" sections.

Disabling and Destroying the Guest Shell

The guestshell disable command shuts down and disables Guest Shell. When Guest Shell is disabled and the
system is reloaded, Guest Shell remains disabled.
The guestshell destroy command removes the rootfs from the flash filesystem. All files, data, installed Linux
applications and custom Python tools and utilities are deleted, and are not recoverable.

Accessing Guest Shell on a Device

Network administrators can use Cisco IOS commands to manage files and utilities in the Guest Shell.
During the Guest Shell installation, SSH access is setup with a key-based authentication. The access to the
Guest Shell is restricted to the user with the highest privilege (15) in Cisco IOS. This user is granted access
into the Linux container as the guestshell Linux user, who is a sudoer, and can perform all root operations.
Commands executed through the Guest Shell are executed with the same privilege that a user has when logged
into the Cisco IOS terminal.
At the Guest Shell prompt, you can execute standard Linux commands.

Accessing Guest Shell Through the Management Port

By default, Guest Shell allows applications to access the management network. Users cannot change the
management VRF networking configurations from inside the Guest Shell.

Note For platforms without a management port, a VirtualPortGroup can be associated with Guest Shell in the
Cisco IOS configuration. For more information, see the Sample VirtualPortGroup Configuration section.

Cisco Catalyst 9200 Series Switches, Cisco Catalyst 9300 Series Switches, and Cisco Catalyst 9400 Series
Switches support the AppGigabitEthernet intterface and management interface (mgmt-if) to access Guest
Shell.
Cisco Catalyst 9500 and 9500 High-Performance Series Switches and Cisco Catalyst 9600 Series Switches
do not support AppGigabitEthernet interfaces.

Note Cisco Catalyst 9200L SKUs do not support Guest Shell.

Day Zero Guest Shell Provisioning Using Front-Panel Port or Fiber Uplink
On Day Zero, when the device has no management connectivity, and the only connectivity is either through
the front-panel port or fibre uplink port, Guest Shell is internally configured to use the available port. The
AppGigabitEthernet interface connects Guest Shell to the server.
When Guest Shell is connected to the server, the device downloads the configuration script, and configures
the device. This configuration also includes downloading, setting, and starting of the virtual machine (VM).
After the day zero configuration is complete, based on your configuration the system may reboot. Ensure that
the system boots with only the user-specific configuration.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

93
 Shells and Scripting
Stacking with Guest Shell

Guest Shell Connectivity Using the USB Port

The device uses a serial adapter to connect to multiple other devices. This serial adapter is connected through
the USB port that is present on the front panel of the device.
The VM controls the serial adapter, and if there are any changes to the connected devices that are attached to
the USB interface while VM is running, the VM is notified.

Stacking with Guest Shell

Guest Shell supports 1+1 high availability. 1+1 high availability is when one device is designated as the active,
and the other is designated as the standby. N+1 high availability is not supported.
When Guest Shell is installed, a guest-share directory is automatically created in the flash file system. This
directory is synchronized across stack members. Any files stored in the guest-share folder will be maintained
when the active device goes down and the standby takes over. To preserve up to 50 MB of data during high
availability switchover, ensure that data is placed in this directory. If the size of the guest-share folder is
more than 50 MB, it will not be synched to stack members.
During a high availability switchover, the new active device creates its own Guest Shell installation and
restores Guest Shell to the synchronized state; the old file system is not maintained. Guest Shell state is
internally synchronized across all stack members.

Cisco IOx Overview

Cisco IOx (IOs + linuX) is an end-to-end application framework that provides application-hosting capabilities
for different application types on Cisco network platforms. The Cisco Guest Shell, a special container
deployment, is one such application, that is useful in system deployment.
Cisco IOx facilitates the life cycle management of applications and data exchange by providing a set of services
that helps developers to package prebuilt applications, and host them on a target device. IOx life cycle
management includes distribution, deployment, hosting, starting, stopping (management), and monitoring of
applications and data. IOx services also include application distribution and management tools that help users
discover and deploy applications to the IOx framework.
Cisco IOx application hosting provides the following features:
• Hides network heterogeneity.
• Cisco IOx application programming interfaces (APIs) remotely manage the life cycle of applications
hosted on a device.
• Centralized application life cycle management.
• Cloud-based developer experience.

IOx Tracing and Logging Overview

IOx tracing and logging feature allows guest application to run separately on the host device that can help
reporting the logging and tracing of the data to the host. The tracing data is saved into IOx tracelog, and the
logging data is saved into the Cisco IOS syslog on the host device.
You can redirect the tracing data to the appropriate storage device on the host device which can help in
debugging of guest application.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

94
 Shells and Scripting
IOXMAN Structure

IOXMAN Structure
Each guest application, a system LXC or a KVM instance is configured with its own syslogd and logfiles
stored within a visible file system and are not accessible to the host device. To support logging data to the
Cisco IOS syslog and tracing data to IOx tracelog on the host, two serial devices, /dev/ttyS2 and /dev/ttyS3,
are designated on the guest application for delivering data to the host as shown in the following figure.
Figure 2: IOXMAN Structure

IOXMAN is a process to establish the tracing infrastructure to provide logging or tracing services for the
guest application, except Libvirt that emulates serial devices. IOXMAN is based on the lifecycle of the guest
application to enable and disable tracing service, to send logging data to the Cisco IOS syslog, to save tracing
data to IOx tracelog, and to maintain IOx tracelog for each guest application.

NETCONF Access from Guest Shell

NETCONF-YANG can be accessed from within the Guest Shell, so that users can run Python scripts and
invoke Cisco-custom package CLIs using the NETCONF protocol.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

95
 Shells and Scripting
Logging and Tracing System Flow

The Guest Shell application will establish an SSH connection without a passwordless SSH connection to the
localhost and NETCONF port, by using guestshell as the username. This username does not correspond to
any actual users configured on the device. Even if the device does have a guestshell user configured, there is
no connection to this passwordless access. Only users with PRIV15 privilege level can access NETCONF
from within the Guest Shell.
Authentication and authorization is not bypassed; instead, authentication and authorization happens while
granting access to Guest Shell. Only users with the maximum privilege are granted this access.
Users can access the NETCONF service from Guest Shell without opening any external ports. Before connecting
to the NETCONF-YANG server on the device, you must run the initializing commands in Guest Shell. These
commands are:
iosp_client -f netconf_enable guestshell <port-number> and
iosp_client -f netconf_enable_passwordless guestshell <username>

The iosp_client -f netconf_enable guestshell port-number command configures the netconf-yang ssh
local-vrf guestshell command, and blocks connections until NETCONF-YANG is up and running.
The iosp_client -f netconf_enable_passwordless guestshell <username> command creates the SSH keys
required for Guest Shell access.
To remove the NETCONF-YANG access from Guest Shell, use the following commands:
iosp_client -f netconf_disable guestshell and
iosp_client -f netconf_disable_passwordless guestshell <username>

The iosp_client -f netconf_disable guestshell command disables access to NETCONF from within the Guest
Shell; however, the NETCONF-YANG configuration will still exist. To shut down NETCONF-YANG, use
the no netconf-yang command.
The iosp_client -f netconf_disable_passwordless guestshell username command removes the SSH keys for
the specified user. The user will not be able to access NETCONF without a password; however, the user
would still be able to connect by using a password.
The netconf_enable_guestshell python API runs a combination of the iosp_client functions, iosp_client -f
netconf_enable guestshell 830 and iosp_client -f netconf_enable_passwordless guestshell guestshell. This
API hides the unfamiliar-to-user iosp_client function. When this function is called, it does not return a response
until all commands are completed. Unless the function returns an error, you can be sure that NETCONF is
running, and the passwordless setup is complete; and you can start creating connections.

Logging and Tracing System Flow

The following sections describes how the IOx logging and tracing works:

LXC Logging
1. Guest OS enables /dev/ttyS2 on the guest application.
2. Guest application writes data to /dev/ttyS2.
3. Libvirt emulates /dev/ttyS2 to /dev/pts/x on the host.
4. IOXMAN gets the emulated serial device, /dev/pts/x from the XML file.
5. IOXMAN listens and reads available data from /dev/pts/x, sets the severity for the message, filters, parses
and queues the message.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

96
Shells and Scripting
Logging and Tracing System Flow

6. Start timer to send the message to /dev/log device on the host using errmsg.
7. Data is saved to the Cisco IOS syslog.

KVM Logging
1. Guest OS enables /dev/ttyS2 on the guest application.
2. Guest application writes data to /dev/ttyS2.
3. Libvirt emulates /dev/ttyS2 to /dev/pts/x on the host.
4. IOXMAN gets the emulated TCP path from the XML file.
5. IOXMAN opens an UNIX socket, and connects to the remote socket.
6. IOXMAN reads available data from the socket, sets the severity for the message, filters, parses, and queues
the message.
7. Starts the timer to send the message to /dev/log device on the host using errmsg.
8. Data is saved to the Cisco IOS syslog.

LXC Tracing
1. Guest OS enables /dev/ttyS3 on the guest application.
2. Configures syslogd to copy message to /dev/ttyS3.
3. Guest application writes data to /dev/ttyS3.
4. Libvirt emulates /dev/ttyS3 to /dev/pts/y on the host.
5. IOXMAN gets the emulated serial device, /dev/pts/y from the XML file.
6. IOXMAN listens and reads available data from /dev/pts/y, filters, parses, and saves the message to IOx
tracelog.
7. If IOx tracelog is full, IOXMAN rotates the tracelog file to /bootflash/tracelogs.

KVM Tracing
1. Guest OS enables /dev/ttyS3 on the guest application.
2. Configures syslog to copy the message to /dev/ttyS3.
3. Guest application writes data to /dev/ttyS3.
4. Libvirt emulates /dev/ttyS3 to TCP path on the host.
5. IOXMAN gets the emulated TCP path from the XML file.
6. IOXMAN opens an UNIX socket, and connects to the remote socket.
7. IOXMAN reads the available data from the socket, sets the severity level for the message, filters, parses,
and saves the message to IOx tracelog.
8. If IOx tracelog is full, IOXMAN rotates the tracelog file to /bootflash/tracelogs.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

97
 Shells and Scripting
Logging and Tracing of Messages

Logging and Tracing of Messages

The following sections explains the logging and tracing of messages in to the Cisco IOS syslog.

Logging Messages in Cisco IOS Syslog

For any logging messages received from a guest application, IOXMAN sets the severity of the message to
NOTICE by default, before sending it to the Cisco IOS syslog. When a message is received by IOSd, it is
displayed on the console and saved on the syslog in the following message format:
*Apr 7 00:48:21.911: %IM-5-IOX_INST_NOTICE:ioxman: IOX SERVICE guestshell LOG: Guestshell
test
To comply with the Cisco IOS syslog, the IOXMAN does support severity levels for logging messages. To
report logging messages with severity, a guest application must append a header to the front of the message.
[a123b234,version,severity]

a123b234 is magic number.

Version: severity support version. Current version is 1.
Severity: CRIT is 2
ERR is 3
WARN is 4
NOTICE is 5
INFO is 6
DEBUG is 7

The following is an example of a message log:

echo “[a123b234,1,2]Guestshell failed” > /dev/ttyS2

Perform the following steps to report logging data from a guest application to the Cisco IOS syslog:
1. If you are using C programming, use write() to send logging data to the host.
#define SYSLOG_TEST “syslog test”
int fd;
fd = open("/dev/ttyS2", O_WRONLY);
write(fd, SYSLOG_TEST, strlen(SYSLOG_TEST));
close(fd);

2. If you are using a Shell console, use echo to send logging data to the host.
echo “syslog test” > /dev/ttyS2

Tracing Message to IOx Tracelog

Perform the following steps to report tracing messages from a guest application to IOx tracelog:
1. If you are using C programming, use write() to send tracing message to the host.
#define SYSLOG_TEST “tracelog test”
int fd;
fd = open("/dev/ttyS3", O_WRONLY);
write(fd, SYSLOG_TEST, strlen(SYSLOG_TEST));
close(fd);

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

98
 Shells and Scripting
How to Enable the Guest Shell

2. If you are using C programming, use syslog() to send tracing message to the host.
#define SYSLOG_TEST “tracelog test”

syslog(LOG_INFO, “%s\n”, SYSLOG_TEST);

3. If you are using a Shell console, use echo to send tracing data to the host.
echo “tracelog test” > /dev/ttyS3
or
logger “tracelog test”

How to Enable the Guest Shell

Managing IOx
Before you begin
IOx takes upto two minutes to start. CAF, IOXman, and Libvirtd services must be running to enable Guest
Shell successfully.

SUMMARY STEPS
1. enable
2. configure terminal
3. iox
4. exit
5. show iox-service
6. show app-hosting list

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 iox Configures IOx services.

Example:
Device(config)# iox

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

99
 Shells and Scripting
Managing the Guest Shell

Command or Action Purpose

Step 4 exit Exits global configuration mode and returns to privileged
EXEC mode.
Example:
Device(config)# exit

Step 5 show iox-service Displays the status of the IOx service

Example:
Device# show iox-service

Step 6 show app-hosting list Displays the list of app-hosting services enabled on the
device.
Example:
Device# show app-hosting list

Example
The following is sample output from the show iox-service command:

Device# show iox-service

IOx Infrastructure Summary:

---------------------------
IOx service (CAF) 1.10.0.0 : Running
IOx service (HA) : Running
IOx service (IOxman) : Running
IOx service (Sec storage) : Not Running
Libvirtd 1.3.4 : Running
Dockerd 18.03.0 : Running
Application DB Sync Info : Available
Sync Status : Disabled

The following is sample output from the show app-hosting list command:

Device# show app-hosting list

App id State
------------------------------------------------------
guestshell RUNNING

Managing the Guest Shell

Note VirtualPortGroups are supported only on routing platforms.

Before you begin

IOx must be configured and running for Guest Shell access to work. If IOx is not configured, a message to
configure IOx is displayed. Removing IOx removes access to the Guest Shell, but the rootfs remains unaffected.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

100
 Shells and Scripting
Managing the Guest Shell

An application or management interface must also be configured to enable and operate Guest Shell. See
"Configuring the AppGigabitEthernet Interface for Guest Shell" and "Enabling Guest Shell on the Management
Interface" sections for more information on enabling an interface for Guest Shell.

SUMMARY STEPS
1. enable
2. guestshell enable
3. guestshell run linux-executable
4. guestshell run bash
5. guestshell disable
6. guestshell destroy

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 guestshell enable Enables the Guest Shell service.

Example: Note • The guestshell enable command uses the
Device# guestshell enable management virtual routing and forwarding
(VRF) instance for networking.
• When using VirtualPortGroups (VPGs) for
front panel networking, the VPG must be
configured first.
• The guest IP address and the gateway IP
address must be in the same subnet.

Step 3 guestshell run linux-executable Executes or runs a Linux program in the Guest Shell.
Example: Note In Cisco IOS XE Amsterdam 17.3.1 and later
Device# guestshell run python releases, only Python version 3 is supported.
or
Device# guestshell run python3

Step 4 guestshell run bash Starts a Bash shell to access the Guest Shell.
Example:
Device# guestshell run bash

Step 5 guestshell disable Disables the Guest Shell service.

Example:
Device# guestshell disable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

101
 Shells and Scripting
Managing the Guest Shell Using Application Hosting

Command or Action Purpose

Step 6 guestshell destroy Deactivates and uninstalls the Guest Shell service.
Example:
Device# guestshell destroy

Managing the Guest Shell Using Application Hosting

Note This section is applicable to Cisco routing platforms. VirtualPortGroups are not supported on Cisco
Catalyst Switching platforms.

IOx must be configured and running for Guest Shell access to work. If IOx is not configured, a message to
configure IOx is displayed. Removing IOx removes access to the Guest Shell, but the rootfs remains unaffected.

Note Use this procedure (Managing the Guest Shell Using Application Hosting) to enable the Guest Shell in
Cisco IOS XE Fuji 16.7.1 and later releases. For Cisco IOS XE Everest 16.6.x and previous releases,
use the procedure in Managing the Guest Shell, on page 100.

Device(config)# interface GigabitEthernet1

Device(config-if)# ip address dhcp
Device(config-if)# ip nat outside
Device(config-if)# exit

Device(config-if)# interface VirtualPortGroup0

Device(config-if)# ip address 192.168.35.1 255.255.255.0
Device(config-if)# ip nat inside
Device(config-if)# exit

Device(config)# ip nat inside source list GS_NAT_ACL interface GigabitEthernet1 overload

Device(config)# ip access-list standard GS_NAT_ACL
Device(config)# permit 192.168.0.0 0.0.255.255

Device(config)# app-hosting appid guestshell

Device(config-app-hosting)# app-vnic gateway1 virtualportgroup 0 guest-interface 0
guest-ipaddress 192.168.35.2
netmask 255.255.255.0 gateway 192.168.35.1 name-server 8.8.8.8 default
Device(config-app-hosting)# app-resource profile custom cpu 1500 memory 512
Device(config-app-hosting)# end

Device# guestshell enable

Device# guestshell run python

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

102
 Shells and Scripting
Configuring the AppGigabitEthernet Interface for Guest Shell

Figure 3: Managing the Guest Shell using Application Hosting

For front panel networking, you must configure the GigabitEthernet and VirtualPortGroup interfaces as shown
above. The Guest Shell uses a Virtualportgroup as the source interface to connect to the outside network
through NAT.
The following commands are used to configure inside NAT. They allow the Guest Shell to reach the internet;
for example, to obtain Linux software updates:
ip nat inside source list
ip access-list standard
permit

The guestshell run command in the example above, runs a python executable. You can also use the guestshell
run command to run other Linux executables; for example, see the example guestshell run bash command,
which starts a Bash shell or the guestshell disable command which shuts down and disables the Guest Shell.
If the system is later reloaded, the Guest Shell remains disabled.

Configuring the AppGigabitEthernet Interface for Guest Shell

Note The following task is applicable only to Catalyst switches that have the AppGigabitEthernet interface.
All other Catalyst switches use the management port.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

103
 Shells and Scripting
Configuring the AppGigabitEthernet Interface for Guest Shell

SUMMARY STEPS
1. enable
2. configure terminal
3. interface AppGigabitEthernet interface-number
4. switchport mode trunk
5. exit
6. app-hosting appid name
7. app-vnic AppGigabitEthernet trunk
8. vlan vlan-ID guest-interface guest-interface-number
9. guest-ipaddress ip-address netmask netmask
10. exit
11. exit
12. app-default-gateway ip-address guest-interface network-interface
13. nameserver# ip-address
14. end
15. guestshell enable

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 interface AppGigabitEthernet interface-number Configures the AppGigabitEthernet interface and enters
interface configuration mode.
Example:
Device(config)# interface AppGigabitEthernet 1/0/1

Step 4 switchport mode trunk Sets the interface into permanent trunking mode and
negotiates to convert the neighboring link into a trunk link.
Example:
Device(config-if)# switchport mode trunk

Step 5 exit Exits interface configuration mode and returns to global

configuration mode.
Example:
Device(config-if)# exit

Step 6 app-hosting appid name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid guestshell

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

104
 Shells and Scripting
Configuring the AppGigabitEthernet Interface for Guest Shell

Command or Action Purpose

Step 7 app-vnic AppGigabitEthernet trunk Configures a trunk port as the front-panel port for
application hosting, and enters application-hosting trunk
Example:
configuration mode.
Device(config-app-hosting)# app-vnic
AppGigabitEthernet trunk

Step 8 vlan vlan-ID guest-interface guest-interface-number Configures a VLAN guest interface and enters
application-hosting VLAN-access IP configuration mode.
Example:
Device(config-config-app-hosting-trunk)# vlan 4094
guest-interface 0

Step 9 guest-ipaddress ip-address netmask netmask (Optional) Configures a static IP address.

Example:
Device(config-config-app-hosting-vlan-access-ip)#
guest-ipaddress 192.168.2.2 netmask 255.255.255.0

Step 10 exit Exits application-hosting VLAN-access IP configuration

mode and returns to application-hosting trunk configuration
Example:
mode
Device(config-config-app-hosting-vlan-access-ip)#
exit

Step 11 exit Exits application-hosting trunk configuration mode and

returns to application-hosting configuration mode.
Example:
Device(config-config-app-hosting-trunk)# exit

Step 12 app-default-gateway ip-address guest-interface Configures the default management gateway.

network-interface
Example:
Device(config-app-hosting)# app-default-gateway
192.168.2.1 guest-interface 0

Step 13 nameserver# ip-address Configures the Domain Name System (DNS) server.
Example:
Device(config-app-hosting)# name-server0
172.16.0.1

Step 14 end Exits application-hosting configuration mode and returns

to privileged EXEC mode.
Example:
Device(config-app-hosting)# end

Step 15 guestshell enable Enables the Guest Shell service.

Example:
Device# guestshell enable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

105
 Shells and Scripting
Enabling Guest Shell on the Management Interface

Enabling Guest Shell on the Management Interface

Note This task is applicable to Cisco Catalyst 9200 Series Switches, Cisco Catalyst 9300 Series Switches,
Cisco Catalyst 9400 Series Switches, Cisco Catalyst 9500 Series Switches, and Cisco Catalyst 9600
Series Switches.

SUMMARY STEPS
1. enable
2. configure terminal
3. app-hosting appid name
4. app-vnic management guest-interface interface-number
5. end
6. show app-hosting list
7. guestshell enable

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 app-hosting appid name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid guestshell

Step 4 app-vnic management guest-interface interface-number Configures the management gateway of the virtual network
interface and guest interface, and enters application-hosting
Example:
management-gateway configuration mode.
Device(config-app-hosting)# app-vnic management
guest-interface 0

Step 5 end Exits application-hosting management-gateway

configuration mode and returns to privileged EXEC mode.
Example:
Device(config-app-hosting-mgmt-gateway)# end

Step 6 show app-hosting list Displays the current status of the installed applications.
Example: Note Guest Shell is displayed in the list of
Device# show app-hosting list applications, only if it is installed.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

106
 Shells and Scripting
Enabling and Disabling NETCONF Access from Guest Shell

Command or Action Purpose

Step 7 guestshell enable Enables the Guest Shell service.
Example:
Device# guestshell enable

Enabling and Disabling NETCONF Access from Guest Shell

Before you begin
Initialize the following commands from within the Guest Shell to initialize the NETCONF-YANG access:

SUMMARY STEPS
1. iosp_client -f netconf_enable guestshell port-number
2. iosp_client -f netconf_enable_passwordless guestshell username
3. iosp_client -f netconf_disable guestshell
4. iosp_client -f netconf_disable_passwordless guestshell username

DETAILED STEPS

Command or Action Purpose

Step 1 iosp_client -f netconf_enable guestshell port-number Configures the netconf-yang ssh local-vrf guestshell
command, and blocks connections until NETCONF-YANG
Example:
is up and running.
Guest Shell: iosp_client -f netconf_enable
guestshell 3

Step 2 iosp_client -f netconf_enable_passwordless guestshell Creates the SSH keys required for Guest Shell access.
username
Example:
Guest Shell: iosp_client -f netconf_enable
guestshell guestshell

Step 3 iosp_client -f netconf_disable guestshell Removes access to NETCONF from within the Guest Shell.
Example: • NETCONF-YANG configuration will still exist. To
GuestShell: iosp_client -f netconf_disable shut down NETCONF-YANG use the no
guestshell netconf-yang command.

Step 4 iosp_client -f netconf_disable_passwordless guestshell Removes the access keys for the specified user.
username
• NETCONF access is still enabled for the user; however
Example: the user will have to use a password to connect to
Guest Shell: iosp_client -f NETCONF.
netconf_disable_passwordless guestshell guestshell

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

107
 Shells and Scripting
Accessing the Python Interpreter

Example

Accessing the Python Interpreter

Python can be used interactively or Python scripts can be run in the Guest Shell. Use the guestshell run
python command to launch the Python interpreter in Guest Shell and open the Python terminal.

Note In releases prior to Cisco IOS XE Amsterdam 17.3.1, Python V2 is the default. Python V3 is supported
in Cisco IOS XE Amsterdam 17.1.1, and Cisco IOS XE Amsterdam 17.2.1. In Cisco IOS XE Amsterdam
17.3.1 and later releases, Python V3 is the default.

In Releases Prior to Cisco IOS XE Amsterdam 17.3.1

The guestshell run command is the Cisco IOS equivalent of running Linux executables, and when running
a Python script from Cisco IOS, specify the absolute path. The following example shows how to specify the
absolute path for the command:

Guestshell run python /flash/guest-share/sample_script.py parameter1 parameter2

The following example shows how to enable Python on a Cisco Catalyst 3650 Series Switch or a Cisco Catalyst
3850 Series Switch:

Device# guestshell run python

Python 2.7.11 (default, March 16 2017, 16:50:55)

[GCC 4.7.0] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>>>

The following example shows how to enable Python on a Cisco ISR 4000 Series Integrated Services Router:

Device# guestshell run python

Python 2.7.5 (default, Jun 17 2014, 18:11:42)

[GCC 4.8.2 20140120 (Red Hat 4.8.2-16)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>>>

In Cisco IOS XE Amsterdam 17.3.1 and Later Releases

The following example shows how to enable Python on Cisco Catalyst 9000 Series Switches:

Device# guestshell run python3

Python 3.6.8 (default, Nov 21 2019, 22:10:21)

[GCC 8.3.1 20190507 (Red Hat 8.3.1-4)] on linux
Type "help", "copyright", "credits" or "license" for more information.>>>>>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

108
 Shells and Scripting
Configuration Examples for the Guest Shell

Configuration Examples for the Guest Shell

Example: Managing the Guest Shell

In Cisco IOS XE Amsterdam 17.1.x to Cisco IOS XE Amsterdam 17.2.x

The following example shows how to enable Guest Shell. In Cisco IOS XE Amsterdam 17.1.x and
Cisco IOS XE Amsterdam 17.2.x, both Python V2.7 and Python V3.6 are supported. However,
Python V2.7 is the default in these releases.

Device> enable
Device# guestshell enable

Management Interface will be selected if configured

Please wait for completion
Guestshell enabled successfully

Device# guestshell run python

or
Device# guestshell run python3

Python 2.7.5 (default, Jun 17 2014, 18:11:42)

[GCC 4.8.2 20140120 (Red Hat 4.8.2-16)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>>>

Device# guestshell run bash

[guestshell@guestshell ~]$

Device# guestshell disable

Guestshell disabled successfully

Device# guestshell destroy

Guestshell destroyed successfully

In Cisco IOS XE Amsterdam 17.3.1 and Later Releases

The following example shows how to enable Guest Shell. In Cisco IOS XE Amsterdam 17.3.1 and
later releases, only Python V3.6 is supported.

Device> enable
Device# guestshell enable

Management Interface will be selected if configured

Please wait for completion
Guestshell enabled successfully

Device# guestshell run python3

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

109
 Shells and Scripting
Sample VirtualPortGroup Configuration

Python 3.6.8 (default, Nov 21 2019, 22:10:21)

[GCC 8.3.1 20190507 (Red Hat 8.3.1-4)] on linux
Type "help", "copyright", "credits" or "license" for more information.>>>>>

>>>>>

Device# guestshell run bash

[guestshell@guestshell ~]$

Device# guestshell disable

Guestshell disabled successfully

Device# guestshell destroy

Guestshell destroyed successfully

Sample VirtualPortGroup Configuration

Note VirtualPortGroups are supported only on Cisco routing platforms.

When using the VirtualPortGroup interface for Guest Shell networking, the VirtualPortGroup interface
must have a static IP address configured. The front port interface must be connected to the Internet
and Network Address Translation (NAT) must be configured between the VirtualPortGroup and the
front panel port.
The following is a sample VirtualPortGroup configuration:

Device> enable
Device# configure terminal
Device(config)# interface VirtualPortGroup 0
Device(config-if)# ip address 192.168.35.1 255.255.255.0
Device(config-if)# ip nat inside
Device(config-if)# no mop enabled
Device(config-if)# no mop sysid
Device(config-if)# exit
Device(config)# interface GigabitEthernet 0/0/3
Device(config-if)# ip address 10.0.12.19 255.255.0.0
Device(config-if)# ip nat outside
Device(config-if)# negotiation auto
Device(config-if)# exit
Device(config)# ip route 0.0.0.0 0.0.0.0 10.0.0.1
Device(config)# ip route 10.0.0.0 255.0.0.0 10.0.0.1
!Port forwarding to use ports for SSH and so on.
Device(config)# ip nat inside source static tcp 192.168.35.2 7023 10.0.12.19 7023 extendable
Device(config)# ip nat outside source list NAT_ACL interface GigabitEthernet 0/0/3 overload
Device(config)# ip access-list standard NAT_ACL
Device(config-std-nacl)# permit 192.168.0.0 0.0.255.255
Device(config-std-nacl)# exit

! App-hosting configuration
Device(config)# app-hosting appid guestshell
Device(config-app-hosting)# app-vnic gateway1 virtualportgroup 0 guest-interface 0

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

110
 Shells and Scripting
Example: Configuring the AppGigabitEthernet Interface for Guest Shell

guest-ipaddress 192.168.35.2
netmask 255.255.255.0 gateway 192.168.35.1 name-server 8.8.8.8 default
Device(config-app-hosting)# app-resource profile custom cpu 1500 memory 512
Device(config-app-hosting)# end

Device# guestshell enable

Device# guestshell run python

Example: Configuring the AppGigabitEthernet Interface for Guest Shell

Note The following task is applicable only to Catalyst switches that have the AppGigabitEthernet interface.
All other Catalyst switches use the management port.

The following example shows how to configure an AppGigabitEthernet interface for Guest Shell.
Here, VLAN 4094 creates a Network Address Translation (NAT) this is used for Guest Shell. VLAN
1 is an external interface.
Device> enable
Device# configure terminal
Device(config)# ip nat inside source list NAT_ACL interface vlan 1 overload
Device(config)# ip access-list standard NAT_ACL
Device(config-std-nacl)# permit 192.168.0.0 0.0.255.255
Device(config-std-nacl)# exit
Device(config)# vlan 4094
Device(config-vlan)# exit
Device(config)# interface vlan 4094
Device(config-if)# ip address 192.168.2.1 255.255.255.0
Device(config-if)# ip nat inside
Device(config-if)# exit
Device(config)# interface vlan 1
Device(config-if)# ip nat outside
Device(config-if)# exit
Device(config)# ip routing
Device(config)# ip route 0.0.0.0 0.0.0.0 209.165.201.1
Device(config)# interface AppGigabitEthernet 1/0/1
Device(config-if)# switchport mode trunk
Device(config-if)# exit
Device(config)# app-hosting appid guestshell
Device(config-app-hosting)# app-vnic AppGigEthernet trunk
Device(config-config-app-hosting-trunk)# vlan 4094 guest-interface 0
Device(config-config-app-hosting-vlan-access-ip)# guest-ipaddress 192.168.2.2 netmask
255.255.255.0
Device(config-config-app-hosting-vlan-access-ip)# exit
Device(config-config-app-hosting-trunk)# exit
Device(config-app-hosting)# app-default-gateway 192.168.2.1 guest-interface 0
Device(config-app-hosting)# name-server0 172.16.0.1
Device(config-app-hosting)# name-server1 198.51.100.1
Device(config-app-hosting)# end
Device# guestshell enable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

111
 Shells and Scripting
Example: Enabling Guest Shell on the Management Interface

Example: Enabling Guest Shell on the Management Interface

This example is applicable to Cisco Catalyst 9200 Series Switches, Cisco Catalyst 9300 Series Switches,
Cisco Catalyst 9400 Series Switches, Cisco Catalyst 9500 Series Switches, and Cisco Catalyst 9600 Series
Switches.
Device> enable
Device# configure terminal
Device(config)# app-hosting appid guestshell
Device(config-app-hosting)# app-vnic management guest-interface 0
Device(config-app-hosting-mgmt-gateway)# end
Device# guestshell enable

Example: Guest Shell Usage

From the Guest Shell prompt, you can run Linux commands. The following example shows the usage
of some Linux commands.

[guestshell@guestshell~]$ pwd
/home/guestshell

[guestshell@guestshell~]$ whoami
guestshell

[guestshell@guestshell~]$ uname -a
Linux guestshell 5.4.85 #1 SMP Tue Dec 22 10:50:44 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux

Cisco 4000 Series Integrated Services Routers use the dohost provided by CentOS Linux release
7.1.1503.

Note The dohost command requires the ip http server command to be configured on the device.

Example: Guest Shell Networking Configuration

The following is a sample Guest Shell networking configuration.
• Configure Domain Name System (DNS)
• Configure proxy settings
• Configure YUM or PIP to use proxy settings

Sample DNS Configuration for Guest Shell

The following is a sample DNS configuration for Guest Shell:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

112
 Shells and Scripting
Example: Configuring Proxy Environment Variables

[guestshell@guestshell ~]$ cat/etc/resolv.conf

nameserver 192.0.2.1

Other Options:
[guestshell@guestshell ~]$ cat/etc/resolv.conf
domain cisco.com
search cisco.com
nameserver 192.0.2.1
search cisco.com
nameserver 198.51.100.1
nameserver 172.16.0.6
domain cisco.com
nameserver 192.0.2.1
nameserver 172.16.0.6
nameserver 192.168.255.254

Example: Configuring Proxy Environment Variables

If your network is behind a proxy, configure proxy variables in Linux. If required, add these variables
to your environment.
The following example shows how to configure your proxy variables:

[guestshell@guestshell ~]$cat /bootflash/proxy_vars.sh

export http_proxy=http://proxy.example.com:80/
export https_proxy=http://proxy.example.com:80/
export ftp_proxy=http://proxy.example.com:80/
export no_proxy=example.com
export HTTP_PROXY=http://proxy.example.com:80/
export HTTPS_PROXY=http://proxy.example.com:80/
export FTP_PROXY=http://proxy.example.com:80/
guestshell ~] source /bootflash/proxy_vars.sh

Example: Configuring Yum and PIP for Proxy Settings

The following example shows how to use Yum for setting proxy environment variables:

cat /etc/yum.conf | grep proxy

[guestshell@guestshell~]$ cat/bootflash/yum.conf | grep proxy
proxy=http://proxy.example.com:80/

PIP install picks up environment variable used for proxy settings. Use sudo with -E option for PIP
installation. If the environment variables are not set, define them explicitly in PIP commands as
shown in following example:

sudo pip --proxy http://proxy.example.com:80/install requests

sudo pip install --trusted-bost pypi.example.com --index-url
http://pypi.example.com/simple requests

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

113
 Shells and Scripting
Additional References for Guest Shell

The following example shows how to use PIP install for Python:

Sudo -E pip install requests

[guestshell@guestshell ~]$ python
Python 2.17.11 (default, Feb 3 2017, 19:43:44)
[GCC 4.7.0] on linux2
Type "help", "copyright", "credits" or "license" for more information
>>>import requests

Additional References for Guest Shell

Related Documents

Related Topic Document Title

Python module CLI Python Module

Zero-Touch Provisioning Zero-Touch Provisioning

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for Guest Shell

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

114
Shells and Scripting
Feature Information for Guest Shell

Table 8: Feature Information for Guest Shell

Feature Name Release Feature Information

Guest Shell Cisco IOS XE Everest 16.5.1a Guest Shell is a secure container
that is an embedded Linux
Cisco IOS XE Everest 16.5.1b
environment that allows customers
to develop and run Linux and
custom Python applications for
automated control and management
of Cisco switches. It also includes
the automated provisioning of
systems. This container shell
provides a secure environment,
decoupled from the host device, in
which users can install scripts or
software packages and run them.
In Cisco IOS XE Everest 16.5.1a,
this feature was implemented on
the following platforms:
• Cisco Catalyst 3650 Series
Switches
• Cisco Catalyst 3850 Series
Switches
• Cisco Catalyst 9300 Series
Switches
• Cisco Catalyst 9500 Series
Switches

In Cisco IOS Everest 16.5.1b, this

feature was implemented on the
following platforms:
• Cisco 4000 Series Integrated
Services Routers

Cisco IOS XE Everest 16.6.2 In Cisco IOS XE Everest 16.6.2,

this feature was implemented on
Cisco Catalyst 9400 Series
Switches.

Cisco IOS XE Fuji 16.7.1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

115
 Shells and Scripting
Feature Information for Guest Shell

Feature Name Release Feature Information

In Cisco IOS XE Fuji 16.7.1, this
feature was implemented on the
following platforms:
• Cisco ASR 1000 Series
Aggregation Services Routers
• Cisco Cloud Services Router
1000v Series

In Cisco IOS XE Fuji 16.7.1, for

Guest Shell feature, the Logging
and Tracing support was
implemented on Cisco ASR 1000
Aggregation Services Routers.

Cisco IOS XE Fuji 16.8.1 In Cisco IOS XE Fuji 16.8.1, this

feature was implemented on Cisco
Catalyst 9500-High Performance
Series Switches.

Cisco IOS XE Fuji 16.9.1 In Cisco IOS XE Fuji 16.9.1, this

feature was implemented on Cisco
1000 Series Integrated Services
Routers.

Cisco IOS XE Gibraltar 16.11.1b In Cisco IOS XE Gibraltar

16.11.1b, this feature was
implemented on the following
platforms:
• Cisco Catalyst 9800-40
Wireless Controllers
• Cisco Catalyst 9800-80
Wireless Controllers

Cisco IOS XE Gibraltar 16.12.1 In Cisco IOS XE Gibraltar 16.12.1,

this feature was implemented on
the following platforms:
• Cisco Catalyst 9200 Series
Switches
Note This feature is not
supported on
C9200L SKUs.

• Cisco Catalyst 9300L SKUs

• Cisco Catalyst 9600 Series
Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

116
Shells and Scripting
Feature Information for Guest Shell

Feature Name Release Feature Information

Cisco IOS XE Amsterdam 17.3.1 In Cisco IOS XE Amsterdam
17.3.1, this feature was
implemented on the following
platforms:
• Cisco Catalyst 8200 Series
Edge Platforms
• Cisco Catalyst 8300 Series
Edge Platforms
• Cisco Catalyst 8500 and
8500L Series Edge Platforms

NETCONF Access from Guest Cisco IOS XE Bengaluru 17.6.1 NETCONF can be accessed from
Shell within the Guest Shell, so that users
can run Python scripts and invoke
Cisco-custom package CLIs using
the NETCONF protocol.
In 17.6.1, this feature was
implemented on the following
platforms:
• Cisco Catalyst 9200 Series
Switches
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series
Switches

Python 3 Support in Guest Shell Cisco IOS XE Amsterdam 17.1.1 Python Version 3.6 is supported in
Guest Shell. Python Version 3.6 is
available on all supported
platforms.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

117
 Shells and Scripting
Feature Information for Guest Shell

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

118
 CHAPTER 5
Python API
Python programmabililty supports Python APIs.
• About Python , on page 119
• Additional References for Python API, on page 127
• Feature Information for Python API, on page 127

About Python
The Cisco IOS XE devices support Python Version 2.7 in both interactive and non-interactive (script) modes
within the Guest Shell. The Python scripting capability gives programmatic access to a device's CLI to perform
various tasks and Zero Touch Provisioning or Embedded Event Manager (EEM) actions.

Cisco Python Module

Cisco provides a Python module that provides access to run EXEC and configuration commands. You can
display the details of the Cisco Python module by entering the help() command. The help() command displays
the properties of the Cisco CLI module.
The following example displays information about the Cisco Python module:

Device# guestshell run python

Python 2.7.5 (default, Jun 17 2014, 18:11:42)

[GCC 4.8.2 20140120 (Red Hat 4.8.2-16)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> >>> from cli import cli,clip,configure,configurep, execute, executep
>>> help(configure)
Help on function configure in module cli:

configure(configuration)
Apply a configuration (set of Cisco IOS CLI config-mode commands) to the device
and return a list of results.

configuration = '''interface gigabitEthernet 0/0

no shutdown'''

# push it through the Cisco IOS CLI.

try:
results = cli.configure(configuration)
print "Success!"

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

119
 Shells and Scripting
Cisco Python Module

except CLIConfigurationError as e:
print "Failed configurations:"
for failure in e.failed:
print failure

Args:
configuration (str or iterable): Configuration commands, separated by newlines.

Returns:
list(ConfigResult): A list of results, one for each line.

Raises:
CLISyntaxError: If there is a syntax error in the configuration.

>>> help(configurep)
Help on function configurep in module cli:

configurep(configuration)
Apply a configuration (set of Cisco IOS CLI config-mode commands) to the device
and prints the result.

configuration = '''interface gigabitEthernet 0/0

no shutdown'''

# push it through the Cisco IOS CLI.

configurep(configuration)

Args:
configuration (str or iterable): Configuration commands, separated by newlines.
>>> help(execute)
Help on function execute in module cli:

execute(command)
Execute Cisco IOS CLI exec-mode command and return the result.

command_output = execute("show version")

Args:
command (str): The exec-mode command to run.

Returns:
str: The output of the command.

Raises:
CLISyntaxError: If there is a syntax error in the command.

>>> help(executep)
Help on function executep in module cli:

executep(command)
Execute Cisco IOS CLI exec-mode command and print the result.

executep("show version")

Args:
command (str): The exec-mode command to run.

>>> help(cli)
Help on function cli in module cli:

cli(command)
Execute Cisco IOS CLI command(s) and return the result.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

120
 Shells and Scripting
Cisco Python Module to Execute IOS CLI Commands

A single command or a delimited batch of commands may be run. The

delimiter is a space and a semicolon, " ;". Configuration commands must be
in fully qualified form.

output = cli("show version")

output = cli("show version ; show ip interface brief")
output = cli("configure terminal ; interface gigabitEthernet 0/0 ; no shutdown")

Args:
command (str): The exec or config CLI command(s) to be run.

Returns:
string: CLI output for show commands and an empty string for
configuration commands.

Raises:
errors.cli_syntax_error: if the command is not valid.
errors.cli_exec_error: if the execution of command is not successful.

>>> help(clip)
Help on function clip in module cli:

clip(command)
Execute Cisco IOS CLI command(s) and print the result.

A single command or a delimited batch of commands may be run. The

delimiter is a space and a semicolon, " ;". Configuration commands must be
in fully qualified form.

clip("show version")
clip("show version ; show ip interface brief")
clip("configure terminal ; interface gigabitEthernet 0/0 ; no shutdown")

Args:
command (str): The exec or config CLI command(s) to be run.

Cisco Python Module to Execute IOS CLI Commands

Note Guest Shell must be enabled for Python to run. For more information, see the Guest Shell chapter.

The Python programming language uses six functions that can execute CLI commands. These functions are
available from the Python CLI module. To use these functions, execute the import cli command. The ip http
server command must be enabled for these functions to work.
Arguments for these functions are strings of CLI commands. To execute a CLI command through the Python
interpreter, enter the CLI command as an argument string of one of the following six functions:
• cli.cli(command)—This function takes an IOS command as an argument, runs the command through
the IOS parser, and returns the resulting text. If this command is malformed, a Python exception is raised.
The following is sample output from the cli.cli(command) function:

>>> import cli

>>> cli.clip('configure terminal; interface loopback 10; ip address

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

121
 Shells and Scripting
Cisco Python Module to Execute IOS CLI Commands

10.10.10.10 255.255.255.255')
*Mar 13 18:39:48.518: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback10, changed
state to up
>>> cli.clip('show clock')
'\n*18:11:53.989 UTC Mon Mar 13 2017\n'
>>> output=cli.cli('show clock')
>>> print(output)
*18:12:04.705 UTC Mon Mar 13 2017

• cli.clip(command)—This function works exactly the same as the cli.cli(command) function, except
that it prints the resulting text to stdout rather than returning it. The following is sample output from the
cli.clip(command) function:

>>>cli
>>>cli.clip('configure terminal; interface loopback 11; ip address
10.11.11.11 255.255.255.255')
*Mar 13 18:42:35.954: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback11, changed
state to up
*Mar 13 18:42:35.954: %LINK-3-UPDOWN: Interface Loopback11, changed state to up
>>> cli.clip('show clock')
*18:13:35.313 UTC Mon Mar 13 2017
>>> output=cli.clip('show clock')
*18:19:26.824 UTC Mon Mar 13 2017
>>> print (output)
None

• cli.execute(command)—This function executes a single EXEC command and returns the output; however,
does not print the resulting text No semicolons or newlines are allowed as part of this command. Use a
Python list with a for-loop to execute this function more than once. The following is sample output from
the cli.execute(command)
function:

>>> cli.execute("show clock")

'15:11:20.816 UTC Thu Jun 8 2017'
>>>
>>> cli.execute('show clock'; 'show ip interface brief')
File "<stdin>", line 1
cli.execute('show clock'; 'show ip interface brief')
^
SyntaxError: invalid syntax
>>>

• cli.executep(command)—This function executes a single command and prints the resulting text to stdout
rather than returning it. The following is sample output from the cli.executep(command) function:

>>> cli.executep('show clock')

*18:46:28.796 UTC Mon Mar 13 2017
>>> output=cli.executep('show clock')
*18:46:36.399 UTC Mon Mar 13 2017
>>> print(output)
None

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

122
 Shells and Scripting
Python Scripts Overview

• cli.configure(command)—This function configures the device with the configuration available in

commands. It returns a list of named tuples that contains the command and its result as shown below:
[Think: result = (bool(success), original_command, error_information)]

The command parameters can be in multiple lines and in the same format that is displayed in the output
of the show running-config command. The following is sample output from the cli.configure(command)
function:

>>>cli.configure(["interface GigabitEthernet1/0/7", "no shutdown",

"end"])
[ConfigResult(success=True, command='interface GigabitEthernet1/0/7',
line=1, output='', notes=None), ConfigResult(success=True, command='no shutdown',
line=2, output='', notes=None), ConfigResult(success=True, command='end',
line=3, output='', notes=None)]

• cli.configurep(command)—This function works exactly the same as the cli.configure(command)

function, except that it prints the resulting text to stdout rather than returning it. The following is sample
output from the cli.configurep(command) function:

>>>cli.configurep(["interface GigabitEthernet1/0/7", "no shutdown",

"end"])
Line 1 SUCCESS: interface GigabitEthernet1/0/7
Line 2 SUCCESS: no shut
Line 3 SUCCESS: end

Python Scripts Overview

Python run in a virtualized Linux-based environment, Guest Shell. For more information, see the Guest Shell
chapter. Cisco provides a Python module that allows user’s Python scripts to run IOS CLI commands on the
host device.

Interactive Python Prompt

When you execute the guestshell run python command on a device, the interactive Python prompt is opened
inside the Guest Shell. The Python interactive mode allows users to execute Python functions from the Cisco
Python CLI module to configure the device.
The following example shows how to enable the interactive Python prompt:

Device# guestshell run python

Python 2.7.5 (default, Jun 17 2014, 18:11:42)

[GCC 4.8.2 20140120 (Red Hat 4.8.2-16)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>

Device#

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

123
 Shells and Scripting
Python Script

Python Script
Python scripts can run in non-interactive mode by providing the Python script name as an argument in the
Python command. Python scripts must be accessible from within the Guest Shell. To access Python scripts
from the Guest Shell, save the scripts in bootflash/flash that is mounted within the Guest Shell.

Note The ip http server command must be configured for the import cli in Python to work.

The following sample Python script uses different CLI functions to configure and print show commands:
Device# more flash:sample_script.py

import sys
import cli

intf= sys.argv[1:]
intf = ''.join(intf[0])

print "\n\n *** Configuring interface %s with 'configurep' function *** \n\n" %intf
cli.configurep(["interface loopback55","ip address 10.55.55.55 255.255.255.0","no
shut","end"])

print "\n\n *** Configuring interface %s with 'configure' function *** \n\n"
cmd='interface %s,logging event link-status ,end' % intf
cli.configure(cmd.split(','))

print "\n\n *** Printing show cmd with 'executep' function *** \n\n"
cli.executep('show ip interface brief')

print "\n\n *** Printing show cmd with 'execute' function *** \n\n"
output= cli.execute('show run interface %s' %intf)
print (output)

print "\n\n *** Configuring interface %s with 'cli' function *** \n\n"
cli.cli('config terminal; interface %s; spanning-tree portfast edge default' %intf)

print "\n\n *** Printing show cmd with 'clip' function *** \n\n"
cli.clip('show run interface %s' %intf)

To run a Python script from the Guest Shell, execute the guestshell run python
/flash/script.py command
at the device prompt.
The following example shows how to run a Python script from the Guest Shell:

The following example shows how to run a Python script from the Guest Shell:

Device# guestshell run python /flash/sample_script.py loop55

*** Configuring interface loop55 with 'configurep' function ***

Line 1 SUCCESS: interface loopback55

Line 2 SUCCESS: ip address 10.55.55.55 255.255.255.0
Line 3 SUCCESS: no shut
Line 4 SUCCESS: end

*** Configuring interface %s with 'configure' function ***

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

124
 Shells and Scripting
Supported Python Versions

*** Printing show cmd with 'executep' function ***

Interface IP-Address OK? Method Status Protocol

Vlan1 unassigned YES NVRAM administratively down down
GigabitEthernet0/0 192.0.2.1 YES NVRAM up up
GigabitEthernet1/0/1 unassigned YES unset down down
GigabitEthernet1/0/2 unassigned YES unset down down
GigabitEthernet1/0/3 unassigned YES unset down down
:
:
:
Te1/1/4 unassigned YES unset down down
Loopback55 10.55.55.55 YES TFTP up up
Loopback66 unassigned YES manual up up

*** Printing show cmd with 'execute' function ***

Building configuration...
Current configuration : 93 bytes
!
interface Loopback55
ip address 10.55.55.55 255.255.255.0
logging event link-status
end

*** Configuring interface %s with 'cli' function ***

*** Printing show cmd with 'clip' function ***

Building configuration...
Current configuration : 93 bytes
!
interface Loopback55
ip address 10.55.55.55 255.255.255.0
logging event link-status
end

Supported Python Versions

Guest Shell is pre-installed with Python Version 2.7. Guest Shell is a virtualized Linux-based environment,
designed to run custom Linux applications, including Python applications for automated control and
management of Cisco devices. Platforms with Montavista CGE7 support Python Version 2.7.11, and platforms
with CentOS 7 support Python Version 2.7.5.
The following table provides information about Python versions and the supported platforms:

Table 9: Python Version Support

Python Version Platform

Python Version 2.7.5 All supported platforms except for Cisco Catalyst
3650 Series Switches and Cisco Catalyst 3850 Series
Switches.

Python Version 2.7.11 • Cisco Catalyst 3650 Series Switches

• Cisco Catalyst 3850 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

125
 Shells and Scripting
Updating the Cisco CLI Python Module

Python Version Platform

Python Version 3.6 Supported in Cisco IOS XE Amsterdam 17.1.1 and

later releases.
In Cisco IOS XE Amsterdam 17.1.1 and Cisco IOS
XE Amsterdam 17.2.1, Python V2 is the default.
However, in Cisco IOS XE Amsterdam 17.3.1 and
later releases, Python V3 is the default.
Note Cisco Catalyst 9200 Series Switches do
not support Python Version 3.6 in Cisco
IOS XE Amsterdam 17.1.1 and Cisco IOS
XE Amsterdam 17.2.1. Cisco Catalyst
9200 Series Switches support Python V3
in Cisco IOS XE Amsterdam 17.3.1 and
later releases.

Note Not supported by Cisco Catalyst 3650

Series Switches and Cisco Catalyst 3850
Series Switches.

Platforms with CentOS 7 support the installation of Redhat Package Manager (RPM) from the open source
repository.

Updating the Cisco CLI Python Module

The Cisco CLI Python module and EEM module are pre-installed on devices. However, when you update the
Python version by using either Yum or prepackaged binaries, the Cisco-provided CLI module must also be
updated.

Note When you update to Python Version 3 on a device that already has Python Version 2, both versions of
Python exist on the device. Use one of the following IOS commands to run Python:
• The guestshell run python2 command enables Python Version 2.
• The guestshell run python3 command enables Python Version 3.
• The guestshell run python command enables Python Version 2.

Use one of the following methods to update the Python version:

• Standalone tarball installation
• PIP install for the CLI module

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

126
 Shells and Scripting
Additional References for Python API

Additional References for Python API

Related Documents

Related Topic Document Title

Guest Shell Guest Shell

EEM Python Module Python Scripting in EEM

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for Python API

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

127
 Shells and Scripting
Feature Information for Python API

Table 10: Feature Information for the CLI Python Module

Feature Name Release Feature Information

CLI Python Module Cisco IOS XE Everest Python programmabilty provides a Python
16.5.1a module that allows users to interact with IOS
using CLIs.
In Cisco IOS XE Everest 16.5.1a, this feature
was implemented on the following platforms:
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

In Cisco IOS XE Everest 16.5.1b, this feature

was implemented on the following platforms:
• Cisco 4000 Series Integrated Services
Routers

Cisco IOS XE Everest 16.6.2 This feature was implemented on Cisco

Catalyst 9400 Series Switches.

Cisco IOS XE Fuji 16.7.1 This feature was implemented on the

following platforms:
• Cisco ASR 1000 Aggregation Services
Routers
• Cisco CSR 1000v Series Cloud Services
Routers

Cisco IOS XE Fuji 16.8.1 In Cisco IOS XE Fuji 16.8.1, this feature was
implemented on following platforms:
Cisco IOS XE Fuji 16.8.1a
• Cisco ASR 1004 Router
• Cisco ASR 1006 Router
• Cisco ASR 1006-X Router
• Cisco ASR 1009-X Router
• Cisco ASR 1013 Router
• Cisco 4000 Series Integrated Services
Router models with a minimum of 4 GB
RAM.

In Cisco IOS XE Fuji 16.8.1a, this feature was

implemented on Cisco Catalyst 9500-High
Performance Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

128
 CHAPTER 6
EEM Python Module
Embedded Event Manager (EEM) policies support Python scripts. Python scripts can be executed as part of
EEM actions in EEM applets.
• Prerequisites for the EEM Python Module, on page 129
• Information About EEM Python Module, on page 129
• How to Configure the EEM Python Policy, on page 132
• Additional References EEM Python Module, on page 137
• Feature Information for EEM Python Module, on page 138

Prerequisites for the EEM Python Module

Guest Shell must be working within the container. Guest Shell is not enabled by default. For more information
see the Guest Shell feature.

Information About EEM Python Module

Python Scripting in EEM
Embedded Event Manager (EEM) policies support Python scripts. You can register Python scripts as EEM
policies, and execute the registered Python scripts when a corresponding event occurs. The EEM Python script
has the same event specification syntax as the EEM TCL policy.
Configured EEM policies run within the Guest Shell. Guest Shell is a virtualized Linux-based environment,
designed to run custom Linux applications, including Python for automated control and management of Cisco
devices. The Guest Shell container provides a Python interpreter.

EEM Python Package

The EEM Python package can be imported to Python scripts for running EEM-specific extensions.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

129
 Shells and Scripting
Python-Supported EEM Actions

Note The EEM Python package is available only within the EEM Python script (The package can be registered
with EEM, and has the EEM event specification in the first line of the script.) and not in the standard
Python script (which is run using the Python script name).

The Python package includes the following application programming interfaces (APIs):
• Action APIs—Perform EEM actions and have default parameters.
• CLI-execution APIs—Run IOS commands, and return the output. The following are the list of
CLI-execution APIs:
• eem_cli_open()
• eem_cli_exec()
• eem_cli_read()
• eem_cli_read_line()
• eem_cli_run()
• eem_cli_run_interactive()
• eem_cli_read_pattern()
• eem_cli_write()
• eem_cli_close()

• Environment variables-accessing APIs—Get the list of built-in or user-defined variables. The following
are the environment variables-accessing APIs:
• eem_event_reqinfo ()-Returns the built-in variables list.
• eem_user_variables()-Returns the current value of an argument.

Python-Supported EEM Actions

The Python package (is available only within the EEM script, and not available for the standard Python script)
supports the following EEM actions:
• Syslog message printing
• Send SNMP traps
• Reload the box
• Switchover to the standby device
• Run a policy
• Track Object read
• Track Object Set
• Cisco Networking Services event generation

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

130
 Shells and Scripting
EEM Variables

The EEM Python package exposes the interfaces for executing EEM actions. You can use the Python script
to call these actions, and they are forwarded from the Python package via Cisco Plug N Play (PnP) to the
action handler.

EEM Variables
An EEM policy can have the following types of variables:
• Event-specific built-in variables—A set of predefinied variables that are populated with details about
the event that triggered the policy. The eem_event_reqinfo () API returns the builtin variables list. These
variables can be stored in the local machine and used as local variables. Changes to local variables do
not reflect in builtin variables.
• User-defined variables—Variables that can be defined and used in policies. The value of these variables
can be referred in the Python script. While executing the script, ensure that the latest value of the variable
is available. The eem_user_variables() API returns the current value of the argument that is provided in
the API.

EEM CLI Library Command Extensions

The following CLI library commands are available within EEM for the Python script to work:
• eem_cli_close()—Closes the EXEC process and releases the VTY and the specified channel handler
connected to the command.
• eem_cli_exec—Writes the command to the specified channel handler to execute the command. Then
reads the output of the command from the channel and returns the output.
• eem_cli_open—Allocates a VTY, creates an EXEC CLI session, and connects the VTY to a channel
handler. Returns an array including the channel handler.
• eem_cli_read()—Reads the command output from the specified CLI channel handler until the pattern of
the device prompt occurs in the contents read. Returns all the contents read up to the match.
• eem_cli_read_line()—Reads one line of the command output from the specified CLI channel handler.
Returns the line read.
• eem_cli_read_pattern()—Reads the command output from the specified CLI channel handler until the
pattern that is to be matched occurs in the contents read. Returns all the contents read up to the match.
• eem_cli_run()—Iterates over the items in the clist and assumes that each one is a command to be executed
in the enable mode. On success, returns the output of all executed commands and on failure, returns
error.
• eem_cli_run_interactive()—Provides a sublist to the clist which has three items. On success, returns the
output of all executed commands and on failure, returns the error. Also uses arrays when possible as a
way of making things easier to read later by keeping expect and reply separated.
• eem_cli_write()—Writes the command that is to be executed to the specified CLI channel handler. The
CLI channel handler executes the command.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

131
 Shells and Scripting
How to Configure the EEM Python Policy

How to Configure the EEM Python Policy

For the Python script to work, you must enable the Guest Shell. For more information, see the Guest Shell
chapter.

Registering a Python Policy

SUMMARY STEPS
1. enable
2. configure terminal
3. event manager directory user policy path
4. event manager policy policy-filename
5. exit
6. show event manager policy registered
7. show event manager history events

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 event manager directory user policy path Specifies a directory to use for storing user library files or
user-defined EEM policies.
Example:
Device(config)# event manager directory user policy Note You must have a policy in the specified path.
flash:/user_library For example, in this step, the eem_script.py
policy is available in the flash:/user_library
folder or path.

Step 4 event manager policy policy-filename Registers a policy with EEM.

Example: • The policy is parsed based on the file extension. If the
Device(config)# event manager policy eem_script.py file extension is .py, the policy is registered as Python
policy.
• EEM schedules and runs policies on the basis of an
event specification that is contained within the policy
itself. When the event manager policy command is
invoked, EEM examines the policy and registers it to
be run when the specified event occurs.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

132
 Shells and Scripting
Running Python Scripts as Part of EEM Applet Actions

Command or Action Purpose

Step 5 exit Exits global configuration mode and returns to privileged
EXEC mode.
Example:
Device(config)# exit

Step 6 show event manager policy registered Displays the registered EEM policies.
Example:
Device# show event manager policy registered

Step 7 show event manager history events Displays EEM events that have been triggered.
Example:
Device# show event manager history events

Example
The following is sample output from the show event manager policy registered command:
Device# show event manager policy registered

No. Class Type Event Type Trap Time Registered Name

1 script user multiple Off Tue Aug 2 22:12:15 2016 multi_1.py
1: syslog: pattern {COUNTER}
2: none: policyname {multi_1.py} sync {yes}
trigger delay 10.000
correlate event 1 or event 2
attribute tag 1 occurs 1
nice 0 queue-priority normal maxrun 100.000 scheduler rp_primary Secu none

2 script user multiple Off Tue Aug 2 22:12:20 2016 multi_2.py

1: syslog: pattern {COUNTER}
2: none: policyname {multi_2.py} sync {yes}
trigger
correlate event 1 or event 2
nice 0 queue-priority normal maxrun 100.000 scheduler rp_primary Secu none

3 script user multiple Off Tue Aug 2 22:13:31 2016 multi.tcl

1: syslog: pattern {COUNTER}
2: none: policyname {multi.tcl} sync {yes}
trigger
correlate event 1 or event 2
attribute tag 1 occurs 1
nice 0 queue-priority normal maxrun 100.000 scheduler rp_primary Secu none

Running Python Scripts as Part of EEM Applet Actions

Python Script: eem_script.py

An EEM applet can include a Python script with an action command. In this example, an user is
trying to run a standard Python script as part of the EEM action, however; EEM Python package is

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

133
 Shells and Scripting
Running Python Scripts as Part of EEM Applet Actions

not available in the standard Python script. The standard Python script in IOS has a package named
from cli import cli,clip and this package can be used to execute IOS commands.

import sys
from cli import cli,clip,execute,executep,configure,configurep

intf= sys.argv[1:]
intf = ''.join(intf[0])

print ('This script is going to unshut interface %s and then print show ip interface
brief'%intf)

if intf == 'loopback55':
configurep(["interface loopback55","no shutdown","end"])
else :
cmd='int %s,no shut ,end' % intf
configurep(cmd.split(','))

executep('show ip interface brief')

This following is sample output from the guestshell run python command.
Device# guestshell run python /flash/eem_script.py loop55

This script is going to unshut interface loop55 and then print show ip interface brief
Line 1 SUCCESS: int loop55
Line 2 SUCCESS: no shut
Line 3 SUCCESS: end
Interface IP-Address OK? Method Status Protocol
Vlan1 unassigned YES NVRAM administratively down down
GigabitEthernet0/0 5.30.15.37 YES NVRAM up up
GigabitEthernet1/0/1 unassigned YES unset down down
GigabitEthernet1/0/2 unassigned YES unset down down
GigabitEthernet1/0/3 unassigned YES unset down down
GigabitEthernet1/0/4 unassigned YES unset up up
GigabitEthernet1/0/5 unassigned YES unset down down
GigabitEthernet1/0/6 unassigned YES unset down down
GigabitEthernet1/0/7 unassigned YES unset down down
GigabitEthernet1/0/8 unassigned YES unset down down
GigabitEthernet1/0/9 unassigned YES unset down down
GigabitEthernet1/0/10 unassigned YES unset down down
GigabitEthernet1/0/11 unassigned YES unset down down
GigabitEthernet1/0/12 unassigned YES unset down down
GigabitEthernet1/0/13 unassigned YES unset down down
GigabitEthernet1/0/14 unassigned YES unset down down
GigabitEthernet1/0/15 unassigned YES unset down down
GigabitEthernet1/0/16 unassigned YES unset down down
GigabitEthernet1/0/17 unassigned YES unset down down
GigabitEthernet1/0/18 unassigned YES unset down down
GigabitEthernet1/0/19 unassigned YES unset down down
GigabitEthernet1/0/20 unassigned YES unset down down
GigabitEthernet1/0/21 unassigned YES unset down down
GigabitEthernet1/0/22 unassigned YES unset down down
GigabitEthernet1/0/23 unassigned YES unset up up
GigabitEthernet1/0/24 unassigned YES unset down down
GigabitEthernet1/1/1 unassigned YES unset down down
GigabitEthernet1/1/2 unassigned YES unset down down
GigabitEthernet1/1/3 unassigned YES unset down down
GigabitEthernet1/1/4 unassigned YES unset down down
Te1/1/1 unassigned YES unset down down
Te1/1/2 unassigned YES unset down down
Te1/1/3 unassigned YES unset down down

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

134
 Shells and Scripting
Adding a Python Script in an EEM Applet

Te1/1/4 unassigned YES unset down down

Loopback55 10.55.55.55 YES manual up up

Device#
Jun 7 12:51:20.549: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback55,
changed state to up
Jun 7 12:51:20.549: %LINK-3-UPDOWN: Interface Loopback55, changed state to up

The following is a sample script for printing messages to the syslog. This script must be stored in a
file, copied to the file system on the device, and registered using the event manager policy file.

::cisco::eem::event_register_syslog tag "1" pattern COUNTER maxrun 200

import eem
import time

eem.action_syslog("SAMPLE SYSLOG MESSAGE","6","TEST")

The following is sample script to print EEM environment variables. This script must be stored in a
file, copied to the file system on the device, and registered using the event manager policy file.

::cisco::eem::event_register_syslog tag "1" pattern COUNTER maxrun 200

import eem
import time

c = eem.env_reqinfo()

print "EEM Environment Variables"

for k,v in c.iteritems():
print "KEY : " + k + str(" ---> ") + v

print "Built in Variables"

for i,j in a.iteritems() :
print "KEY : " + i + str(" ---> ") + j

Adding a Python Script in an EEM Applet

SUMMARY STEPS
1. enable
2. configure terminal
3. event manager applet applet-name
4. event [tag event-tag] syslog pattern regular-expression
5. action label cli command cli-string
6. action label cli command cli-string [ pattern pattern-string ]
7. end
8. show event manager policy active
9. show event manager history events

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

135
 Shells and Scripting
Adding a Python Script in an EEM Applet

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 event manager applet applet-name Registers an applet with the Embedded Event Manager
(EEM) and enters applet configuration mode.
Example:
Device(config)# event manager applet
interface_Shutdown

Step 4 event [tag event-tag] syslog pattern regular-expression Specifies a regular expression to perform the syslog message
pattern match.
Example:
Device(config-applet)# event syslog pattern
"Interface Loopback55,
changed state to administratively down"

Step 5 action label cli command cli-string Specifies the IOS command to be executed when an EEM
applet is triggered.
Example:
Device(config-applet)# action 0.0 cli command "en"

Step 6 action label cli command cli-string [ pattern pattern-string Specifies the action to be specified with the pattern
] keyword.
Example: • Specify a regular expression pattern string that will
Device(config-applet)# action 1.0 cli command match the next solicited prompt.
"guestshell run python3 /bootflash/eem_script.py
loop55"

Step 7 end Exits applet configuration mode and returns to privileged

EXEC mode.
Example:
Device(config-applet)# end

Step 8 show event manager policy active Displays EEM policies that are executing.
Example:
Device# show event manager policy active

Step 9 show event manager history events Displays the EEM events that have been triggered.
Example:
Device# show event manager history events

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

136
 Shells and Scripting
Additional References EEM Python Module

What to do next
The following example shows how to trigger the Python script configured in the task:
Device(config)# interface loopback 55
Device(config-if)# shutdown
Device(config-if)# end
Device#

Mar 13 10:53:22.358 EDT: %SYS-5-CONFIG_I: Configured from console by console

Mar 13 10:53:24.156 EDT: %LINK-5-CHANGED: Line protocol on Interface Loopback55, changed
state to down
Mar 13 10:53:27.319 EDT: %LINK-3-UPDOWN: Interface Loopback55, changed state to
administratively down
Enter configuration commands, one per line. End with CNTL/Z.
Mar 13 10:53:35.38 EDT: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback55, changed
state to up
*Mar 13 10:53:35.39 EDT %LINK-3-UPDOWN: Interface Loopback55, changed state to up
+++ 10:54:33 edi37(default) exec +++
show ip interface br
Interface IP-Address OK? Method Status Protocol
GigabitEthernet0/0/0 unassigned YES unset down down
GigabitEthernet0/0/1 unassigned YES unset down down
GigabitEthernet0/0/2 10.1.1.31 YES DHCP up up
GigabitEthernet0/0/3 unassigned YES unset down down
GigabitEthernet0 192.0.2.1 YES manual up up
Loopback55 198.51.100.1 YES manual up up
Loopback66 172.16.0.1 YES manual up up
Loopback77 192.168.0.1 YES manual up up
Loopback88 203.0.113.1 YES manual up up

Additional References EEM Python Module

Related Documents

Related Topic Document Title

EEM configuration Embedded Event Manager Configuration Guide

EEM commands Embedded Event Manager Command Reference

Guest Shell configuration Guest Shell

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

137
 Shells and Scripting
Feature Information for EEM Python Module

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for EEM Python Module

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

138
Shells and Scripting
Feature Information for EEM Python Module

Table 11: Feature Information for EEM Python Module

Feature Name Release Feature Information

EEM Python Module Cisco IOS XE Everest This feature supports Python scripts as EEM
16.5.1a policies.
Cisco IOS XE Everest No new commands were introduced.
16.5.1b
In Cisco IOS XE Everest 16.5.1a, this feature
was implemented on the following platforms:
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
•
In Cisco IOS XE Everest 16.5.1b, this feature
was implemented on the following platforms:
• Cisco ISR 4000 Series Integrated Service
Routers

Cisco IOS XE Everest 16.6.2 In Cisco IOS XE Everest 16.6.2, this feature
was implemented on Cisco Catalyst 9400
Series Switches.

Cisco IOS XE Fuji 16.8.1a In Cisco IOS XE Fuji 16.8.1a, this feature was
implemented on Cisco Catalyst 9500-High
Performance Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

139
 Shells and Scripting
Feature Information for EEM Python Module

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

140
PA R T III
Model-Driven Programmability
• NETCONF Protocol, on page 143
• RESTCONF Protocol, on page 187
• NETCONF and RESTCONF Service-Level ACLs, on page 223
• gNMI Protocol, on page 229
• gRPC Network Operations Interface, on page 253
• Model Based AAA, on page 273
• Model-Driven Telemetry, on page 281
• In-Service Model Update, on page 341
 CHAPTER 7
NETCONF Protocol
• Information About the NETCONF Protocol, on page 143
• How to Configure the NETCONF Protocol, on page 165
• Verifying the NETCONF Protocol Configuration Through the CLI, on page 170
• Displaying NETCONF-YANG Diagnostics Through RPCs, on page 173
• Additional References for NETCONF Protocol, on page 176
• Feature Information for the NETCONF Protocol, on page 177

Information About the NETCONF Protocol

Introduction to Data Models - Programmatic and Standards-Based
Configuration
The traditional way of managing network devices is by using Command Line Interfaces (CLIs) for
configurational (configuration commands) and operational data (show commands). For network management,
Simple Network Management Protocol (SNMP) is widely used, especially for exchanging management
information between various network devices. Although CLIs and SNMP are heavily used, they have several
restrictions. CLIs are highly proprietary, and human intervention is required to understand and interpret their
text-based specification. SNMP does not distinguish between configurational and operational data.
The solution lies in adopting a programmatic and standards-based way of writing configurations to any network
device, replacing the process of manual configuration. Network devices running on Cisco IOS XE support
the automation of configuration for multiple devices across the network using data models. Data models are
developed in a standard, industry-defined language, that can define configuration and state information of a
network.
Cisco IOS XE supports the Yet Another Next Generation (YANG) data modeling language. YANG can be
used with the Network Configuration Protocol (NETCONF) to provide the desired solution of automated and
programmable network operations. NETCONF (RFC 6241) is an XML-based protocol that client applications
use to request information from and make configuration changes to the device. YANG is primarily used to
model the configuration and state data used by NETCONF operations.
In Cisco IOS XE, model-based interfaces interoperate with existing device CLI, Syslog, and SNMP interfaces.
These interfaces are optionally exposed northbound from network devices. YANG is used to model each
protocol based on RFC 6020.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

143
 Model-Driven Programmability
NETCONF

Note To access Cisco YANG models in a developer-friendly way, clone the GitHub repository, and navigate
to the vendor/cisco subdirectory. Models for various releases of IOS-XE, IOS-XR, and NX-OS platforms
are available here.

NETCONF
NETCONF provides a mechanism to install, manipulate, and delete the configuration of network devices.
It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the
protocol messages.
NETCONF uses a simple Remote Procedure Call (RPC) based mechanism to facilitate communication between
a client and a server. The client can be a script or application running as part of a network manager. The server
is typically a network device (switch or router). It uses Secure Shell (SSH) as the transport layer across network
devices. It uses SSH port number 830 as the default port. The port number is a configurable option.
NETCONF also supports capability discovery and model downloads. Supported models are discovered using
the ietf-netconf-monitoring model. Revision dates for each model are shown in the capabilities response.
Data models are available for optional download from a device using the get-schema RPC. You can use these
YANG models to understand or export the data model. For more details on NETCONF, see RFC 6241.
In releases prior to Cisco IOS XE Fuji 16.8.1, an operational data manager (based on polling) was enabled
separately. In Cisco IOS XE Fuji 16.8.1 and later releases, operational data works on platforms running
NETCONF (similar to how configuration data works), and is enabled by default. For more information on
the components that are enabled for operational data queries or streaming, see the GitHub respository, to view
*-oper in the naming convention.

Restrictions for the NETCONF Protocol

• The NETCONF feature is not supported on a device running dual IOSd configuration or software
redundancy.
• If RP addresses from the NETCONF datastore are removed using the no ip pim rp-address command,
there could be inconsistencies in the datastore, due to parser limitations. To remove RP address entries
from the NETCONF datastore, use the RPC.

YANG Model Version 1.1

YANG Version 1.1 is described by the RFC 7950, The YANG 1.1 Data Modeling Language. YANG Version
1.1 is a maintenance release of the YANG language that addresses ambiguities and defects in the YANG
Version 1.0 specification.
The YANG module in YANG Version 1.1 is advertised through the ietf-yang-library instead of the NETCONF
hello messages.
The following example shows the NETCONF <get> RPC that retrieves a list of all the YANG modules
supported by a device:

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

<get>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

144
Model-Driven Programmability
YANG Model Version 1.1

<filter>
<modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"/>
</filter>
</get>
</rpc>

The output of the RPC reply contains a list of all the YANG modules regardless of the YANG version each
module uses.
Cisco IOS XE Cupertino 17.7.1 uses the YANG Version 1.0; however, you can still download the YANG
Version 1.1 from GitHub at https://github.com/YangModels/yang/tree/master/vendor/cisco/xe.
Alternatively, you can also download the YANG models from the device using the NETCONF get-schema
operation, and migrate the downloaded models to this version using the migrate_yang_version.py script.
The following example shows how to migrate from YANG Version 1.0 to YANG Version 1.1 using the script:

migrate_yang_version.py [-h] [--out OUT] path

Use the help command to view the options available with the script:

python migrate_yang_version.py --help

usage: migrate_yang_version.py [-h] [--out OUT] path

positional arguments:
path Path to the YANG files

optional arguments:
-h, --help show this help message and exit
--out OUT Path to the output YANG file

The following example shows how to use the out argument to move a file from its original location to another
folder:

python migrate_yang_version.py --out testdir/outdir testdir/indir

In the above example, testdir/outdir is the directory in which the YANG model Version 1.1 resides or where
the output of the script is placed. This directory will be created, if it is not available.
The testdir/indir directory is where the YANG model Version 1.0 resides; the input for the script.
After the YANG model Version 1.1 is created, either by downloading it from GitHub or by using the
migrate_yang_version.py script and compiled on the client application, end-to-end YANG model tests can
be executed and validated against Cisco IOS XE devices.

Note The YANG models on the device is still YANG Version 1.0. However; there is no need to change the
RPC payload of the client test cases.

For inquiries related to the migrate_yang_version.py script or the Cisco IOS XE YANG migration process,
send an email to [email protected].
Cisco IOS XE Cupertino 17.8.1 uses YANG Version 1.1. The difference between YANG Version 1.1 and
Version 1.0 is documented at https://tools.ietf.org/html/rfc7950#page-10.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

145
 Model-Driven Programmability
NETCONF RESTCONF IPv6 Support

YANG Version in Cisco IOS XE Dublin 17.10.1

Cisco-defined YANG models are in YANG Version 1.1 in Cisco IOS XE Dublin 17.10.1 and later releases.
You can download this version from GitHub at
https://github.com/YangModels/yang/tree/master/vendor/cisco/xe.
In YANG Version 1.1, the critical change that impacts client applications that use NETCONF is in the <hello>
message content. As per RFC 7950, a server advertises support for YANG 1.1 modules by using the
ietf-yang-library, instead of listing them as capabilities in the <hello> message. We recommend that you use
the ietf-yang-library to gather the list of supported YANG modules, instead of deriving this list from the
<hello> message content.

NETCONF RESTCONF IPv6 Support

Data model interfaces (DMIs) support the use of IPv6 protocol. DMI IPv6 support helps client applications
to communicate with services that use IPv6 addresses. External facing interfaces will provide dual-stack
support; both IPv4 and IPv6.
DMIs are a set of services that facilitate the management of network elements. Application layer protocols
such as, NETCONF and RESTCONF access these DMIs over a network.
If IPv6 addresses are not configured, external-facing applications will continue to listen on IPv6 sockets; but
these sockets will be unreachable.

Converting IOS Commands to XML

In Cisco IOS XE Cupertino 17.7.1 and later releases, you can automatically translate IOS commands into
relevant NETCONF-YANG XML or RESTCONF-JSON request messages. You can analyze the generated
configuration messages and familiarize with the Xpaths used in these messages. The generated configuration
in the structured format can be used to provision other devices in the network; however, this configuration
cannot be modified.
Use the show running-config | format netconf-xml command or the show running-config | format
restconf-json command to translate IOS commands.
If the netconf-xml keyword is selected, the IOS commands are translated into the NETCONF-YANG XML
format, and if the restconf-json keyword is selected, the IOS commands are translated into the
RESTCONF-JSON format.
The translation of IOS commands into a structured format is disabled by default. You must initially configure
NETCONF-YANG, and once the data model interfaces (DMIs) are initialized, use the appropriate format
option to translate the commands.
The following is sample output from the show running-config | format netconf-xml command:
Device# show running-config | format netconf-xml

<config xmlns="http://tail-f.com/ns/config/1.0">
<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<version>17.8</version>
<boot-start-marker/>
<boot>
<system>
<flash>
<flash-list-ordered-by-user>

<flash-leaf>bootflash:c8000v-universalk9.BLD_POLARIS_DEV_LATEST_20211020_005209.SSA.bin</

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

146
Model-Driven Programmability
Converting IOS Commands to XML

flash-leaf>
</flash-list-ordered-by-user>
</flash>
</system>
</boot>
<boot-end-marker/>
<memory>
<free>
<low-watermark>
<processor>64219</processor>
</low-watermark>
</free>
</memory>
<call-home>
<contact-email-addr xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-call-home">
[email protected]</contact-email-addr>
<tac-profile xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-call-home">
<profile>
<CiscoTAC-1>
<active>true</active>
<destination>
<transport-method>http</transport-method>
</destination>
</CiscoTAC-1>
</profile>
</tac-profile>
</call-home>
<service>
<timestamps>
<debug-config>
<datetime>
<msec/>
<localtime/>
<show-timezone/>
</datetime>
</debug-config>
<log-config>
<datetime>
<msec/>
<localtime/>
<show-timezone/>
</datetime>
</log-config>
</timestamps>
<call-home/>
</service>
<platform>
<console xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-platform">
<output>serial</output>
</console>
<qfp xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-platform">
<utilization>
<monitor>
<load>80</load>
</monitor>
</utilization>
</qfp>
<punt-keepalive xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-platform">
<disable-kernel-core>true</disable-kernel-core>
</punt-keepalive>
</platform>
<hostname>pi-prog-csr1</hostname>
<enable>
<password>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

147
 Model-Driven Programmability
Converting IOS Commands to XML

<secret>lab</secret>
</password>
</enable>
<username>
<name>admin</name>
<privilege>15</privilege>
<password>
<encryption>0</encryption>
<password>lab</password>
</password>
</username>
<vrf>
<definition>
<name>Mgmt-intf</name>
<address-family>
<ipv4>
</ipv4>
<ipv6>
</ipv6>
</address-family>
</definition>
</vrf>
<ip>
<domain>
<name>cisco</name>
</domain>
<forward-protocol>
<protocol>nd</protocol>
</forward-protocol>
<route>
<ip-route-interface-forwarding-list>
<prefix>10.0.0.0</prefix>
<mask>255.255.0.0</mask>
<fwd-list>
<fwd>10.45.0.1</fwd>
</fwd-list>
</ip-route-interface-forwarding-list>
<vrf>
<name>Mgmt-intf</name>
<ip-route-interface-forwarding-list>
<prefix>0.0.0.0</prefix>
<mask>0.0.0.0</mask>
<fwd-list>
<fwd>10.104.54.129</fwd>
</fwd-list>
</ip-route-interface-forwarding-list>
</vrf>
</route>
<ssh>
<ssh-version>2</ssh-version>
</ssh>
<tftp>
<source-interface>
<GigabitEthernet>1</GigabitEthernet>
</source-interface>
<blocksize>8192</blocksize>
</tftp>
<http xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-http">
<authentication>
<local/>
</authentication>
<server>true</server>
<secure-server>true</secure-server>
</http>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

148
Model-Driven Programmability
Converting IOS Commands to XML

</ip>
<ipv6>
<unicast-routing/>
</ipv6>
<interface>
<GigabitEthernet>
<name>1</name>
<vrf>
<forwarding>Mgmt-intf</forwarding>
</vrf>
<ip>
<address>
<primary>
<address>10.104.54.222</address>
<mask>255.255.255.128</mask>
</primary>
</address>
</ip>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
<GigabitEthernet>
<name>2</name>
<ip>
<address>
<primary>
<address>9.45.21.231</address>
<mask>255.255.0.0</mask>
</primary>
</address>
</ip>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
<GigabitEthernet>
<name>3</name>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
<GigabitEthernet>
<name>4</name>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

149
 Model-Driven Programmability
Converting IOS Commands to XML

<GigabitEthernet>
<name>5</name>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
</interface>
<control-plane>
</control-plane>
<clock>
<timezone>
<zone>IST</zone>
<hours>5</hours>
<minutes>30</minutes>
</timezone>
</clock>
<logging>
<console-config>
<console>false</console>
</console-config>
</logging>
<aaa>
<new-model xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa"/>
<authentication xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">
<login>
<name>default</name>
<a1>
<local/>
</a1>
</login>
</authentication>
<authorization xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">
<exec>
<name>default</name>
<a1>
<local/>
</a1>
</exec>
</authorization>
<common-criteria xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">
<policy>enable_secret_policy</policy>
<char-changes>4</char-changes>
<lower-case>1</lower-case>
<max-length>127</max-length>
<min-length>10</min-length>
<numeric-count>1</numeric-count>
<upper-case>1</upper-case>
</common-criteria>
<session-id xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">common</session-id>
</aaa>
<login>
<on-success>
<log>
</log>
</on-success>
</login>
<multilink>
<bundle-name
xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ppp">authenticated</bundle-name>
</multilink>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

150
Model-Driven Programmability
Converting IOS Commands to XML

<redundancy>
</redundancy>
<spanning-tree>
<extend xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-spanning-tree">
<system-id/>
</extend>
</spanning-tree>
<subscriber>
<templating/>
</subscriber>
<crypto>
<pki xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-crypto">
<certificate>
<chain>
<name>SLA-TrustPoint</name>
<certificate>
<serial>01</serial>
<certtype>ca</certtype>
</certificate>
</chain>
<chain>
<name>TP-self-signed-2685563505</name>
<certificate>
<serial>01</serial>
<certtype>self-signed</certtype>
</certificate>
</chain>
</certificate>
<trustpoint>
<id>SLA-TrustPoint</id>
<enrollment>
<pkcs12/>
</enrollment>
<revocation-check>crl</revocation-check>
</trustpoint>
<trustpoint>
<id>TP-self-signed-2685563505</id>
<enrollment>
<selfsigned/>
</enrollment>
<revocation-check>none</revocation-check>
<rsakeypair>
<key-label>TP-self-signed-2685563505</key-label>
</rsakeypair>
<subject-name>cn=IOS-Self-Signed-Certificate-2685563505</subject-name>
</trustpoint>
</pki>
</crypto>
<license>
<udi>
<pid>C8000V</pid>
<sn>93SHKMJKOC6</sn>
</udi>
<boot>
<level>
<network-advantage>
<addon>dna-advantage</addon>
</network-advantage>
</level>
</boot>
</license>
<line>
<aux>
<first>0</first>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

151
 Model-Driven Programmability
Converting IOS Commands to XML

</aux>
<console>
<first>0</first>
<exec-timeout>
<minutes>0</minutes>
<seconds>0</seconds>
</exec-timeout>
<stopbits>1</stopbits>
</console>
<vty>
<first>0</first>
<last>4</last>
<exec-timeout>
<minutes>0</minutes>
<seconds>0</seconds>
</exec-timeout>
<password>
<secret>lab</secret>
</password>
<transport>
<input>
<all/>
</input>
<output>
<all/>
</output>
</transport>
</vty>
<vty>
<first>5</first>
<last>31</last>
<transport>
<input>
<all/>
</input>
<output>
<all/>
</output>
</transport>
</vty>
</line>
<diagnostic xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-diagnostics">
<bootup>
<level>minimal</level>
</bootup>
</diagnostic>
</native>
</config>
pi-prog-csr1#
pi-prog-csr1#
pi-prog-csr1#show running-config | format restconf-json
{
"data": {
"Cisco-IOS-XE-native:native": {
"version": "17.8",
"boot-start-marker": [null],
"boot": {
"system": {
"flash": {
"flash-list-ordered-by-user": [
{
"flash-leaf":
"bootflash:c8000v-universalk9.BLD_POLARIS_DEV_LATEST_20211020_005209.SSA.bin"
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

152
Model-Driven Programmability
Converting IOS Commands to XML

]
}
}
},
"boot-end-marker": [null],
"memory": {
"free": {
"low-watermark": {
"processor": 64219
}
}
},
"call-home": {
"Cisco-IOS-XE-call-home:contact-email-addr": "[email protected]",
"Cisco-IOS-XE-call-home:tac-profile": {
"profile": {
"CiscoTAC-1": {
"active": true,
"destination": {
"transport-method": "http"
}
}
}
}
},
"service": {
"timestamps": {
"debug-config": {
"datetime": {
"msec": [null],
"localtime": [null],
"show-timezone": [null]
}
},
"log-config": {
"datetime": {
"msec": [null],
"localtime": [null],
"show-timezone": [null]
}
}
},
"call-home": [null]
},
"platform": {
"Cisco-IOS-XE-platform:console": {
"output": "serial"
},
"Cisco-IOS-XE-platform:qfp": {
"utilization": {
"monitor": {
"load": 80
}
}
},
"Cisco-IOS-XE-platform:punt-keepalive": {
"disable-kernel-core": true
}
},
"hostname": "pi-prog-csr1",
"enable": {
"password": {
"secret": "lab"
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

153
 Model-Driven Programmability
Converting IOS Commands to XML

},
"username": [
{
"name": "admin",
"privilege": 15,
"password": {
"encryption": "0",
"password": "lab"
}
}
],
"vrf": {
"definition": [
{
"name": "Mgmt-intf",
"address-family": {
"ipv4": {
},
"ipv6": {
}
}
}
]
},
"ip": {
"domain": {
"name": "cisco"
},
"forward-protocol": {
"protocol": "nd"
},
"route": {
"ip-route-interface-forwarding-list": [
{
"prefix": "10].0.0.0",
"mask": "255.255.0.0",
"fwd-list": [
{
"fwd": "9.45.0.1"
}
]
}
],
"vrf": [
{
"name": "Mgmt-intf",
"ip-route-interface-forwarding-list": [
{
"prefix": "0.0.0.0",
"mask": "0.0.0.0",
"fwd-list": [
{
"fwd": "10.104.54.129"
}
]
}
]
}
]
},
"ssh": {
"ssh-version": "2"
},
"tftp": {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

154
Model-Driven Programmability
Converting IOS Commands to XML

"source-interface": {
"GigabitEthernet": "1"
},
"blocksize": 8192
},
"Cisco-IOS-XE-http:http": {
"authentication": {
"local": [null]
},
"server": true,
"secure-server": true
}
},
"ipv6": {
"unicast-routing": [null]
},
"interface": {
"GigabitEthernet": [
{
"name": "1",
"vrf": {
"forwarding": "Mgmt-intf"
},
"ip": {
"address": {
"primary": {
"address": "10.104.54.222",
"mask": "255.255.255.128"
}
}
},
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
},
{
"name": "2",
"ip": {
"address": {
"primary": {
"address": "10.45.21.231",
"mask": "255.255.0.0"
}
}
},
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
},
{
"name": "3",
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

155
 Model-Driven Programmability
Converting IOS Commands to XML

"auto": true
}
},
{
"name": "4",
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
},
{
"name": "5",
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
}
]
},
"control-plane": {
},
"clock": {
"timezone": {
"zone": "IST",
"hours": 5,
"minutes": 30
}
},
"logging": {
"console-config": {
"console": false
}
},
"aaa": {
"Cisco-IOS-XE-aaa:new-model": [null],
"Cisco-IOS-XE-aaa:authentication": {
"login": [
{
"name": "default",
"a1": {
"local": [null]
}
}
]
},
"Cisco-IOS-XE-aaa:authorization": {
"exec": [
{
"name": "default",
"a1": {
"local": [null]
}
}
]
},
"Cisco-IOS-XE-aaa:common-criteria": [
{
"policy": "enable_secret_policy",

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

156
Model-Driven Programmability
Converting IOS Commands to XML

"char-changes": 4,
"lower-case": 1,
"max-length": 127,
"min-length": 10,
"numeric-count": 1,
"upper-case": 1
}
],
"Cisco-IOS-XE-aaa:session-id": "common"
},
"login": {
"on-success": {
"log": {
}
}
},
"multilink": {
"Cisco-IOS-XE-ppp:bundle-name": "authenticated"
},
"redundancy": {
},
"spanning-tree": {
"Cisco-IOS-XE-spanning-tree:extend": {
"system-id": [null]
}
},
"subscriber": {
"templating": [null]
},
"crypto": {
"Cisco-IOS-XE-crypto:pki": {
"certificate": {
"chain": [
{
"name": "SLA-TrustPoint",
"certificate": [
{
"serial": "01",
"certtype": "ca"
}
]
},
{
"name": "TP-self-signed-2685563505",
"certificate": [
{
"serial": "01",
"certtype": "self-signed"
}
]
}
]
},
"trustpoint": [
{
"id": "SLA-TrustPoint",
"enrollment": {
"pkcs12": [null]
},
"revocation-check": ["crl"]
},
{
"id": "TP-self-signed-2685563505",
"enrollment": {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

157
 Model-Driven Programmability
Converting IOS Commands to XML

"selfsigned": [null]
},
"revocation-check": ["none"],
"rsakeypair": {
"key-label": "TP-self-signed-2685563505"
},
"subject-name": "cn=IOS-Self-Signed-Certificate-2685563505"
}
]
}
},
"license": {
"udi": {
"pid": "C8000V",
"sn": "93SHKMJKOC6"
},
"boot": {
"level": {
"network-advantage": {
"addon": "dna-advantage"
}
}
}
},
"line": {
"aux": [
{
"first": "0"
}
],
"console": [
{
"first": "0",
"exec-timeout": {
"minutes": 0,
"seconds": 0
},
"stopbits": "1"
}
],
"vty": [
{
"first": 0,
"last": 4,
"exec-timeout": {
"minutes": 0,
"seconds": 0
},
"password": {
"secret": "lab"
},
"transport": {
"input": {
"all": [null]
},
"output": {
"all": [null]
}
}
},
{
"first": 5,
"last": 31,
"transport": {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

158
 Model-Driven Programmability
NETCONF Global Session Lock

"input": {
"all": [null]
},
"output": {
"all": [null]
}
}
}
]
},
"Cisco-IOS-XE-diagnostics:diagnostic": {
"bootup": {
"level": "minimal"
}
}
}
}
}

NETCONF Global Session Lock

The NETCONF protocol provides a set of operations to manage device configurations and retrieve device
state information. NETCONF supports a global lock, and the ability to kill non-responsive sessions are
introduced in NETCONF.
To ensure consistency and prevent conflicting configurations through multiple simultaneous sessions, the
owner of the session can lock the NETCONF session. The NETCONF lock RPC locks the configuration
parser and the running configuration database. All other NETCONF sessions (that do not own the lock) cannot
perform edit operations; but can perform read operations. These locks are intended to be short-lived and allow
the owner to make changes without interaction with other NETCONF clients, non-NETCONF clients (such
as, SNMP and CLI scripts), and human users.
A global lock held by an active session is revoked when the associated session is killed. The lock gives the
session holding the lock exclusive write access to the configuration. When a configuration change is denied
due to a global lock, the error message will specify that a NETCONF global lock is the reason the configuration
change has been denied.
The <lock> operation takes a mandatory parameter, <target> that is the name of the configuration datastore
that is to be locked. When a lock is active, the <edit-config> and <copy-config> operations are not allowed.
If the clear configuration lock command is specified while a NETCONF global lock is being held, a full
synchronization of the configuration is scheduled and a warning syslog message is produced. This command
clears only the parser configuration lock.
The following is a sample RPC that shows the <lock> operation:

<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

159
 Model-Driven Programmability
NETCONF Kill Session

NETCONF Kill Session

During a session conflict or client misuse of the global lock, NETCONF sessions can be monitored via the
show netconf-yang sessions command, and non-responsive sessions can be cleared using the clear
netconf-yang session command. The clear netconf-yang session command clears both the NETCONF lock
and the configuration lock.
A <kill-session> request will force a NETCONF session to terminate. When a NETCONF entity receives a
<kill-session> request for an open session, it stops all operations in process, releases all locks and resources
associated with the session, and closes any associated connections.
A <kill-session> request requires the session-ID of the NETCONF session that is to be terminated. If the value
of the session-ID is equal to the current session ID, an invalid-value error is returned. If a NETCONF session
is terminated while its transaction is still in progress, the data model infrastructure will request a rollback,
apply it to the network element, and trigger a synchronization of all YANG models.
If a session kill fails, and a global lock is held, enter the clear configuration lock command via the console
or vty. At this point, the data models can be stopped and restarted.

NETCONF-YANG SSH Server Support

NETCONF-YANG uses the IOS Secure Shell (SSH) Rivest, Shamir, and Adleman (RSA) public keys to
authenticate users as an alternative to password-based authentication.
For public-key authentication to work on NETCONF-YANG, the IOS SSH server must be configured. To
authenticate users to the SSH server, use one of the RSA keys configured by using the ip ssh pubkey-chain
and user commands.
NACM is a group-based access control mechanism. When users are authenticated, they are automatically
placed in an NACM privilege group based on their configured privilege level. Users can also be manually
placed in other user-defined groups. The default privilege level is 1. There are 16 privilege levels, PRIV00
to PRIV15.
If a user authenticates via the public-key; but does not have a corresponding Authentication, Authorization,
and Accounting (AAA) configuration, this user is rejected. If a user authenticates via a public-key; but the
AAA configuration for NETCONF is using a AAA source other than the local, this user is also rejected. Local
and TACACS+ AAA authorization are supported.
Token-based RESTCONF authentication is not supported. SSH user certificates are not supported.

Candidate Configuration Support

The Candidate Configuration feature enables support for candidate capability by implementing RFC 6241
with a simple commit option.
The candidate datastore provides a temporary work space in which a copy of the device's running configuration
is stored. You can create and modify the running configuration before committing the running configuration
to the device. Candidate capability is indicated by the following NETCONF capability:
urn:ietf:params:netconf:capability:candidate:1.0. This NETCONF capability indicates that the device supports
the candidate datastore.
This is a shared data store which enables the user to create, add, delete and make changes to the device
configuration without affecting the running configuration on the device. A commit operation pushes the
configuration from the candidate to the running configuration on the device. When the candidate data store

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

160
 Model-Driven Programmability
NETCONF Operations on Candidate

is enabled, the running data store is not writable through NETCONF sessions, and all configurations get
committed only through the candidate. In other words, the writable-running NETCONF capability is not
enabled with the candidate configuration.

Note It must be kept in mind that candidate datastore is a shared data store. Multiple NETCONF sessions can
modify it contents simultaneously. Therefore, it is important to lock the datastore before modifying its
contents, to prevent conflicting commits that can eventually lead to the loss of any configuration changes.

NETCONF Operations on Candidate

The following operations can be performed on the candidate data store.

Note The information in this section has been referenced from section 8.3.4 of RFC 6241. Please refer to the
RFC for more details and the exact RPCs.

Lock
A <lock> RPC is used to lock the target data store. This prevents others users from modifying the configuration
in the locked data store. Both candidate and running data can be locked through the lock operation.

Note Locking the candidate datastore does not affect the Cisco IOS config lock or the running configuration
lock and vice versa.

Commit
A <commit> RPC, copies the candidate configuration to the device’s running configuration. A commit operation
must be performed after you have updated the candidate configuration to push the configuration to the device.
If either the running or the candidate datastore is locked by another NETCONF session, the <commit> RPC
will fail with an RPC error reply. The <error-tag> should be <in-use> and <error-info> should have the session
ID of the NETCONF session holding the lock. You can also lock the running configuration by using the global
lock by entering the conf t lock mode, but, the commit operation will fail with an RPC error reply, with
error-tag value <in-use> and the session-id will be “0”.

Edit-config
The candidate configuration can be used as a target for the edit-config operation to modify a configuration.
You can change the candidate configuration without affecting the running configuration on the device.

Discard
To remove the changes made to the candidate configuration, perform a discard operation to revert the candidate
configuration to running configuration.
If contents of the candidate datastore are modified by NETCONF session A, and session B tries to lock the
candidate datastore, the lock fails. NETCONF session B must perform a <discard> operation to remove any

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

161
 Model-Driven Programmability
Confirmed Candidate Configuration Commit

outstanding configuration changes on the candidate datastore from other NETCONF sessions before locking
a candidate.

Unlock
After working on candidate configuration, such as, lock, edit-config, or commit operations, you can unlock
the datastore, by specifying candidate as target in the unlock RPC. The candidate datastore is now available
for all operations in other sessions.
If a failure occurs with outstanding changes to the candidate datastore, it can be challenging to recover the
configuration, and may create problems for other sessions. To avoid any issues, outstanding changes must be
discarded when the lock is released—either implicitly on “NETCONF session failure” or explicitly by using
the unlock operation.

Get-config, Copy-config, Validate

The candidate datastore can be used as a source or target for any of the get-config, copy-config or validate
config operations. If you do not want to commit the changes in the candidate datastore to the device; but only
to validate the configuration, you ca nuse the <validate> RPC followed by a discard operation.

Modifying the Candidate Datastore

The following diagram explains the recommended best practice when modifying the device configuration
through candidate datastore:
Figure 4: Modifying Candidate Datastore Steps

1. Lock the running datastore.

2. Lock the candidate datastore.
3. Make modifications to the candidate configuration through edit-config RPCs with the target candidate.
4. Commit the candidate configuration to the running configuration.
5. Unlock the candidate and running datastores.

Confirmed Candidate Configuration Commit

The candidate configuration supports the confirmed commit capability. This implementation is as specified
in RFC 6241 for the confirmed commit capability which, when issued, sets the running configuration to the
current contents of the candidate configuration and starts a confirmed commit timer. The confirmed commit
operation will be rolled back if the commit is not issued within the timeout period. The default timeout period
is 600 seconds or 10 minutes.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

162
Model-Driven Programmability
Confirmed Candidate Configuration Commit

When you commit the candidate configuration, you can require an explicit confirmation for the commit to
become permanent. The confirmed commit operation is useful for verifying that a configuration change works
correctly and does not prevent management access to the device. If the change prevents access or causes other
errors, the automatic rollback to the previous configuration restores access after the rollback deadline passes.
If the commit is not confirmed within the specified amount of time,by default, the device automatically
retrieves and commits (rolls back to) the previously committed configuration.

Note RESTCONF does not support confirmed commit.

In a NETCONF session, to commit the candidate configuration and to explicitly confirm the commit to become
permanent, a client application encloses the empty <confirmed/> tag in the <commit> and <rpc> tag elements:

<rpc>
<commit>
<confirmed/>
</commit>
</rpc>

The following sample RPC shows how to change the default rollback timer:

<rpc>
<commit>
<confirmed/>
<confirm-timeout>nnn</confirm-timeout> !nnn is the rollback-delay in seconds.
</commit>
</rpc>

The following sample RPC shows that the NETCONF server confirms that the candidate configuration is
committed temporarily:

<rpc-reply xmlns="URN" xmlns:junos="URL">

<ok/>
</rpc-reply>

If the NETCONF server cannot commit the candidate configuration, the <rpc-reply> element will enclose an
<rpc-error> element explaining the reason for the failure. The most common causes are semantic or syntactic
errors in the candidate configuration.
To delay the rollback to a time later than the current rollback timer, the client application sends a <confirmed/>
tag inside a <commit> tag element again before the deadline passes. Optionally, it includes the
<confirm-timeout> element to specify how long to delay the next rollback. The client application can delay
the rollback indefinitely by sending the <confirmed/> tag repeatedly.
To commit the configuration permanently, the client application sends the <commit/> tag enclosed in an <rpc>
tag element before the rollback deadline passes. The rollback is canceled and the candidate configuration is
committed immediately. If the candidate configuration is the same as the temporarily committed configuration,
the temporarily committed configuration is recommitted.
If another application uses the <kill-session/> tag element to terminate this application’s session while a
confirmed commit is pending (this application has committed changes but not yet confirmed them), the
NETCONF server that is using this session restores the configuration to its state before the confirmed commit
instruction was issued.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

163
 Model-Driven Programmability
Candidate Support Configuration

The candidate datastore is disabled by using the no netconf-yang feature candidate-datastore command.
Because the candidate datastore confirmed commit is enabled when the candidate datastore is enabled, the
confirmed commit is disabled when the candidate datastore is disabled. All sessions in progress are terminated,
and the confd program is restarted.

Candidate Support Configuration

The candidate datastore functionality can be enabled by using the netconf-yang feature candidate-datastore
command. When the datastore state changes from running to candidate or back, a warning message is displayed,
notifying the user that a restart of NETCONF or RESTCONF will occur in order for the change to take effect.
If the selection of the candidate or running datastore is specified in the configuration when a NETCONF-YANG
or RESTCONF confd process starts, a warning message appears as shown below:
Device(config)# netconf-yang feature candidate-datastore

netconf-yang initialization in progress - datastore transition not allowed, please try again
after 30 seconds

If the selection of the candidate or running datastore is made after the NETCONF-YANG or RESTCONF
confd process starts, the following apply:
• If the netconf-yang feature candidate-datastore command is configured, the command enables the
candidate datastore and prints the following warning:
“netconf-yang and/or restconf is transitioning from running to candidate netconf-yang
and/or restconf will now be restarted,
and any sessions in progress will be terminated”.

• If the netconf-yang feature candidate-datastore command is removed, the command disables the
candidate datastore, enables the running datastore and prints the following warning:
netconf-yang and/or restconf is transitioning from candidate to running netconf-yang
and/or restconf will now be restarted,
and any sessions in progress will be terminated”.

• When NETCONF-YANG or RESTCONF are restarted, sessions in progress will be lost.

Side-Effect Synchronization of the Configuration Database

During configuration changes in the data model interface (DMI), a partial synchronization of the changes that
are triggered when a command or RPC is configured happens. This is called the side-effect synchronization,
and it reduces the synchronization time and NETCONF downtime. Prior to the side-effect synchronization,
any configuration change used to trigger a time-consuming full synchronization of the configuration database.
The side-effect synchronization is enabled by the netconf-yang feature side-effect-sync command.
Some commands, when they are configured, triggers changes in some already configured commands. For
example, the following is the configuration on a device before the NETCONF edit-config RPC is configured:
hostname device123

The NETCONF edit-config RPC:

<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<hostname xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" nc:operation="delete"/>
</native>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

164
 Model-Driven Programmability
How to Configure the NETCONF Protocol

The following is the configuration on the device after the NETCONF edit-config RPC is configured:
hostname Switch

Here, the side-effect of the NETCONF edit-config RPC is a change to the running configuration that is not
directly intended by the RPC. The edit-config request is supposed to delete the host name, but instead the
hostname is changed back to Switch. The side-effect synchronization does a synchronization of this
configuration change to the NETCONF database without synchronizing the entire configuration, thereby
improving performance.
The side-effect synchronization is based on the CLI-mode tree concept, where the commands are maintained
with modes and submodes structure. This CLI-mode tree data structure consists of three main nodes:
• Same-Level Node: This node points to the list of CLI nodes that belongs to the same parent and on the
same level.
• Parent Node: This node points to the CLI nodes parent, its mode, and submode node.
• Child Node: This node points to the child CLI; the CLI under the current mode or submode. If the node
has multiple child nodes then those child nodes are linked as part of the same-level node pointers.

How to Configure the NETCONF Protocol

NETCONF-YANG uses the primary trustpoint of a device. If a trustpoint does not exist, when
NETCONF-YANG is configured, it creates a self-signed trustpoint. For more information, see the Public Key
Infrastructure Configuration Guide, Cisco IOS XE Gibraltar 16.10.x.

Providing Privilege Access to Use NETCONF

To start working with NETCONF APIs, you must be a user with privilege level 15.

SUMMARY STEPS
1. enable
2. configure terminal
3. username name privilege level password password
4. aaa new-model
5. aaa authentication login default local
6. aaa authorization exec default local
7. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: Enter your password if prompted.
Device# enable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

165
 Model-Driven Programmability
Configuring NETCONF-YANG

Command or Action Purpose

Step 2 configure terminal Enters global configuration mode.
Example:
Device# configure terminal

Step 3 username name privilege level password password Establishes a user name-based authentication system.
Configure the following keywords:
Example:
Device(config)# username example-name privilege 15 • privilege level: Sets the privilege level for the user.
password example_password For the NETCONF protocol, it must be 15.
• password password: Sets a password to access the
CLI view.

Step 4 aaa new-model (Optional) Enables authorisation, authentication, and

accounting (AAA).
Example:
Device(config)# aaa new-model If the aaa new-model command is configured, AAA
authentication and authorization is required.

Step 5 aaa authentication login default local Sets the login authentication to use the local username
database.
Example:
Device(config)# aaa authentication login default Note Only the default AAA authentication login
local method is supported for the NETCONF protocol.

• For a remote AAA server, replace local with your

AAA server.
The default keyword applies the local user database
authentication to all ports.

Step 6 aaa authorization exec default local Configures user AAA authorization, check the local
database, and allows the user to run an EXEC shell.
Example:
Device(config)# aaa authorization exec default • For a remote AAA server, replace local with your
local AAA server.
• The default keyword applies the local user database
authentication to all ports.

Step 7 end Exits global configuration mode and returns to privileged

EXEC mode.
Example:
Device(config)# end

Configuring NETCONF-YANG
If the legacy NETCONF protocol is enabled on your device, the RFC-compliant NETCONF protocol does
not work. Disable the legacy NETCONF protocol by using the no netconf legacy command.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

166
 Model-Driven Programmability
Configuring NETCONF Options

SUMMARY STEPS
1. enable
2. configure terminal
3. netconf-yang
4. netconf-yang feature candidate-datastore
5. exit

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 netconf-yang Enables the NETCONF interface on your network device.

Example: Note After the initial enablement through the CLI,
Device (config)# netconf-yang network devices can be managed subsequently
through a model based interface. The complete
activation of model-based interface processes
may require up to 90 seconds.

Step 4 netconf-yang feature candidate-datastore Enables candidate datastore.

Example:
Device(config)# netconf-yang feature
candidate-datastore

Step 5 exit Exits global configuration mode.

Example:
Device (config)# exit

Configuring NETCONF Options

Configuring SNMP
Enable the SNMP Server in IOS to enable NETCONF to access SNMP MIB data using YANG models
generated from supported MIBs, and to enable supported SNMP traps in IOS to receive NETCONF notifications
from the supported traps.
Perform the following steps:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

167
 Model-Driven Programmability
Configuring SNMP

SUMMARY STEPS
1. Enable SNMP features in IOS.
2. After NETCONF-YANG starts, enable SNMP Trap support by sending the following RPC <edit-config>
message to the NETCONF-YANG port.
3. Send the following RPC message to the NETCONF-YANG port to save the running configuration to the
startup configuration.

DETAILED STEPS

Step 1 Enable SNMP features in IOS.

Example:
configure terminal
logging history debugging
logging snmp-trap emergencies
logging snmp-trap alerts
logging snmp-trap critical
logging snmp-trap errors
logging snmp-trap warnings
logging snmp-trap notifications
logging snmp-trap informational
logging snmp-trap debugging
!
snmp-server community public RW
snmp-server trap link ietf
snmp-server enable traps snmp authentication linkdown linkup
snmp-server enable traps syslog
snmp-server manager
exit

Step 2 After NETCONF-YANG starts, enable SNMP Trap support by sending the following RPC <edit-config> message to the
NETCONF-YANG port.
Example:
<?xml version="1.0" encoding="utf-8"?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="">
<edit-config>
<target>
<running/>
</target>
<config>
<netconf-yang xmlns="http://cisco.com/yang/cisco-self-mgmt">
<cisco-ia xmlns="http://cisco.com/yang/cisco-ia">
<snmp-trap-control>
<trap-list>
<trap-oid>1.3.6.1.4.1.9.9.41.2.0.1</trap-oid>
</trap-list>
<trap-list>
<trap-oid>1.3.6.1.6.3.1.1.5.3</trap-oid>
</trap-list>
<trap-list>
<trap-oid>1.3.6.1.6.3.1.1.5.4</trap-oid>
</trap-list>
</snmp-trap-control>
</cisco-ia>
</netconf-yang>
</config>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

168
 Model-Driven Programmability
Configuring the SSH Server to Perform RSA-Based User Authentication

</edit-config>
</rpc>

Step 3 Send the following RPC message to the NETCONF-YANG port to save the running configuration to the startup
configuration.
Example:
<?xml version="1.0" encoding="utf-8"?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="">
<cisco-ia:save-config xmlns:cisco-ia="http://cisco.com/yang/cisco-ia"/>
</rpc>

Configuring the SSH Server to Perform RSA-Based User Authentication

Perform this task to configure the SSH public key for NETCONF-YANG to authenticate users.

SUMMARY STEPS
1. enable
2. configure terminal
3. ip ssh pubkey-chain
4. username username
5. key-string
6. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 ip ssh pubkey-chain Configures SSH-RSA keys for user and server
authentication on the SSH server and enters public-key
Example:
configuration mode.
Device(config)# ip ssh pubkey-chain
• The user authentication is successful if the RSA public
key stored on the server is verified with the public or
the private key pair stored on the client.

Step 4 username username Configures the SSH username and enters public-key user
configuration mode.
Example:
Device(conf-ssh-pubkey)# username user1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

169
 Model-Driven Programmability
Verifying the NETCONF Protocol Configuration Through the CLI

Command or Action Purpose

Step 5 key-string Specifies the RSA public key of the remote peer and enters
public-key data configuration mode.
Example:
Device(conf-ssh-pubkey-user)# key-string Note You can obtain the public key value from an
open SSH client; that is, from the .ssh/id_rsa.pub
file.

Step 6 end Exits public-key data configuration mode and returns to

privileged EXEC mode.
Example:
Device(conf-ssh-pubkey-data)# end • Use no hostname command to return to the default
host.

Verifying the NETCONF Protocol Configuration Through the CLI

Use the following commands to verify your NETCONF configuration.

SUMMARY STEPS
1. show netconf-yang datastores
2. show netconf-yang sessions
3. show netconf-yang sessions detail
4. show netconf-yang diagnostics summary
5. show netconf-yang statistics
6. show platform software yang-management process

DETAILED STEPS

Step 1 show netconf-yang datastores

Displays information about NETCONF-YANG datastores.
Example:
Device# show netconf-yang datastores

Device# show netconf-yang datastores

Datastore Name : running
Globally Locked By Session : 42
Globally Locked Time : 2018-01-15T14:25:14-05:00

Step 2 show netconf-yang sessions

Displays information about NETCONF-YANG sessions.
Example:
Device# show netconf-yang sessions

R: Global-lock on running datastore

C: Global-lock on candidate datastore

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

170
 Model-Driven Programmability
Verifying the NETCONF Protocol Configuration Through the CLI

S: Global-lock on startup datastore

Number of sessions : 10
session-id transport username source-host global-lock
-------------------------------------------------------------------------------
40 netconf-ssh admin 10.85.70.224 None
42 netconf-ssh admin 10.85.70.224 None
44 netconf-ssh admin 10.85.70.224 None
46 netconf-ssh admin 10.85.70.224 None
48 netconf-ssh admin 10.85.70.224 None
50 netconf-ssh admin 10.85.70.224 None
52 netconf-ssh admin 10.85.70.224 None
54 netconf-ssh admin 10.85.70.224 None
56 netconf-ssh admin 10.85.70.224 None
58 netconf-ssh admin 10.85.70.224 None

Step 3 show netconf-yang sessions detail

Displays detailed information about NETCONF-YANG sessions.
Example:
Device# show netconf-yang sessions detail

R: Global-lock on running datastore

C: Global-lock on candidate datastore
S: Global-lock on startup datastore

Number of sessions : 1

session-id : 19
transport : netconf-ssh
username : admin
source-host : 2001:db8::1
login-time : 2018-10-26T12:37:22+00:00
in-rpcs : 0
in-bad-rpcs : 0
out-rpc-errors : 0
out-notifications : 0
global-lock : None

Step 4 show netconf-yang diagnostics summary

Displays a summary of the NETCONF-YANG diagnostic information.
Example:
Device# show netconf-yang diagnostics summary

Diagnostic Debugging is ON
Diagnostic Debugging Level: Maximum
Total Log Size (bytes): 20097
Total Transactions: 1
message username session-id transaction-id start-time end-time log size
----------------------------------------------------------------------------------------
1 admin 35 53 03/12/21 14:31:03 03/12/21 14:31:04 20097

Step 5 show netconf-yang statistics

Displays information about NETCONF-YANG statistics.
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

171
 Model-Driven Programmability
Verifying the NETCONF Protocol Configuration Through the CLI

Device# show netconf-yang statistics

netconf-start-time : 2018-01-15T12:51:14-05:00
in-rpcs : 0
in-bad-rpcs : 0
out-rpc-errors : 0
out-notifications : 0
in-sessions : 10
dropped-sessions : 0
in-bad-hellos : 0

Step 6 show platform software yang-management process

Displays the status of the software processes required to support NETCONF-YANG.
Example:
Device# show platform software yang-management process

confd : Running
nesd : Running
syncfd : Running
ncsshd : Running
dmiauthd : Running
vtyserverutild : Running
opdatamgrd : Running
nginx : Running
ndbmand : Running

Note The process nginx runs if ip http secure-server or ip http server is configured on the device. This process is
not required to be in the running state for NETCONF to function properly. However, the nginx process is
required for RESTCONF.

Table 12: show platform software yang-management process Field Descriptions

Field Description

confd Configuration daemon

nesd Network element synchronizer daemon

syncfd Sync from daemon

ncsshd NETCONF Secure Shell (SSH) daemon

dmiauthd Device management inteface (DMI) authentication daemon

vtyserverutild VTY server util daemon

opdatamgrd Operational Data Manager daemon

nginx NGINX web server

ndbmand NETCONF database manager

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

172
 Model-Driven Programmability
Displaying NETCONF-YANG Diagnostics Through RPCs

Displaying NETCONF-YANG Diagnostics Through RPCs

You can either use the show netconf-yang diagnostics command or the following RPCs to view the diagnostics
information.
The following is a sample RPC that enables NETCONF-YANG diagnostics, and the RPC response received
from the host:

#308
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:b0f45ac0-3fe2-4e1d-a3a1-f57985965be6">
<enable-netconf-diag xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-rpc">
<diag-level>diag-maximum</diag-level>
</enable-netconf-diag>
</nc:rpc>

##

Received message from host

<?xml version="1.0" ?>
<rpc-reply message-id="urn:uuid:b0f45ac0-3fe2-4e1d-a3a1-f57985965be6"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>

The following is a sample RPC that shows the current status and the RPC response received from the host:

#294
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:c6c986ac-fc44-45e2-9390-f8a5968dc8d4">
<nc:get>
<nc:filter>
<netconf-diag-oper-data
xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-oper"/>
</nc:filter>
</nc:get>
</nc:rpc>

Received message from host

<?xml version="1.0" ?>
<rpc-reply message-id="urn:uuid:c6c986ac-fc44-45e2-9390-f8a5968dc8d4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-diag-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-oper">

<diag-summary>
<level>diag-maximum</level>
<log-size>0</log-size>
<trans-count>0</trans-count>
</diag-summary>
</netconf-diag-oper-data>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

173
 Model-Driven Programmability
Displaying NETCONF-YANG Diagnostics Through RPCs

</data>
</rpc-reply>

The following is a sample RPC to change the host name and the RPC response received from the host:
#
#364
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:f3005ee6-8a11-4146-b616-dd95a92b97d1">
<nc:edit-config>
<nc:target>
<nc:running/>
</nc:target>
<nc:config>
<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<hostname>new-ott-c9300-35</hostname>
</native>
</nc:config>
</nc:edit-config>
</nc:rpc>

##

Received message from host

<?xml version="1.0" ?>
<rpc-reply message-id="urn:uuid:f3005ee6-8a11-4146-b616-dd95a92b97d1"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>

The following is a sample RPC to display the current status and the RPC response received from the host:

#294
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:9bffb8d5-3866-48ef-b59d-0486e508fbc4">
<nc:get>
<nc:filter>
<netconf-diag-oper-data
xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-oper"/>
</nc:filter>
</nc:get>
</nc:rpc>

##

Received message from host

<?xml version="1.0" ?>
<rpc-reply message-id="urn:uuid:9bffb8d5-3866-48ef-b59d-0486e508fbc4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-diag-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-oper">

<diag-summary>
<level>diag-maximum</level>
<log-size>20775</log-size>
<trans-count>1</trans-count>
</diag-summary>
<diag-trans>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

174
Model-Driven Programmability
Displaying NETCONF-YANG Diagnostics Through RPCs

<message>1</message>
<username>lab</username>
<session-id>31</session-id>
<trans-id>50</trans-id>
<start-time>2021-03-12T14:08:26.830334+00:00</start-time>
<end-time>2021-03-12T14:08:28.279414+00:00</end-time>
<log-size>20775</log-size>
</diag-trans>
</netconf-diag-oper-data>
</data>
</rpc-reply>

The following is a sample RPC to archive the collected system error messages, and the RPC response from
the host:
#
#256
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:1dbc795c-f594-4194-a89b-fd4d88446b69">
<archive-netconf-diag-logs xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-rpc"/>
</nc:rpc>

##

Received message from host

<?xml version="1.0" ?>
<rpc-reply message-id="urn:uuid:1dbc795c-f594-4194-a89b-fd4d88446b69"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<log-file xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-rpc">
bootflash:netconf-yang-diag.20210312141009.tar.gz</log-file>

</rpc-reply>

The following is a sample RPC that disables NETCONF-YANG diagnostics, and the RPC response received
from the host:

#309
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:d253a313-4aec-42bc-80a2-672e9bb9ad56">
<enable-netconf-diag xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-netconf-diag-rpc">
<diag-level>diag-disabled</diag-level>
</enable-netconf-diag>
</nc:rpc>

##

Received message from host

<?xml version="1.0" ?>
<rpc-reply message-id="urn:uuid:d253a313-4aec-42bc-80a2-672e9bb9ad56"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

175
 Model-Driven Programmability
Additional References for NETCONF Protocol

Additional References for NETCONF Protocol

Related Documents

Related Topic Document Title

YANG data models for various release of To access Cisco YANG models in a developer-friendly way,
IOS-XE, IOS-XR, and NX-OS platforms please clone the GitHub repository, and navigate to the
vendor/cisco subdirectory. Models for various releases of
IOS-XE, IOS-XR, and NX-OS platforms are available here.

Standards and RFCs

Standard/RFC Title
RFC 6020 YANG - A Data Modeling Language for the Network Configuration
Protocol (NETCONF)

RFC 6241 Network Configuration Protocol (NETCONF)

RFC 6536 Network Configuration Protocol (NETCONF) Access Control Model

RFC 7950 The YANG 1.1 Data Modeling Language

RFC 8040 RESTCONF Protocol

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, http://www.cisco.com/support
including documentation and tools for troubleshooting and resolving
technical issues with Cisco products and technologies.
To receive security and technical information about your products,
you can subscribe to various services, such as the Product Alert Tool
(accessed from Field Notices), the Cisco Technical Services
Newsletter, and Really Simple Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a
Cisco.com user ID and password.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

176
 Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Information for the NETCONF Protocol

Table 13: Feature Information for NETCONF Protocol

Feature Name Release Feature Information

NETCONF Protocol Cisco IOS XE Denali 16.3.1 The NETCONF Protocol feature facilitates a
programmatic and standards-based way of
writing configurations and reading operational
data from network devices.
The following command was introduced:
netconf-yang.
This feature was implemented on the
following platforms:
• Cisco 4000 Series Integrated Services
Routers
• Cisco ASR 1000 Series Aggregation
Services Routers
• Cisco Cloud Services Router 1000V
Series

Cisco IOS XE Everest 16.5.1a This feature was implemented on the

following platforms:
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches

Cisco IOS XE Everest 16.6.2 This feature was implemented on the

following platforms:
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Fuji 16.8.1a

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

177
 Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

In Cisco IOS XE Fuji 16.8.1a, this feature was
implemented on the following platforms:
• Cisco 1000 Series Integrated Services
Routers
• Cisco ASR 900 Series Aggregation
Services Routers
• Cisco ASR 920 Series Aggregation
Services Routers
• Cisco Catalyst 9500-High Performance
Series Switches
• Cisco CBR-8 Series Routers
• Cisco Network Convergence System
4200 Series

Cisco IOS XE Fuji 16.9.2 This feature was implemented on the

following platforms:
• Cisco Catalyst 9200 and 9200L Series
Switches
• Cisco Catalyst 9300L SKUs

Cisco IOS XE Gibraltar In Cisco IOS XE Gibraltar 16.10.1, this

16.10.1 feature was implemented on the following
platforms:
• Cisco Catalyst 9800-40 Wireless
Controllers
• Cisco Catalyst 9800-80 Wireless
Controllers
• Cisco Network Convergence System 520
Series

Cisco IOS XE Gibraltar In Cisco IOS XE Gibraltar 16.11.1, this

16.11.1 feature was implemented on Cisco Catalyst
9600 Series Switches.

Cisco IOS XE Gibraltar In Cisco IOS XE Gibraltar 16.12.1, this

16.12.1 feature was implemented on Cisco Catalyst
9800-L Wireless Controllers.

Cisco IOS XE Amsterdam

17.3.1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

178
Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

In Cisco IOS XE Amsterdam 17.3.1, this
feature was implemented on the following
platforms:
• Cisco Catalyst 8200 Series Edge
Platforms
• Cisco Catalyst 8300 Series Edge
Platforms
• Cisco Catalyst 8500 and 8500L Series
Edge Platforms

NETCONF and RESTCONF Cisco IOS XE Fuji 16.8.1a IPv6 support for the NETCONF and
IPv6 Support RESTCONF protocols. This feature was
implemented on the following platforms:
• Cisco 4000 Series Integrated Services
Routers
• Cisco ASR 1000 Series Aggregation
Services Routers
• Cisco ASR 900 Series Aggregation
Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco CBR-8 Series Routers
• Cisco Cloud Services Router 1000V
Series

Cisco IOS XE Gibraltar In Cisco IOS XE Gibraltar 16.11.1, this

16.11.1 feature was implemented on Cisco Catalyst
9500-High Performance Series Switches.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

179
 Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

NETCONF Global Lock and Cisco IOS XE Fuji 16.8.1a The NETCONF protocol supports a global
Kill Session lock, and the ability to kill non-responsive
sessions. This feature is implemented on the
following platforms:
• Cisco 1100 Series Integrated Services
Routers
• Cisco 4000 Series Integrated Services
Routers
• Cisco ASR 1000 Series Aggregation
Services Routers
• Cisco ASR 900 Series Aggregation
Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco CBR-8 Series Routers
• Cisco Cloud Services Router 1000v
Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

180
Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

NETCONF: Candidate Cisco IOS XE Fuji 16.9.1 The Candidate Config Support feature enables
Configuration Support support for candidate capability by
implementing RFC 6241 with a simple commit
option.
This feature was implemented on the
following platforms:
• Cisco 4000 Series Integrated Services
Routers
• Cisco ASR 1000 Series Aggregation
Services Routers
• Cisco ASR 900 Series Aggregation
Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco CBR-8 Series Routers
• Cisco Cloud Services Router 1000V
Series

The following command was introduced:

netconf-yang feature candidate-datastore.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

181
 Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

NETCONF: Candidate Cisco IOS XE Amsterdam The candidate configuration supports the
Configuration Commit 17.1.1 confirmed commit capability.
Confirm
This feature was implemented on the
following platforms:
• Cisco 1000 Series Integrated Services
Routers
• Cisco 4000 Series Integrated Services
Routers
• Cisco ASR 1000 Series Aggregation
Services Routers
• Cisco ASR 900 Series Aggregation
Services Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco cBR-8 Converged Broadband
Router
• Cisco Cloud Services Router 1000V
Series
• Cisco Network Convergence System 520
Series
• Cisco Network Convergence System
4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

182
Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

NETCONF-YANG SSH Cisco IOS XE Gibraltar This feature was implemented on the
Server Support 16.12.1 following platforms:
• Cisco 1000 Series Integrated Services
Routers
• Cisco 4000 Series Integrated Services
Routers
• Cisco ASR 900 Series Aggregation
Services Routers
• Cisco ASR 920 Series Aggregation
Services Routers
• Cisco ASR 1000 Aggregation Services
Routers
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800 Series Wireless
Controllers
• Cisco cBR-8 Converged Broadband
Router
• Cisco Cloud Services Router 1000V
Series
• Cisco Network Convergence System 520
Series
• Cisco Network Convergence System
4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

183
 Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

Side-Effect Synchronization Cisco IOS XE Bengaluru During configuration changes in the DMI, a
of the Configuration Database 17.4.1 partial synchronization of the changes that are
triggered when a command or RPC is
configured happens. This is called the
side-effect synchronization, and it reduces the
synchronization time and NETCONF
downtime.
This feature was implemented on the
following platforms:
• Cisco ASR 1000 Aggregation Services
Routers
• Cisco Catalyst 8500 and 8500L Series
Edge Platforms
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

184
Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

YANG Model Version 1.1 Cisco IOS XE Cupertino Cisco IOS XE Cupertino 17.7.1 uses the
17.7.1 YANG Version 1.0; however, you can also
use YANG Version 1.1. Download the YANG
Version 1.1 from GitHub at
https://github.com/YangModels/yang/tree/master/vendor/cisco/xefolder.
This feature was implemented on the
following platforms:
• Cisco 1000 Series Integrated Services
Routers
• Cisco 4000 Series Integrated Services
Routers
• Cisco ASR 900 Aggregation Services
Routers
• Cisco ASR 920 Aggregation Services
Routers
• Cisco ASR 1000 Aggregation Services
Routers
• Cisco Catalyst 9200 and 9200L Series
Switches
• Cisco Catalyst 9300 and 9300L Series
Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High
Performance Series Switches
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-40 Wireless
Controllers
• Cisco Catalyst 9800-80 Wireless
Controllers
• Cisco cBR-8 Converged Broadband
Router
• Cisco Cloud Services Router 1000V
Series
• Cisco Network Convergence System 520
Series
• Cisco Network Convergence System
4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

185
 Model-Driven Programmability
Feature Information for the NETCONF Protocol

Feature Name Release Feature Information

Cisco IOS XE Cupertino Cisco IOS XE Cupertino 17.8.1 uses YANG
17.8.1 Version 1.1. The difference between YANG
Version 1.1 and Version 1.0 is documented at
https://tools.ietf.org/html/rfc7950#page-10

Cisco IOS XE Dublin 17.10.1 Cisco-defined YANG models are in YANG

Version 1.1 in Cisco IOS XE Dublin 17.10.1
and later releases.

Converting IOS Commands Cisco IOS XE Cupertino This feature helps to automatically translate
to XML 17.7.1 IOS commands into relevant
NETCONF-YANG XML or
RESTCONF-JSON request messages.
This feature is supported on all platforms that
support NETCONF-YANG.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

186
 CHAPTER 8
RESTCONF Protocol
This chapter describes how to configure the HTTP-based Representational State Transfer Configuration
Protocol (RESTCONF). RESTCONF provides a programmatic interface based on standard mechanisms for
accessing configuration data, state data, data-model-specific Remote Procedure Call (RPC) operations and
events, defined in the YANG model.
• Prerequisites for the RESTCONF Protocol, on page 187
• Restrictions for the RESTCONF Protocol, on page 187
• Information About the RESTCONF Protocol, on page 188
• How to Configure the RESTCONF Protocol, on page 208
• Configuration Examples for the RESTCONF Protocol, on page 213
• Additional References for the RESTCONF Protocol, on page 216
• Feature Information for the RESTCONF Protocol, on page 217

Prerequisites for the RESTCONF Protocol

• Enable the Cisco IOS-HTTP services for RESTCONF. For more information, see Examples for
RESTCONF RPCs

Restrictions for the RESTCONF Protocol

The following restrictions apply to the RESTCONF protocol:
• Notifications and event streams
• YANG patch
• Optional query parameters, such as, filter, start-time, stop-time, replay, and action
• The RESTCONF feature is not supported on a device running dual IOSd configuration or software
redundancy.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

187
 Model-Driven Programmability
Information About the RESTCONF Protocol

Information About the RESTCONF Protocol

Overview of RESTCONF
This section describes the protocols and modelling languages that enable a programmatic way of writing
configurations to a network device.
• RESTCONF—Uses structured data (XML or JSON) and YANG to provide a REST-like APIs, enabling
you to programmatically access different network devices. RESTCONF APIs use HTTPs methods.
• YANG—A data modelling language that is used to model configuration and operational features . YANG
determines the scope and the kind of functions that can be performed by NETCONF and RESTCONF
APIs.

In releases prior to Cisco IOS XE Fuji 16.8.1, an operational data manager (based on polling) was enabled
separately. In Cisco IOS XE Fuji 16.8.1 and later releases, operational data works on platforms running
NETCONF (similar to how configuration data works), and is enabled by default. For more information on
the components that are enabled for operational data queries or streaming, see the GitHub respository, and
view *-oper in the naming convention.

HTTPs Methods
The HTTPS-based RESTCONF protocol (RFC 8040), is a stateless protocol that uses secure HTTP methods
to provide CREATE, READ, UPDATE, and DELETE (CRUD) operations on a conceptual datastore containing
YANG-defined data, which is compatible with a server that implements NETCONF datastores.
The following table shows how the RESTCONF operations relate to NETCONF protocol operations:

OPTIONS SUPPORTED METHODS

GET Read

PATCH Update

PUT Create or Replace

POST Create or Operations (reload, default)

DELETE Deletes the targeted resource

HEAD Header metadata (no response body)

RESTCONF Root Resource

• A RESTCONF device determines the root of the RESTCONF API through the link element:
/.well-known/host-meta resource that contains the RESTCONF attribute.
• A RESTCONF device uses the RESTCONF API root resource as the initial part of the path in the request
URI.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

188
 Model-Driven Programmability
Displaying Version Information

Example:
Example returning /restconf:

The client might send the following:

GET /.well-known/host-meta HTTP/1.1

Host: example.com
Accept: application/xrd+xml

The server might respond as follows:

HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn

<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>

Example of URIs:
• GigabitEthernet0/0/2 -
https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=0%2F0%2F2
• fields=name –
https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=0%2F0%2F2?fields=name
• depth=1 -
https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet?depth=1
• Name and IP -
https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface?fields=GigabitEthernet/ip/address/primary;name
• MTU (fields) -
https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface?fields=GigabitEthernet(mtu)
• MTU -
https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=3/mtu
• Port-Channel -
https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/Port-channel
• “Char” to “Hex” conversion chart: http://www.columbia.edu/kermit/ascii.html

Displaying Version Information

The Cisco-IOS-XE-install-oper module that has various nodes to display the version information.
The following sample RPC shows the some of the supported nodes of the Cisco-IOS-XE-install-oper module
and the response from the host that contains the major and minor release version:

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:7d0908d8-0d5f-4521-9d7b-380b81304776">
<nc:get>
<nc:filter>
<install-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-install-oper">
<install-location-information>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

189
 Model-Driven Programmability
Displaying Version Information

<install-version-info>
<version/>
<version-extension/>
<current/>
<src-filename/>
</install-version-info>
</install-location-information>
</install-oper-data>
</nc:filter>
</nc:get>
</nc:rpc>

##
Received message from host

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="urn:uuid:7d0908d8-0d5f-4521-9d7b-380b81304776">
<data>
<install-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-install-oper">
<install-location-information>
<install-version-info>
<version>17.06.04.0.3870</version>
<version-extension>1651661105</version-extension>
<current>install-version-state-present</current>
<src-filename/>
</install-version-info>
<install-version-info>
<version>17.09.01.0.158212</version>
<version-extension>1651125381</version-extension>
<current>install-version-state-present</current>
<src-filename/>
</install-version-info>
<install-version-info>
<version>17.10.01.0.158658</version>
<version-extension>1651754624</version-extension>
<current>install-version-state-present</current>

<src-filename>/bootflash/c8000v-universalk9nic.2022-05-05_18.13.SSA.bin</src-filename>
</install-version-info>
<install-version-info>
<version>17.10.01.0.160585</version>
<version-extension>1656581638</version-extension>
<current>install-version-state-provisioned-committed</current>
<src-filename>/bootflash/c8000v-universalk9.2022-06-30_15.03.SSA.bin</src-filename>

</install-version-info>
<install-version-info>
<version>17.10.01.0.162616</version>
<version-extension>1657120419</version-extension>
<current>install-version-state-present</current>
<src-filename>/bootflash/c8000v-universalk9.BLD_POLARIS_DEV_LATEST_20220706_
143733.SSA.bin</src-filename>
</install-version-info>
</install-location-information>
</install-oper-data>
</data>
</rpc-reply>

When using the protocol, gNMI, NETCONF, or RESTCONF, the Cisco-IOS-XE-native:version module only
displays the major release version.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

190
 Model-Driven Programmability
RESTCONF API Resource

RESTCONF API Resource

The API resource is the top-level resource located at +restconf. It supports the following media types:

Note Media is the type of YANG formated RPC that is sent to the RESCONF server (XML or JSON).

• Application/YANG-Data+XML OR Application/YANG-Data+JSON
• The API resource contains the RESTCONF root resource for the RESTCONF DATASTORE and
OPERATION resources. For example:

The client may then retrieve the top-level API resource, using the
root resource "/restconf".

GET /restconf HTTP/1.1

Host: example.com
Accept: application/yang-data+json

The server might respond as follows:

HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json

{
"ietf-restconf:restconf" : {
"data" : {},
"operations" : {},
"yang-library-version" : "2016-06-21"
}
}

For more information, refer to RFC 3986

Methods
Methods are HTTPS operations (GET/PATCH/POST/DELETE/OPTIONS/PUT) performed on a target
resource. A YANG-formated RPC invokes a particular method on a given resource that pertains to a target
YANG model residing in the RESTCONF server. The uniform resource identifier (URI) acts as a location
identification for a given resource, so that the client RESTCONF method can locate that particular resource
to take an action specified by an HTTPS method or property.
For more information, see RFC 8040 - RESTCONF Protocol

RESTCONF YANG-Patch Support

RESTCONF supports YANG-Patch media type as specified by RFC 8072. A YANG-Patch is an ordered list
of edits that are applied to the target datastore by the RESTCONF server. The YANG Patch operation is
invoked by the RESTCONF client by sending a Patch method request with a representation using either the
media type application/yang-patch+xml or application/yang-patch+json.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

191
 Model-Driven Programmability
RESTCONF YANG-Patch Support

A YANG-Patch is identified by a unique patch-id. A patch is an ordered collection of edits and each edit is
identified by an edit-id. It has an edit operation ("create", "delete", "insert", "merge", "move", "replace", or
"remove") that is applied to the target resource.
To verify if the RESTCONF YANG-Patch is supported issue the following RESTCONF Get request:
$ curl -k -s -u admin:DMIdmi1! --location-trusted
"https://10.1.1.1/restconf/data/ietf-restconf-monitoring:restconf-state/capabilities" -X
GET

<capabilities xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"
xmlns:rcmon="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">

<capability>urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit</capability>

<capability>urn:ietf:params:restconf:capability:depth:1.0</capability>
<capability>urn:ietf:params:restconf:capability:fields:1.0</capability>
<capability>urn:ietf:params:restconf:capability:with-defaults:1.0</capability>
<capability>urn:ietf:params:restconf:capability:filter:1.0</capability>
<capability>urn:ietf:params:restconf:capability:replay:1.0</capability>

<capability>urn:ietf:params:restconf:capability:yang-patch:1.0</capability>
<capability>http://tail-f.com/ns/restconf/collection/1.0</capability>
<capability>http://tail-f.com/ns/restconf/query-api/1.0</capability>
</capabilities>

This section provides a few RESTCONF YANG-Patch examples.

Add Resource Error

While trying to edit a file, the first edit already exists and an error is reported. The rest of the edits are not
attempted because the first edit failed. XML encoding is used in this example
The following example show an add resource request from the RESTCONF client:
<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-hostname-patch</patch-id>
<edit>
<edit-id>edit1</edit-id>
<operation>create</operation>
<target>/hostname</target>
<value>
<hostname
xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">Cat9K-test</hostname>
</value>
</edit>
<edit>
<edit-id>edit2</edit-id>
<operation>create</operation>
<target>/interface/Loopback=1</target>
<value>
<interface xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<Loopback>
<name>1</name>
</Loopback>
</interface>
</value>
</edit>
</yang-patch>

The following examples shows a JSON response from the RESTCONF server:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

192
Model-Driven Programmability
RESTCONF YANG-Patch Support

Device:/nobackup/folder1/confd_6313/bin $ curl -k -s -u admin:DMIdmi1! --location-trusted

"https://10.1.1.1/restconf/data/Cisco-IOS-XE-native:native" -X PATCH -H "Accept:
application/yang-data+json" -d
'@yang_patch_create_hostname' -H "Content-type: application/yang-patch+xml"
{
"ietf-yang-patch:yang-patch-status": {
"patch-id": "add-hostname-patch",
"edit-status": {
"edit": [
{
"edit-id": "edit1",
"errors": {
"error": [
{
"error-type": "application",
"error-tag": "data-exists",
"error-path": "/Cisco-IOS-XE-native:native/hostname",
"error-message": "object already exists: /ios:native/ios:hostname"
}
]
}
}
]
}
}
}

The following example shows an XML response from the RESTCONF server:
Device:/nobackup/folder1/confd_6313/bin $ curl -k -s -u admin:DMIdmi1! --location-trusted
"https://10.1.1.1/restconf/data/Cisco-IOS-XE-native:native" -X PATCH -H "Accept:
application/yang-data+xml" -d
'@yang_patch_create_hostname' -H "Content-type: application/yang-patch+xml"

<yang-patch-status xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-hostname-patch</patch-id>
<edit-status>
<edit>
<edit-id>edit1</edit-id>
<errors>
<error>
<error-type>application</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:ios="http://cisco.com/ns/yang/Cisco-IOS-XE-native">/ios:native/ios:hostname</error-path>

<error-message>object already exists: /ios:native/ios:hostname</error-message>

</error>
</errors>
</edit>
</edit-status>
</yang-patch-status>device:/nobackup/folder1/confd_6313/bin $

Add Resource Success

The following example shows an edit request:
<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-Loopback-patch</patch-id>
<edit>
<edit-id>edit1</edit-id>
<operation>create</operation>
<target>/Loopback=1</target>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

193
 Model-Driven Programmability
RESTCONF YANG-Patch Support

<value>
<Loopback xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<name>1</name>
</Loopback
</value>
</edit>
</yang-patch>

The following example shows that the edit request is successful:

Device:/nobackup/folder1/confd_6313/bin $ curl -k -s -u admin:DMIdmi1! --location-trusted
"https://10.1.1.1/restconf/data/Cisco-IOS-XE-native:native/interface" -X PATCH -H "Accept:
application/yang-data+json"
-d '@yang_patch_create_Loopback_interface' -H "Content-type: application/yang-patch+xml"
Device:/nobackup/folder1/confd_6313/bin
{
"ietf-yang-patch:yang-patch-status": {
"patch-id": "add-Loopback-patch",
“ok" : [null]
}
}

Insert List Entry

The following example shows that the Loopback 1 is inserted after Loopback 0:
<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>insert-Loopback-patch</patch-id>
<edit>
<edit-id>edit1</edit-id>
<operation>insert</operation>
<target>/Loopback=1</target>
<point>/Loopback=0</point>
<where>after</where>
<value>
<Loopback xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<name>1</name>
</Loopback>
</value>
</edit>
</yang-patch>

The following example shows that the insert list request is successful:
Device:/nobackup/folder1/confd_6313/bin $ curl -k -s -u admin:DMIdmi1! --location-trusted
"https://10.1.1.1/restconf/data/Cisco-IOS-XE-native:native/interface" -X PATCH -H "Accept:
application/yang-data+json" -d
'@yang_patch_create_Loopback_interface' -H "Content-type: application/yang-patch+xml"
Device:/nobackup/folder1/confd_6313/bin
{
"ietf-yang-patch:yang-patch-status": {
"patch-id": "insert-Loopback-patch",
“ok" : [null]
}
}

Move List Entry

The following example shows Loopback 1 is moved before Loopback 0:
<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>move-Loopback-patch</patch-id>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

194
 Model-Driven Programmability
NETCONF RESTCONF IPv6 Support

<edit>
<edit-id>edit1</edit-id>
<operation>move</operation>
<target>/Loopback=1</target>
<point>/Loopback=0</point>
<where>before</where>
<value>
<Loopback xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<name>1</name>
</Loopback>
</value>
</edit>
</yang-patch>

The following example shows that the move request is successful:

Device:/nobackup/folder1/confd_6313/bin $ curl -k -s -u admin:DMIdmi1! --location-trusted

"https://10.1.1.1/restconf/data/Cisco-IOS-XE-native:native/interface" -X PATCH -H "Accept:
application/yang-data+json" -d
'@yang_patch_create_Loopback_interface' -H "Content-type: application/yang-patch+xml"
Device:/nobackup/folder1/confd_6313/bin
{
"ietf-yang-patch:yang-patch-status": {
"patch-id": "move-Loopback-patch",
“ok" : [null]
}
}

NETCONF RESTCONF IPv6 Support

Data model interfaces (DMIs) support the use of IPv6 protocol. DMI IPv6 support helps client applications
to communicate with services that use IPv6 addresses. External facing interfaces will provide dual-stack
support; both IPv4 and IPv6.
DMIs are a set of services that facilitate the management of network elements. Application layer protocols
such as, NETCONF and RESTCONF access these DMIs over a network.
If IPv6 addresses are not configured, external-facing applications will continue to listen on IPv6 sockets; but
these sockets will be unreachable.

Converting IOS Commands to XML

In Cisco IOS XE Cupertino 17.7.1 and later releases, you can automatically translate IOS commands into
relevant NETCONF-YANG XML or RESTCONF-JSON request messages. You can analyze the generated
configuration messages and familiarize with the Xpaths used in these messages. The generated configuration
in the structured format can be used to provision other devices in the network; however, this configuration
cannot be modified.
Use the show running-config | format netconf-xml command or the show running-config | format
restconf-json command to translate IOS commands.
If the netconf-xml keyword is selected, the IOS commands are translated into the NETCONF-YANG XML
format, and if the restconf-json keyword is selected, the IOS commands are translated into the
RESTCONF-JSON format.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

195
 Model-Driven Programmability
Converting IOS Commands to XML

The translation of IOS commands into a structured format is disabled by default. You must initially configure
NETCONF-YANG, and once the data model interfaces (DMIs) are initialized, use the appropriate format
option to translate the commands.
The following is sample output from the show running-config | format netconf-xml command:
Device# show running-config | format netconf-xml

<config xmlns="http://tail-f.com/ns/config/1.0">
<native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
<version>17.8</version>
<boot-start-marker/>
<boot>
<system>
<flash>
<flash-list-ordered-by-user>

<flash-leaf>bootflash:c8000v-universalk9.BLD_POLARIS_DEV_LATEST_20211020_005209.SSA.bin</
flash-leaf>
</flash-list-ordered-by-user>
</flash>
</system>
</boot>
<boot-end-marker/>
<memory>
<free>
<low-watermark>
<processor>64219</processor>
</low-watermark>
</free>
</memory>
<call-home>
<contact-email-addr xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-call-home">
[email protected]</contact-email-addr>
<tac-profile xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-call-home">
<profile>
<CiscoTAC-1>
<active>true</active>
<destination>
<transport-method>http</transport-method>
</destination>
</CiscoTAC-1>
</profile>
</tac-profile>
</call-home>
<service>
<timestamps>
<debug-config>
<datetime>
<msec/>
<localtime/>
<show-timezone/>
</datetime>
</debug-config>
<log-config>
<datetime>
<msec/>
<localtime/>
<show-timezone/>
</datetime>
</log-config>
</timestamps>
<call-home/>
</service>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

196
Model-Driven Programmability
Converting IOS Commands to XML

<platform>
<console xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-platform">
<output>serial</output>
</console>
<qfp xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-platform">
<utilization>
<monitor>
<load>80</load>
</monitor>
</utilization>
</qfp>
<punt-keepalive xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-platform">
<disable-kernel-core>true</disable-kernel-core>
</punt-keepalive>
</platform>
<hostname>pi-prog-csr1</hostname>
<enable>
<password>
<secret>lab</secret>
</password>
</enable>
<username>
<name>admin</name>
<privilege>15</privilege>
<password>
<encryption>0</encryption>
<password>lab</password>
</password>
</username>
<vrf>
<definition>
<name>Mgmt-intf</name>
<address-family>
<ipv4>
</ipv4>
<ipv6>
</ipv6>
</address-family>
</definition>
</vrf>
<ip>
<domain>
<name>cisco</name>
</domain>
<forward-protocol>
<protocol>nd</protocol>
</forward-protocol>
<route>
<ip-route-interface-forwarding-list>
<prefix>10.0.0.0</prefix>
<mask>255.255.0.0</mask>
<fwd-list>
<fwd>10.45.0.1</fwd>
</fwd-list>
</ip-route-interface-forwarding-list>
<vrf>
<name>Mgmt-intf</name>
<ip-route-interface-forwarding-list>
<prefix>0.0.0.0</prefix>
<mask>0.0.0.0</mask>
<fwd-list>
<fwd>10.104.54.129</fwd>
</fwd-list>
</ip-route-interface-forwarding-list>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

197
 Model-Driven Programmability
Converting IOS Commands to XML

</vrf>
</route>
<ssh>
<ssh-version>2</ssh-version>
</ssh>
<tftp>
<source-interface>
<GigabitEthernet>1</GigabitEthernet>
</source-interface>
<blocksize>8192</blocksize>
</tftp>
<http xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-http">
<authentication>
<local/>
</authentication>
<server>true</server>
<secure-server>true</secure-server>
</http>
</ip>
<ipv6>
<unicast-routing/>
</ipv6>
<interface>
<GigabitEthernet>
<name>1</name>
<vrf>
<forwarding>Mgmt-intf</forwarding>
</vrf>
<ip>
<address>
<primary>
<address>10.104.54.222</address>
<mask>255.255.255.128</mask>
</primary>
</address>
</ip>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
<GigabitEthernet>
<name>2</name>
<ip>
<address>
<primary>
<address>9.45.21.231</address>
<mask>255.255.0.0</mask>
</primary>
</address>
</ip>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
<GigabitEthernet>
<name>3</name>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

198
Model-Driven Programmability
Converting IOS Commands to XML

<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
<GigabitEthernet>
<name>4</name>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
<GigabitEthernet>
<name>5</name>
<mop>
<enabled>false</enabled>
<sysid>false</sysid>
</mop>
<negotiation xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ethernet">
<auto>true</auto>
</negotiation>
</GigabitEthernet>
</interface>
<control-plane>
</control-plane>
<clock>
<timezone>
<zone>IST</zone>
<hours>5</hours>
<minutes>30</minutes>
</timezone>
</clock>
<logging>
<console-config>
<console>false</console>
</console-config>
</logging>
<aaa>
<new-model xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa"/>
<authentication xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">
<login>
<name>default</name>
<a1>
<local/>
</a1>
</login>
</authentication>
<authorization xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">
<exec>
<name>default</name>
<a1>
<local/>
</a1>
</exec>
</authorization>
<common-criteria xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">
<policy>enable_secret_policy</policy>
<char-changes>4</char-changes>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

199
 Model-Driven Programmability
Converting IOS Commands to XML

<lower-case>1</lower-case>
<max-length>127</max-length>
<min-length>10</min-length>
<numeric-count>1</numeric-count>
<upper-case>1</upper-case>
</common-criteria>
<session-id xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-aaa">common</session-id>
</aaa>
<login>
<on-success>
<log>
</log>
</on-success>
</login>
<multilink>
<bundle-name
xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-ppp">authenticated</bundle-name>
</multilink>
<redundancy>
</redundancy>
<spanning-tree>
<extend xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-spanning-tree">
<system-id/>
</extend>
</spanning-tree>
<subscriber>
<templating/>
</subscriber>
<crypto>
<pki xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-crypto">
<certificate>
<chain>
<name>SLA-TrustPoint</name>
<certificate>
<serial>01</serial>
<certtype>ca</certtype>
</certificate>
</chain>
<chain>
<name>TP-self-signed-2685563505</name>
<certificate>
<serial>01</serial>
<certtype>self-signed</certtype>
</certificate>
</chain>
</certificate>
<trustpoint>
<id>SLA-TrustPoint</id>
<enrollment>
<pkcs12/>
</enrollment>
<revocation-check>crl</revocation-check>
</trustpoint>
<trustpoint>
<id>TP-self-signed-2685563505</id>
<enrollment>
<selfsigned/>
</enrollment>
<revocation-check>none</revocation-check>
<rsakeypair>
<key-label>TP-self-signed-2685563505</key-label>
</rsakeypair>
<subject-name>cn=IOS-Self-Signed-Certificate-2685563505</subject-name>
</trustpoint>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

200
Model-Driven Programmability
Converting IOS Commands to XML

</pki>
</crypto>
<license>
<udi>
<pid>C8000V</pid>
<sn>93SHKMJKOC6</sn>
</udi>
<boot>
<level>
<network-advantage>
<addon>dna-advantage</addon>
</network-advantage>
</level>
</boot>
</license>
<line>
<aux>
<first>0</first>
</aux>
<console>
<first>0</first>
<exec-timeout>
<minutes>0</minutes>
<seconds>0</seconds>
</exec-timeout>
<stopbits>1</stopbits>
</console>
<vty>
<first>0</first>
<last>4</last>
<exec-timeout>
<minutes>0</minutes>
<seconds>0</seconds>
</exec-timeout>
<password>
<secret>lab</secret>
</password>
<transport>
<input>
<all/>
</input>
<output>
<all/>
</output>
</transport>
</vty>
<vty>
<first>5</first>
<last>31</last>
<transport>
<input>
<all/>
</input>
<output>
<all/>
</output>
</transport>
</vty>
</line>
<diagnostic xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-diagnostics">
<bootup>
<level>minimal</level>
</bootup>
</diagnostic>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

201
 Model-Driven Programmability
Converting IOS Commands to XML

</native>
</config>
pi-prog-csr1#
pi-prog-csr1#
pi-prog-csr1#show running-config | format restconf-json
{
"data": {
"Cisco-IOS-XE-native:native": {
"version": "17.8",
"boot-start-marker": [null],
"boot": {
"system": {
"flash": {
"flash-list-ordered-by-user": [
{
"flash-leaf":
"bootflash:c8000v-universalk9.BLD_POLARIS_DEV_LATEST_20211020_005209.SSA.bin"
}
]
}
}
},
"boot-end-marker": [null],
"memory": {
"free": {
"low-watermark": {
"processor": 64219
}
}
},
"call-home": {
"Cisco-IOS-XE-call-home:contact-email-addr": "[email protected]",
"Cisco-IOS-XE-call-home:tac-profile": {
"profile": {
"CiscoTAC-1": {
"active": true,
"destination": {
"transport-method": "http"
}
}
}
}
},
"service": {
"timestamps": {
"debug-config": {
"datetime": {
"msec": [null],
"localtime": [null],
"show-timezone": [null]
}
},
"log-config": {
"datetime": {
"msec": [null],
"localtime": [null],
"show-timezone": [null]
}
}
},
"call-home": [null]
},
"platform": {
"Cisco-IOS-XE-platform:console": {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

202
Model-Driven Programmability
Converting IOS Commands to XML

"output": "serial"
},
"Cisco-IOS-XE-platform:qfp": {
"utilization": {
"monitor": {
"load": 80
}
}
},
"Cisco-IOS-XE-platform:punt-keepalive": {
"disable-kernel-core": true
}
},
"hostname": "pi-prog-csr1",
"enable": {
"password": {
"secret": "lab"
}
},
"username": [
{
"name": "admin",
"privilege": 15,
"password": {
"encryption": "0",
"password": "lab"
}
}
],
"vrf": {
"definition": [
{
"name": "Mgmt-intf",
"address-family": {
"ipv4": {
},
"ipv6": {
}
}
}
]
},
"ip": {
"domain": {
"name": "cisco"
},
"forward-protocol": {
"protocol": "nd"
},
"route": {
"ip-route-interface-forwarding-list": [
{
"prefix": "10].0.0.0",
"mask": "255.255.0.0",
"fwd-list": [
{
"fwd": "9.45.0.1"
}
]
}
],
"vrf": [
{
"name": "Mgmt-intf",

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

203
 Model-Driven Programmability
Converting IOS Commands to XML

"ip-route-interface-forwarding-list": [
{
"prefix": "0.0.0.0",
"mask": "0.0.0.0",
"fwd-list": [
{
"fwd": "10.104.54.129"
}
]
}
]
}
]
},
"ssh": {
"ssh-version": "2"
},
"tftp": {
"source-interface": {
"GigabitEthernet": "1"
},
"blocksize": 8192
},
"Cisco-IOS-XE-http:http": {
"authentication": {
"local": [null]
},
"server": true,
"secure-server": true
}
},
"ipv6": {
"unicast-routing": [null]
},
"interface": {
"GigabitEthernet": [
{
"name": "1",
"vrf": {
"forwarding": "Mgmt-intf"
},
"ip": {
"address": {
"primary": {
"address": "10.104.54.222",
"mask": "255.255.255.128"
}
}
},
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
},
{
"name": "2",
"ip": {
"address": {
"primary": {
"address": "10.45.21.231",
"mask": "255.255.0.0"

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

204
Model-Driven Programmability
Converting IOS Commands to XML

}
}
},
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
},
{
"name": "3",
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
},
{
"name": "4",
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
},
{
"name": "5",
"mop": {
"enabled": false,
"sysid": false
},
"Cisco-IOS-XE-ethernet:negotiation": {
"auto": true
}
}
]
},
"control-plane": {
},
"clock": {
"timezone": {
"zone": "IST",
"hours": 5,
"minutes": 30
}
},
"logging": {
"console-config": {
"console": false
}
},
"aaa": {
"Cisco-IOS-XE-aaa:new-model": [null],
"Cisco-IOS-XE-aaa:authentication": {
"login": [
{
"name": "default",
"a1": {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

205
 Model-Driven Programmability
Converting IOS Commands to XML

"local": [null]
}
}
]
},
"Cisco-IOS-XE-aaa:authorization": {
"exec": [
{
"name": "default",
"a1": {
"local": [null]
}
}
]
},
"Cisco-IOS-XE-aaa:common-criteria": [
{
"policy": "enable_secret_policy",
"char-changes": 4,
"lower-case": 1,
"max-length": 127,
"min-length": 10,
"numeric-count": 1,
"upper-case": 1
}
],
"Cisco-IOS-XE-aaa:session-id": "common"
},
"login": {
"on-success": {
"log": {
}
}
},
"multilink": {
"Cisco-IOS-XE-ppp:bundle-name": "authenticated"
},
"redundancy": {
},
"spanning-tree": {
"Cisco-IOS-XE-spanning-tree:extend": {
"system-id": [null]
}
},
"subscriber": {
"templating": [null]
},
"crypto": {
"Cisco-IOS-XE-crypto:pki": {
"certificate": {
"chain": [
{
"name": "SLA-TrustPoint",
"certificate": [
{
"serial": "01",
"certtype": "ca"
}
]
},
{
"name": "TP-self-signed-2685563505",
"certificate": [
{

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

206
Model-Driven Programmability
Converting IOS Commands to XML

"serial": "01",
"certtype": "self-signed"
}
]
}
]
},
"trustpoint": [
{
"id": "SLA-TrustPoint",
"enrollment": {
"pkcs12": [null]
},
"revocation-check": ["crl"]
},
{
"id": "TP-self-signed-2685563505",
"enrollment": {
"selfsigned": [null]
},
"revocation-check": ["none"],
"rsakeypair": {
"key-label": "TP-self-signed-2685563505"
},
"subject-name": "cn=IOS-Self-Signed-Certificate-2685563505"
}
]
}
},
"license": {
"udi": {
"pid": "C8000V",
"sn": "93SHKMJKOC6"
},
"boot": {
"level": {
"network-advantage": {
"addon": "dna-advantage"
}
}
}
},
"line": {
"aux": [
{
"first": "0"
}
],
"console": [
{
"first": "0",
"exec-timeout": {
"minutes": 0,
"seconds": 0
},
"stopbits": "1"
}
],
"vty": [
{
"first": 0,
"last": 4,
"exec-timeout": {
"minutes": 0,

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

207
 Model-Driven Programmability
How to Configure the RESTCONF Protocol

"seconds": 0
},
"password": {
"secret": "lab"
},
"transport": {
"input": {
"all": [null]
},
"output": {
"all": [null]
}
}
},
{
"first": 5,
"last": 31,
"transport": {
"input": {
"all": [null]
},
"output": {
"all": [null]
}
}
}
]
},
"Cisco-IOS-XE-diagnostics:diagnostic": {
"bootup": {
"level": "minimal"
}
}
}
}
}

How to Configure the RESTCONF Protocol

Authentication of NETCONF/RESTCONF Using AAA
Before you begin
NETCONF and RESTCONF connections must be authenticated using authentication, authorization, and
accounting (AAA). As a result, RADIUS or TACACS+ users defined with privilege level 15 access are
allowed access into the system.

SUMMARY STEPS
1. enable
2. configure terminal
3. aaa new-model
4. aaa group server radius server-name
5. server-private ip-address key key-name
6. ip vrf forwarding vrf-name

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

208
 Model-Driven Programmability
Authentication of NETCONF/RESTCONF Using AAA

7. exit
8. aaa authentication login default group group-name local
9. aaa authentication login list-name none
10. aaa authorization exec default group group-name local
11. aaa session-id common
12. line console number
13. login authentication authentication-list
14. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 aaa new-model Enables AAA.

Example:
Device(config)# aaa new-model

Step 4 aaa group server radius server-name Adds the RADIUS server and enters server group RADIUS
configuration mode.
Example:
Device(config)# aaa group server radius ISE • The server-name argument specifies the RADIUS
server group name.

Step 5 server-private ip-address key key-name Configures a IP address and encryption key for a private
RADIUS server.
Example:
Device(config-sg-radius)# server-private
172.25.73.76 key Cisco123

Step 6 ip vrf forwarding vrf-name Configures the virtual routing and forwarding (VRF)
reference of a AAA RADIUS or TACACS+ server group.
Example:
Device(config-sg-radius)# ip vrf forwarding
Mgmt-intf

Step 7 exit Exits server group RADIUS configuration mode and

returns to global configuration mode.
Example:
Device(config-sg-radius)# exit

Step 8 aaa authentication login default group group-name local Sets the specified group name as the default local AAA
authentication during login.
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

209
 Model-Driven Programmability
Enabling Cisco IOS HTTP Services for RESTCONF

Command or Action Purpose

Device(config)# aaa authentication login default
group ISE local

Step 9 aaa authentication login list-name none Specifies that no authentication is required while logging
into a system.
Example:
Device(config)# aaa authentication login NOAUTH
none

Step 10 aaa authorization exec default group group-name local Runs authorization to determine if an user is allowed to
run an EXEC shell.
Example:
Device(config)# aaa authorization exec default
group ISE local

Step 11 aaa session-id common Ensures that session identification (ID) information that
is sent out for a given call will be made identical.
Example:
Device(config)# aaa session-id common

Step 12 line console number Identifies a specific line for configuration and enter line
configuration mode.
Example:
Device(config)# line console 0

Step 13 login authentication authentication-list Enables AAA authentication for logins.

Example:
Device(config-line)# login authentication NOAUTH

Step 14 end Exits line configuration mode and returns to privileged

EXEC mode.
Example:
Device(config-line)# end

Enabling Cisco IOS HTTP Services for RESTCONF

Perform this task to use the RESTCONF interface.

SUMMARY STEPS
1. enable
2. configure terminal
3. restconf
4. ip http secure-server
5. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

210
 Model-Driven Programmability
Verifying RESTCONF Configuration

Command or Action Purpose

Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 restconf Enables the RESTCONF interface on your network device.

Example:
Device(config)# restconf

Step 4 ip http secure-server Enables a secure HTTP (HTTPS) server.

Example:
Device(config)# ip http secure-server

Step 5 end Exits global configuration mode and enters privileged EXEC
mode
Example:
Device(config)# end

Verifying RESTCONF Configuration

When a device boots up with the startup configuration, the nginx process will be running. However; DMI
proceses are not enabled.
The following sample output from the show platform software yang-management process monitor command
shows that the nginx process is running:
Device# show platform software yang-management process monitor

COMMAND PID S VSZ RSS %CPU %MEM ELAPSED

nginx 27026 S 332356 18428 0.0 0.4 01:34
nginx 27032 S 337852 13600 0.0 0.3 01:34

NGINX is an internal webserver that acts as a proxy webserver. It provides Transport Layer Security
(TLS)-based HTTPS. RESTCONF request sent via HTTPS is first received by the NGINX proxy web serve,r
and the request is transferred to the confd web server for further syntax/semantics check.
The following sample output from the show platform software yang-management process command shows
the status of the all processes when a device is booted with the startup-configuration:

Device# show platform software yang-management process

confd : Not Running

nesd : Not Running
syncfd : Not Running
ncsshd : Not Running
dmiauthd : Not Running
nginx : Running
ndbmand : Not Running

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

211
 Model-Driven Programmability
Verifying RESTCONF Configuration

pubd : Not Running

The nginx process gets restrated and DMI process are started, when the restconf command is configured.
The following sample output from the show platform software yang-management process command shows
that the nginx process and DMI processes are up and running:
Device# show platform software yang-management process

confd : Running
nesd : Running
syncfd : Running
ncsshd : Not Running ! NETCONF-YANG is not configured, hence ncsshd process is
in not running.
dmiauthd : Running
vtyserverutild : Running
opdatamgrd : Running
nginx : Running ! nginx process is up due to the HTTP configuration, and it is
restarted when RESTCONF is enabled.
ndbmand : Running

The following sample output from the show platform software yang-management process monitor command
displays detailed information about all processes:
Device#show platform software yang-management process monitor
COMMAND PID S VSZ RSS %CPU %MEM ELAPSED
confd 28728 S 860396 168496 42.2 4.2 00:12
confd-startup.s 28448 S 19664 4496 0.2 0.1 00:12
dmiauthd 29499 S 275356 23340 0.2 0.5 00:10
ndbmand 29321 S 567232 65564 2.1 1.6 00:11
nesd 29029 S 189952 14224 0.1 0.3 00:11
nginx 29711 S 332288 18420 0.6 0.4 00:09
nginx 29717 S 337636 12216 0.0 0.3 00:09
pubd 28237 S 631848 68624 2.1 1.7 00:13
syncfd 28776 S 189656 16744 0.2 0.4 00:12

After AAA and the RESTCONF interface is configured, and nginx process and relevant DMI processes are
running; the device is ready to receive RESTCONF requests.
Use the show netconf-yang sessions command to view the status of NETCONF/RESTCONF sessions:
Device# show netconf-yang sessions

R: Global-lock on running datastore

C: Global-lock on candidate datastore
S: Global-lock on startup datastore

Number of sessions : 1

session-id transport username source-host global-lock

--------------------------------------------------------------------------------
19 netconf-ssh admin 2001:db8::1 None

Use the show netconf-yang sessions detail command to view detailed information about
NETCONF/RESTCONF sessions:
Device# show netconf-yang sessions detail

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

212
 Model-Driven Programmability
Configuration Examples for the RESTCONF Protocol

R: Global-lock on running datastore

C: Global-lock on candidate datastore
S: Global-lock on startup datastore

Number of sessions : 1

session-id : 19
transport : netconf-ssh
username : admin
source-host : 2001:db8::1
login-time : 2018-10-26T12:37:22+00:00
in-rpcs : 0
in-bad-rpcs : 0
out-rpc-errors : 0
out-notifications : 0
global-lock : None

Configuration Examples for the RESTCONF Protocol

Example: Configuring the RESTCONF Protocol
RESTCONF Requests (HTTPS Verbs):
The following is a sample RESTCONF request that shows the HTTPS verbs allowed on a targeted resource.
In this example, the logging monitor command is used..

root:~# curl -i -k -X "OPTIONS"

"https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity"
\
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 23 Apr 2018 15:27:57 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Allow: DELETE, GET, HEAD, PATCH, POST, PUT, OPTIONS >>>>>>>>>>> Allowed methods
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Accept-Patch: application/yang-data+xml, application/yang-data+json
Pragma: no-cache

root:~#

POST (Create) Request

The POST operation creates a configuration which is not present in the targeted device.

Note Ensure that the logging monitor command is not availabel in the running configuration.

The following sample POST request uses the logging monitor alerts command.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

213
 Model-Driven Programmability
Example: Configuring the RESTCONF Protocol

Device:~# curl -i -k -X "POST"

"https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor" \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \
> -d $'{
> "severity": "alerts"
> }'
HTTP/1.1 201 Created
Server: nginx
Date: Mon, 23 Apr 2018 14:53:51 GMT
Content-Type: text/html
Content-Length: 0
Location:
https://10.85.116.30/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 14:53:51 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-495231-97239
Pragma: no-cache

Device:~#

PUT: (Create or Replace) Request:

If the specified command is not present on the device, the POST request creates it ; however, if it is
already present in the running configuration, the command will be replaced by this request.
The following sample PUT request uses the logging monitor warnings command.
Device:~# curl -i -k -X "PUT"
"https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity"
\
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \
> -d $'{
> "severity": "warnings"
> }'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 14:58:36 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 14:57:46 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-495466-326956
Pragma: no-cache

Device:~#

PATCH: (Update) Request

The following sample PATCH request uses the logging monitor informational command.
Device:~# curl -i -k -X "PATCH"
"https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native" \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

214
Model-Driven Programmability
Example: Configuring the RESTCONF Protocol

> -d $'{
> "native": {
> "logging": {
> "monitor": {
> "severity": "informational"
> }
> }
> }
> }'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 15:07:56 GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 15:07:56 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-496076-273016
Pragma: no-cache
Device:~#

GET Request (To Read)

The following sample GET request uses the logging monitor informational command.
Device:~# curl -i -k -X "GET"
"https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity"
\
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 23 Apr 2018 15:10:59 GMT
Content-Type: application/yang-data+json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache

{
"Cisco-IOS-XE-native:severity": "informational"
}
Device:~#

DELETE Request (To Delete the Configuration)

Device:~# curl -i -k -X "DELETE"

"https://10.85.116.30:443/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity"
\
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 15:26:05 GMT
Content-Type: text/html
Content-Length: 0

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

215
 Model-Driven Programmability
Additional References for the RESTCONF Protocol

Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 15:26:05 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-497165-473206
Pragma: no-cache

linux_host:~#

Additional References for the RESTCONF Protocol

Related Documents

Related Topic Document Title

YANG data models for various releases To access Cisco YANG models in a developer-friendly way, please
of IOS XE, IOS XR, and NX-OS clone the GitHub repository, and navigate to the
platforms vendor/ciscosubdirectory. Models for various releases of IOS-XE,
IOS-XR, and NX-OS platforms are available here.

Standards and RFCs

Standard/RFC Title

RFC 6020 YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)

RFC 8040 RESTCONF Protocol

RFC 8072 YANG Patch Media Type

Technical Assistance

Description Link

The Cisco Support website provides extensive online https://www.cisco.com/c/en/us/support/index.html

resources, including documentation and tools for
troubleshooting and resolving technical issues with Cisco
products and technologies.
To receive security and technical information about your
products, you can subscribe to various services, such as
the Product Alert Tool (accessed from Field Notices), the
Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website
requires a Cisco.com user ID and password.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

216
 Model-Driven Programmability
Feature Information for the RESTCONF Protocol

Feature Information for the RESTCONF Protocol

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

217
 Model-Driven Programmability
Feature Information for the RESTCONF Protocol

Table 14: Feature Information for the RESTCONF Protocol

Feature Releases Feature Information

Name

RESTCONF Cisco IOS XE RESTCONF provides a programmatic interface based on standard

Protocol Everest 16.6.1 mechanisms for accessing configuration data, state data,
data-model-specific RPC operations and event notifications defined in
the YANG model.
This feature was introduced on the following platforms:
• Cisco 4000 Series Integrated Services Router
• Cisco ASR 1000 Aggregation Services Routers
• Cisco Cloud Services Router 1000V Series

The following commands were introduced or modified: ip http server

and restconf

Cisco IOS XE Fuji In Cisco IOS XE Fuji 16.8.1a, this feature was implemented on the
16.8.1a following platforms:
• Cisco 1000 Series Integrated Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregation Services Router
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High Performance Series Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Network Convergence System 4200 Series

Cisco IOS XE Fuji In Cisco IOS XE Fuji 16.9.2, this feature was implemented on the
16.9.2 following platforms:
• Cisco Catalyst 9200 and 9200L Series Switches
• Cisco Catalyst 9300L SKUs

Cisco IOS XE
Gibraltar 16.11.1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

218
Model-Driven Programmability
Feature Information for the RESTCONF Protocol

Feature Releases Feature Information

Name
In Cisco IOS XE Gibraltar 16.11.1, this feature was implemented on
the following platforms:
• Cisco Catalyst 9600 Series Switches
• Cisco Catalyst 9800-CL Wireless Controllers
• Cisco Catalyst 9800-40 Wireless Controllers
• Cisco Catalyst 9800-80 Wireless Controllers
• Cisco Network Convergence System 520 Series

Cisco IOS XE In Cisco IOS XE Gibraltar 16.12.1, this feature was implemented on
Gibraltar 16.12.1 Cisco Catalyst 9800-L Wireless Controllers.

Cisco IOS XE In Cisco IOS XE Amsterdam 17.3.1, this feature was implemented on
Amsterdam 17.3.1 the following platforms:
• Cisco Catalyst 8200 Series Edge Platforms
• Cisco Catalyst 8300 Series Edge Platforms
• Cisco Catalyst 8500 and 8500L Series Edge Platforms

Cisco IOS XE In Cisco IOS XE Bengaluru 17.4.1, this feature was implemented on
Bengaluru 17.4.1 Cisco Catalyst 8000V Edge Software.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

219
 Model-Driven Programmability
Feature Information for the RESTCONF Protocol

Feature Releases Feature Information

Name

RESTCONF Cisco IOS XE RESTCONF supports YANG-Patch media type as specified by RFC
YANG-Patch Amsterdam 17.1.1 8072.
Support
This feature was implemented on the following platforms:
• Cisco 1000 Series Integrated Services Routers
• Cisco 4000 Series Integrated Services Routers
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 1000 Aggregation Services Routers (ASR1000-RP2,
ASR1000-RP3, ASR1001-HX, ASR1001-X, ASR1002-HX,
ASR1002-X)
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco cBR-8 Converged Broadband Router
• Cisco Cloud Services Router 1000V Series
• Cisco Network Convergence System 520 Series
• Cisco Network Convergence System 4200 Series

NETCONF Cisco IOS XE Fuji • Cisco 4000 Series Integrated Services Routers
and 16.8.1a
RESTCONF • Cisco ASR 1000 Series Aggregation Services Routers
IPv6 • Cisco ASR 900 Series Aggregation Services Routers
Support
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco CBR-8 Series Routers
• Cisco Cloud Services Router 1000V Series

Cisco IOS XE In Cisco IOS XE Gibraltar 16.11.1, this feature was implemented on
Gibraltar 16.11.1 Cisco Catalyst 9500-High Performance Series Switches.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

220
Model-Driven Programmability
Feature Information for the RESTCONF Protocol

Feature Releases Feature Information

Name

Converting Cisco IOS XE This feature helps to automatically translate IOS commands into relevant
IOS Cupertino 17.7.1 NETCONF-XML or RESTCONF/JSON request messages.
Commands
This feature is supported on all platforms that support RESTCONF.
to XML

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

221
 Model-Driven Programmability
Feature Information for the RESTCONF Protocol

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

222
 CHAPTER 9
NETCONF and RESTCONF Service-Level ACLs
This module describes the service-levels ACLs supported on NETCONF and RESTCONF, and how to
configure it.
• Information About NETCONF and RESTCONF Service-Level ACLs, on page 223
• How to Configure NETCONF and RESTCONF Service-Level ACLs, on page 223
• Configuration Examples for NETCONF and RESTCONF Service-Level ACLs, on page 226
• Additional References for NETCONF and RESTCONF Service-Level ACLs, on page 227
• Feature Information for NETCONF and RESTCONF Service-Level ACLs, on page 227

Information About NETCONF and RESTCONF Service-Level ACLs

Overview of NETCONF and RESTCONF Service-Level ACLs
You can configure an IPv4 or IPv6 access control list (ACL) for NETCONF and RESTCONF sessions. Clients
that do not conform to the configured ACLs are not allowed to access the NETCONF or RESTCONF
subsystems. When service-level ACLs are configured, NETCONF-YANG and RESTCONF connection
requests are filtered based on the source IP address.
If no service-level ACLs are configured, all NETCONF-YANG and RESTCONF connection requests are
permitted into the subsystems.

Note Only named ACLs are supported; numbered ACLs are not supported.

How to Configure NETCONF and RESTCONF Service-Level ACLs

Configuring an ACL for a NETCONF-YANG Session
You can either configure an IP access-list or an IPv6 access list for your NETCONF-YANG session.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

223
 Model-Driven Programmability
Configuring an ACL for a NETCONF-YANG Session

SUMMARY STEPS
1. enable
2. configure terminal
3. • ip access-list {standard | extended} access-list-name
• ipv6 access-list access-list-name
4. permit {host-address | host-name | any} [wildcard]
5. deny {host-address | host-name | any} [wildcard]
6. exit
7. netconf-yang ssh {{ipv4 | ipv6 }access-list name access-list-name} | port port-number}
8. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 • ip access-list {standard | extended} access-list-name • Specifies a standard IP access list and enters standard
• ipv6 access-list access-list-name access-list configuration mode.
Example: • Specifies an IPv6 access list and enters IPv6 access-list
Device(config)# ip access-list standard acl1_permit configuration mode.

Device(config)# ipv6 access-list ipv6-acl1_permit

Step 4 permit {host-address | host-name | any} [wildcard] Sets conditions in an IP/IPv6 access list that will permit
packets.
Example:
Device(config-std-nacl)# permit 192.168.255.0
0.0.0.255

Step 5 deny {host-address | host-name | any} [wildcard] Sets conditions in an IP or IPv6 access list that will deny
packets.
Example:
Device(config-std-nacl)# deny any

Step 6 exit Exits standard access-list configuration mode and returns

to global configuration mode.
Example:
Device(config-std-nacl)# exit

Step 7 netconf-yang ssh {{ipv4 | ipv6 }access-list name Configures an ACL for the NETCONF-YANG session.
access-list-name} | port port-number}
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

224
 Model-Driven Programmability
Configuring an ACL for a RESTCONF Session

Command or Action Purpose

Device(config)# netconf-yang ssh ipv4 access-list
name acl1_permit

Step 8 end Exits global configuration mode and returns to privileged

EXEC mode.
Example:
Device(config)# end

Configuring an ACL for a RESTCONF Session

You can either configure an IP access list or an IPv6 access list for your RESTCONF session.

SUMMARY STEPS
1. enable
2. configure terminal
3. • ip access-list {standard | extended} access-list-name
• ipv6 access-list access-list-name
4. permit {protocol-number | ipv6-source-address | ipv6-source-prefix | protocol}any
5. deny {protocol-number | ipv6-source-address | ipv6-source-prefix | protocol}any any
6. exit
7. restconf {ipv4 | ipv6 }access-list name access-list-name
8. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 • ip access-list {standard | extended} access-list-name • Specifies a standard IP access list and enters standard
• ipv6 access-list access-list-name access-list configuration mode.
Example: • Specifes an IPv6 access list and enters IPv6 access list
Device(config)# ip access-list standard acl1_permit configuration mode.

Device(config)# ipv6 access-list ipv6-acl1_permit

Step 4 permit {protocol-number | ipv6-source-address | Sets conditions in an IPv6 access list that will permit
ipv6-source-prefix | protocol}any packets.
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

225
 Model-Driven Programmability
Configuration Examples for NETCONF and RESTCONF Service-Level ACLs

Command or Action Purpose

Device(config-ipv6-acl)# permit ipv6 2001:db8::1/32
any

Step 5 deny {protocol-number | ipv6-source-address | Sets conditions in an IPv6 access list that will deny packets.
ipv6-source-prefix | protocol}any any
Example:
Device(config-ipv6-acl)# deny ipv6 any any

Step 6 exit Exits IPv6 access list configuration mode and returns to
global configuration mode.
Example:
Device(config-ipv6-acl)# exit

Step 7 restconf {ipv4 | ipv6 }access-list name access-list-name Configures an ACL for the RESTCONF session.
Example:
Device(config)# restconf ipv6 access-list name
ipv6-acl1_permit

Step 8 end Exits global configuration mode and returns to privileged

EXEC mode.
Example:
Device(config)# end

Configuration Examples for NETCONF and RESTCONF

Service-Level ACLs
Example: Configuring an ACL for a NETCONF Session

Device# enable
Device# configure terminal
Device(config)# ip access-list standard acl1_permit
Device(config-std-nacl)# permit 192.168.255.0 0.0.0.255
Device(config-std-nacl)# deny any
Device(config-std-nacl)# exit
Device(config)# netconf-yang ssh ipv4 access-list name acl1_permit
Device(config)# end

Example: Configuring an ACL for a RESTCONF Session

Device# enable
Device# configure terminal
Device(config)# ipv6 access-list ipv6-acl1_permit
Device(config-ipv6-acl)# permit ipv6 2001:db8::1/32 any
Device(config-ipv6-acl)# deny ipv6 any any

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

226
 Model-Driven Programmability
Additional References for NETCONF and RESTCONF Service-Level ACLs

Device(config-ipv6-acl)# exit
Device(config)# restconf ipv6 access-list name ipv6-acl1_permit
Device(config)# end

Additional References for NETCONF and RESTCONF

Service-Level ACLs
Related Documents

Related Topic Document Title

NETCONF-YANG NETCONF Protocol

RESTCONF RESTCONF Protocol

Programmability commands Programmability Command Reference

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for NETCONF and RESTCONF Service-Level

ACLs
The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

227
 Model-Driven Programmability
Feature Information for NETCONF and RESTCONF Service-Level ACLs

Table 15: Feature Information for NETCONF and RESTCONF Service-Level ACLs

Feature Name Releases Feature Information

NETCONF and Cisco IOS XE You can configure an access control list (ACL) for NETCONF and
RESTCONF Everest RESTCONF sessions. Clients that do not conform to the configured ACL
Service-Level 16.11.1 are not allowed to access the NETCONF or RESTCONF subsystems.
ACLs
The following commands were introduced or modified: netconf-yang
ssh access-list and restconf access-list
• Cisco ASR 900 Series Aggregation Services Routers
• Cisco ASR 920 Series Aggregated Services Routers (RSP2)
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst IE 3200, 3300, 3400 Rugged Series
• Cisco Embedded Services 3300 Series Switches
• Cisco IR1101 Integrated Services Router Rugged
• Cisco Network Convergence System 4200 Series
• Cisco Network Convergence System 520 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

228
 CHAPTER 10
gNMI Protocol
This feature describes the model-driven configuration and retrieval of operational data using the gRPC Network
Management Interface (gNMI) Capabilities, Get, Set and Subscribe remote procedure calls (RPCs). gNMI
version 0.4.0 is supported.
• Restrictions for the gNMI Protocol, on page 229
• Information About the gNMI Protocol, on page 230
• How to Enable the gNMI Protocol, on page 240
• Configuration Examples for the gNMI Protocol, on page 246
• Additional References for the gNMI Protocol, on page 247
• Feature Information for the gNMI Protocol, on page 247

Restrictions for the gNMI Protocol

The following restrictions apply to the feature:
• JSON, BYTES, PROTO, and ASCI encoding options are not supported.
JSON IETF keys must contain a YANG-prefix where the namespace of the following elements differs
from the parent. This means that the routed-vlan derived from augmentation in openconfig-vlan.yang
must be entered as oc-vlan:routed-vlan because it is different from the namespace of the parent nodes
(parent nodes have the prefix, oc-if)
• GetRequest:
• Operational data filtering is not supported.
• Use models are not supported. These are a set of model data messages indicating the schema definition
modules that define the data elements that must be returned in response to a Get RPC call.

• GetResponse:
• Alias is not supported. It is a string that provides an alias for a prefix specified within the notification
message.
• Delete is not supported. It is a set of paths that are to be removed from a data tree.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

229
 Model-Driven Programmability
Information About the gNMI Protocol

Information About the gNMI Protocol

About GNMI
gNMI is gRPC Network Management Interface developed by Google. gNMI provides the mechanism to
install, manipulate, and delete the configuration of network devices, and also to view operational data. The
content provided through gNMI can be modeled using YANG.
gRPC is a remote procedure call developed by Google for low-latency, scalable distributions with mobile
clients communicating to a cloud server. gRPC carries gNMI, and provides the means to formulate and transmit
data and operation requests.
When a gNMI service failure occurs, the gNMI broker (GNMIB) will indicate an operational change of state
from up to down, and all RPCs will return a service unavailable message until the database is up and running.
Upon recovery, the GNMIB will indicate a change of operation state from down to up, and resume normal
handling of RPCs.
gNMI supports <subscribe> RPC services. For more information, see the Model-Driven Telemetry chapter.

JSON IETF Encoding for YANG Data Trees

RFC 7951 defines JavaScript Object Notation (JSON) encoding for YANG data trees and their subtrees. gNMI
uses JSON for encoding data in its content layer.
The JSON type indicates that the value is encoded as a JSON string. JSON_IETF-encoded data must conform
to the rules for JSON serialisation described in RFC 7951. Both the client and target must support JSON
encoding.
Instances of YANG data nodes (leafs, containers, leaf-lists, lists, anydata nodes, and anyxml nodes) are
encoded as members of a JSON object or name/value pairs. Encoding rules are identical for all types of data
trees, such as configuration data, state data, parameters of RPC operations, actions, and notifications.
Every data node instance is encoded as a name/value pair where the name is formed from the data node
identifier. The value depends on the category of the data node.

The leaf Data Node

A leaf node has a value, but no children, in a data tree. A leaf instance is encoded as a name/value pair. This
value can be a string, number, literal true or false, or the special array [null], depending on the type of the
leaf. In the case that the data item at the specified path is a leaf node (which means it has no children, and an
associated value) the value of that leaf is encoded directly. (A bare JSON value is included; it does not require
a JSON object.)
The following example shows a leaf node definition:
leaf foo {
type uint8;
}

The following is a valid JSON-encoded instance:

"foo": 123

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

230
 Model-Driven Programmability
gNMI GET Request

gNMI GET Request

The gNMI Get RPC specifies how to retrieve one or more of the configuration attributes, state attributes,
derived state attributes, or all attributes associated with a supported mode from a date tree. A GetRequest is
sent from a client to the target to retrieve values from the data tree. A GetResponse is sent in response to a
GetRequest.

GetRequest JSON Structure

The following is a sample GetRequest JSON structure. Both the GetRequest and GetResponse are displayed.
GetRequest
The following is a path for the
openconfig-interfaces model
++++++++ Sending get request: ++++++++
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
}

GetResponse
encoding: JSON_IETF
++++++++ Received get response: ++++++++
notification {
timestamp: 1521699434792345469
update {
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "\"Loopback111\""
}
}
}

val {
json_ietf_val: "{\n\t\"openconfig-interfaces:name\":\t\
"Loopback111\",\n\t\
"openconfig-interfaces:config\":\t{\n\t\t\
"openconfig-interfaces:type\":\t\"ianaift:
softwareLoopback\",\n\t\t\
"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\
"openconfig-interfaces:enabled\":\t\"true\"\n\t},\n\t\
"openconfig-interfaces:state\":\t{\n\t\t\
"openconfig-interfaces:type\":\t\"ianaift:
softwareLoopback\",\n\t\t\
"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

231
 Model-Driven Programmability
gNMI GET Request

"openconfig-interfaces:enabled\":\t\"true\",\n\t\t\
"openconfig-interfaces:ifindex\":\t52,\n\t\t\

"openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\
"openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\
"openconfig-interfaces:last-change\":\t2018,\n\t\t\
"openconfig-interfaces:counters\":\t{\n\t\t\t\
"openconfig-interfaces:in-octets\":\t0,\n\t\t\t\
"openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:in-discards\":\t0,\n\t\t\t\
"openconfig-interfaces:in-errors\":\t0,\n\t\t\t\
"openconfig-interfaces:in-unknown-protos\":\t0,\n\t\t\t\
"openconfig-interfaces:out-octets\":\t0,\n\t\t\t\
"openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:out-discards\":\t0,\n\t\t\t\
"openconfig-interfaces:out-errors\":\t0,\n\t\t\t\
"openconfig-interfaces:last-clear\":\t2018\n\t\t},\n\t\t\

"openconfig-platform:hardware-port\":\t\
"Loopback111\"\n\t},\n\t\
"openconfig-interfaces:subinterfaces\":\t{\n\t\t\
"openconfig-interfaces:index\":\t0,\n\t\t\
"openconfig-interfaces:config\":\t{\n\t\t\t\
"openconfig-interfaces:index\":\t0,\n\t\t\t\
"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\t\
"openconfig-interfaces:enabled\":\t\"true\"\n\t\t},\n\t\t\
"openconfig-interfaces:state\":\t{\n\t\t\t\
"openconfig-interfaces:index\":\t0,\n\t\t\t\
"openconfig-interfaces:name\":\t\"Loopback111.0\",\n\t\t\t\
"openconfig-interfaces:enabled\":\t\"true\",\n\t\t\t\
"openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\t\
"openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\t\
"openconfig-interfaces:last-change\":\t2018,\n\t\t\t\
"openconfig-interfaces:counters\":\t{\n\t\t\t\t\
"openconfig-interfaces:in-octets\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-discards\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-errors\":\t0,\n\t\t\t\t\

"openconfig-interfaces:out-octets\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-discards\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-errors\":\t0,\n\t\t\t\t\
"openconfig-interfaces:last-clear\":\
t2018\n\t\t\t}\n\t\t},\n\t\t\
"openconfig-if-ip:ipv6\":\t{\n\t\t\t\
"openconfig-if-ip:config\":\t\"false\",\n\t\t\t\
"openconfig-if-ip:state\":\t\"false\"\n\t\t}\n\t}\n}"
}
}
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

232
Model-Driven Programmability
gNMI GET Request

GetRequest on a Leaf Value

The following is a sample GetRequest on a Leaf value. Both the GetRequest and the corresponding GetResponse
are displayed.
GetRequest

++++++++ Sending get request: ++++++++

path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
elem {
name: "state"
}
elem {
name: "oper-status"
}
}

GetResponse

encoding: JSON_IETF
++++++++ Received get response: ++++++++
notification {
timestamp: 1521699326012374332
update {
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "\"Loopback111\""
}
}
elem {
name: "state"
}
elem {
name: "oper-status"
}
}
val {
json_ietf_val: "\"UP\""
}
}
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

233
 Model-Driven Programmability
gNMI SetRequest

gNMI SetRequest
The Set RPC specifies how to set one or more configurable attributes associated with a supported model. A
SetRequest is sent from a client to a target to update the values in the data tree.
SetRequests also support JSON keys, and must contain a YANG-prefix, in which the namespace of the element
differs from parent.
For example, the routed-vlan element derived from augmentation in openconfig-vlan.yang must be entered
as oc-vlan:routed-vlan, because it is different from the namespace of the parent node (The parent node prefix
is oc-if.).
The total set of deletes, replace, and updates contained in any one SetRequest is treated as a single transaction.
If any subordinate element of the transaction fails; the entire transaction is disallowed and rolled back. A
SetResponse is sent back for a SetRequest.

Table 16: Example of a SetRequest JSON Structure

SetRequest SetResponse
++++++++ Sending set request: ++++++++ ++++++++ Received set response: ++++++++
update { response {
path { path {
elem { elem {
name: "interfaces" name: "interfaces"
} }
elem { elem {
name: "interface" name: "interface"
key { key {
key: "name" key: "name"
value: "Loopback111" value: "Loopback111"
} }
} }
elem { elem {
name: "config" name: "config"
} }
} }
val { op: UPDATE
json_ietf_val: }
"{\"openconfig-interfaces:enabled\":\"false\"}" timestamp: 1521699342123890045

}
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

234
 Model-Driven Programmability
gNMI Namespace

Table 17: Example of a SetRequest on Leaf Value

SetRequest SetResponse
++++++++ Sending set request: ++++++++ ++++++++ Received set response: ++++++++
update { response {
path { path {
elem { elem {
name: "interfaces" name: "interfaces"
} }
elem { elem {
name: "interface" name: "interface"
key { key {
key: "name" key: "name"
value: "Loopback111" value: "Loopback111"
} }
} }
elem { elem {
name: "config" name: "config"
} }
elem { elem {
name: "description" name: "description"
} }
} }
val { op: UPDATE
json_ietf_val: "\"UPDATE DESCRIPTION\"" }
} timestamp: 1521699342123890045
}

gNMI Namespace
A namespace specifies the path prefixing to be used in the origin field of a message.
This section describes the namespaces used in Cisco IOS XE Gibraltar 16.10.1 and later releases:
• RFC 7951-specified namespaces: Path prefixes use the YANG module name as defined in RFC 7951.
The RFC 7951-specified value prefixing uses the YANG module name.
Value prefixing is not affected by the selected path prefix namespace. The following example shows an
RFC 7951-specified value prefix:
val {
json_ietf_val:"{
"openconfig-interfaces:config": {
“openconfig-interfaces:description":
“DESCRIPTION”
}
}"
}

An RFC 7951-specified namespace prefixing also uses the YANG module name. For example, the
openconfig path to a loopback interface will be
/openconfig-interfaces:interfaces/interface[name=Loopback111]/

The following example shows a gNMI path with RFC7951 namespacing:

path {
origin: “rfc7951"
elem {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

235
 Model-Driven Programmability
gNMI Namespace

name: "openconfig-interface:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
}

• Openconfig: No path prefixes are used. These can only be used with a path to an openconfig model.
The behavior of the Openconfig namespace prefixing is the same when no origin or namespace is provided.
For example, the openconfig path to a loopback interface will be
/interfaces/interface[name=Loopback111]/

The following example shows a gNMI path with an Openconfig namespacing:

path {
origin: “openconfig"
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
}

• Blank: Same as the openconfig prefix. This is the default.

The following example shows a gNMI path with a blank Openconfig namespacing:
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
}

This section describes the path prefixing used in releases prior to Cisco IOS XE Gibraltar 16.10.1.
Here, path prefixing uses the YANG module prefix as defined in the YANG module definition. For example,
the openconfig path to a loopback interface will be
/oc-if:interfaces/interface[name=Loopback111]/

The following example shows a gNMI Path with with legacy namespacing:
path {
origin: “legacy"
elem {
name: "oc-if:interfaces"
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

236
 Model-Driven Programmability
gNMI Wildcards

elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
}

gNMI Wildcards
The gNMI protocol supports wildcards for Get paths. This is the ability to use a wildcards in a path to match
multiple elements. These wildcards indicate all elements in a given subtree in the schema.
An elem is an element, and it is a value between / characters in an xPath. An elem is also available in a gNMI
path. For example, the position of a wildcard relative to elem names implies that the wildcard stands for an
interface, and is interpreted as all interfaces.
There are two types of wildcards; implicit and explicit, and both are supported. Get paths support all types
and combinations of path wildcards.
• Implicit wildcards: These expand a list of elements in an element tree. Implicit wildcard occurs when a
key value is not provided for elements of a list.
The following is a sample path implicit wildcard. This wildcard will return the descriptions of all interfaces
on a device:
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
}
elem {
name: "config"
}
elem {
name: "description"
}
}

• Explicit wildcards: Provides the same functionality by

• Specifying an asterisk (*) for either the path element name or key name.
The following sample shows a path asterisk wildcard as the key name. This wildcard returns the
description for all interfaces on a device.
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "*"
}
}
elem {
name: “config"

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

237
 Model-Driven Programmability
gNMI Wildcards

}
elem {
name: "description"
}
}

The following sample shows a path asterisk wildcard as the path name. This wildcard will return
the description for all elements that are available in the Loopback111 interface.
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
elem {
name: "*"
}
elem {
name: "description"
}
}

• Specifying an ellipsis (...) or a blank entry as element names. These wildcards can expand to multiple
elements in a path.
The following sample shows a path ellipsis wildcard. This wildcard returns all description fields
available under /interfaces.
path {
elem {
name: "interfaces"
}
elem {
name: "..."
}
elem {
name: "description"
}
}

The following is a sample GetRequest with an implicit wildcard. This GetRequest will return the oper-status
of all interfaces on a device.

path {
elem {
name: "interfaces"
}
elem {
name: "interface"
}
elem {
name: "state"
}
elem {
name: "oper-status"
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

238
Model-Driven Programmability
gNMI Wildcards

},
type: 0,
encoding: 4

The following is a sample GetResponse with an implicit wildcard:

notification {
timestamp: 1520627877608777450
update {
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "\"FortyGigabitEthernet1/1/1\""
}
}
elem {
name: "state"
}
elem {
name: "oper-status"
}
}
val {
json_ietf_val: "\"LOWER_LAYER_DOWN\""
}
},

<snip>
…
</snip>

update {
path {
elem {
name: "interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "\"Vlan1\""
}
}
elem {
name: "state"
}
elem {
name: "oper-status"
}
}
val {
json_ietf_val: "\"DOWN\""
}
}
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

239
 Model-Driven Programmability
gNMI Configuration Persistence

gNMI Configuration Persistence

The gNMI Configuration Persistence feature ensures that all successful configuration changes made through
the gNMI SetRequest RPC persists across device restarts. Prior to this feature, the gNMI configuration was
stored in the running configuration of a device. And the changes were saved by issuing the write memory
command, or the SaveConfig NETCONF RPC.
All changes in the running configuration, even if the data was modified by processes other than gNMI, the
data is saved to the startup configuration, when the SetRequest RPC is issued.
This feature is enabled by default and cannot be disabled.

gNMI Username and Password Authentication

User credentials, the username and password provide authorization as metadata in each gNMI RPC. The
following is a sample gNMI Capabilities RPC that use the username and password:

metadata = [('username','admin'), ('password','lab')]

cap_request = gnmi_pb2.CapabilityRequest()
# pass metadata to the gnmi_pb2_grpc.gNMIStub object
secure_stub.Capabilities(cap_request, metadata=metadata)

gNMI Error Messages

When errors occur, gNMI returns descriptive error messages. The following section displays some gNMI
error messages.
The following sample error message is displayed when the path is invalid:

gNMI Error Response:

<_Rendezvous of RPC that terminated with (StatusCode.TERMINATED,
An error occurred while parsing provided xpath: unknown tag:
“someinvalidxpath" Additional information: badly formatted or nonexistent path)>

The following sample error message is displayed for an unimplemented error:

gNMI Error Response:

<_Rendezvous of RPC that terminated with (StatusCode.UNIMPLEMENTED,
Requested encoding "ASCII" not supported)>

The following sample error message is displayed when the data element is empty:

gNMI Error Response:

<_Rendezvous of RPC that terminated with (StatusCode.NOT_FOUND,
Empty set returned for path "/oc-if:interfaces/noinfohere")>

How to Enable the gNMI Protocol

Perform the following steps to enable the gNMI protocol:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

240
 Model-Driven Programmability
Creating Certs with OpenSSL on Linux

1. Create a set of certs for the gNMI client and device signed by a Certificate Authority (CA).
a. Create Certs with OpenSSL on Linux.
b. Install Certs on a device.
c. Configure gNMI on the device.
d. Verify whether gNMI is enabled and running.

2. Connect the gNMI client using client and root certificates configured in previous steps.

Creating Certs with OpenSSL on Linux

Certs and trustpoint are only required for secure gNMI servers.
The following example shows how to create Certs with OpenSSL on a Linux machine:
# Setting up a CA
openssl genrsa -out rootCA.key 2048
openssl req -subj /C=/ST=/L=/O=/CN=rootCA -x509 -new -nodes -key rootCA.key -sha256 -out
rootCA.pem

# Setting up device cert and key

openssl genrsa -out device.key 2048
openssl req -subj /C=/ST=/L=/O=/CN=<hostnameFQDN> -new -key device.key -out device.csr
openssl x509 -req -in device.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out
device.crt -sha256
# Encrpyt device key - needed for input to IOS
openssl rsa -des3 -in device.key -out device.des3.key -passout pass:<password - remember
this for later>

# Setting up client cert and key

openssl genrsa -out client.key 2048
openssl req -subj /C=/ST=/L=/O=/CN=gnmi_client -new -key client.key -out client.csr
openssl x509 -req -in client.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out
client.crt -sha256

Installing Certs on a Device Through the CLI

The following example show how to install certs on a device:

# Send:
Device# configure terminal
Device(config)# crypto pki import trustpoint1 pem terminal password password1

# Receive:
% Enter PEM-formatted CA certificate.
% End with a blank line or "quit" on a line by itself.

# Send:
# Contents of rootCA.pem, followed by newline + 'quit' + newline:
-----BEGIN CERTIFICATE-----
<snip>
-----END CERTIFICATE-----
quit

# Receive:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

241
 Model-Driven Programmability
Enabling gNMI in Insecure Mode

% Enter PEM-formatted encrypted private General Purpose key.

% End with "quit" on a line by itself.

# Send:
# Contents of device.des3.key, followed by newline + 'quit' + newline:
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,D954FF9E43F1BA20
<snip>
-----END RSA PRIVATE KEY-----
quit

# Receive:
% Enter PEM-formatted General Purpose certificate.
% End with a blank line or "quit" on a line by itself.

# Send:
# Contents of device.crt, followed by newline + 'quit' + newline:
-----BEGIN CERTIFICATE-----
<snip>
-----END CERTIFICATE-----
quit

# Receive:
% PEM files import succeeded.
Device(config)#

# Send:
Device(config)# crypto pki trustpoint trustpoint1
Device(ca-trustpoint)# revocation-check none
Device(ca-trustpoint)# end
Device#

Enabling gNMI in Insecure Mode

Note This task is applicable in Cisco IOS XE Amsterdam 17.3.1 and later releases.

In a Day Zero setup, first enable the device in insecure mode, then disable it, and enable the secure mode. To
stop gNxI in insecure mode, use the no gnxi server command.

Note gNxI insecure and secure servers can run simultaneously on a device.

Note The gnxi commands apply to both gNMI and gRPC Network Operations Interface (gNOI) services.
gNxI tools are a collection of tools for Network Management that use the gNMI and gNOI protocols.

SUMMARY STEPS
1. enable
2. configure terminal

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

242
 Model-Driven Programmability
Enabling gNMI in Secure Mode

3. gnxi
4. gnxi server
5. gnxi port port-number
6. end
7. show gnxi state

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 gnxi Starts the gNxI process.

Example:
Device(config)# gnxi

Step 4 gnxi server Enables the gNxI server in insecure mode.

Example:
Device(config)# gnxi server

Step 5 gnxi port port-number Sets the gNxI port to listen to.
Example: • The default insecure gNxI port is 50052.
(Optional) Device(config)# gnxi port 50000

Step 6 end Exits global configuration mode and returns to privileged

EXEC mode.
Example:
Device(config)# end

Step 7 show gnxi state Displays the status of gNxI interfaces.

Example:
Device# show gnxi state

Enabling gNMI in Secure Mode

Note This task is applicable in Cisco IOS XE Amsterdam 17.3.1 and later releases.

To stop gNxI in secure mode, use the no gnxi secure-server command.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

243
 Model-Driven Programmability
Enabling gNMI in Secure Mode

Note gNxI insecure and secure servers can simultaneously run on a device.

Note The gnxi commands apply to both gNMI and gRPC Network Operations Interface (gNOI) services.
gNxI tools are a collection of tools for Network Management that use the gNMI and gNOI protocols.

SUMMARY STEPS
1. enable
2. configure terminal
3. gnxi
4. gnxi secure-server
5. gnxi secure-trustpoint trustpoint-name
6. gnxi secure-client-auth
7. gnxi secure-port
8. end
9. show gnxi state

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 gnxi Starts the gNxI process.

Example:
Device(config)# gnxi

Step 4 gnxi secure-server Enables the gNxI server in secure mode.

Example:
Device(config)# gnxi secure-server

Step 5 gnxi secure-trustpoint trustpoint-name Specifies the trustpoint and cert set that gNxI uses for
authentication.
Example:
Device(config)# gnxi secure-trustpoint trustpoint1

Step 6 gnxi secure-client-auth (Optional) The gNxI process authenticates the client
certificate against the root certificate.
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

244
 Model-Driven Programmability
Connecting the gNMI Client

Command or Action Purpose

Device(config)# gnxi secure-client-auth

Step 7 gnxi secure-port (Optional) Sets the gNxI port to listen to.
Example: • The default secure gNxI port is 9339.
Device(config)# gnxi secure-port

Step 8 end Exits global configuration mode and returns to privileged

EXEC mode.
Example:
Device(config)# end

Step 9 show gnxi state Displays the status of gNxI servers.

Example:
Device# show gnxi state

Example
The following is sample output from the show gnxi state command:

Device# show gnxi state

State Status
--------------------------------
Enabled Up

Connecting the gNMI Client

The gNMI client is connected by using the client and root certificates that are previously configured.
The following example shows how to connect the gNMI client using Python:

# gRPC Must be compiled in local dir under path below:

>>> import sys
>>> sys.path.insert(0, "reference/rpc/gnmi/")
>>> import grpc
>>> import gnmi_pb2
>>> import gnmi_pb2_grpc
>>> gnmi_dir = '/path/to/where/openssl/creds/were/generated/'

# Certs must be read in as bytes

>>> with open(gnmi_dir + 'rootCA.pem', 'rb') as f:
>>> ca_cert = f.read()
>>> with open(gnmi_dir + 'client.crt', 'rb') as f:
>>> client_cert = f.read()
>>> with open(gnmi_dir + 'client.key', 'rb') as f:
>>> client_key = f.read()

# Create credentials object

>>> credentials = grpc.ssl_channel_credentials(root_certificates=ca_cert,
private_key=client_key, certificate_chain=client_cert)

# Create a secure channel:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

245
 Model-Driven Programmability
Configuration Examples for the gNMI Protocol

# Default port is 9339, can be changed on ios device with 'gnxi secure-port ####'
>>> port = 9339
>>> host = <HOSTNAME FQDN>
>>> secure_channel = grpc.secure_channel("%s:%d" % (host, port), credentials)

# Create secure stub:

>>> secure_stub = gnmi_pb2_grpc.gNMIStub(secure_channel)

# Done! Let's test to make sure it works:

>>> secure_stub.Capabilities(gnmi_pb2.CapabilityRequest())
supported_models {
<snip>
}
supported_encodings: <snip>
gNMI_version: "0.4.0"

Configuration Examples for the gNMI Protocol

Example: Enabling gNMI in Insecure Mode

Note This example is applicable in Cisco IOS XE Amsterdam 17.3.1 and later releases.

The following example shows how to enable the gNxI server in insecure mode:

Device> enable
Device# configure terminal
Device(config)# gnxi
Device(config)# gnxi server
Device(config)# gnxi port 50000 <The default port is 50052.>
Device(config)# end
Device#

Example: Enabling gNMI in Secure Mode

Note This example is applicable in Cisco IOS XE Amsterdam 17.3.1 and later releases.

The following example shows how to enable the gNxI server in secure mode:

Device> enable
Device# configure terminal
Device(config)# gnxi
Device(config)# gnxi server
Device(config)# gnxi secure-server
Device(config)# gnxi secure-trustpoint trustpoint1
Device(config)# gnxi secure-client-auth
Device(config)# gnxi secure-port 50001 <The default port is 9339.>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

246
 Model-Driven Programmability
Additional References for the gNMI Protocol

Device(config)# end
Device#

Additional References for the gNMI Protocol

Related Documents

Related Topic Document Title

DevNet https://developer.cisco.com/site/ios-xe/

gNMI https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md

gNMI path https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-path-conventions.md

encoding

Standards and RFCs

Standard/RFC Title
RFC 7951 JSON Encoding of Data Modeled with YANG

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for the gNMI Protocol

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

247
 Model-Driven Programmability
Feature Information for the gNMI Protocol

Table 18: Feature Information for the gNMI Protocol

Feature Name Release Feature Information

gNMI Protocol Cisco IOS XE Fuji 16.8.1a This feature describes the model-driven
configuration and retrieval of operational data
using the gNMI capabilities, GET and SET
RPCs.
This feature was implemented on the
following platforms:
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Gibraltar In Cisco IOS XE Gibraltar 16.10.1, this feature

16.10.1 was implemented on Cisco Catalyst
9500-High Performance Series Switches.

Cisco IOS XE Gibraltar In Cisco IOS XE Gibraltar 16.11.1, this feature

16.11.1 was implemented on Cisco Catalyst 9600
Series Switches.

Cisco IOS XE Gibraltar In Cisco IOS XE Gibraltar 16.12.1, this feature

16.12.1 was implemented on the following platforms:
• Cisco Catalyst 9200 and 9200L Series
Switches
• Cisco Catalyst 9300L SKUs
• Cisco cBR-8 Converged Broadband
Router

Cisco IOS XE Amsterdam In Cisco IOS XE Amsterdam 17.1.1, this

17.1.1 feature was implemented on the following
platforms:
• Cisco ASR 900 Series Aggregation
Services Routers
• Cisco ASR 920 Series Aggregation
Services Router
• Cisco Network Convergence System 520
Series
• Cisco Network Convergence System
4200 Series

Cisco IOS XE Amsterdam In Cisco IOS XE Amsterdam 17.2.1r, this

17.2.1r feature was implemented on Cisco ASR 1000
Series Aggregation Services Routers.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

248
Model-Driven Programmability
Feature Information for the gNMI Protocol

Feature Name Release Feature Information

Cisco IOS XE Cupertino In Cisco IOS XE Cupertino 17.8.1, this feature

17.8.1 was implemented on the following platforms:
• Cisco 1000 Series Integrated Services
Routers
• Cisco 4000 Series Integrated Services
Routers
• Cisco Catalyst 9800-CL Wireless
Controllers
• Cisco Catalyst 9800-40 Wireless
Controllers
• Cisco Catalyst 9800-80 Wireless
Controllers

gNMI IPv6 Support Cisco IOS XE Dublin 17.10.1 gNMI IPv6 Support is enabled in Cisco IOS
XE Dublin 17.10.1.
• Cisco Catalyst 9200 and 9200L Series
Switches
• Cisco Catalyst 9300, 9300L, and 9300X
Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500
High-Performance Series Switches
• Cisco Catalyst 9600 Series Switches

gNMI Username and Cisco IOS XE Gibraltar The Username and Password Authentication
Password Authentication 16.12.1 feature was added to the gNMI protocol. This
feature is supported on all IOS XE platforms
that support gNMI.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

249
 Model-Driven Programmability
Feature Information for the gNMI Protocol

Feature Name Release Feature Information

gNMI Configuration Cisco IOS XE Amsterdam All successful configuration changes made
Persistence 17.3.1 through the gNMI SetRequest RPC persists
across device restarts. This feature was
implemented on the following platforms:
• Cisco 1000 Series Integrated Services
Routers
• Cisco 4000 Series Integrated Services
Routers
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

gNOI Certificate Management Cisco IOS XE Amsterdam The gNOI Certificate Management Service
17.3.1 provides RPCs to install, rotate, get certificate,
revoke certificate, and generate certificate
signing request. This feature was implemented
on the following platforms:
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

250
Model-Driven Programmability
Feature Information for the gNMI Protocol

Feature Name Release Feature Information

gNOI Bootstrapping with Cisco IOS XE Amsterdam After installing gNOI certificates,
Certificate Service 17.3.1 bootstrapping is used to configure or operate
a target device. gNMI bootstrapping is enabled
by using the gnxi-secure-int command and
disabled by using the
secure-allow-self-signed-trustpoint
command.
This feature was implemented on the
following platforms:
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

251
 Model-Driven Programmability
Feature Information for the gNMI Protocol

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

252
 CHAPTER 11
gRPC Network Operations Interface
The Google Remote Procedure Call (gRPC) Network Operations Interface (gNOI) is a suite of microservices,
each corresponding to a set of operations. This module describes the supported gNOI services.
• Information About the gRPC Network Operations Interface, on page 253
• Additional References for the gRPC Network Operations Interface, on page 268
• Feature Information for the gRPC Network Operations Interface, on page 269

Information About the gRPC Network Operations Interface

gNOI Protocol
gNOI defines a set of gRPC-based microservices for executing operational commands on network devices.
The gNMI service defines operations for configuration management, operational state retrieval, and bulk data
collection through streaming telemetry. gNOI only allows the adoption of services that a device supports.
gNOI supports the OS installation service.
gNOI can be used with or without user authentication. User authentication is disabled by default. Use the gnxi
secure-password-auth command to enable user authentication. For information about enabling user
authentication through the OpenConfig model, see https://github.com/YangModels/yang/blob/master/vendor/
cisco/xe/1751/openconfig-system-management.yang.
The gNOI protocol supports the following operations:
• Certificate Management
• Bootstrapping
• OS Installation Service
• Factory Reset Service

Certificate Management Service

The Certificate Management Service primarily exports two main RPCs, Install and Rotate, that are used for
the installation of new certificates, and the rotation of existing certificates on a device, respectively.
The following RPCs are supported by the Certificate Management Service:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

253
 Model-Driven Programmability
Install RPC

• Install: Installs a certificate. All certificates are uniquely identified by a certificate ID. The certificate ID
is a string.
• Rotate: Rotates an existing certificate.
• RevokeCertificates: Revokes one or more certificates.
• GetCertificates: Queries all certificates.
• CanGenerateCSR: Queries whether the device can generate a Certificate Signing Request (CSR).

Trustpoints and certificates created through the RPCs mentioned above persist across switchovers and device
reboots.
The following is a sample Certificate Management Service definition:

service CertificateManagement {
rpc Install(stream InstallCertificateRequest)
returns (stream InstallCertificateResponse);

rpc Rotate(stream RotateCertificateRequest)

returns (stream RotateCertificateResponse);

rpc RevokeCertificates(RevokeCertificateRequest)
returns (RevokeCertificateResponse);

rpc GetCertificates(GetCertificateRequest)
returns (GetCertificateResponse);

rpc CanGenerateCSR(CanGenerateCSRRequest)
returns (CanGenerateCSRResponse);
}

Install RPC
The Install RPC adds a new certificate to a device by creating a new CSR request. The new certificate is
associated with a new certificate ID on the device. If the device has a pre-existing certificate with the given
certificate ID, the operation fails.
The Install RPC is a bidirectional streaming RPC. It has an input (InstallCertificateRequest) and an output
(IntsallCertificateResponse) both of which are streaming. If the stream is broken, or any steps in the process
fail, the device rolls back the changes.
The following is an example of the Install RPC definition and messages:

rpc Install(stream InstallCertificateRequest)

returns (stream InstallCertificateResponse);

// Request messages to install new certificates on the target.

message InstallCertificateRequest {
// Request Messages.
oneof install_request {
GenerateCSRRequest generate_csr = 1;
LoadCertificateRequest load_certificate = 2;
}
}
// Request to generate the CSR.
message GenerateCSRRequest {
// Parameters for creating a CSR.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

254
Model-Driven Programmability
Install RPC

CSRParams csr_params = 1;
// The certificate id with which this CSR will be associated. The target
// configuration should bind an entity which wants to use a certificate to
// the certificate_id it should use.
string certificate_id = 2;
}
// Parameters to be used when generating a Certificate Signing Request.
message CSRParams {
// The type of certificate which will be associated for this CSR.
CertificateType type = 1;

// Minimum size of the key to be used by the target when generating a

// public/private key pair.
uint32 min_key_size = 2;

// If provided, the target must use the provided key type. If the target
// cannot use the algorithm specified in the key_type, it should cancel the
// stream with an Unimplemented error.
KeyType key_type = 3;

// --- common set of parameters applicable for any type of certificate --- //
string common_name = 4; // e.g "device.corp.google.com"
string country = 5; // e.g "US"
string state = 6; // e.g "CA"
string city = 7; // e.g "Mountain View"
string organization = 8; // e.g "Google"
string organizational_unit = 9; // e.g "Security"
string ip_address = 10;
string email_id = 11;
}
// A certificate.
message Certificate {
// Type of certificate.
CertificateType type = 1;

// Actual certificate.
// The exact encoding depends upon the type of certificate.
// for X509, this should be a PEM encoded Certificate.
bytes certificate = 2;
}

message LoadCertificateRequest {
// The certificate to be Loaded on the target.
Certificate certificate = 1;

// The key pair to be used with the certificate. This is provided in the event
// that the target cannot generate a CSR (and the corresponding public/private
// keys).
KeyPair key_pair = 2;

// Certificate Id of the above certificate. This is to be provided only when

// there is an externally generated key pair.
string certificate_id = 3;

// Optional pool of CA certificates to be used for authenticating the client.

repeated Certificate ca_certificate = 4;
}

// A message representing a pair of public/private keys.

message KeyPair {
bytes private_key = 1;
bytes public_key = 2;
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

255
 Model-Driven Programmability
Rotate RPC

// Response Messages from the target for the InstallCertificateRequest.

message InstallCertificateResponse {
// Response messages.
oneof install_response {
GenerateCSRResponse generated_csr = 1;
LoadCertificateResponse load_certificate = 2;
}
}

// GenerateCSRResponse contains the CSR associated with the Certificate ID

// supplied in the GenerateCSRRequest. When a Certificate is subsequently
// installed on the target in the same streaming RPC session, it must be
// associated to that Certificate ID.
//
// An Unimplemented error will be returned if the target cannot generate a CSR
// as per the request. In this case, the caller must generate its own key pair.
message GenerateCSRResponse {
CSR csr = 1;
}

// A Certificate Signing Request.

message CSR {
// Type of certificate.
CertificateType type = 1;

// Bytes representing the CSR.

// The exact encoding depends upon the type of certificate requested.
// for X509: This should be the PEM encoded CSR.
bytes csr = 2;
}

After the target device is up and gNOI is in default state, the controller (a third-party implementation) uses
the Install RPC to install a certificate that is signed by a Certificate Authority (CA). The certificate is uniquely
identified by a certificate ID. This ID is used as the trustpoint name in the Public Key Infrastructure (PKI)
configuration. The installation will fail, if you try to install a certificate that has an existing certificate ID.
The following section describes how a CSR is generated by a device:
1. The device generates a self-signed certificate through the Install RPC. The controller does not require a
copy of this certificate because in encrypted mode (or gNMI default state) the controller does not validate
the certificate presented by the target device. This is the default state.
2. The controller requests the device to generate a CSR, sends the CSR to the CA, and gets the signed
certificate back from the CA.
3. The signed certificate is installed into the device along with the CA certificates used to sign the certificate.
The CA certificate is present in the ca_certificates bundle, and is required by the PKI to install the device
certificate.
4. The gNMI or the gNOI service restarts using the newly installed certificate that is now in the provisioned
state.

Rotate RPC
The Rotate RPC renews an existing certificate; a certificate that is already installed. If a certificate is not
already installed, the Rotate RPC fails. A certificate that is not in use can be rotated, but the client cannot test
it.
The following is a sample Rotate RPC definition:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

256
 Model-Driven Programmability
Revoke RPC

rpc Rotate(stream RotateCertificateRequest)

returns (stream RotateCertificateResponse);

// Request messages to rotate existing certificates on the target.

message RotateCertificateRequest {
// Request Messages.
oneof rotate_request {
GenerateCSRRequest generate_csr = 1;
LoadCertificateRequest load_certificate = 2;
FinalizeRequest finalize_rotation = 3;
}
}

// A Finalize message is sent to the target to confirm the Rotation of

// the certificate and that the certificate should not be rolled back when
// the RPC concludes. The certificate must be rolled back if the target returns
// an error after receiving a Finalize message.
message FinalizeRequest {
}

message RotateCertificateResponse {
// Response messages.
oneof rotate_response {
GenerateCSRResponse generated_csr = 1;
LoadCertificateResponse load_certificate = 2;
}
}

The Rotate RPC differs from the Install RPC in the following ways:
• PKI has to save or cache the old certificate and the CA certificate when installing a new certificate (for
the purpose of rollback).
• The controller creates a new connection to test whether the renewed certificate works, and in case of
success, finalizes the certificate rotation.

Revoke RPC
This RPC is used to revoke one or more certificates, each uniquely identified by a certificate ID. Revocation
of a certificate results in the corresponding trustpoint to be removed from the Cisco IOS XE configuration.
If the corresponding trustpoints are currently in use, or if the trustpoints do not exist, revocation of the
certificates may fail.
A RevokeCertificate RPC may have certificates revoked successfully or unsuccessfully. On the target device,
revocation is a simple delete operation; the actual revocation with the CA is done by the client. If the client
revokes a certificate that is in use, new connections fail, but the existing connections are unaffected.
The following is a sample RevokeCertificate RPC:

// An RPC to revoke specific certificates.

// If a certificate is not present on the target, the request should silently
// succeed. Revoking a certificate should render the existing certificate
// unusable by any endpoints.
rpc RevokeCertificates(RevokeCertificatesRequest)
returns (RevokeCertificatesResponse);

message RevokeCertificatesRequest {
// Certificates to revoke.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

257
 Model-Driven Programmability
GetCertificate RPC

repeated string certificate_id = 1;

}

message RevokeCertificatesResponse {
// List of certificates successfully revoked.
repeated string revoked_certificate_id = 1;

// List of errors why certain certificates could not be revoked.

repeated CertificateRevocationError certificate_revocation_error = 2;
}

// An error message indicating why a certificate id could not be revoked.

message CertificateRevocationError {
string certificate_id = 1;
string error_message = 2;
}

GetCertificate RPC
This RPC queries all certificate IDs.
The response to the query contains the following information:
• Certificate information for all the certificates that are identified by a certificate ID.
• The list of endpoints, for example, tunnels, daemons, and so on, that use this certificate.

Note Endpoints are not supported.

Note Responses do not contain the ca_certificate bundle.

The following is a sample GetCertificate RPC:

// An RPC to get the certificates on the target.

rpc GetCertificates(GetCertificatesRequest) returns (GetCertificatesResponse);

// The request to query all the certificates on the target.

message GetCertificatesRequest {
}

// Response from the target about the certificates that exist on the target what
// what is using them.
message GetCertificatesResponse {
repeated CertificateInfo certificate_info = 1;
}

message CertificateInfo {
string certificate_id = 1;
Certificate certificate = 2;

// List of endpoints using this certificate.

repeated Endpoint endpoints = 3;

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

258
 Model-Driven Programmability
CanGenerateCSR RPC

// System modification time when the certificate was installed/rotated in

// nanoseconds since epoch.
int64 modification_time = 4;
}

// An endpoint represents an entity on the target which can use a certificate.

message Endpoint {
// Type of endpoint that can use a cert. This list is to be extended based on
// conversation with vendors.
enum Type {
EP_UNSPECIFIED = 0;
EP_IPSEC_TUNNEL = 1;
EP_DAEMON = 2;
}
Type type = 1;

// Human readable identifier for an endpoint.

string endpoint = 2;
}

CanGenerateCSR RPC
This RPC queries whether a device can generate a CSR for a specific key type, certificate type, and key size.
The supported key type is Rivest, Shamir, and Adelman (RSA), and the supported certificate type is X.509.
When this RPC request is made for installing a completely new certificate as part of the Install RPC, the device
must ensure that the certificate ID is new and no entities on the device are bound to this certificate ID. If any
existing certificate matches the certificate ID, this request fails.
When this RPC request is made for rotating an existing certificate as part of the Rotate RPC, the device must
ensure that the certificate ID is already available. If certificate rotation proceeds to load the certificate, it must
associate the new certificate with the previously created certificate ID.
The following is a sample CanGenerateCSR RPC:

// An RPC to ask a target if it can generate a Certificate.

rpc CanGenerateCSR(CanGenerateCSRRequest) returns (CanGenerateCSRResponse);

// A request to ask the target if it can generate key pairs.

message CanGenerateCSRRequest {
KeyType key_type = 1;
CertificateType certificate_type = 2;
uint32 key_size = 3;
}

// Algorithm to be used for generation the key pair.

enum KeyType {
// 1 - 500, for known types.
// 501 and onwards for private use.
KT_UNKNOWN = 0;
KT_RSA = 1;
}

// Types of certificates.
enum CertificateType {
// 1 - 500 for public use.
// 501 onwards for private use.
CT_UNKNOWN = 0;
CT_X509 = 1;
}

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

259
 Model-Driven Programmability
Mutual Authentication

// Response from the target about whether it can generate a CSR with the given
// parameters.
message CanGenerateCSRResponse {
bool can_generate = 4;
}

Mutual Authentication
Mutual authentication is a two-way authentication; two parties authenticate each other at the same time. To
enable mutual-authentication, use the gnmi-yang secure-peer-verify-trustpoint command. If this command
is not enabled, the authentication service validates the gNMI client against all the existing trustpoints and the
contents of the trustpool.
Rotation of the CA certificates for mutual authentication requires the client to present a new bundle to the
target device, and the old bundle to be removed. However, the CA certificates reside in a trustpool, and cannot
be selectively deleted from the trustpool.

Bootstrapping with Certificate Service

After installing gNOI certificates, bootstrapping is used to configure or operate a target device. When a target
device does not have any pre-existing certificates, bootstrapping allows the installing of certificates by using
the gNOI Certificate Management Service. After the certificate installation, the device is capable of establishing
secure gNOI or gNMI connections. This process assumes a pre-existing secure environment.
To enable gNMI bootstrapping, use the gnxi secure-int command.

Note The gNOI Certificate Management Service must be installed before bootstapping.

The gNOI Certificate Management Service has two states. These states are supported by both the gNOI service
and the gNMI service.
• Default/Encrypted: gNOI and gNMI on the device use a self-signed (default) certificate that the client
does not verify; the certificate does not require authentication. In this state, only the gNOI certificate
service is enabled on the target device.
• Provisioned: gNOI and gNMI on the device use an installed certificate that is verified by the client, and
the client presents its certificate, which the device verifies against its certificate store. The device verifies
the client certificate only if mutual authentication is enabled.

OS Installation Service
The OS installation service defines a gNOI API that is used for installation. The OS installation service is
supported in the gNOI protocol.
This service provides an interface for the installation of an OS on a device. It supports the following three
RPCs:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

260
Model-Driven Programmability
OS Installation Service

• Install: This RPC transfers an image to a device. These images are uniquely identified by a version string.
This RPC is the similar to the install add command; the main difference is that the image is transferred
as part of the RPC.
• Activate: This RPC sets the requested OS version, which is part of the input to the RPC, as the version
to be used at the next reboot, and reboots the device. This RPC is the same as the install activate and
the install commit commands.
• Verify: This RPC verifies the current OS version.

Cisco IOS XE devices support both install mode and bundle mode to boot software images.
In install mode, you can bring up your device by booting the software package provisioning file that resides
in the flash: file system. The ISO file system in each installed package is mounted to the root file system
(rootfs) directly from the flash.
In bundle mode, you can boot your device by using the bundle (.bin) file. Packages are extracted from the
bundle, and copied to the RAM. The ISO file system in each package is mounted to the rootfs. Unlike install
boot mode, additional memory that is equivalent to the size of the bundle is used when booting in bundle
mode.
In the following scenarios, an error message is generated when a device starts in bundle mode:
• The device starts with the current image running in bundle mode.
• The install RPC is initiated on the device to install a new image.

The following is a sample error message:

May 11 09:24:15.385 PST: %INSTALL-3-OPERATION_ERROR_MESSAGE:
Switch 1 R0/0: install_engine: Failed to install_add package
flash:gNOI_iosxe_17.05.01.0.144.1617180620.bin, Error: [2|install_add(ERR, )]:
Booted in bundle mode. For Bundle-to-Install mode conversion,
please use one-shot CLI - install add file <> activate commit

Even though an error message is generated, the install RPC returns a success to the client. The error message
can be safely ignored; the subsequent activate RPC is not affected. After rebooting with the new image, the
device is in install mode.

Note This error message is not displayed if the device was initially running in install mode. It is applicable
only when the device starts in bundle mode.
To view all the error messages, see https://github.com/openconfig/gnoi/blob/master/os/os.proto#L218.

For more information about installation modes, see the "Performing Device Setup Configuration" chapter of
the System Management Configuration Guide for all the Cisco Catalyst 9000 Series Switches.

Dual Route Processor Support

Cisco devices support both In-Service Software Update (ISSU) (only install mode is supported) and non-ISSU
modes. When ISSU is not supported or is not possible through the Install RPC, the gNOI OS installation
service will request a non-ISSU install.
If a device supports ISSU upgrade in case of dual Route Processors (RPs), the gNOI OS installation service
interface invokes the install activate ISSU workflow. In all other scenarios, where ISSU not is supported, or

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

261
 Model-Driven Programmability
OS Install RPC

the device supports a single RP, the gNOI OS installation service uses a regular non-ISSU image install
workflow to process the gRPC activate request.
In bundle mode, the upgrade is done through the install add file filename activate commit command. This
upgrade is the same for devices with a single RP. No ISSU support means that both the RPs are reloaded at
the same time, and the device is down until one RP comes up.
In install mode without ISSU, both the RPs are reloaded at the same time and the device is down until one
RP comes up. In install mode with ISSU, the reload of the RPs is simultaneous, and the device downtime is
shorter.

OS Install RPC
The Install RPC transfers an image to a device. The RPC consists of the input InstallRequest RPC, and the
output InstallResponse RPC, both of which are bidirectional streaming RPCs.
This RPC does not support Software Maintenance Update (SMU).
The following is a high-level message sequence for an Install RPC on a device with a single RP that is running
the operating system Version 1:
1. A client initiates an Install RPC to the device.
2. The client sends a TransferRequest message to the device, with version set to Version 2.
3. The device responds with a TransferReady message to the client. This is required for the client to start
transferring the image.
4. The client transfers the image by sending multiple transfer_content messages to the device.
5. Optionally, the device sends TransferProgress messages to the client.
6. The client sends a TransferEnd message to the device, indicating that the image transfer is complete.
7. In install mode, the device does an operation equivalent of the install add command programmatically.
The contents of the package are extracted.
8. The device sends a Validated message, which contains the version extracted from the image, to the client,
indicating that the image transfer is valid.

Note If the Install RPC is stopped prematurely by the client, or if any part of the operation fails, the local
image file is removed, and the install remove inactive command is invoked automatically. An appropriate
status code is returned to the client.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

262
 Model-Driven Programmability
OS Activate RPC

Figure 5: Single-RP Image Install Workflow

OS Activate RPC
The Activate RPC sets the requested operating system version as the version to be used at the next reboot,
and reboots the target device. The RPC activates an installed operating system version. If the version is not
already installed, the Activate RPC fails.
The client must provide a version that has been received in the Validated message of the Install RPC.
The following is the message sequence for an Activate RPC on a device with a single RP running operating
system Version 1:
1. The client initiates an Activate RPC to a device.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

263
 Model-Driven Programmability
OS Activate RPC

2. The client sends an ActivateRequest message to the device with Version 2.

For the purpose of this message sequence, assume that Version 2 is already installed through the Install
RPC.
3. The device does a programmatic operation equivalent to the install activate commit command, if it is in
install mode, or the install add file activate commit command if it is in bundle mode.
4. Because no errors are detected in the activate process, the device responds with an ActivateResponse(OK)
message to the client.
5. The device reloads with Version 2.
6. When the device comes up after the reload, it does a programmatic operation equivalent to the install
commit command.

Note Only one inactive image version is supported. Because of this, if a client installs Version 2 and then
Version 3, the Version 2 files get deleted.
The following images display the image activation workflow.

Figure 6: Single-RP Image Activation Workflow

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

264
Model-Driven Programmability
OS Activate RPC

Figure 7: Dual-RP Image Install + non-ISSU Activation Workflow in Bundle Mode

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

265
 Model-Driven Programmability
OS Activate RPC

Figure 8: Dual-RP Image Install + non-ISSU Activation Workflow

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

266
 Model-Driven Programmability
OS Verify RPC

OS Verify RPC
The Verify RPC verifies the running OS version. The response to the RPC contains information about the
support and presence of a standby RP.
If there was an error in the last activate RPC, that error is returned in the response as a string. The gNOI OS
installation service uses the install operational model and platform model to populate this information. Currently,
the install operational model does not support different versions running on two RPs.

GNOI Factory-Reset Services

Cisco IOS XE Cupertino 17.7.1 supports gNOI factory-reset services as specified in the reset.proto.
The gNOI factory-reset service supports a single RPC, Start. This RPC instructs a device to clean the existing
state, and boot the device in the same condition as it was shipped from the factory. The state includes, storage,
configuration, logs, certificates, licenses, crashinfo, and Rommon variables. Not all Rommon variables are
removed, enough are preserved on a per-platform basis to allow the image to automatically reboot with the
preserved image. The device then reboots with the current Operating System image, and comes back into the
default state, based on the simplified bootstrapping workflow. This RPC is accepted only if the target device
is in a provisioned state.
The Start RPC is similar to the factory-reset all command, however; the RPC preserves the current Operating
System image, unlike the command, which deletes the image. As part of the factory-reset scripts, both the
flash: or harddisk:, where the current image resides is cleaned up. However, when the factory-reset scripts
are run, the boot image or packages are backed up to the /tmp folder, and restored.
The regular factory-reset erases all the customer-specific data stored in a device and restores the device to its
original configuration at the time of shipping. Data that is erased includes configurations, log files, boot
variables, core files, and credentials such as Federal Information Processing Standard-related (FIPS-related)
keys. The erasure is consistent with the clear method, as described in NIST SP 800-88 Rev. 1. For more
information, see the "Performing Factory Reset Services" module of the System Management Configuration
Guide for your platform.

gNOI Factory-Reset Error Messages

gNOI factory-reset services return an empty ResetSuccess message upon successfully triggering the factory
reset on a device.
Some of the error messages that are returned in the context of gRPC and factory reset services are described
in this section:

Table 19: gNOI Factory-Reset Error Messages

Error Message Error Description

When the factory_os field is requested, the GNMIB In the ResetError message, the client will also receive
returns a gRPC error code of the factory_os_unsupported field set to TRUE. The
INVALID_ARGUMENT along with the message, other fields in the message will have default values.
“Factory OS rollback is not supported.”

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

267
 Model-Driven Programmability
Additional References for the gRPC Network Operations Interface

Error Message Error Description

This device does not support the requested zero-fill The StartRequest message has an optional field,
option. zero_fill that instructs the target device to zero fill the
persistent storage state data.
When a client requests a zero-fill, and if the device
cannot perform a zero fill, then the gRPC error code
of INVALID_ARGUMENT is sent back to the client
along with the message, “This device does not support
the requested zero-fill option.”
In the ResetError message, the zero_fill_unsupported
field is set to TRUE.

This device does not support the requested zero-fill When the device can perform a zero-fill, but the client
option. has not made a request for a zero-fill, then the gRPC
error code of INVALID_ARGUMENT is sent back
to the client with the message, “This device does not
support the requested zero-fill option.”
In the ResetError message, the zero_fill_unsupported
field is set to FALSE.

Factory reset capability is not present. When the gNOI factory-reset script is run on an
unsupported platform, the factory-reset services
returns the gRPC error code of UNIMPLEMENTED
with the message, “Factory reset capability is not
present.”

Factory reset interface is not ready. When the gNOI factory-reset management interface
is down or busy, the factory-reset services returns the
gRPC error code of UNAVAILABLE with the
message, “Factory reset interface is not ready.”

Without using a cert.proto provisioning operation, or configuring gNOI with a signed certificate (not
self-signed), the gNOI factory-reset service will always return the FAILED_PRECONDITION error code.

Additional References for the gRPC Network Operations

Interface
Related Documents

Related Topic Document Title

DevNet https://developer.cisco.com/site/ios-xe/

gNOI https://github.com/openconfig/gnoi

OS Service https://github.com/openconfig/gnoi/blob/master/os/os.proto

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

268
 Model-Driven Programmability
Feature Information for the gRPC Network Operations Interface

Related Topic Document Title

gNOI Factory https://github.com/openconfig/gnoi/blob/master/factory_reset/factory_reset.proto
Reset Service

Performing • System Management Configuration Guide, Catalyst 9200 Switches

Device Setup
Configuration • System Management Configuration Guide, Catalyst 9300 Switches
• System Management Configuration Guide, Catalyst 9400 Switches
• System Management Configuration Guide, Catalyst 9500 Switches
• System Management Configuration Guide, Catalyst 9600 Switches

Performing • System Management Configuration Guide, Catalyst 9300 Switches

Factory Reset
• System Management Configuration Guide, Catalyst 9300 Switches
• System Management Configuration Guide, Catalyst 9300 Switches
• System Management Configuration Guide, Catalyst 9300 Switches
• System Management Configuration Guide, Catalyst 9300 Switches

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for the gRPC Network Operations Interface

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

269
 Model-Driven Programmability
Feature Information for the gRPC Network Operations Interface

Table 20: Feature Information for the gRPC Network Operations Interface

Feature Name Release Feature Information

gNOI Certificate Management Cisco IOS XE Amsterdam The gNOI Certificate Management Service
17.3.1 provides RPCs to install, rotate, get certificate,
revoke certificate, and generate certificate
signing request.
In Cisco IOS XE Amsterdam 17.3.1, this
feature was implemented on the following
platforms:
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

gNOI Bootstrapping with Cisco IOS XE Amsterdam After installing gNOI certificates,
Certificate Service 17.3.1 bootstrapping is used to configure or operate
a target device. gNMI bootstrapping can be
enabled by using the gnxi secure-int
command.
In Cisco IOS XE Amsterdam 17.3.1, this
feature was implemented on the following
platforms:
• Cisco Catalyst 9200 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches
• Cisco Catalyst 9600 Series Switches

gNOI OS Installation Service Cisco IOS XE Bengaluru The gNOI OS installation service defines a
17.5.1 gNOI API that is used for installation.
In Cisco IOS XE Bengaluru 17.5.1, this
feature was implemented on the following
platforms:
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High
Performance Series Switches
• Cisco Catalyst 9600 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

270
Model-Driven Programmability
Feature Information for the gRPC Network Operations Interface

Feature Name Release Feature Information

gNOI Factory Reset Services Cisco IOS XE Cupertino The gNOI factory reset service provides an
17.7.1 interface that instructs target devices to clean
the existing state, and boot the devices in same
condition as it was shipped from the factory.
In Cisco IOS XE Cupertino 17.7.1, this feature
was implemented on the following platforms:
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 and 9500-High
Performance Series Switches
• Cisco Catalyst 9800-40 Wireless
Controllers
• Cisco Catalyst 9800-80 Wireless
Controllers

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

271
 Model-Driven Programmability
Feature Information for the gRPC Network Operations Interface

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

272
 CHAPTER 12
Model Based AAA
The NETCONF and RESTCONF interfaces implement the NETCONF Access Control Model (NACM).
NACM is a form of role-based access control (RBAC) specified in RFC 6536.
• Model Based AAA, on page 273
• Additional References for Model Based AAA, on page 279
• Feature Information for Model-Based AAA, on page 279

Model Based AAA

Prerequisites for Model Based AAA
Working with the model based AAA feature requires prior understanding of the following :
• NETCONF-YANG
• NETCONF-YANG kill-session
• RFC 6536: Network Configuration Protocol (NETCONF) Access Control Model

Initial Operation
Upon enabling the NETCONF and/or RESTCONF services, a device that has no prior configuration of the
/nacm subtree will deny read, write, and execute access to all operations and data other than the users of
privilege level 15. This is described in the following configuration of the /nacm subtree:
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<enable-nacm>true</enable-nacm>
<read-default>deny</read-default>
<write-default>deny</write-default>
<exec-default>deny</exec-default>
<enable-external-groups>true</enable-external-groups>
<rule-list>
<name>admin</name>
<group>PRIV15</group>
<rule>
<name>permit-all</name>
<module-name>*</module-name>
<access-operations>*</access-operations>
<action>permit</action>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

273
 Model-Driven Programmability
Group Membership

</rule>
</rule-list>
</nacm>

Group Membership
The group membership of a user can come from two sources- first, from the privilege level of the user as
configured on the AAA server used for authorization, and second, from those configured in the /nacm/groups
subtree. The names of the groups that correspond to each privilege level are as follows:

Privilege level NACM group name

0 PRIV00

1 PRIV01

2 PRIV02

3 PRIV03

4 PRIV04

5 PRIV05

6 PRIV06

7 PRIV07

8 PRIV08

9 PRIV09

10 PRIV10

11 PRIV11

12 PRIV12

13 PRIV13

14 PRIV14

15 PRIV15

Note Traditional IOS command authorization, such as those based on privilege level, does not apply to
NETCONF or RESTCONF.

Note Access granted to a NACM group based on a privilege level do not inherently apply to NACM groups
with higher privilege level. For example, rules that apply to PRIV10 do not automatically apply to
PRIV11, PRIV12, PRIV13, PRIV14, and PRIV15 as well.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

274
 Model-Driven Programmability
NACM Privilege Level Dependencies

NACM Privilege Level Dependencies

If the AAA configuration is configured with no aaa new-model, the privilege level locally configured for
the user is used. If the AAA configuration is configured with aaa new-model, the privilege level is determined
by the AAA servers associated with the method list aaa authorization exec default.

NACM Configuration Management and Persistance

The NACM configuration can be modified using NETCONF or RESTCONF. In order for a user to be able
to acccess the NCAM configuration, they must have explicit permission to do so, that is, through a NACM
rule. Configuration under the /nacm subtree persists when the copy running-config startup-config EXEC
command is issued, or the cisco-ia:save-config RPC is issued.
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<save-config xmlns="http://cisco.com/yang/cisco-ia"/>
</rpc>

Note The NACM rules that apply to a NETCONF session are those that are configured in the /nacm subtree
at the time of session establishment. Modifying the /nacm subtree has no effect on NETCONF sessions
as they are already established. The <kill-session> RPC or the clear netconf-yang session EXEC
command can be used to forcibly end an unwanted NETCONF session. See NETCONF Kill Session,
on page 160.

Note Care should be taken when crafting rules to deny access to certain data as the same data may be exposed
through multiple YANG modules and data node paths. For example, interface configuration is exposed
through both Cisco-IOS-XE-native and ietf-interface. Rules that may apply to one representation of
the same underlying data may not apply to other representations of that data.

Resetting the NACM Configuration

Use the following command to reset the /nacm subtree configuration to the initial configuration (see Initial
Operation).
Router#request platform software yang-management nacm reset-config

Sample NACM Configuration

Note The examples in this section are for illustrative purposes only.

The following is a sample for groups configuration.

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups>
<group>
<name>administrators</name>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

275
 Model-Driven Programmability
Sample NACM Configuration

<user-name>admin</user-name>
<user-name>root</user-name>
</group>

<group>
<name>limited-permission</name>
<user-name>alice</user-name>
<user-name>bob</user-name>
</group>
</groups>
</nacm>

Table 21: Description of the Configuration Paramenters for Groups Configuration

Parameter Description

<name>administrators</name> Group name

<user-name>admin</user-name> User name

<user-name>root</user-name> User name

The following is a sample for creating module rules.

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>only-ietf-interfaces</name>
<group>limited-permission</group>
<rule>
<name>deny-native</name>
<module-name>Cisco-IOS-XE-native</module-name>
<access-operations>*</access-operations>
<action>deny</action>
</rule>
<rule>
<name>allow-ietf-interfaces</name>
<module-name>ietf-interfaces</module-name>
<access-operations>*</access-operations>
<action>permit</action>
</rule>
</rule-list>
</nacm>

Table 22: Description of the Configuration Paramenters for Creating Module Rules

Parameter Description

<name>only-ietf-interfaces</name> Unique rule-list name

<group>limited-permission</group> Groups that rule-list applies to

<name>deny-native</name> Unique rule name

<module-name>Cisco-IOS-XE-native</module-name> Name of the YANG module

<access-operations>*</access-operations> CRUDx operation types

<action>deny</action> Permit/deny

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

276
Model-Driven Programmability
Sample NACM Configuration

The following is a sample for creating protocol operation rules.

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>only-get</name>
<group>limited-permission</group>

<rule>
<name>deny-edit-config</name>
<module-name>ietf-netconf</module-name>
<rpc-name>edit-config</rpc-name>
<access-operations>exec</access-operations>
<action>deny</action>
</rule>
<rule>
<name>allow-get</name>
<module-name>ietf-netconf</module-name>
<rpc-name>get</rpc-name>
<access-operations>exec</access-operations>
<action>permit</action>
</rule>
</rule-list>
</nacm>

Table 23: Description of the Configuration Paramenters for Creating Protocol Operation Rules

Parameter Description

<name>only-get</name> Unique rule-list name

<group>limited-permission</group> Groups that rule-list applies to

<name>deny-edit-config</name> Unique rule name

<module-name>ietf-netconf</module-name> Name of module containing the RPC

<rpc-name>edit-config</rpc-name> Name of the RPC

<access-operations>exec</access-operations> Execute permission for the RPC

<action>deny</action> Permit/deny

The following is a sample for creating data node rules.

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>hide-enable-passwords</name>
<group>limited-permission</group>

<rule>
<name>deny-enable-passwords</name>
<path xmlns:ios="http://cisco.com/ns/yang/Cisco-IOS-XE-native>/ios:native/enable
</path>
<access-operations>*</access-operations>
<action>deny</action>
</rule>
</rule-list>
</nacm>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

277
 Model-Driven Programmability
Sample NACM Configuration

Table 24: Description of the Configuration Paramenters for Creating Data Node Rules

Parameter Description

<name>hide-enable-passwords</name> Unique rule-list name

<group>limited-permission</group> Groups that rule-list applies to

<name>deny-enable-passwords</name> Unique rule name

<path Path to the data node being granted/denied

xmlns:ios="http://cisco.com/ns/yang/Cisco-IOS-XE-native>/ios:native/enable</path>

<access-operations>*</access-operations> CRUDx operation types

<action>deny</action> Permit/deny

The following is an example NACM configuration that permits all groups to use the standard NETCONF
RPCs <get> and <get-config>, the schema download RPC <get-schema>, and read-only access to the data in
the module ietf-interfaces:
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>readonly-protocol</name>
<group>*</group>
<rule>
<name>get-permit</name>
<module-name>ietf-netconf</module-name>
<rpc-name>get</rpc-name>
<access-operations>exec</access-operations>
<action>permit</action>
</rule>
<rule>
<name>get-config-permit</name>
<module-name>ietf-netconf</module-name>
<rpc-name>get-config</rpc-name>
<access-operations>exec</access-operations>
<action>permit</action>
</rule>
<rule>
<name>get-schema-permit</name>
<module-name>ietf-netconf-monitoring</module-name>
<rpc-name>get-schema</rpc-name>
<access-operations>exec</access-operations>
<action>permit</action>
</rule>
</rule-list>
<rule-list>
<name>readonly-data</name>
<group>*</group>
<rule>
<name>ietf-interfaces-permit</name>
<module-name>ietf-interfaces</module-name>
<access-operations>read</access-operations>
<action>permit</action>
</rule>
</rule-list>
</nacm>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

278
 Model-Driven Programmability
Additional References for Model Based AAA

Additional References for Model Based AAA

Related Documents

Related Topic Document Title

YANG data models for various release of To access Cisco YANG models in a developer-friendly way,
IOS-XE, IOS-XR, and NX-OS platforms please clone the GitHub repository, and navigate to the
vendor/cisco subdirectory. Models for various releases of
IOS-XE, IOS-XR, and NX-OS platforms are available here.

Standards and RFCs

Standard/RFC Title
RFC 6020 YANG - A Data Modeling Language for the Network Configuration
Protocol (NETCONF)

RFC 6241 Network Configuration Protocol (NETCONF)

RFC 6536 Network Configuration Protocol (NETCONF) Access Control Model

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, http://www.cisco.com/support
including documentation and tools for troubleshooting and resolving
technical issues with Cisco products and technologies.
To receive security and technical information about your products,
you can subscribe to various services, such as the Product Alert Tool
(accessed from Field Notices), the Cisco Technical Services
Newsletter, and Really Simple Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a
Cisco.com user ID and password.

Feature Information for Model-Based AAA

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

279
 Model-Driven Programmability
Feature Information for Model-Based AAA

Table 25: Feature Information for Programmability: Data Models

Feature Name Release Feature Information

Model-Based AAA Cisco IOS XE Fuji 16.8.1 This feature was implemented on the
following platforms:
• Cisco ASR 900 Series Aggregated
Services Routers
• Cisco ASR 920 Series Aggregated
Services Routers
• Cisco ASR 1000 Series Aggregated
Services Routers
• Cisco CSR 1000v Switches
• Cisco ISR 1100 Series Integrated
Services Routers
• Cisco ISR 4000 Series Integrated
Services Routers
• Cisco NCS 4200 Series

Cisco IOS XE Fuji 16.8.1a This feature was implemented on the

following platforms:
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

280
 CHAPTER 13
Model-Driven Telemetry
• Model-Driven Telemetry, on page 281

Model-Driven Telemetry
Model-driven telemetry provides a mechanism to stream YANG-modelled data to a data collector. This module
describes model-driven telemetry and provides sample telemetry remote procedure calls (RPCs).

Prerequisites for Model-Driven Telemetry

• Knowledge of YANG is needed to understand and define the data that is required when using telemetry.
• Knowledge of XML, XML namespaces, and XML XPath.
• Knowledge of standards and principles defined by the IETF telemetry specifications.
• The urn:ietf:params:netconf:capability:notification:1.1 capability must be listed in hello messages. This
capability is advertised only on devices that support IETF telemetry.
• NETCONF-YANG must be configured and running on the device.

Note Either NETCONF-YANG or gNXI must be configured for telemetry to

work. If your platform does not support gNXI, you must configure
NETCONF, even if NETCONF is not used. For more information on
configuring NETCONF-YANG, see the NETCONF Protocol module. For
more information on gNXI, see the gNMI Protocol module.

Verify that the following processes are running, by using the show platform software yang-management
process command:

Device# show platform software yang-management process

confd : Running
nesd : Running
syncfd : Running
ncsshd : Running
dmiauthd : Running
nginx : Running

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

281
 Model-Driven Programmability
Prerequisites for Model-Driven Telemetry

ndbmand : Running
pubd : Running
gnmib : Running

Note The process pubd is the model-driven telemetry process, and if it is not
running, model-driven telemetry will not work.

The following table provides details about each of the Device Management Interface (DMI) processes.

Table 26: Field Descriptions

Device Management Interface Process Name Primary Role

confd Configuration daemon.

nesd Network element synchronizer daemon.

syncfd Sync daemon (maintains synchronization between

the running state and corresponding models).

ncsshd NETCONF Secure Shell (SSH) daemon.

dmiauthd DMI authentication daemon.

nginx NGINX web server. Acts as a web server for

RESTCONF.

ndbmand NETCONF database manager.

pubd Publication manager and publisher used for

model-driven telemetry.

gnmib GNMI protocol server.

NETCONF-Specific Prerequisites
• Knowledge of NETCONF and how to use it, including:
• Establishing a NETCONF session.
• Sending and receiving hello and capabilities messages.
• Sending and receiving YANG XML RPCs over the established NETCONF session. For more
information, see the Configure NETCONF/YANG and Validate Example for Cisco IOS XE 16.x
Platforms document.

Enabling and Validating NETCONF

The NETCONF functionality can be verified by creating an SSH connection to the device using a valid
username and password and receiving a hello message, which contains the capability of the device:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

282
Model-Driven Programmability
Prerequisites for Model-Driven Telemetry

Device:~ USER1$ ssh -s [email protected] -p 830 netconf

[email protected]'s password: cisco1

<?xml version="1.0" encoding="UTF-8"?>

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
<capability>urn:ietf:params:netconf:base:1.1</capability>
<capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability>
<capability>urn:ietf:params:netconf:capability:xpath:1.0</capability>
<capability>urn:ietf:params:netconf:capability:validate:1.0</capability>
<capability>urn:ietf:params:netconf:capability:validate:1.1</capability>
<capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability
.
.
.
</capabilities>
<session-id>2870</session-id></hello>]]>]]>

Use < ^C > to exit

NETCONF is ready to use, when a successful reply is received in response to your hello message.

RESTCONF-Specific Prerequisites
• Knowledge of RESTCONF and how to use it (when creating a subscription using RESTCONF).
• RESTCONF must be configured on the device.
• RESTCONF must send correctly-formed Uniform Resource Identifiers (URIs) that adhere to RESTCONF
RFC 8040.

Enabling and Validating RESTCONF

Validate RESTCONF using appropriate credentials and the following URI:
Operation: GET
Headers:
" Accept: application/yang-data.collection+json, application/yang-data+json,
application/yang-data.errors+json
" Content-Type: application/yang-data+json
Returned Output (omitted for breverity):
{
"ietf-restconf:data": {
"ietf-yang-library:modules-state": {
"module": [
{
"name": "ATM-FORUM-TC-MIB",
"revision": "",
"schema":
"https://10.85.116.28:443/restconf/tailf/modules/ATM-FORUM-TC-MIB",
"namespace": "urn:ietf:params:xml:ns:yang:smiv2:ATM-FORUM-TC-MIB"
},
{
"name": "ATM-MIB",
"revision": "1998-10-19",
"schema":
"https://10.85.116.28:443/restconf/tailf/modules/ATM-MIB/1998-10-19",
"namespace": "urn:ietf:params:xml:ns:yang:smiv2:ATM-MIB"
},
{
"name": "ATM-TC-MIB",

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

283
 Model-Driven Programmability
Restrictions for Model-Driven Telemetry

"revision": "1998-10-19",
"schema": "https://10.85.116.28:443/restconf/tailf/
..
<snip>
..
}

RESTCONF is validated successfully when you receive the above reply with all device capabilities.

gRPC-Specific Prerequisites
• Set up a gRPC collector that understands key-value Google Protocol Buffers (GPB) encoding.

Restrictions for Model-Driven Telemetry

• Automatic hierarchy in selections is not supported for on-change subscriptions when using the yang-push
stream. This means that when selecting a list, child lists of the list are not automatically included. For
example, the subscriber must manually create a subscription for each child list.
• Checking the authorization of data access is not supported. All the data requested by a subscriber is sent.
• Subtree filters are not supported. If subtree filters are specified, the subscription is marked as invalid.
• Defining multiple receivers within subscription parameters is not supported; only the first receiver
destination is attempted. Other defined receivers are ignored.

gRPC-Specific Restrictions
• Transport Layer Security-based (TLS-based) authentication between a device and receiver is not supported.
TLS-based authentication is supported in Cisco IOS XE Amsterdam 17.1.1 and later releases.

yang-push-Specific Restriction
• Subscription quality of service (QoS) is not supported.

Information About Model-Driven Telemetry

The following sections provide information about the various aspects of model-driven telemetry.

Model-Driven Telemetry Overview

Telemetry is an automated communications process by which measurements and other data are collected at
remote or inaccessible points and transmitted to the receiving equipment for monitoring. Model-driven
telemetry provides a mechanism to stream YANG-modeled data to a data collector.
Applications can subscribe to specific data items they need, by using standards-based YANG data models
over NETCONF, RESTCONF, or gRPC Network Management Interface (gNMI) protocols. Subscriptions
can also be created by using CLIs if it is a configured subscription.
Structured data is published at a defined cadence, or on-change, based upon the subscription criteria and data
type.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

284
 Model-Driven Programmability
Telemetry Roles

Telemetry Roles
In systems that use telemetry, different roles are involved. In this document the following telemetry roles are
described:
• Publisher: Network element that sends the telemetry data.
• Receiver: Receives the telemetry data. This is also called the collector.
• Controller: Network element that creates subscriptions but does not receive the telemetry data. The
telemetry data associated with the subscriptions, it creates goes to receivers. This is also called the
management agent or management entity.
• Subscriber: Network element that creates subscriptions. Technically, while this does not have to be the
receiver too, in this document, both are the same.

Subscription Overview
Subscriptions are items that create associations between telemetry roles, and define the data that is sent between
them.
Specifically, a subscription is used to define the set of data that is requested as part of the telemetry data; when
the data is required, how the data is to be formatted, and, when not implicit, who (which receivers) should
receive the data.
Even though the maximum number of supported subscriptions is platform-dependent, currently 100
subscriptions are supported. The subscriptions can be either configured or dynamic, and use any combination
of transport protocols. If too many subscriptions are operating at the same time to allow all the valid configured
subscriptions to be active, the removal of an active subscription will cause one of the inactive but valid
configured subscriptions to be attempted. Periodic triggered subscriptions (100 centiseconds is the default
minimum) and on-change triggered subscriptions are supported.
NETCONF and other northbound programmable interfaces (such as RESTCONF or gNMI) are supported to
configure subscriptions.
Two types of subscriptions are used in telemetry on Cisco IOS XE systems: dynamic and configured
subscriptions.
Because dynamic subscriptions are created by clients (the subscriber) that connect into the publisher, they are
considered dial-in. Configured subscriptions cause the publisher to initiate connections to receivers, and as a
result, they are considered dial-out.

Dial-In and Dial-Out Model-Driven Telemetry

The two flavors of model-driven telemetry are, dial-in and dial-out.

Table 27: Dial-in and Dial-Out Model-Driven Telemetry

Dial-In (Dynamic) Dial-Out (Static or Configured)

Telemetry updates are sent to the initiator or Telemetry updates are sent to the specified receiver
subscriber. or collector.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

285
 Model-Driven Programmability
Data Source Specifications

Dial-In (Dynamic) Dial-Out (Static or Configured)

Life of the subscription is tied to the connection Subscription is created as part of the running
(session) that created it, and over which telemetry configuration; it remains as the device configuration
updates are sent. No change is observed in the running till the configuration is removed.
configuration.

Dial-in subscriptions need to be reinitiated after a Dial-out subscriptions are created as part of the device
reload, because established connections or sessions configuration, and they automatically reconnect to the
are killed during stateful switchover. receiver after a stateful switchover.

Subscription ID is dynamically generated upon Subscription ID is fixed and configured on the device
successful establishment of a subscription. as part of the configuration.

Data Source Specifications

Sources of telemetry data in a subscription are specified by the use of a stream and a filter. The term stream
refers to a related set of events. RFC 5277 defines an event stream as a set of event notifications matching
some forwarding criteria.
Normally, the set of events from a stream are filtered. Different filter types are used for different stream types.
Cisco IOS XE supports two streams: yang-push and yang-notif-native.

Update Notifications
As part of a subscription, you can specify when data is required. However this is stream-dependent. Some
streams support making data available only when there a change happens, or after an event within the stream.
Other streams make data available when there is a change or at a defined time period.
The result of the when specification is a series of update notifications that carry the telemetry data of interest.
How the data is sent is dependent on the protocol used for the connection between the publisher and the
receiver.

Subscription Identifiers
Subscriptions are identified by a 32-bit positive integer value. The IDs for configured subscriptions is set by
the controller, and for dynamic subscriptions is set by the publisher.
Controllers must limit the values they use for configured subscriptions in the range 0 to 2147483647 to avoid
collisions with the dynamic subscriptions created on the publisher. The dynamic subscription ID space is
global, meaning that the subscription IDs for independently-created dynamic subscriptions do not overlap.

Subscription Management
Any form of management operation can be used to create, delete, and modify configured subscriptions. This
includes both CLIs and network protocol management operations.
All subscriptions, both configured and dynamic, can be displayed using show commands and network protocol
management operations.
The following table describes the supported streams and encodings along with the combinations that are
supported. While streams-as-inputs is intended to be independent of the protocols-as-outputs, not all
combinations are supported.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

286
 Model-Driven Programmability
RPC Support in Telemetry

Table 28: Supported Combination of Protocols

Transport NETCONF gRPC gNMI

Protocol

Dial-In Dial-Out Dial-In Dial-Out Dial-In Dial-Out

Stream

yang-push Yes No No Yes Yes No

yang-notif-native Yes No No Yes No No

Encodings XML No No Key-value JSON_IETF No

Google
Protocol
Buffers
(kvGPB)

RPC Support in Telemetry

You can send and receive YANG XML remote procedure calls (RPCs) in established NETCONF sessions.
The <establish-subscription> and <delete-subscription> RPCs are supported for telemetry.
When an <establish-subscription> RPC is sent, the RPC reply from a publisher contains an <rpc-reply>
message with a <subscription-result> element containing a result string.
The following table displays the response and reason for the response in an <rpc-reply> message:

Result String RPC Cause

ok <establish-subscription> Success
<delete-subscription>

error-no-such-subscription <delete-subscription> The specified subscription does not

exist.

error-no-such-option <establish-subscription> The requested subscription is not

supported.

error-insufficient-resources <establish-subscription> A subscription cannot be created

because of the following reasons:
• There are too many
subscriptions.
• The amount of data requested
is too large.
• The interval for a periodic
subscription is too small.

error-other <establish-subscription> Some other error.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

287
 Model-Driven Programmability
Service gNMI

Service gNMI
The gNMI specification identifies a single top-level service named gNMI that contains high-level RPCs. The
following is a service definition that contains the subscribe service RPC:

service gNMI{
.
.
.
rpc Subscribe(stream SubscribeRequest)
returns (stream SubscribeResponse);

The <subscribe RPC> is used by a management agent to request a dynamic subscription. This RPC contains
a set of messages. The following section describes the messages supported by the <subscribe RPC>

SubscribeRequest Message
This message is sent by a client to request updates from the target for a specified set of paths. The following
is a message definition:

message SubscribeRequest {
oneof request {
SubscriptionList subscribe = 1;
PollRequest poll = 3;
AliasList aliases = 4;
}
Repeated gNMI_ext.Extensions = 5;
}

Note Only request.subscribe is supported.

SubscribeResponse Message
This message is carried from the target to the client over an established <subscribe RPC>. The following is
a message definition:
message SubscribeResponse {
oneof response {
Notification update = 1;
Bool sync_response = 3;
Error error = 4 [deprecated=true];
}
}

Note Only Notification update is supported.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

288
Model-Driven Programmability
Service gNMI

SubscriptionList Message
This message is used to indicate a set of paths for which common subscription behavior are required. Within
the specification of the SubscriptionList message, the client can identify one or more subscriptions to a given
prefix in the model. The following is a SubscriptionList message defintion:
message SubscriptionList {
Path prefix = 1;
repeated Subscription subscription = 2;
bool use_aliases = 3;
QOSMarking qos = 4;
enum Mode {
STREAM = 0;
ONCE = 1;
POLL = 2;
}
Mode mode = 5;
bool allow_aggregation = 6;
repeated ModelData use_models = 7;
Encoding encoding = 8; // only JSON_IETF supported in R16.12
Bool updates_only = 9;

Note Path prefix (only explicit element names), Subscription subscription, Mode mode STREAM, and
Encoding encoding IETF_JSON are supported.

Prefix Message
A valid subscription list may or may not contain a filled in prefix, composed of the shared (across all requested
subscriptions) portion of the xPath.

message Path {
repeated string element = 1; [ deprecated ]
string origin = 2;
repeated PathElem elem = 3;
optional string target = 4;
}

Note Origin (supported values are “” and “openconfig”), elem (supported element name is prefix-free), and
target are supported.

Subscription Message
This message generically describes a set of data that is to be subscribed to by a client. It contains a path,and
attributes used to govern the notification behaviors. The following is a Subscription message definition:

message Subscription {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

289
 Model-Driven Programmability
Service gNMI

Path path = 1;
SubscriptionMode mode = 2;
uint64 sample_interval = 3;
bool suppress_redundant = 4;
uint64 heartbeat_interval = 5;
}

Note Path path, SubscriptionMode mode, Uint64 sample_interval, and Uint64 heartbeat_interval (only if the
value is set to 0) are supported.

Path Message
A valid subscription contains a filled in path, which when added to the prefix associated with the subscription
list constitutes a full qualified path. The following is a Path message definition:

message Path {
repeated string element = 1; [ deprecated ]
string origin = 2;
repeated PathElem elem = 3;
optional string target = 4;
}

Note Origin (supported values are “” and “openconfig”), elem (supported element name is prefix-free), and
target are supported.

SubscriptionMode Message
This message informs the target about how to trigger notifications updates. The following is a SubscriptionMode
message definition:

enum SubscriptionMode {
TARGET_DEFINED = 0;
ON_CHANGE = 1;
SAMPLE = 2;
}

Note Only SAMPLE is supported.

Notifications Message
This message delivers telemetry data from the subscription target to the collector. The following is a
Notifications message definition:

message Notification {

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

290
 Model-Driven Programmability
Dynamic Subscription Management

int64 timestamp = 1;
Path prefix = 2;
string alias = 3;
repeated Update update = 4;
repeated Path delete = 5;
bool atomic = 6;
}

Note Timestamp, prefix, and update are supported.

Dynamic Subscription Management

This section describes how to create and delete dynamic subscriptions.

Creating Dynamic Subscriptions for NETCONF Dial-In

Dynamic subscriptions are created by subscribers who connect to the publisher and call for subscription
creation using a mechanism within that connection, usually, an RPC. The lifetime of the subscription is limited
to the lifetime of the connection between the subscriber and the publisher, and telemetry data is sent only to
that subscriber. These subscriptions do not persist if either the publisher or the subscriber is rebooted. You
can create dynamic subscriptions by using the in-band <establish-subscription> RPC. The
<establish-subscription> RPC is sent from an IETF telemetry subscriber to the network device. The stream,
xpath-filter, and period fields in the RPC are mandatory.
RPCs that are used to create and delete dynamic subscriptions using NETCONF are defined in Custom
Subscription to Event Notifications draft-ietf-netconf-subscribed-notifications-03 and Subscribing to YANG
datastore push updates draft-ietf-netconf-yang-push-07.

Periodic Dynamic Subscriptions

The following is a sample periodic subscription for NETCONF Dial-In:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-event-notifications"
xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<stream>yp:yang-push</stream>
<yp:xpath-filter>/mdt-oper:mdt-oper-data/mdt-subscriptions</yp:xpath-filter>
<yp:period>1000</yp:period>
</establish-subscription>
</rpc>

On-Change Dynamic Subscription

The following is a sample on-change dynamic subscription over NETCONF:

<establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-event-notifications"
xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<stream>yp:yang-push</stream>

<yp:xpath-filter>/cdp-ios-xe-oper:cdp-neighbor-details/cdp-neighbor-detail</yp:xpath-filter>

<yp:dampening-period>0</yp:dampening-period>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

291
 Model-Driven Programmability
Deleting Dynamic Subscriptions

</establish-subscription>

Deleting Dynamic Subscriptions

You can delete dynamic subscriptions by using the in-band <delete subscription> RPC, the clear telemetry
ietf subscription command, and the <kill-subscription> RPC along with disconnecting the transport session.
For gNMI each subscription in the SubscribeRequest.subscribe.subscription a separate dynamic subscription
ID is generated. Killing any of these subscription IDs, either through the <kill-subscription> RPC or clear
CLI, will cause all subscriptions specified in the subscribe request to be killed.
Introduced in Cisco IOS XE Gibraltar 16.10.1, the <delete-subscription> RPC can be issued only by a
subscriber, and it deletes only the subscriptions owned by that subscriber.
In Cisco IOS XE Gibraltar 16.11.1 and later releases, you can use the clear telemetry ietf subscription
command to delete a dynamic subscription. Introduced in Cisco IOS XE Gibraltar 16.11.1, the
<kill-subscription> RPC deletes dynamic subscription, the same way as the clear telemetry ietf subscription
command.
A subscription is also deleted when the parent NETCONF session is torn down or disconnected. If the network
connection is interrupted, it may take some time for the SSH or NETCONF session to timeout, and for
subsequent subscriptions to be removed.
The <kill-subscription> RPC is similar to the <delete-subscription> RPC. However, the <kill-subscription>
RPC uses the identifier element that contains the ID of the subscription to be deleted, instead of the
subscription-id element. The transport session used by the target subscription also differs from the one used
by the <delete-subscription> RPC.

Deleting Subscriptions Using the CLI

The following sample output shows all the available subscriptions:
Device# show telemetry ietf subscription all

Telemetry subscription brief

ID Type State Filter type

--------------------------------------------------------
2147483648 Dynamic Valid xpath
2147483649 Dynamic Valid xpath

The following example shows how to delete a dynamic subscription:

Device# clear telemetry ietf subscription 2147483648

Deleting Subscriptions Using NETCONF <delete-Subscription> RPC

The following example shows how to delete a subscription using NETCONF:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

<delete-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-event-notifications"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-id>2147483650</subscription-id>
</delete-subscription>
</rpc>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

292
Model-Driven Programmability
Deleting Dynamic Subscriptions

Deleting Subscriptions Using NETCONF <kill-Subscription> RPC

The following examples show how to delete subscriptions using the <kill-subscription> RPC:

<get>
<filter>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions/>
</mdt-oper-data>
</filter>
</get>

* Enter a NETCONF operation, end with an empty line

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<data>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions>
<subscription-id>2147483652</subscription-id>
<base>
…
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>
<comments/>
<mdt-receivers>
…
</mdt-receivers>
<last-state-change-time>2018-12-13T21:16:48.848241+00:00</last-state-change-time>
</mdt-subscriptions>
<mdt-subscriptions>
<subscription-id>2147483653</subscription-id>
<base>
…
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>
<comments/>
<mdt-receivers>
…
</mdt-receivers>
<last-state-change-time>2018-12-13T21:16:51.319279+00:00</last-state-change-time>
</mdt-subscriptions>
<mdt-subscriptions>
<subscription-id>2147483654</subscription-id>
<base>
…
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>
<comments/>
<mdt-receivers>
…
</mdt-receivers>
<last-state-change-time>2018-12-13T21:16:55.302809+00:00</last-state-change-time>
</mdt-subscriptions>
<mdt-subscriptions>
<subscription-id>2147483655</subscription-id>
<base>
…
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

293
 Model-Driven Programmability
Deleting Dynamic Subscriptions

<comments/>
<mdt-receivers>
…
</mdt-receivers>
<last-state-change-time>2018-12-13T21:16:57.440936+00:00</last-state-change-time>
</mdt-subscriptions>
</mdt-oper-data>
</data>
</rpc-reply>
<kill-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-event-notifications"
xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<identifier>2147483653</identifier>
</kill-subscription>

* Enter a NETCONF operation, end with an empty line

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<subscription-result xmlns="urn:ietf:params:xml:ns:yang:ietf-event-notifications"

xmlns:notif-bis="urn:ietf:params:xml:ns:yang:ietf-event-notifications">notif-bis:ok</subscription-result>
</rpc-reply>
<get>
<filter>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions/>
</mdt-oper-data>
</filter>
</get>

* Enter a NETCONF operation, end with an empty line

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<data>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions>
<subscription-id>2147483652</subscription-id>
<base>
…
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>
<comments/>
<mdt-receivers>
…
</mdt-receivers>
<last-state-change-time>2018-12-13T21:16:48.848241+00:00</last-state-change-time>
</mdt-subscriptions>
<mdt-subscriptions>
<subscription-id>2147483654</subscription-id>
<base>
…
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>
<comments/>
<mdt-receivers>
…
</mdt-receivers>
<last-state-change-time>2018-12-13T21:16:55.302809+00:00</last-state-change-time>
</mdt-subscriptions>
<mdt-subscriptions>
<subscription-id>2147483655</subscription-id>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

294
 Model-Driven Programmability
Configured Subscription Management

<base>
…
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>
<comments/>
<mdt-receivers>
…
</mdt-receivers>
<last-state-change-time>2018-12-13T21:16:57.440936+00:00</last-state-change-time>
</mdt-subscriptions>
</mdt-oper-data>
</data>
</rpc-reply>

Configured Subscription Management

This section describes how to create, modifiy, and delete configured subscriptions.

Creating Configured Subscriptions

Configured subscriptions are created by management operations on the publisher by controllers, and explicitly
include the specification of the receiver of the telemetry data defined by a subscription. These subscriptions
persist across reboots of the publisher.
Configured subscriptions can be configured with multiple receivers, however; only the first valid receiver is
used. Connection to other receivers is not attempted, if a receiver is already connected, or is in the process of
being connected. If that receiver is deleted, another receiver is connected.
Configured dial-out subscriptions are configured on the device by the following methods:
• Using configuration CLIs to change to device configuration through console/VTY.
• Using NETCONF/RESTCONF to configure the desired subscription.

This section displays sample RPCs to create configured subscriptions.

Periodic Subscription
The following example shows how to configure gRPC as the transport protocol for configured subscriptions
using the CLI:

telemetry ietf subscription 101

encoding encode-kvgpb
filter xpath /memory-ios-xe-oper:memory-statistics/memory-statistic
stream yang-push
update-policy periodic 6000
source-vrf Mgmt-intf
receiver ip address 10.28.35.45 57555 protocol grpc-tcp

The following sample RPC shows how to create a periodic subscription using NETCONF that sends telemetry
updates to the receiver every 60 seconds:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><edit-config>
<target>
<running/>
</target>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<mdt-config-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-cfg">

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

295
 Model-Driven Programmability
Creating Configured Subscriptions

<mdt-subscription>
<subscription-id>200</subscription-id>
<base>
<stream>yang-push</stream>
<encoding>encode-kvgpb</encoding>
<period>6000</period>
<xpath>/memory-ios-xe-oper:memory-statistics/memory-statistic</xpath>
</base>
<mdt-receivers>
<address>10.22.23.48</address>
<port>57555</port>
<protocol>grpc-tcp</protocol>
</mdt-receivers>
</mdt-subscription>
</mdt-config-data>
</config>
</edit-config>
</rpc>

The following sample RPC creates a periodic subscription using RESTCONF:

URI:https://10.85.116.28:443/restconf/data/Cisco-IOS-XE-mdt-cfg:mdt-config-data
Headers:
application/yang-data.collection+json, application/yang-data+json,
application/yang-data.errors+json
Content-Type:
application/yang-data+json
BODY:
{
"mdt-config-data": {
"mdt-subscription":[
{
"subscription-id": "102",
"base": {
"stream": "yang-push",
"encoding": "encode-kvgpb",
"period": "6000",
"xpath": "/memory-ios-xe-oper:memory-statistics/memory-statistic"
}
"mdt-receivers": {
"address": "10.22.23.48"
"port": "57555"
}
}
]
}
}

On-Change Subscription
The following sample RPC shows how to create an on-change subscription using NETCONF that sends
updates only when there is a change in the target database:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><edit-config>
<target>
<running/>
</target>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<mdt-config-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-cfg">
<mdt-subscription>
<subscription-id>200</subscription-id>
<base>
<stream>yang-push</stream>
<encoding>encode-kvgpb</encoding>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

296
Model-Driven Programmability
Creating Configured Subscriptions

<no-synch-on-start>false</no-synch-on-start>
<xpath>/cdp-ios-xe-oper:cdp-neighbor-details/cdp-neighbor-detail</xpath>
</base>
<mdt-receivers>
<address>10.22.23.48</address>
<port>57555</port>
<protocol>grpc-tcp</protocol>
</mdt-receivers>
</mdt-subscription>
</mdt-config-data>
</config>
</edit-config>
</rpc>

The following sample RPC shows how to create an on-change subscription using RESTCONF:
URI:
https://10.85.116.28:443/restconf/data/Cisco-IOS-XE-mdt-cfg:mdt-config-data
Headers:
application/yang-data.collection+json, application/yang-data+json,
application/yang-data.errors+json
Content-Type:
application/yang-data+json
BODY:
{
"mdt-config-data": {
"mdt-subscription":[
{
"subscription-id": "102",
"base": {
"stream": "yang-push",
"encoding": "encode-kvgpb",
"dampening period": "0",
"xpath": "/cdp-ios-xe-oper:cdp-neighbor-details/cdp
-neighbor-detail "
}
"mdt-receivers": {
"address": "10.22.23.48"
"port": "57555"
}
}
]
}
}

gNMI Dial-In Subscription

The following is a sample gNMI dial-in subscription:

subscribe: <
prefix: <>
subscription: <
path: <
origin: "openconfig"
elem: <name: "routing-policy">
>
mode: SAMPLE
sample_interval: 10000000000
>
mode: STREAM
encoding: JSON_IETF
>'

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

297
 Model-Driven Programmability
Modifying Configured Subscriptions

subscribe: <
prefix: <>
subscription: <
path: <
origin: "legacy"
elem: <name: "oc-platform:components">
elem: <
name: "component"
key: <
key: "name"
value: "PowerSupply8/A"
>
>
elem: <name: "power-supply">
elem: <name: "state">
>
mode: SAMPLE
sample_interval: 10000000000
>
mode: STREAM
encoding: JSON_IETF
>'

Modifying Configured Subscriptions

There are two ways to modify configured subscriptions:
• Management protocol configuration operations, such as NETCONF <edit-config> RPC
• CLI (same process as creating a subscription)

Subscription receivers are identified by the address and port number. Receivers cannot be modified. To change
the characteristics (protocol, profile, and so on) of a receiver, it must be deleted first and a new receiver created.
If a valid receiver configuration on a valid subscription is in the disconnected state, and the management wants
to force a new attempt at setting up the connection to the receiver, it must rewrite the receiver with the exact
same characteristics.

Deleting Configured Subscriptions

You can use the CLI or management operation to delete configured subscriptions. The no telemetry ietf
subscription command removes the configured subscriptions. Note that configured subscriptions cannot be
deleted using RPCs, only through the configuration interface.

Deleting Subscriptions Using the CLI

Device# configure terminal
Device(config)# no telemetry ietf subscription 101
Device(config)# end

Deleting Subscriptions Using NETCONF

The following sample RPC shows how to delete a configured subscription:

<edit-config>
<target>
<running/>
</target>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

298
 Model-Driven Programmability
FQDN Support for gRPC Subscriptions

<config>
<mdt-config-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-cfg">
<mdt-subscription operation="delete">
<subscription-id>102</subscription-id>
</mdt-subscription>
</mdt-config-data>
</config>
</edit-config>

FQDN Support for gRPC Subscriptions

gRPC telemetry subscriptions are configuration-based, which means that users must specify the receiving
host and other subscription parameters as part of the device configuration. This receiver configuration is used
to determine the connection details for sending telemetry updates. With the introduction of the FQDN Support
for gRPC Subscriptions feature, along with IP addresses, Fully Qualified Domain Names (FQDNs) can also
be used for gRPC subscriptions.
In a telemetry subscription, receiver details can now be specified either as part of the subscription, or they
can be configured independently; where the receiver has a name and this name is used to specify the receiver
when configuring the subscription. In both the cases, it is possible to specify the same receiver name for
multiple subscriptions.
This feature cannot be disabled.

Named Receivers
With FQDN support, a new method of configuring receivers is introduced, called the named-receiver
configuration. Named receivers are top-level configuration entities that can exist independent of subscriptions.
Named receivers are identified by a name. The name is an arbitrary string, and is the index or key of the named
receiver records in the system. The named receiver configuration contains all configurations associated with
the receiver that is not subscription-dependent.
The advantages of using named receivers are as follows:
• Capable of supporting different types of receivers.
• Better state and diagnostics information.
• Hostname can be used instead of an IP address to specify the host for protocol receivers.
• Parameters of a receiver that is used by multiple subscriptions can be changed at a single place.

Only protocol-type named receivers are supported, and these are:

• cloud-native: Cloud native protocol
• cntp-tcp: Civil Network Time Protocol (CNTP) TCP protocol
• cntp-tls: CNTP TLS protocol
• grpc-tcp: gRPC TCP protocol
• grpc-tls: gRPC TLS protocol
• native: Native protocol
• tls-native: Native TLS protocol

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

299
 Model-Driven Programmability
Named Protocol Receivers

Named Protocol Receivers

Named protocol receivers are used to specify telemetry transports that use protocols. In addition to the name
that identifies a receiver, named protocol receivers also use a host specification. The host specification takes
a hostname or IP address, and a destination port number. Secure protocol transports also use a profile string.

Note When a valid named protocol receiver is created, it is not automatically connected to the receiver. The
named protocol receiver must be requested by at least one subscription to create a connection to the
receiver.

You can configure a named protocol receiver by using the CLI or YANG models.

Configuring the Named Protocol Receiver Using YANG Models

The YANG model, Cisco-IOS-XE-mdt-cfg, contains the named protocol receiver. The container
mdt-named-protocol-rcvrs inside the top level mdt-config-data container has a list of mdt-named-protocol-rcvr
structures. This group has five members:
• Name, which is the index in the list
• Protocol
• Profile
• Hostname
• Port number

The following is a sample NETCONF RPC that shows how to create a named protocol receiver:

<edit-config>
<target>
<running/>
</target>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<mdt-config-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-cfg">
<mdt-named-protocol-rcvrs>
<mdt-named-protocol-rcvr>
<name>receiver1</name>
<protocol>tls-native</protocol>
<profile>tls-trustpoint</profile>
<host>
<hostname>rcvr.test.com</hostname>
</host>
<port>45000</port>
</mdt-named-protocol-rcvr>
</mdt-named-protocol-rcvrs>
</mdt-config-data>
</config>
</edit-config>

Subscription Configuration Using Named Receivers

To use a named receiver with a subscription, both the receiver type and receiver name must be specified. No
additional receiver configuration is required, since all receiver-specific configuration is part of the named

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

300
 Model-Driven Programmability
Configuring a Named-Receiver Subscription Configuration Using YANG Model

receiver configuration. However; named protocol receivers still use the source VRF and source address of
the subscriptions as part of the connection resolution process.
The only supported name receiver type is protocol.
Subscriptions can use either named receivers or legacy receivers, but cannot use both. If the legacy receiver
is configured, setting the subscription receiver type and a named-receiver name is blocked. Similarly, if a
subscription receiver type or a named receiver is specified, you cannot configure legacy receivers.
Note that subscriptions use only one receiver, even if more than one receiver is configured.
Subscriptions using legacy receivers and subscriptions using named receivers are permitted to use the same
connection; however, it is not recommended.

Configuring a Named-Receiver Subscription Configuration Using YANG Model

The only value supported for rcvr-type is rcvr-type-protocol, when named receivers are used. When legacy
receivers are used, the value is the default rcvr-type-unspecified.
The following is a sample NETCONF RPC that shows how to create a subscription using a named
protocol-receiver:

<edit-config>
<target>
<running/>
</target>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<mdt-config-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-cfg">
<mdt-subscription>
<subscription-id>1</subscription-id>
<base>
<rcvr-type>rcvr-type-protocol</rcvr-type>
</base>
<mdt-receiver-names>
<mdt-receiver-name>
<name>receiver1</name>
</mdt-receiver-name>
</mdt-receiver-names>
</mdt-subscription>
</mdt-config-data>
</config>
</edit-config>

Named Receiver Operation and Operational State

Named receiver objects and subscription receiver objects (that refer to the named receiver) have two different
operational states. The operational states are valid or invalid. The most common reason for a named receiver
to be invalid is incomplete configuration, however; it could also be due to other reasons. The operational state
view of a named receiver has a field that provides a text explanation on why the receiver is invalid. When the
receiver state is valid, this field is empty.

Displaying Named Receiver State Using the CLI

To view the state of named receivers of all types, use the show telemetry receiver command. The all keyword
displays information about all named receivers in a brief format, and the name keyword displays detailed
information about the specified named receiver.
The following is sample output from the show telemetry receiver all command:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

301
 Model-Driven Programmability
Named Receiver State Using YANG Models

Device# show telemetry receiver all

Telemetry receivers

Name <…> Type Profile State Explanation

-----------<…>---------------------------------------------------------------------
receiver1 <…> protocol tls-trustpoint Valid

The following is sample output from the show telemetry receiver name command:

Device# show telemetry receiver name receiver1

Name: receiver1
Profile: tls-trustpoint
State: Valid
Last State Change: 08/12/20 19:55:54
Explanation:
Type: protocol
Protocol: tls-native
Host: rcvr.test.com
Port: 45000

Named Receiver State Using YANG Models

The state of the named receivers can be retrieved using the Cisco-IOS-XE-mdt-oper-v2 YANG model. The
mdt-oper-v2-data container contains an mdt-named-receivers list that contains the operational state of all
named receivers.
The following is a sample NETCONF reply to retrieve the state of named receivers:

<get>
<filter>
<mdt-oper-v2-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper-v2">
<mdt-named-receivers/>
</mdt-oper-v2-data>
</filter>
</get>

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<data>
<mdt-oper-v2-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper-v2">
<mdt-named-receivers>
<name>receiver1</name>
<profile>tls-trustpoint</profile>
<params>
<protocol>tls-native</protocol>
<host>
<hostname>rcvr.test.com </hostname>
</host>
<port>45000</port>
</params>
<state>named-rcvr-state-valid</state>
<last-state-change-time>2020-…:00</last-state-change-time>
</mdt-named-receivers>
</mdt-oper-v2-data>
</data>
</rpc-reply>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

302
 Model-Driven Programmability
Subscription Receiver Operation and Operational States

Subscription Receiver Operation and Operational States

Subscription receivers are the subscription-related objects that connects to the actual subscription receiver or
collector. While the mechanism needed to reach the collector is specific to the receiver type, a connection is
the entity that is used to allow the subscription to reach its receiver or collector.
Subscription receiver state is based on its ability to request and use the connection to the receiver and has a
number of states that are associated with the control of other resources required to allow the subscription to
send updates to the receiver or collector.

Subscription Receiver States

The operational state of a subscription receiver consists of the configured name (that is the index of the
connection), the state of the receiver, an explanation or note about the state, and the time of the last state
change. The explanation string is not always used.
The possible states of a subscription receiver are shown in the table below.

Table 29: Subscription Receiver States

Subscription Receiver State Description

CLI Value YANG Value

Disconnected rcvr-state-disconnected The receiver is disconnected and

no attempt is made to reconnect it.

Resolving rcvr-state-resolving Resolving the connection

parameters required to reach the
receiver.

Transport requested rcvr-state-transport-requested A request for a connection to reach

the receiver was using the
connection parameters determined
from the resolving state.

Connecting rcvr-state-connecting Resources needed to connect the

subscription to the receiver are
being allocated.

Connected rcvr-state-connected The subscription is connected to the

receiver, and updates can flow to
the receiver.

Disconnecting rcvr-state-disconnecting Resources used on the connection

are being re-allocated.

The YANG value rcvr-state-invalid is used only by legacy receivers. Subscription receivers that are invalid
cannot be connected, so the subscription receiver state is set to disconnected when it is invalid. The explanation
string provides the distinction between invalid subscription receivers and disconnected subscription receivers.
A subscription receiver may be disconnected due to the following reasons:
• Another receiver on the subscription is not disconnected.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

303
 Model-Driven Programmability
Subscription Receiver Connections

• Connection setup failed permanently.

• Named receiver does not exist.
• Named receiver is not the type specified in the subscription.
• Named receiver is not valid.
• Subscription is invalid.
• The requested connection is in use by a different receiver.

Subscription Receiver Connections

This section provides information on how subscription receivers use connections.

Telemetry Connections
Telemetry connections represent the transport instances used by subscriptions to reach the receivers and are
purely operational. Telemetry connections are identified by an integer index value. Other information about
the connections is specific to the type of connection, which is based on the type of receiver that the subscription
is configured to use.
For the secure Cisco proprietary transports, the host part of the configured named receiver must match the
distinguished name (DN) of the certificate provided by the receiver, when the connection is set up. For this
reason, it is not permitted to have more than one receiver using the same connection.
While all the states discussed in this section are available to all types of connections, not all have to be used.

Table 30: Telemetry Connection States

Connection State Description

CLI Value YANG Value

Pending con-state-pending The connection has been created,

but not yet initiated.

Connecting con-state-connecting A request to set up the connection

is in progress.

Active con-state-active The connection is up and is

available for use by subscription
receivers.

Disconnecting con-state -disconnecting The connection has been torn down

and is waiting to be released by
subscription receivers.

Additional operational state associated with a connection includes the identity of the remote receiver (the
peer, when available), and the time of the last state change.

Telemetry Protocol Connections

This section discusses protocol type connections and how these are used by subscription receivers that are
assigned to named protocol receivers.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

304
Model-Driven Programmability
Telemetry Protocol Connections

Table 31: Parameters of a Protocol-Type Connection

Parameter Origin Comments

Destination IP address Named receiver host Because hosts use domain names,
domain name resolution may be
required.

Destination port number Named receiver port Must be explicitly configured.

Source VRF Subscription, if specified Default VRF is used, if not

specified. Otherwise the VRF name
is resolved to an internal identifier.

Source IP address Subscription, if specified If not specified, the source IP

address is determined based on the
VRF and destination IP address.

Some of these parameters are based on the configuration of the subscription receiver’s parent subscription.
When resolving the connection parameters from the configuration, the VRF is determined first, followed by
the destination IP address, and finally the source IP address, if an order is not specified. If a given step in the
resolution fails non-permanently, there are infinite retries at 5 second intervals.
A connection is instantiated as soon as it is requested. That is, as soon as the first subscription receiver goes
from the resolving state to the transport requested state, a connection instance with the parameters that were
resolved by the subscription receiver is created.
If the requested connection is successfully setup and used by telemetry, the connection state changes to
connected, which means that a connection exists between the Cisco IOS XE device and the receiver device.
To reallocate the resources used by the receiver, the subscription receivers that want to use the resources are
informed that the connection is set up. These subscription receivers then transition to the connecting state to
set up the resources required to connect the subscription to the receiver. Once these resources are in place,
the subscription receiver’s state changes to connected, and update notifications are received by the receiver.
The following are some of the reasons why a telemetry connection cannot become active:
• Destination unreachable.
• No listener at the remote host port.
• Listener at the remote host port is of the wrong type.
• Authentication failures.

Note When a connection setup is in progress, any subscription receiver using this connection is in the
connecting state because it has successfully resolved the parameters needed to initiate the connection
setup.

The action taken when a connection setup fails is specific to the protocol. The following table shows the retry
behaviors for connections within a single setup request and for re-resolution requests when the connection
setup request fails. This behavior is the same for connections requested by the legacy receivers as well.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

305
 Model-Driven Programmability
Troubleshooting Named Receiver Connections

Table 32: Protocol-Specific Retry Intervals

Protocol Connection Retries Re-resolution Requests

• grpc-tcp 5 retries at 1, 3, 4, and 7 seconds in No limit; continuously requests

between them re-resolution when connection
• grpc-tls retries fail. (14 seconds per try.)

• cloud-native 5, 10, 15, 20, 25, and 30 seconds.

• cntp-tcp
• cntp-tls
• native
• tls-native

Troubleshooting Named Receiver Connections

When a subscription is set up, one of the common problems is that no telemetry update messages are received.
Possible reasons could be that there are no events to send, or the subscription is not valid. This section describes
how to troubleshoot some of the common problems that occur in named receiver connections.
The logs from the telemetry process, and the output of some of the show commands provide information that
can be used for troubleshooting the named receiver configuration.

Table 33: Troubleshooting Named Receiver Connections

Problem How to Check/Symptom What to Do

Subscription is not valid. show telemetry ietf subscription Fix the subscription configuration.
id details

Subscription receiver is not valid. show telemetry ietf subscription Fix the named receiver
id receiver configuration.

Subscription receiver’s connection show telemetry ietf subscription Verify the receiver, the network
parameters cannot be resolved. id receiver configuration, or the interface state.
Subscription receiver state appears
to never leave the resolving state.

Subscription receiver connection show telemetry ietf subscription Verify that the resolved connection
does not come up. id receiver is valid, and the receiver or
collector is reachable and able to
Subscription receiver state
accept inbound connections using
constantly changes from resolving
the specified transport.
to connecting.

Subscription receiver connections show telemetry ietf subscription Verify that the collector is of the
are rejected. id receiver correct type, and that the configured
authentication and authorization is
Subscription receiver state
valid.
constantly changes through all
states except disconnected.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

306
 Model-Driven Programmability
Displaying On-Change Subscription YANG Models

Problem How to Check/Symptom What to Do

Subscription receiver is connected, show telemetry internal Verify that the collector is able to
but no updates are received. subscription id stats keep up with the flow of update
notifications.
Message drop count is
incrementing, but the records sent
is not.

Subscription receiver is connected, show telemetry internal If the subscription is on-change,

but no updates are received. subscription ensure that there really have been
no events.
No change in the count.
If the subscription is periodic,
ensure that the update period is
small, that the time is specified in
hundredths of a second.

show telemetry internal connection: This command takes an optional connection index value. When no
index is specified, it displays the basic connection parameter information for all connections that are being
used. When a connection index is specified in the command, it shows low-level details about the connection.
The command output is transport-specific, and might not be available for all transports. The output from this
command is subject to change.
show telemetry internal diagnostics: This command attempts to dump all telemetry logs and operational
state. When reporting problems, it may be helpful to use this command as close to the problem time as possible
and provide the output of the show running-config | section telemetry command as well.

Displaying On-Change Subscription YANG Models

To display the list of YANG models that support on-change subscriptions, use the show platform software
ndbman switch {switch-number | active | standby} models command.

Note On Cisco Catalyst 9800-80 Wireless Controllers, use the show platform software ndbman chassis
{number | active | standby} models commands.

The Cisco-IOS-XE-mdt-capabilities-oper.YANG model also displays the models supported for on-change
subscriptions.

Subscription Monitoring
Subscriptions of all types can be monitored by using CLIs and management protocol operations.

CLI
Use the show telemetry ietf subscription command to display information about telemetry subscriptions.
The following is sample output from the command:
Device# show telemetry ietf subscription 2147483667 detail

Telemetry subscription detail:

Subscription ID: 2147483667

State: Valid

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

307
 Model-Driven Programmability
Subscription Monitoring

Stream: yang-push
Encoding: encode-xml
Filter:
Filter type: xpath
XPath: /mdt-oper:mdt-oper-data/mdt-subscriptions
Update policy:
Update Trigger: periodic
Period: 1000
Notes:

NETCONF
The following is a sample NETCONF message that displays information about telemetry subscriptions:
<get>
<filter>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions/>
</mdt-oper-data>
</filter>
</get>

* Enter a NETCONF operation, end with an empty line

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<data>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions>
<subscription-id>101</subscription-id>
<base>
<stream>yang-push</stream>
<encoding>encode-kvgpb</encoding>
<source-vrf>RED</source-vrf>
<period>10000</period>
<xpath>/ios:native/interface/Loopback[name="1"]</xpath>
</base>
<type>sub-type-static</type>
<state>sub-state-valid</state>
<comments/>
<mdt-receivers>
<address>5.22.22.45</address>
<port>57500</port>
<protocol>grpc-tcp</protocol>
<state>rcvr-state-connecting</state>
<comments/>
<profile/>
<last-state-change-time>1970-01-01T00:00:00+00:00</last-state-change-time>
</mdt-receivers>
<last-state-change-time>1970-01-01T00:00:00+00:00</last-state-change-time>
</mdt-subscriptions>
<mdt-subscriptions>
<subscription-id>2147483648</subscription-id>
<base>
<stream>yang-push</stream>
<encoding>encode-xml</encoding>
<source-vrf/>
<period>1000</period>
<xpath>/if:interfaces-state/interface[name="GigabitEthernet0/0"]/oper-status</xpath>

</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

308
 Model-Driven Programmability
Streams

<comments/>
<mdt-receivers>
<address>5.22.22.45</address>
<port>51259</port>
<protocol>netconf</protocol>
<state>rcvr-state-connected</state>
<comments/>
<profile/>
<last-state-change-time>1970-01-01T00:00:00+00:00</last-state-change-time>
</mdt-receivers>
<last-state-change-time>1970-01-01T00:00:00+00:00</last-state-change-time>
</mdt-subscriptions>
</mdt-oper-data>
</data>
</rpc-reply>

Streams
A stream defines a set of events that can be subscribed to, and this set of events can be almost anything.
However, as per the definition of each stream, all possible events are related in some way. This section
describes the supported streams.
To view the set of streams that are supported, use management protocol operations to retrieve the streams
table from the Cisco-IOS-XE-mdt-oper module (from the YANG model Cisco-IOS-XE-mdt-oper.yang) in
the mdt-streams container.
The following example shows how to use NETCONF to retrieve supported streams:
<get>
<filter>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-streams/>
</mdt-oper-data>
</filter>
</get>

* Enter a NETCONF operation, end with an empty line

<?xml version="1.0" encoding="UTF-8"?>

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<data>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-streams>
<stream>native</stream>
<stream>yang-notif-native</stream>
<stream>yang-push</stream>
</mdt-streams>
</mdt-oper-data>
</data>
</rpc-reply>

The example shows that three streams are supported: native, yang-notif-native, and yang-push. The stream
native is not available for general use and can be ignored.

Note Currently there are no CLIs to return the list of supported streams.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

309
 Model-Driven Programmability
The yang-push Stream

The yang-push Stream

The yang-push stream is the data in configuration and operational databases that is described by a supported
YANG model. This stream supports an XPath filter to specify what data is of interest within the stream, and
where the XPath expression is based on the YANG model that defines the data of interest.
Update notifications for this stream can be sent either when data changes or during fixed periods, but not for
both, for a given subscription. Subscriptions for data that does not currently exist are permitted, and these run
as normal subscriptions.
The only target database that is supported is running.

Determining On-Change Capability

Currently, there is no indication within YANG models about the type of data that can be subscribed to, by
using an on-change subscription. Attempts to subscribe to data that cannot be subscribed to by using on-change
subscription results in a failure (dynamic) or an invalid subscription (configured). For more information on
On-Change Publication, see the section, On-Change Publication for yang-push.

IETF Draft Compliance

Telemetry using the yang-push stream is based on the IETF NETCONF working group's early drafts for
telemetry. These are:
• Custom Subscription to Event Notifications, Version 03
• Subscribing to YANG datastore push updates, Version 07

Note The following features that are described in the corresponding drafts are not supported:

• Subtree filters
• Out-of-band notifications
• Any subscription parameter not explicitly stated as supported

X-Path Filter for yang-push

The dataset within the yang-push stream to be subscribed to should be specified by the use of an XPath filter.
The following guidelines apply to the XPath expression:
• XPath expressions can have keys to specify a single entry in a list or container. The supported key
specification syntax is
[{key name}={key value}]

The following is an example of an XPath expression:

filter xpath
/rt:routing-state/routing-instance[name="default"]/ribs/rib[name="ipv4-default"]/routes/route

# VALID!

Compound keys are supported by the use of multiple key specifications. Key names and values must be
exact; no ranges or wildcard values are supported.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

310
 Model-Driven Programmability
XPath Expressions Supported on Cisco Catalyst 9800 Wireless Controllers

• In XPath expressions, select multiple keys using [] between the keys, and encapsulate the string with “.
The following is an example of an XPath expression:
filter xpath
/environment-ios-xe-oper:environment-sensors/environment-sensor[location=\"Switch\ 1\"]
[name=\"Inlet\ Temp\ Sens\"]/current-reading

XPath Expressions Supported on Cisco Catalyst 9800 Wireless Controllers

In Cisco IOS XE Bengaluru, 17.4.1, the following set of OpenConfig XPath expressions are supported on the
Cisco Catalyst 9800 Series Wireless Controllers.
Ensure that you run the following RPC using any of the programmability interfaces, such as NETCONF,
RESTCONF, or gNMI protocol, to enable telemetry subscription:
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
<edit-config>
<target>
<running/>
</target>
<config>
<provision-aps xmlns="http://openconfig.net/yang/wifi/ap-manager">
<provision-ap>
<mac>eth_mac_of_the_AP</mac>
<config>
<mac>eth_mac_of_the_AP</mac>
<hostname>AP_NAME</hostname>
</config>
</provision-ap>
</provision-aps>
</config>
</edit-config>
</rpc>

All of the XPath expressions listed below are a part of the openconfig-access-points YANG model, except
the last one, which is a part of the openconfig-ap-manager YANG model. For the telemetry operation to work
correctly, ensure that configurations are done based on the OpenConfig model.
• /access-points/access-point/radios/radio/state
• /access-points/access-point/radios/radio/neighbors/neighbor
• /access-points/access-point/radios/radio/neighbors/neighbor/state
• /access-points/access-point/ssids/ssid/bssids/bssid/state/counters
• /access-points/access-point/ssids/ssid/clients/client/state/counters
• /access-points/access-point/ssids/ssid/clients/client/client-rf/state
• /access-points/access-point/ssids/ssid/clients/client/client-connection/state
• /access-points/access-point/system/aaa/server-groups/server-group/servers/server/radius/state
• /joined-aps/joined-ap/state/opstate

When you subscribe to an XPath, you receive data for the subscribed XPath and all the XPaths under it in the
hierarchy. For example, subscribing to /access-points/access-point/radios/radio/state delivers data for all the
leaves associated with it, as well as the subcontainers under it.
If you require only a subset of information, set filters in the XPath expressions to limit the updates. To filter
the data of a specific access point (AP), use a key after the node. For example, to receive data for an AP with

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

311
 Model-Driven Programmability
XPath Expressions Supported on Cisco Catalyst 9800 Wireless Controllers

hostname ‘my_hostname’, use the subscription XPath: access-point[hostname=’my_hostname’]. Note that

the data updates will contain data objects from all the leaves, and not just from the limited subset that is
defined.

Scale Information
The following tables show the minimum recommended intervals for each of the gathering points under three
different scale scenarios.
Scenario1: Full Scale with four SSIDs

Table 34: Setup

APs 2,000

Clients 30,000

SSIDs per AP 4

BSSIDs per AP 8

Physical neighbors per 12

AP

Neighbors per AP 96

Table 35: Recommended Intervals

Gathering Point Records Recommended Interval Recommended Interval

(Seconds) (Seconds)
One Collector Two Collectors

Joined 2000 30 60

AAA 2000 30 60

Radio 4000 30 60

Client RF 30,000 30 60

Client CNTR 30,000 30 60

Client CONN 30,000 60 120

BSSID 16,000 90 180

Neighbor 192,000 180 360

Scenario2: Full Scale with six SSIDs

Table 36: Setup

APs 2,000

Clients 30,000

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

312
Model-Driven Programmability
XPath Expressions Supported on Cisco Catalyst 9800 Wireless Controllers

SSIDs per AP 6

BSSIDs per AP 12

Physical neighbors per 12

AP

Neighbors per AP 144

Table 37: Recommended Intervals

Gathering Records Recommended Interval (Seconds) Recommended Interval (Seconds)

point
One Collector Two Collectors

Joined 2000 30 60

AAA 2000 30 60

Radio 4000 30 60

Client RF 30,000 30 60

Client CNTR 30,000 30 60

Client CONN 30,000 60 120

BSSID 24,000 120 240

Neighbor 288,000 240 420

Scenario3: Reduced Scale with six SSIDs

Table 38: Setup

APs 1,000

Clients 15,000

SSIDs per AP 6

BSSIDs per AP 12

Physical neighbors per 12

AP

Neighbors per AP 144

Table 39: Recommended Intervals

Gathering Records Recommended Interval (Seconds) Recommended Interval (Seconds)

Point
One Collector Two Collectors

Joined 1000 NA 30

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

313
 Model-Driven Programmability
XPath Values and Corresponding Rates on Cisco Catalyst 9800 Wireless Controllers

Gathering Records Recommended Interval (Seconds) Recommended Interval (Seconds)

Point
One Collector Two Collectors

AAA 1000 NA 30

Radio 2000 NA 30

Client RF 15,000 NA 30

Client CNTR 15,000 NA 30

Client CONN 15,000 NA 30

BSSID 12,000 NA 120

Neighbor 144,000 NA 180

XPath Values and Corresponding Rates on Cisco Catalyst 9800 Wireless Controllers
In the Cisco-IOS-XE-wireless-mesh-rpc, following are the permitted values and corresponding rates for XPath
/exec-linktest-ap/data-rate-idx:

ewlc-mesh-linktest-rate-idx-1 1 Mbps
ewlc-mesh-linktest-rate-idx-2 2 Mbps
ewlc-mesh-linktest-rate-idx-3 5 Mbps
ewlc-mesh-linktest-rate-idx-4 6 Mbps
ewlc-mesh-linktest-rate-idx-5 9 Mbps
ewlc-mesh-linktest-rate-idx-6 11 Mbps
ewlc-mesh-linktest-rate-idx-7 12 Mbps
ewlc-mesh-linktest-rate-idx-8 18 Mbps
ewlc-mesh-linktest-rate-idx-9 24 Mbps
ewlc-mesh-linktest-rate-idx-10 36 Mbps
ewlc-mesh-linktest-rate-idx-11 48 Mbps
ewlc-mesh-linktest-rate-idx-12 54 Mbps
ewlc-mesh-linktest-rate-idx-13 108 Mbps
ewlc-mesh-linktest-rate-idx-14 m0
ewlc-mesh-linktest-rate-idx-15 m1
ewlc-mesh-linktest-rate-idx-16 m2
ewlc-mesh-linktest-rate-idx-17 m3
ewlc-mesh-linktest-rate-idx-18 m4
ewlc-mesh-linktest-rate-idx-19 m5
ewlc-mesh-linktest-rate-idx-20 m6
ewlc-mesh-linktest-rate-idx-21 m7
ewlc-mesh-linktest-rate-idx-22 m8
ewlc-mesh-linktest-rate-idx-23 m9
ewlc-mesh-linktest-rate-idx-24 m10
ewlc-mesh-linktest-rate-idx-25 m11
ewlc-mesh-linktest-rate-idx-26 m12
ewlc-mesh-linktest-rate-idx-27 m13
ewlc-mesh-linktest-rate-idx-28 m14
ewlc-mesh-linktest-rate-idx-295 m15

Periodic Publication for yang-push

With periodic subscriptions, the first push-update with the subscribed information is sent immediately; but it
can be delayed if the device is busy or due to network congestion. Updates are then sent at the expiry of the
configured periodic timer. For example, if the period is configured as 10 minutes, the first update is sent
immediately after the subscription is created and every 10 minutes thereafter.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

314
 Model-Driven Programmability
On-Change Publication for yang-push

The period is time, in centiseconds (1/100 of a second), between periodic push updates. A period of 1000 will
result in getting updates to the subscribed information every 10 seconds. The minimum period that can be
configured is 100, or one second. There is no default value. This value must be explicitly set in the
<establish-subscription> RPC for dynamic subscriptions and in the configuration for configured subscriptions.
Periodic updates contain a full copy of the subscribed data element or table for all supported transport protocols.
When subscribing for empty data using a periodic subscription, empty update notifications are sent at the
requested period. If data comes into existence, its values at the next period are sent as a normal update
notification.

On-Change Publication for yang-push

When creating an on-change subscription, the dampening period must be set to 0 to indicate that there is no
dampening period; no other value is supported.
With on-change subscriptions, the first push update is the entire set of subscribed to data (the initial
sychronization as defined in the IETF documents). This is not controllable. Subsequent updates are sent when
the data changes, and consist of only the changed data. However, the minimum data resolution for a change
is a row. So, if an on-change subscription is to a leaf within a row, if any item in that row changes, an update
notification is sent. The exact contents of the update notification depend on the transport protocol.
In addition, on-change subscriptions are not hierarchical. That is, when subscribing to a container that has
child containers, changes in the child container are not seen by the subscription.
Subscriptions for data that does not currently exist are permitted and run as normal subscriptions. The initial
synchronization update notification is empty and there are no further updates until data is available.

The yang-notif-native Stream

The yang-notif-native stream is any YANG notification in the publisher where the underlying source of events
for the notification uses Cisco IOS XE native technology. This stream also supports an XPath filter that
specifies which notifications are of interest. Update notifications for this stream are sent only when events
that the notifications are for occur.
Since this stream supports only on-change subscriptions, the dampening interval must be specified with a
value of 0.

Note Currently, this stream is not supported over Google remote procedure call (gRPC).

XPath Filter for yang-notif-native

The dataset within the yang-notif-native stream to be subscribed to is specified by the use of an XPath filter.
The following guidelines apply to the XPath expression:
• XPath expressions must specify a single object. That object can be a container, a leaf, a leaf list or a list.
• XPath expressions must specify an entire YANG notification; attribute filtering is not supported.
• XPath expressions support the use of the union operator (|) to allow a single subscription to support
multiple objects.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

315
 Model-Driven Programmability
TLDP On-Change Notifications

TLDP On-Change Notifications

Targeted Label Discovery Protocol (T-LDP) is an LDP session between label-switched routers (LSRs) that
are not directly connected. The TLDP On-Change Notifications feature notifies users when TLDP sessions
come up or go down and when TLDP is configured or disabled. TLDP must be enabled for the notifications
to work.
Event-based notifications are generated in the following two scenarios:
• Configured events are generated when TLDP is configured and removed from a device. Notifications
are also generated when a TLDP session comes up and goes down.
• Notifications are also generated when a TLDP session comes up and goes down.

Transport Protocol
The protocol that is used for the connection between a publisher and a receiver decides how the data is sent.
This protocol is referred to as the transport protocol, and is independent of the management protocol for
configured subscriptions. The transport protocol affects both the encoding of the data, for example XML,
Google Protocol Buffers (GPB) and the format of the update notification itself.

Note The stream that is chosen may also affect the format of the update notification.

Supported transport protocols are gNMI, gRPC, and NETCONF.

NETCONF Protocol
The NETCONF protocol is available only for the transport of dynamic subscriptions, and can be used with
yang-push and yang-notif-native streams.
Three update notification formats are used when using NETCONF as the transport protocol:
• When the subscription uses the yang-push stream, and if it is periodic or when the initial synchronization
update notification is sent on an on-change subscription.
• When the subscription uses the yang-push stream and it is an on-change subscription, other than the
initial synchronization update notification.
• When the subscription uses the yang-notif-native stream.

The yang-push Format

When the yang-push source stream is sent over NETCONF as a transport with XML encoding, two update
notification formats are defined. These update notification formats are based on the
draft-ietf-netconf-yang-push-07. For more information, see section 3.7 of the IETF draft.

The yang-notif-native Format

When the source stream is yang-notif-native, the format of the update notification when encoded in XML
over NETCONF is as defined by RFC 7950. For more information, see section 7.16.2 of the RFC.
Unlike the formats for the yang-push stream, the subscription ID is not found in the update notification.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

316
 Model-Driven Programmability
gRPC Protocol

gRPC Protocol
The gRPC protocol is available only for the transport of configured subscriptions, and can only be used with
the yang-push stream. Only kvGPB encoding is supported with gRPC transport protocol.
Receiver connection retries based on gRPC protocol (exponential back-off) are supported.
For telemetry messages defined in .proto files, see: mdt_grpc_dialout.proto and telemetry.proto.

Mutual Authentication for gRPC Telemetry

gRPC is one of the supported dial-out protocols used to transmit telemetry data. For dial-out protocols, the
device is considered the client and the collector, the server. gRPC supports both unencrypted TCP and encrypted
TLS-based connections.
A new gRPC-TLS profile that contains a pair of trustpoints is added to the telemetry configuration, so that a
client ID certificate can be used for mutual authentication. The profile contains two trustpoints, one is the
Certificate Authority (CA) certificate for server validation, and the other is the ID certificate for client validation.
When a device connects to a receiver for the first time, based on the server configuration, client or mutual
authentication may be required. The device will receive the receiver's identity certificate and validate whether
the certificate is signed by the CA identified in the certificate associated with the trustpoint configured in the
receiver profile. If the receiver then requests for the certificate ID of the device, the device sends the client
ID certificate previously installed in the profile’s ID-trustpoint field.
If the server is configured to require mutual authentication, and there is no client ID trustpoint in the profile,
the client authentication will not happen, nor will the connection succeed.
The same trustpoint label can be configured for multiple profiles, and the same profile can be configured for
multiple receivers.

Note The trustpoint with the client ID is not mandatory in the profile configuration, as mutual authentication
is not required for gRPC over TLS. As in prior releases, gRPC over TLS can be configured only with
server validation.

To add the client ID trustpoint, use the telemetry protocol grpc profile <name> command.
This feature cannot be disabled; but it can be left unused by not configuring the receivers to use the gRPC-TLS
protocol, or by removing or not configuring the client ID trustpoint field in the receiver configuration.

High Availability in Telemetry

Dynamic telemetry connections are established over a NETCONF session through SSH to the active switch
or a member in a switch stack, or the active route processor in a high-availability-capable device. After
switchover, you must destroy and re-establish all the sessions that use crypto, including NETCONF sessions
that carry telemetry subscriptions. You must also re-create all the dynamic subscriptions after a switchover.
gNMI dial-in subscriptions also work the same as a NETCONF session through SSH.
gRPC dial-out subscriptions are configured on the device as part of the running configuration of the active
switch or member of the stack. When switchover occurs, the existing connections to the telemetry receivers
are torn down and reconnected (as long as there is still a route to the receiver). Subscriptions need not be
reconfigured.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

317
 Model-Driven Programmability
Pubd Restartability

Note In the event of a device reload, subscription configurations must be synchronized to the start-up
configuration of a device. This ensures that after the device reboots, subscription configurations remain
intact on the device. When the necessary processes are up and running, the device attempts to connect
to the telemetry receiver and resume normal operations.

Pubd Restartability
In Cisco IOS XE Cupertino 17.9.1, the pubd process is restartable on all platforms. Prior to this release, pubd
was restartable only on certain platforms. On other platforms, to restart the pubd process, the whole device
had to be restarted.
Pubd can be restarted by removing and re-adding the NETCONF-YANG or gNXI configuration, as applicable.
Note that this will also restart the other NETCONF-YANG or gNXI processes.

Sample Model-Driven Telemetry RPCs

The following section provides a list of sample RPCs, and describes how to configure subscriptions.

Managing Configured Subscriptions

Note Currently, you can only use the gRPC protocol for managing configured subscriptions.

SUMMARY STEPS
1. enable
2. configure terminal
3. telemetry ietf subscription id
4. stream yang-push
5. filter xpath path
6. update-policy {on-change | periodic} period
7. encoding encode-kvgpb
8. source-vrf vrf-id
9. source-address source-address
10. receiver ip address ip-address receiver-port protocol protocol profile name
11. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

318
 Model-Driven Programmability
Managing Configured Subscriptions

Command or Action Purpose

Step 2 configure terminal Enters global configuration mode.
Example:
Device# configure terminal

Step 3 telemetry ietf subscription id Creates a telemetry subscription and enters

telemetry-subscription mode.
Example:
Device(config)# telemetry ietf subscription 101

Step 4 stream yang-push Configures a stream for the subscription.

Example:
Device(config-mdt-subs)# stream yang-push

Step 5 filter xpath path Specifies the XPath filter for the subscription.
Example:
Device(config-mdt-subs)# filter xpath
/memory-ios-xe-oper:memory-statistics/memory-statistic

Step 6 update-policy {on-change | periodic} period Configures a periodic update policy for the subscription.
Example:
Device(config-mdt-subs)# update-policy periodic
6000

Step 7 encoding encode-kvgpb Specifies kvGPB encoding.

Example:
Device(config-mdt-subs)# encoding encode-kvgpb

Step 8 source-vrf vrf-id Configures the source VRF instance.

Example:
Device(config-mdt-subs)# source-address Mgmt-intf

Step 9 source-address source-address Configures the source address.

Example:
Device(config-mdt-subs)# source-vrf 192.0.2.1

Step 10 receiver ip address ip-address receiver-port protocol Configures the receiver IP address, protocol, and profile
protocol profile name for notifications.
Example:
Device(config-mdt-subs)# receiver ip address
10.28.35.45 57555 protocol grpc-tcp

Step 11 end Exits telemetry-subscription configuration mode and

returns to privileged EXEC mode.
Example:
Device(config-mdt-subs)# end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

319
 Model-Driven Programmability
Configuring On-Change gRPC Subscriptions

Configuring On-Change gRPC Subscriptions

SUMMARY STEPS
1. enable
2. configure terminal
3. telemetry ietf subscription id
4. stream yang-push
5. filter xpath path
6. update-policy {on-change | periodic period}
7. encoding encode-kvgpb
8. receiver ip address ip-address receiver-port protocol protocol profile name
9. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 telemetry ietf subscription id Creates a telemetry subscription and enters

telemetry-subscription mode.
Example:
Device(config)# telemetry ietf subscription 8

Step 4 stream yang-push Configures a stream for the subscription.

Example:
Device(config-mdt-subs)# stream yang-push

Step 5 filter xpath path Specifies the XPath filter for the subscription.
Example:
Device(config-mdt-subs)# filter xpath
/iosxe-oper:ios-oper-db/hwidb-table

Step 6 update-policy {on-change | periodic period} Configures an on-change update policy for the subscription.
Example:
Device(config-mdt-subs)# update-policy on-change

Step 7 encoding encode-kvgpb Specifies kvGPB encoding.

Example:
Device(config-mdt-subs)# encoding encode-kvgpb

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

320
 Model-Driven Programmability
Receiving a Response Code

Command or Action Purpose

Step 8 receiver ip address ip-address receiver-port protocol Configures the receiver IP address, protocol, and profile
protocol profile name for notifications.
Example:
Device(config-mdt-subs)# receiver ip address
10.22.22.45 45000 protocol
grpc_tls profile secure_profile

Step 9 end Exits telemetry-subscription configuration mode and returns

to privileged EXEC mode.
Example:
Device(config-mdt-subs)# end

Receiving a Response Code

When a subscription is successfully created, the device responds with a subscription result of notif-bis:ok and
a subscription ID. The following is a sample response RPC message for a dynamic subscription:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

<subscription-result xmlns="urn:ietf:params:xml:ns:yang:ietf-event-notifications"
xmlns:notif-bis="urn:ietf:params:xml:ns:yang:ietf-event-notifications">notif-bis:
ok</subscription-result>
<subscription-id
xmlns="urn:ietf:params:xml:ns:yang:ietf-event-notifications">2147484201</subscription-id>
</rpc-reply>

Receiving Subscription Push Updates for NETCONF Dial-In

Subscription updates pushed from the device are in the form of an XML RPC and are sent over the same
NETCONF session on which these are created. The subscribed information element or tree is returned within
the datastore-contents-xml tag. The following is a sample RPC message that provides the subscribed
information:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2017-05-09T21:34:51.74Z</eventTime>
<push-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<subscription-id>2147483650</subscription-id>
<datastore-contents-xml>
<cpu-usage
xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-process-cpu-oper"><cpu-utilization>
<five-minutes>5</five-minutes></cpu-utilization></cpu-usage>
</datastore-contents-xml>
</push-update>
</notification>

If the information element to which a subscription is made is empty, or if it is dynamic, for example, a named
access list, and does not exist, the periodic update will be empty and will have a self-closing
datastore-contents-xml tag. The following is a sample RPC message in which the periodic update is empty:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2017-05-09T21:34:09.74Z</eventTime>
<push-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

321
 Model-Driven Programmability
Retrieving Subscription Details

<subscription-id>2147483649</subscription-id>
<datastore-contents-xml />
</push-update>
</notification>

Retrieving Subscription Details

You can retrieve the list of current subscriptions by sending a <get> RPC to the Cisco-IOS-XE-mdt-oper
model. You can also use the show telemetry ietf subscription command to display the list of current
subscriptions.
The following is a sample <get> RPC message:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

<get>
<filter>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions/>
</mdt-oper-data>
</filter>
</get>
</rpc>

The following is a sample RPC reply:

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">

<data>
<mdt-oper-data xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-mdt-oper">
<mdt-subscriptions>
<subscription-id>2147485164</subscription-id>
<base>
<stream>yang-push</stream>
<encoding>encode-xml</encoding>
<period>100</period>
<xpath>/ios:native/router/ios-rip:rip/ios-rip:version</xpath>
</base>
<type>sub-type-dynamic</type>
<state>sub-state-valid</state>
<comments/>
<updates-in>0</updates-in>
<updates-dampened>0</updates-dampened>
<updates-dropped>0</updates-dropped>
</mdt-subscriptions>
</mdt-oper-data>
</data>
</rpc-reply>

The following is sample output from the show telemetry ietf subscription dynamic brief command:

Device# show telemetry ietf subscription dynamic brief

Telemetry subscription brief

ID Type State Filter type

-----------------------------------------------------

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

322
Model-Driven Programmability
Retrieving Subscription Details

2147483667 Dynamic Valid xpath

2147483668 Dynamic Valid xpath
2147483669 Dynamic Valid xpath

The following is sample output from the show telemetry ietf subscription subscription-ID detail command:

Device# show telemetry ietf subscription 2147483667 detail

Telemetry subscription detail:

Subscription ID: 2147483667

State: Valid
Stream: yang-push
Encoding: encode-xml
Filter:
Filter type: xpath
XPath: /mdt-oper:mdt-oper-data/mdt-subscriptions
Update policy:
Update Trigger: periodic
Period: 1000
Notes:

The following is sample output from the show telemetry ietf subscription all detail command:
Device# show telemetry ietf subscription all detail

Telemetry subscription detail:

Subscription ID: 101

Type: Configured
State: Valid
Stream: yang-push
Encoding: encode-kvgpb
Filter:
Filter type: xpath
XPath: /iosxe-oper:ios-oper-db/hwidb-table
Update policy:
Update Trigger: on-change
Synch on start: Yes
Dampening period: 0
Notes:

The following sample RPC shows how to retrieve subscription details uisng RESTCONF:
Subscription details can also be retrieved through a RESTCONF GET request to the
Cisco-IOS-XE-mdt-oper database:
URI:
https://10.85.116.28:443/restconf/data/Cisco-IOS-XE-mdt-oper: mdt-oper-data/mdt-subscriptions
Headers:
application/yang-data.collection+json, application/yang-data+json,
application/yang-data.errors+json
Content-Type:
application/yang-data+json
Returned output:
{
"Cisco-IOS-XE-mdt-oper:mdt-subscriptions": [
{
"subscription-id": 101,
"base": {
"stream": "yang-push",

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

323
 Model-Driven Programmability
Configuring Named Protocol Receiver Using the CLI

"encoding": "encode-kvgpb",
"source-vrf": "",
"no-synch-on-start": false,
"xpath": "/iosxe-oper:ios-oper-db/hwidb-table"
},
"type": "sub-type-static",
"state": "sub-state-valid",
"comments": "",
"updates-in": "0",
"updates-dampened": "0",
"updates-dropped": "0",
"mdt-receivers": [
{
"address": "5.28.35.35",
"port": 57555,
"protocol": "grpc-tcp",
"state": "rcvr-state-connecting",
"comments": "Connection retries in progress",
"profile": ""
}
]
}
]
}

Configuring Named Protocol Receiver Using the CLI

SUMMARY STEPS
1. enable
2. configure terminal
3. telemetry receiver protocol receiver-name
4. protocol {cloud-native | cntp-tcp | cntp-tls profile profile-name | grpc-tcp | grpc-tls profile profile-name
| native | tls-native profile profile-name}
5. host {ip ip-address | name hostname} receiver-port
6. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 telemetry receiver protocol receiver-name Configures a named protocol receiver, and enters telemetry
protocol-receiver configuration mode.
Example:
Device(config)# telemetry receiver protocol
receiver1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

324
 Model-Driven Programmability
Subscription Configuration Using Named Receivers Using CLI

Command or Action Purpose

Step 4 protocol {cloud-native | cntp-tcp | cntp-tls profile Configures a protocol for the named protocol receiver
profile-name | grpc-tcp | grpc-tls profile profile-name | connection.
native | tls-native profile profile-name}
Example:
Device(config-mdt-protocol-receiver)# protocol
grpc-tcp

Step 5 host {ip ip-address | name hostname} receiver-port Configures the name protocol receiver hostname.
Example:
Device(config-mdt-protocol-receiver)# host name
rcvr.test.com 45000

Step 6 end Exits telemetry protocol-receiver configuration mode and

returns to privileged EXEC mode.
Example:
Device(config-mdt-protocol-receiver)# end

Subscription Configuration Using Named Receivers Using CLI

SUMMARY STEPS
1. enable
2. configure terminal
3. telemetry ietf subscription id
4. receiver-type protocol }
5. receiver name name
6. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 telemetry ietf subscription id Creates a telemetry subscription and enters

telemetry-subscription mode.
Example:
Device(config)# telemetry ietf subscription 101

Step 4 receiver-type protocol } Configures a protocol-type receiver.

Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

325
 Model-Driven Programmability
Additional References for Model-Driven Telemetry

Command or Action Purpose

Device(config-mdt-subs)# receiver-type protocol

Step 5 receiver name name Configures a name for the receiver for notifications.
Example:
Device(config-mdt-subs)# receiver name receiver1

Step 6 end Exits telemetry telemetry-subscription mode and returns to

privileged EXEC mode.
Example:
Device(config-mdt-subs)# end

Additional References for Model-Driven Telemetry

Related Documents

Related Topic Document Title

NETCONF-YANG patches https://tools.ietf.org/wg/netconf/draft-ietf-netconf-yang-patch/

YANG Explorer https://github.com/CiscoDevNet/yang-explorer

Standards and RFCs

Standard/RFC Title
Custom Subscription to Event Notifications https://tools.ietf.org/id/
draft-ietf-netconf-subscribed-notifications-03 draft-ietf-netconf-subscribed-notifications-03.txt

NETCONF Support for Event Notifications draft-ietf-netconf-netconf-event-notifications-01

RFC 5277 NETCONF Event Notifications

RFC 6241 Network Configuration Protocol (NETCONF)

RFC 7950 The YANG 1.1 Data Modeling Language

RFC 8040 RESTCONF Protocol

Subscribing to Event Notifications draft-ietf-netconf-rfc5277bis-01

Subscribing to YANG Datastore Push Updates draft-ietf-netconf-yang-push-04

Subscribing to YANG datastore push updates https://tools.ietf.org/id/

draft-ietf-netconf-yang-push-07 draft-ietf-netconf-yang-push-07.txt

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

326
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for Model-Driven Telemetry

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

327
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Table 40: Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

Model-Driven Telemetry Cisco IOS XE Everest 16.6.1 Model-driven telemetry allows

NETCONF Dial-In network devices to continuously
stream real time configuration and
operating state information to
subscribers.
• Cisco Catalyst 3650 Series
Switches
• Cisco Catalyst 3850 Series
Switches
• Cisco Catalyst 9300 Series
Switches
• Cisco Catalyst 9500 Series
Switches

Cisco IOS XE Everest 16.6.2 • Cisco Catalyst 9400 Series

Switches

Cisco IOS XE Fuji 16.7.1 • Cisco 4000 Series Integrated

Services Routers
• Cisco ASR 1000 Series
Aggregation Services Routers
(ASR1001-HX, ASR1001-X,
ASR1002-HX, ASR1002-X)

Cisco IOS XE Fuji 16.8.1 • Cisco 1000 Series Integrated

Services Routers
• Cisco ASR 1000 RP2 and RP3
Series Aggregation Services
Routers

Cisco IOS XE Fuji 16.8.1a • Cisco Catalyst 9500-High

Performance Series Switches

Cisco IOS XE Fuji 16.9.1 • Cisco ASR 900 Series

Aggregation Services Routers
• Cisco ASR 920 Series
Aggregation Services Router
• Cisco cBR-8 Converged
Broadband Router
• Cisco Network Convergence
System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

328
Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

Cisco IOS XE Gibraltar 16.9.2 • Cisco Catalyst 9200 and

9200L Series Switches
• Cisco Catalyst 9300L SKUs

Cisco IOS XE Gibraltar 16.10.1 • Cisco Cloud Services Router

1000v
• Cisco Network Convergence
System 520 Series

Cisco IOS XE Gibraltar 16.11.1 • Cisco Catalyst 9600 Series

Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

329
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

Model-Driven Telemetry gNMI Cisco IOS XE Gibraltar 16.12.1 Telemetry updates that are sent to
Dial-In the initiator/subscriber are called
Dial-in.
This feature was implemented on
the following platforms:
• Cisco Catalyst 9200 and
9200L Series Switches
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series
Switches
• Cisco cBR-8 Converged
Broadband Router

Cisco IOS XE Amsterdam 17.1.1 • Cisco ASR 900 Series

Aggregation Services Routers
• Cisco ASR 920 Series
Aggregated Services Router
• Cisco Network Convergence
System 520 Series
• Cisco Network Convergence
System 4200 Series

Cisco IOS XE Amsterdam 17.2.1 Cisco ASR 1000 Series

Aggregation Services Routers

Cisco IOS XE Cupertino 17.8.1 • Cisco 1000 Series Integrated

Services Routers
• Cisco 4000 Series Integrated
Services Routers

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

330
Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

Model-Driven Telemetry gRPC Cisco IOS XE Gibraltar 16.10.1 Configured subscriptions cause the
Dial-Out publisher to initiate connections to
receivers, and these connections are
considered as dial-out.
This feature was implemented on
the following platforms:
• Cisco 1000 Series Integrated
Services Routers
• Cisco 4000 Series Integrated
Services Routers
• Cisco ASR 1000 Series
Aggregation Services Routers
• Cisco ASR 900 Series
Aggregation Services Routers
• Cisco ASR 920 Series
Aggregated Services Router
• Cisco Catalyst 9200 and
9200L Series Switches
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco cBR-8 Converged
Broadband Router
• Cisco Cloud Services Router
1000V Series
• Cisco Network Convergence
System 520 Series
• Cisco Network Convergence
System 4200 Series

Cisco IOS XE Gibraltar 16.11.1 • Cisco Catalyst 9600 Series

Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

331
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

Model-Driven Telemetry: Kill Cisco IOS XE Gibraltar 16.11.1 To delete dynamic subscriptions,
Subscription you can use the CLI and the
kill-subscription RPC.
• Cisco ASR 900 Series
Aggregation Services Routers
• Cisco ASR 920 Series
Aggregated Services Router
(RSP2)
• Cisco Catalyst 3650 Series
Switches
• Cisco Catalyst 3850 Series
Switches
• Cisco Catalyst 9200 and
9200L Series Switches
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco Network Convergence
System 520 Series
• Cisco Network Convergence
System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

332
Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

TLDP On-Change Notifications Cisco IOS XE Amsterdam 17.2.1 The TLDP On-Change
Notifications feature notifies users
when TLDP sessions come up or
go down and when TLDP is
configured or disabled.
This feature was implemented on
the following platforms:
• Cisco 4000 Series Integrated
Services Routers
• Cisco Catalyst 9200 Series
Switches
• Cisco Catalyst 9300 Series
Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 Series
Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

333
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

TLS for gRPC Dial-Out Cisco IOS XE Amsterdam 17.1.1 Transport-Layer Security is
supported for gRPC dial-out. This
feature is supported on the
following platforms:
• Cisco 1000 Series Integrated
Services Routers
• Cisco 4000 Series Integrated
Services Routers
• Cisco ASR 1000 Series
Aggregation Services Routers
• Cisco ASR 900 Series
Aggregation Services Routers
• Cisco ASR 920 Series
Aggregated Services Router
• Cisco Catalyst 9200 and
9200L Series Switches
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series
Switches
• Cisco Catalyst 9800-40 Series
Wireless Controller
• Cisco Catalyst 9800-80 Series
Wireless Controller
• Cisco cBR-8 Converged
Broadband Router
• Cisco Cloud Services Router
1000V Series
• Cisco Network Convergence
System 520 Series
• Cisco Network Convergence
System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

334
Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

FQDN Support for gRPC Cisco IOS XE Bengaluru 17.6.1 With the introduction of the FQDN
Subscriptions Support for gRPC Subscriptions
feature, along with IP addresses,
FQDN can also be used for gRPC
subscriptions.
• Cisco 1000 Series Integrated
Services Routers
• Cisco 4000 Series Integrated
Services Routers
• Cisco ASR 1000 Series
Aggregation Services Routers
• Cisco ASR 900 Series
Aggregation Services Routers
• Cisco ASR 920 Series
Aggregated Services Router
• Cisco Catalyst 9200 and
9200L Series Switches
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series
Switches
• Cisco Catalyst 9800-40 Series
Wireless Controller
• Cisco Catalyst 9800-80 Series
Wireless Controller
• Cisco cBR-8 Converged
Broadband Router
• Cisco Cloud Services Router
1000V Series
• Cisco Network Convergence
System 520 Series
• Cisco Network Convergence
System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

335
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

Leaf-Level Filtering Cisco IOS XE Cupertino 17.7.1 The Leaf-Level Filtering for
Telemetry feature allows filtering
below the gatherpoint level for the
optimized code paths.
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series
Switches

Mutual Authentication for gRPC Cisco IOS XE Cupertino 17.9.1 A new gRPC TLS profile that
Telemetry contains a pair of trustpoints was
added to the telemetry
configuration, so that a client ID
certificate can be specified for
mutual authentication. This new
profile can be used instead of the
trustpoint containing the server CA
certificate when configuring the
receiver profile. The trustpoint
containing the server CA certificate
is now configured as part of the
gRPC TLS profile.
This feature is supported on the
following platforms:
• Cisco Catalyst 9800-CL Series
Wireless Controller
• Cisco Catalyst 9800-40 Series
Wireless Controller
• Cisco Catalyst 9800-80 Series
Wireless Controller

On-Change Notification Cisco IOS XE Dublin 17.10.1 The TDL URI string supports
on-change notifications.
This feature was implemented on
Cisco ASR 1000 Series
Aggregation Services Routers

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

336
Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

Pubd Restartability Cisco IOS XE Cupertino 17.9.1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

337
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

The pubd process is made
restartable from this release
onwards.
This feature is supported on the
following platforms:
• Cisco 1000 Series Integrated
Services Routers
• Cisco 4000 Series Integrated
Services Routers
• Cisco ASR 1000 Series
Aggregation Services Routers
• Cisco ASR 900 Series
Aggregation Services Routers
• Cisco ASR 920 Series
Aggregated Services Router
• Cisco Catalyst 9200 and
9200L Series Switches
• Cisco Catalyst 9300 and
9300L Series Switches
• Cisco Catalyst 9400 Series
Switches
• Cisco Catalyst 9500 and
9500-High Performance Series
Switches
• Cisco Catalyst 9600 Series
Switches
• Cisco Catalyst 9800-CL Series
Wireless Controller
• Cisco Catalyst 9800-40 Series
Wireless Controller
• Cisco Catalyst 9800-80 Series
Wireless Controller
• Cisco cBR-8 Converged
Broadband Router
• Cisco Cloud Services Router
1000V Series
• Cisco Network Convergence
System 520 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

338
Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Feature Name Release Feature Information

• Cisco Network Convergence
System 4200 Series

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

339
 Model-Driven Programmability
Feature Information for Model-Driven Telemetry

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

340
 CHAPTER 14
In-Service Model Update
This module describes how to update the YANG data models on a device through an In-Service Model Update.
• Restrictions for In-Service Model Update, on page 341
• Information About In-Service Model Update, on page 341
• How to Manage In-Service Model Update, on page 344
• Configuration Examples for In-Service Model Updates, on page 345
• Feature Information for In-Service Model Update, on page 349

Restrictions for In-Service Model Update

• High availability or In-Service Software Upgrade (ISSU) is not supported. After a switchover, users must
install the Software Maintenance Update (SMU) on standby device.

Information About In-Service Model Update

Overview of In-Service Model Updates
In-Service Model Update adds new data models or extend functionality to existing data models. The In-Service
Model Update provides YANG model enhancements outside of a release cycle. The update package is a
superset of all existing models; it includes all existing models as well as updated YANG models.
The data model infrastructure implements the YANG model-defined management interfaces for Cisco IOS
XE devices. The data model infrastructure exposes the NETCONF interface northbound from Cisco IOS XE
devices. The supported data models include industry standard models such as IETF, and Cisco IOS XE
device-specific models.
The functionality provided by the In-Service Model Update is integrated into the subsequent Cisco IOS XE
software maintenance release. Data model update packages can be downloaded from the Cisco Download
Software Center.

Compatibility of In-Service Model Update Packages

An update package is built on a per release basis and is specific to a platform. This means that an update
package for Cisco ASR 1000 Series Aggregation Services Routers cannot be installed on Cisco CSR 1000V

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

341
 Model-Driven Programmability
Update Package Naming Conventions

Series Cloud Services Routers. Similarly, an update package built for Cisco IOS XE Fuji 16.7.1 cannot be
applied on a device that runs the Cisco IOS XE Everest 16.5.2 version.
All contents of an update package will be part of future mainline or maintenance release images. The image
and platform versions are checked by the In-Service Model Update commands during the package add and
activate. If an image or platform mismatch occurs, the package install fails.

Update Package Naming Conventions

In-Service Model Updates are packaged as a .bin files. This file includes all updates for a specific release and
platform and the Readme file. These files have a release date and are updated periodically with additional
model updates.
The naming convention of the data model update package follows the format—platform type-license
level.release version.DDTS ID-file. The following is an example of a data model update file:
• isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
• asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin

The readme file provides the following information:

• Console and error messages during data model activation or deactivation
• Data model installation impact
• Side effects and possible workarounds
• Package(s) that the In-Service Model Update impacts
• Restart type

Installing the Update Package

You can install the In-Service Model Update package on a device by using the install add, install activate,
and install commit commands in privileged EXEC mode.
The install add command copies the update package from a remote location to the device. You can also use
other methods to copy the package; however, you must still enable the install add command for the installation
to work. For the install activate command to work, the package must be available in the device bootflash.
Enable the install commit command to make updates persistent over reloads.
Installing an update replaces any previously installed data models. At any time, only one update is installed
on the device. A data model package includes all updated YANG models and all existing YANG models
previously installed on the device.
The following flow chart explains how the model update package works:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

342
 Model-Driven Programmability
Deactivating the Update Package

Figure 9: Committing a Model Update Package

If NETCONG-YANG is enabled during package activation, NETCONF processes are restarted. All active
NETCONF sessions are killed during package activation. Failure during a package verification terminates
the activation process.

Deactivating the Update Package

You can deactivate an update package by using the install deactivate command. Enable the install commit
command to make changes persistent.

Table 41: Deactivating a Model Update Package

Action Command to Use

To remove a package. Use the install remove command.

Note Deactivate a package before removing it.

To deactivate a package Use the install deactivate command, followed by the

install commit command.
Note The install commit command must be
used to ensure that the deactivation of the
model package is persistent across reloads.
Subsequent attempts at removal of the
package will fail, if the deactivation is not
committed.

When you deactivate an update, if more than one model update package is installed, the most recently committed
model update package becomes the model package used by the device. If there are no other previously
committed model packages, then the base version of data models included with the standard image is used.

Rollback of the Update Package

Rollback provides a mechanism to move a device back to the state in which it was operating prior to an update.
After a rollback, NETCONF-YANG processes are restarted before changes are visible.
You can roll back an update to the base version, the last committed version, or a known commit ID by using
the install rollback command.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

343
 Model-Driven Programmability
How to Manage In-Service Model Update

How to Manage In-Service Model Update

Managing the Update Package
SUMMARY STEPS
1. enable
2. install add file tftp: filename
3. install activate file bootflash: filename
4. install commit
5. install deactivate file bootflash: filename
6. install commit
7. install rollback to {base | committed | id commit-ID}
8. install remove {file bootflash: filename | inactive}
9. show install summary

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 install add file tftp: filename Copies the model update package from a remote location
(via FTP, TFTP) to the device, and performs a compatibility
Example:
check for the platform and image versions.
Device# install add file
tftp://172.16.0.1//tftpboot/folder1/ • You can use other methods to copy the update package
isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin from the remote location to the device, however; you
Device# install add file still have to execute the install add command before
tftp://172.16.0.1//tftpboot/folder1/ the package is activated.
asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin

Step 3 install activate file bootflash: filename Validates whether the update package is added through the
install add command, and restarts the NETCONF processes.
Example:
Device# install activate file bootflash: • Perform the install add operation prior to activating
isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin an update package.
Device# install activate file bootflash:
asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin

Step 4 install commit Makes the changes persistent over reload.

Example: • NETCONF processes are not restarted.
Device# install commit

Step 5 install deactivate file bootflash: filename Deactivates the specified update package, and restarts the
NETCONF processes.
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

344
 Model-Driven Programmability
Configuration Examples for In-Service Model Updates

Command or Action Purpose

Device# install deactivate file bootflash:
isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Device# install deactivate file bootflash:
asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin

Step 6 install commit Makes the changes persistent over reload.

Example: • NETCONF processes are not restarted.
Device# install commit

Step 7 install rollback to {base | committed | id commit-ID} Rollbacks the update to the base version, the last committed
version, or a known commit ID, and restarts NETCONF
Example:
processes.
Device# install rollback to base
• Valid values for the commit-id argument are from 1
to 4294967295.
• Older versions of data models updates are available
for use.

Step 8 install remove {file bootflash: filename | inactive} Removes the specified update package from the bootflash.
Example: • A package must be deactivated before it is removed.
Device# install remove file bootflash:
isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Device# install remove file bootflash:
asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin

Step 9 show install summary Displays information about the active package.
Example: • The output of this command varies according to the
Device# show install summary install commands that are configured.

Configuration Examples for In-Service Model Updates

Example: Managing an Update Package
The sample image used in the following examples are a Cisco 4000 Series Integrated Services Router
image.
The following example shows how to add a model update package file:
Device# install add file tftp://172.16.0.1//tftpboot/folder1/
isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin

install_add: START Sun Feb 26 05:57:04 UTC 2017

Downloading file
tftp://172.16.0.1//tftpboot/folder1/isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Finished downloading file
tftp://172.16.0.1//tftpboot/folder1/isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
to bootflash:isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

345
 Model-Driven Programmability
Example: Managing an Update Package

SUCCESS: install_add /bootflash/isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin

Sun Feb 26 05:57:22 UTC 2017
Device#

The sample image used in the following examples are a Cisco ASR1000 Series Aggregated Services
Router image.
The following example shows how to add a model update package file:
Device# install add file tftp://172.16.0.1//tftpboot/folder1/
asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin

install_add: START Sun Feb 26 05:57:04 UTC 2017

Downloading file
tftp://172.16.0.1//tftpboot/folder1/asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin
Finished downloading file
tftp://172.16.0.1//tftpboot/folder1/asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin
to bootflash: asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin
SUCCESS: install_add /bootflash/asr1000-universalk9.2017-08-23_17.48.0.CSCxxxxxxx.SSA.dmp.bin
Sun Feb 26 05:57:22 UTC 2017
Device#

The following is sample output from the show install summary command after adding an update
package file to the device:
Device# show install summary

Active Packages:
No packages
Inactive Packages:
bootflash: isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Committed Packages:
No packages
Uncommitted Packages:
No packages
Device#

The following example shows how to activate an added update package file:
Device# install activate file bootflash:
isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin

install_activate: START Sun Feb 26 05:58:41 UTC 2017

DMP package.
Netconf processes stopped
SUCCESS: install_activate /bootflash/isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Sun Feb 26 05:58:58 UTC 2017*Feb 26 05:58:47.655: %DMI-4-CONTROL_SOCKET_CLOSED:
SIP0: nesd: Confd control socket closed Lost connection to ConfD (45): EOF on socket to
ConfD.
*Feb 26 05:58:47.661: %DMI-4-SUB_READ_FAIL: SIP0: vtyserverutild:
Confd subscription socket read failed Lost connection to ConfD (45):
EOF on socket to ConfD.
*Feb 26 05:58:47.667: %DMI-4-CONTROL_SOCKET_CLOSED: SIP0: syncfd:
Confd control socket closed Lost connection to ConfD (45): EOF on socket to ConfD.
*Feb 26 05:59:43.269: %DMI-5-SYNC_START: SIP0: syncfd:
External change to running configuration detected.
The running configuration will be synchronized to the NETCONF running data store.
*Feb 26 05:59:44.624: %DMI-5-SYNC_COMPLETE: SIP0: syncfd:
The running configuration has been synchronized to the NETCONF running data store.
Device#

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

346
Model-Driven Programmability
Example: Managing an Update Package

The following sample output from the show install summary command displays the status of the
model package as active and uncommitted:
Device# show install summary

Active Packages:
bootflash:isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Inactive Packages:
No packages
Committed Packages:
No packages
Uncommitted Packages:
bootflash:isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Device#

The following example shows how to execute the install commit command:
Device# install commit
install_commit: START Sun Feb 26 06:46:48 UTC 2017
SUCCESS: install_commit Sun Feb 26 06:46:52 UTC 2017
Device#

The following sample output from the show install summary command displays that the update
package is now committed, and that it will be persistent across reloads:
Device# show install summary

Active Packages:
bootflash:isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Inactive Packages:
No packages
Committed Packages:
bootflash:isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Uncommitted Packages:
No packages
Device#

The following example shows how to rollback an update package to the base package:
Device# install rollback to base

install_rollback: START Sun Feb 26 06:50:29 UTC 2017

7 install_rollback: Restarting impacted processes to take effect
7 install_rollback: restarting confd
*Feb 26 06:50:34.957: %DMI-4-CONTROL_SOCKET_CLOSED: SIP0: syncfd:
Confd control socket closed Lost connection to ConfD (45): EOF on socket to ConfD.
*Feb 26 06:50:34.962: %DMI-4-CONTROL_SOCKET_CLOSED: SIP0: nesd:
Confd control socket closed Lost connection to ConfD (45): EOF on socket to ConfD.
*Feb 26 06:50:34.963: %DMI-4-SUB_READ_FAIL: SIP0: vtyserverutild:
Confd subscription socket read failed Lost connection to ConfD (45):
EOF on socket to ConfD.Netconf processes stopped
7 install_rollback: DMP activate complete
SUCCESS: install_rollback Sun Feb 26 06:50:41 UTC 2017
*Feb 26 06:51:28.901: %DMI-5-SYNC_START: SIP0: syncfd:
External change to running configuration detected.
The running configuration will be synchronized to the NETCONF running data store.
*Feb 26 06:51:30.339: %DMI-5-SYNC_COMPLETE: SIP0: syncfd:
The running configuration has been synchronized to the NETCONF running data store.
Device#

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

347
 Model-Driven Programmability
Example: Managing an Update Package

The following is sample output from the show install package command:
Device# show install package bootflash:
isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin

Name: isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Version: 16.5.1.0.199.1484082952..Everest
Platform: ISR4300
Package Type: dmp
Defect ID: CSCxxxxxxx
Package State: Added
Supersedes List: {}
Smu ID: 1
Device#

The following sample NETCONF hello message verifies the new data model package version:

Getting Capabilities: (admin @ 172.16.0.1:830)

PROTOCOL netconf
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
<capability>urn:ietf:params:netconf:base:1.1</capability>
<capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability>
<capability>urn:ietf:params:netconf:capability:xpath:1.0</capability>
<capability>urn:ietf:params:netconf:capability:validate:1.0</capability>
<capability>urn:ietf:params:netconf:capability:validate:1.1</capability>
<capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>
<capability>urn:ietf:params:netconf:capability:notification:1.0</capability>
<capability>urn:ietf:params:netconf:capability:interleave:1.0</capability>
<capability>http://tail-f.com/ns/netconf/actions/1.0</capability>
<capability>http://tail-f.com/ns/netconf/extensions</capability>
<capability>urn:ietf:params:netconf:capability:with-defaults:1.0?basic-mode=
explicit&amp;also-supported=report-all-tagged</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults?
revision=2011-06-01&amp;module=ietf-netconf-with-defaults</capability>
<capability>http://cisco.com/ns/yang/Cisco-IOS-XE-aaa?module=
Cisco-IOS-XE-aaa&amp;revision=2017-02-07</capability>
<<capability>http://cisco.com/ns/yang/Cisco-IOS-XE-native?module=
Cisco-IOS-XE-native&amp;revision=2017-01-07&amp;features=virtual-
template,punt-num,multilink,eth-evc,esmc,efp,dot1x</capability>
Device#

The following is sample output from the show install log command:
Device# show install log

[0|install_op_boot]: START Fri Feb 24 19:20:19 Universal 2017

[0|install_op_boot]: END SUCCESS Fri Feb 24 19:20:23 Universal 2017
[3|install_add]: START Sun Feb 26 05:55:31 UTC 2017
[3|install_add( FATAL)]: File path (scp) is not yet supported for this command
[4|install_add]: START Sun Feb 26 05:57:04 UTC 2017
[4|install_add]: END SUCCESS /bootflash/isr4300-universalk9.16.05.01.CSCxxxxxxx.dmp.bin
Sun Feb 26 05:57:22 UTC 2017
[5|install_activate]: START Sun Feb 26 05:58:41 UTC 2017
Device#

The sample image used in the following examples are a Cisco Catalyst 3000 Series Switch image.
The following example shows how to add a model update package file:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

348
 Model-Driven Programmability
Feature Information for In-Service Model Update

Device# install add file tftp://172.16.0.1//tftpboot/folder1/

cat3k_caa-universalk9.16.06.01.CSCxxxxxxx.dmp.bin

install_add: START Sat Jul 29 05:57:04 UTC 2017

Downloading file tftp://172.16.0.1//tftpboot/folder1/
cat3k_caa-universalk9.16.06.01.CSCxxxxxxx.dmp.bin
Finished downloading file tftp://172.16.0.1//tftpboot/folder1/
cat3k_caa-universalk9.16.06.01.CSCxxxxxxx.SPA.smu.bin
to bootflash:cat3k_caa-universalk9.16.06.01.CSCxxxxxxx.dmp.bin
SUCCESS: install_add /bootflash/cat3k_caa-universalk9.16.06.01.CSCxxxxxxx.dmp.bin
Sat Jul 29 05:57:22 UTC 2017
Device#

The following sample output from the show install summary command displays that the update
package is now committed, and that it will be persistent across reloads:
Device# show install summary

Active Packages:
bootflash:cat3k_caa-universalk9.16.06.01.CSCxxxxxxx.dmp.bin
Inactive Packages:
No packages
Committed Packages:
bootflash:cat3k_caa-universalk9.16.06.01.CSCxxxxxxx.dmp.bin
Uncommitted Packages:
No packages
Device#

Feature Information for In-Service Model Update

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

349
 Model-Driven Programmability
Feature Information for In-Service Model Update

Table 42: Feature Information for In-Service Model Update

Feature Name Release Feature Information

In-Service Model Update Cisco IOS XE Everest This module describes how to update YANG
16.5.1a data models through In-Service Model Update.
Cisco IOS XE Everest In Cisco IOS XE Everest 16.5.1a, this feature
16.5.1b was implemented on the following platforms:
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9500 Series Switches

In Cisco IOS XE Everest 16.5.1b, this feature

was implemented on the following platforms:
• Cisco 4000 Series Integrated Services
Routers
• Cisco Cloud Services Router 1000v
• Cisco Integrated Services Virtual Routers
(ISRv)

The following commands were introduced or

updated: install (Programmability), show
install (Programmability).

Cisco IOS XE Everest 16.6.1 In Cisco IOS XE Everest 16.5.1b, this feature
was implemented on the following platforms:
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches

Cisco IOS XE Fuji 16.7.x In Cisco IOS XE Fuji 16.7.x, this feature was
implemented on the following platform:
• Cisco 1000 Series Aggregated Services
Routers

Cisco IOS XE Fuji 16.8.1a In Cisco IOS XE Fuji 16.8.1a, this feature was
implemented on Cisco Catalyst 9500-High
Performance Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

350
PA R T IV
Application Hosting
• Application Hosting, on page 353
• ThousandEyes Enterprise Agent, on page 393
 CHAPTER 15
Application Hosting
A hosted application is a software as a service (SaaS) solution, and it can be run remotely using commands.
Application hosting gives administrators a platform for leveraging their own tools and utilities.

Note Application hosting supports only Docker applications.

This module describes the Application Hosting feature and how to enable it.
• Restrictions for Application Hosting, on page 353
• Information About Application Hosting, on page 354
• How to Configure Application Hosting, on page 365
• Verifying the Application-Hosting Configuration, on page 381
• Configuration Examples for Application Hosting, on page 384
• Additional References, on page 388
• Feature Information for Application Hosting, on page 389

Restrictions for Application Hosting

• Application hosting is not virtual routing and forwarding aware (VRF-aware).
• In releases prior to Cisco IOS XE Amsterdam 17.3.3, application hosting requires dedicated storage
allocations, and is disabled on the bootflash.
In Cisco IOS XE Amsterdam 17.3.3 and later releases, application hosting is enabled on the bootflash,
however, only Cisco-signed applications are hosted.
• The front-panel Universal Serial Bus (USB) stick is not supported.
Cisco Catalyst 9300 Series Switches support only back-panel Cisco-certified USB.
• Cisco Catalyst 9500-High Performance Series Switches and Cisco Catalyst 9600 Series Switches do not
support front-panel USB for application hosting.
• Cisco Catalyst 9500 and 9500-High Performance Series Switches and Cisco Catalyst 9600 Series Switches
do not support AppGigabitEthernet interfaces.
• Cisco Catalyst 9410R Switches do not support application-hosting in release prior to Cisco IOS XE
Bengaluru 17.5.1.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

353
 Application Hosting
Information About Application Hosting

Configure the enable command on the AppGigabitEthernet interfaces to enable application hosting on
Cisco Catalyst 9410R Switches.

Information About Application Hosting

This section provides information about Application Hosting.

Need for Application Hosting

The move to virtual environments has given rise to the need to build applications that are reusable, portable,
and scalable. Application hosting gives administrators a platform for leveraging their own tools and utilities.
An application, hosted on a network device, can serve a variety of purposes. This ranges from automation,
configuration management monitoring, and integration with existing tool chains.

Note In this document, container refers to Docker applications.

Cisco IOx Overview

Cisco IOx (IOs + linuX) is an end-to-end application framework that provides application-hosting capabilities
for different application types on Cisco network platforms. The Cisco Guest Shell, a special container
deployment, is one such application, that is useful in system deployment.
Cisco IOx facilitates the life cycle management of applications and data exchange by providing a set of services
that helps developers to package prebuilt applications, and host them on a target device. IOx life cycle
management includes distribution, deployment, hosting, starting, stopping (management), and monitoring of
applications and data. IOx services also include application distribution and management tools that help users
discover and deploy applications to the IOx framework.
Cisco IOx application hosting provides the following features:
• Hides network heterogeneity.
• Cisco IOx application programming interfaces (APIs) remotely manage the life cycle of applications
hosted on a device.
• Centralized application life cycle management.
• Cloud-based developer experience.

Application Hosting Overview

The Cisco application-hosting framework is an IOx Python process that manages virtualized and container
applications that run on devices.
Application hosting provides the following services:
• Launches designated applications in containers.
• Checks available resources (memory, CPU, and storage), and allocates and manages them.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

354
 Application Hosting
Application Hosting on Front-Panel Trunk and VLAN Ports

• Provides support for console logging.

• Provides access to services through REST APIs.
• Provides a CLI endpoint.
• Provides an application-hosting infrastructure referred to as Cisco Application Framework (CAF).
• Helps setup platform-specific networking (packet-path) through management interfaces.
Data ports are supported on platforms that have AppGigabitEthernet port functionality.

The application-hosting container that is referred to as the virtualization environment is provided to run a
guest application on the host operating system. The Cisco IOS-XE virtualization services provide manageability
and networking models for running a guest application. The virtualization infrastructure allows an administrator
to define a logical interface that specifies the connectivity between the host and the guest. Cisco IOx maps
the logical interface into a Virtual Network Interface Card (vNIC) that the guest application uses.
Applications that are to be deployed in the containers are packaged as TAR files. The configuration that is
specific to these applications is also packaged as part of the TAR files.
The management interface on the device connects the application-hosting network to the Cisco IOS management
interface. The Layer 3 interface of the guest application receives the Layer 2-bridged traffic from the Cisco
IOS management interface. The management interface connects to the container interface through the
management bridge. The IP address of the application must be on the same subnet as the management interface
IP address.

Note On all Cisco Catalyst stack and stackwise virtual models (all software versions), Guest Shell and the
AppGigabitEthernet interface operate only on the active switch in the stack. Therefore, the
AppGigabitEthernet interface configuration must be applied to the AppGigabitEthernet interface on all
the switches in the stack. If the configuration is not applied to all the switches, the AppGigabitEthernet
interface on the switch will not work after a switchover.

Cisco Catalyst 9000 Series Switches support multiple applications when hosted on the SSD. The applications
must meet the following criteria:
• Cisco-signed
• Meet the switching infrastructure requirements:
• Network configuration on AppGigabitEthernet ports does not create a conflict between the
applications.
• Enough resources are available to run the applications.

Multiple applications cannot be deployed if an application consumes all the available App-hosting resources.
For example, if one application consumes all the compute and run time resources, other applications are
prevented from getting installed on the device.

Application Hosting on Front-Panel Trunk and VLAN Ports

Front-panel VLAN and trunk ports are supported for application hosting. Layer 2 traffic is delivered through
these ports to software components that run outside of the Cisco IOS daemon.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

355
 Application Hosting
Application Hosting on Cisco Catalyst 9300 Series Switches

For application hosting, you can configure the front-panel port as either a trunk interface or a VLAN-specific
interface. When using as a trunk interface, the front-panel port is extended to work as a Layer 2 trunk port,
and all the traffic received by the port is available to the application. When using the port as a VLAN interface,
the application is connected to a specific VLAN network.

Note When using a back-panel USB or an M2 SATA drive for application hosting, the storage medium should
be formatted as an ext4 file system.

Application Hosting on Cisco Catalyst 9300 Series Switches

This section describes application-hosting on Cisco Catalyst 9300 Series Switches.
For application hosting, Cisco Catalyst 9300 Series Switches support the management interface and front-panel
ports.
The USB 3.0 SSD is enabled on Cisco Catalyst 9300 Series Switches. The USB 3.0 SSD provides an extra
120 GB storage for application hosting. For more information, see the "Configuring USB 3.0 SSD" chapter
in the Interfaces and Hardware Configuration Guide.
The following two types of networking applications are supported:
• Control plane: Applications that access the management interface.
• Data plane: Applications that access the front-panel ports.

Front-Panel App Hosting on Cisco Catalyst 9300X Series Switches

Front-panel application hosting is enabled on Cisco Catalyst 9300X Series Switches in Cisco IOS XE Bengaluru
17.6.1.
Applications can use dedicated front-panel ports for hosting. Use the app-vnic AppGigabitEthernet port
command to specify the port to be used for application hosting. Both the front-panel ports can be attached to
the same Layer 2 application.
These switches support application hosting in both access mode and trunk mode. Application hosting can be
enabled on both modes simultaneously.

Note Any configuration done under the app-vnic command can be rejected during activation.

Table 43: Sample Configuration Scenarios for App Hosting in Access and Trunk Modes

Scenario Supported/Unsupported

Single application with two front-panel ports in access Supported.

mode.
No overlapping VLANs.

Single application with two front-panel ports in trunk Supported.

mode.
No overlapping VLANs.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

356
 Application Hosting
High Availability on Cisco Catalyst 9300X Series Switches

Scenario Supported/Unsupported

Single application with two front-panel ports in trunk Supported.

and access modes.
No overlapping VLANs.

Single application with two front-panel ports in trunk Supported.

mode with the default app-gateway configured.
The same application with two interfaces is configured
in different subnets; but the default gateway is
connected to one VLAN, which has external
connectivity.

Single application with two front-panel ports in trunk Not a valid configuration.
and access modes with an overlapping VLAN.
VLAN overlapping with both ports.

Single application in access mode and two front-panel Not a valid configuration.
ports configured on the same VLAN.

Single application in trunk mode and two front-panel Not a valid configuration.
ports configured on an overlapping VLAN range.
The traffic is not isolated, and the VLAN range is
overlapping.

Single application in trunk mode and two front-panel Not a valid configuration.
ports configured on an overlapping VLAN range.
This configuration will be rejected during activation.
Both the front-panel ports are in trunk mode, so any
VLAN can be used. However, the same VLAN is
configured for both the ports, and as a result, the
VLAN overlaps with both the ports.
Note The same scenario applies for access mode.

Single application in trunk and access modes, and Not a valid configuration.
front-panel ports with an overlapping VLAN.
The same VLAN is configured in trunk mode and
access mode. Because of the configuration, the VLAN
overlaps with both ports.

Multiple application in trunk mode. Not a valid configuration.

The traffic is not isolated.

Two applications, one in trunk mode and the other in Not a valid configuration.
access mode.
Overlapping VLAN.

High Availability on Cisco Catalyst 9300X Series Switches

With mixed mode stacking available on Cisco Catalyst 9300X Series Switches, the active and standby devices
use the 1+1 redundancy for application hosting. Mixed mode support is when different model variants and
different network modules are used in a stack.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

357
 Application Hosting
High Availability on Cisco Catalyst 9300X Series Switches

When Cisco Catalyst 9300X Series Switches and Cisco Catalyst 9300 Series Switches are stacked, one of the
two front-panel ports on Cisco Catalyst 9300X Series Switches are dynamically disabled. Only the
AppGigabitEthernet 1/0/1 interface is displayed as enabled.
This section describes some of the high availability scenarios:

Stack Mode Apps Ports Used Behavior

Cisco Catalyst 9300X 2 1 Supported

Series Switch active +
Cisco Catalyst 9300X
Series Switch standby

Cisco Catalyst 9300X 1 1 Supported

Series Switch active +
Cisco Catalyst 9300X
Series Switch standby

Cisco Catalyst 9300X 1 1 Supported.

Series Switch active +
Only if port 1 is used. This configuration is supported, if
Cisco Catalyst 9300
port 1 is configured by using the
Series Switch standby
app-vnic Appgigabitethernet port
1 trunk or the app-vnic
AppgigabitEthernet trunk
commands.
If a port number is not specified, the
default port 1 is used, when a
switchover happens.

Cisco Catalyst 9300X 1 2 Not supported.

Series Switch active +
In this scenario, when a switchover
Cisco Catalyst 9300
happens, the new active will not have
Series Switch standby
two front-panel ports, and the app
configuration fails.
After the switchover, the application
is not restarted on Cisco Catalyst
9300 Series Switch, because only one
front-panel port is configured, and
this configuration fails. The
application must be reconfigured
using the available front-panel port.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

358
 Application Hosting
Application Hosting on Cisco Catalyst 9400 Series Switches

Stack Mode Apps Ports Used Behavior

Cisco Catalyst 9300X 2 2 Not supported.

Series Switch active +
Note Two applications, for
Cisco Catalyst 9300
example, app1 and app2
Series Switch standby
are running, with each
application using a
different front-panel port,
for example, port1 and
port2 respectively.
After a switchover, app1
on front-panel port1 starts
on Cisco Catalyst 9300
Series Switch in a running
state. However, app2 is
not started on Cisco
Catalyst 9300 Series
Switch as there is no
front-panel port2.

Catalyst 9300 Series 1 or more 1 Supported.

Switch active + Catalyst
Note After a switchover, the
9300X Series Switch
application is restarted on
standby
Catalyst 9300X Series
Switch using the
front-panel port.

Application Hosting on Cisco Catalyst 9400 Series Switches

This section describes application-hosting on Cisco Catalyst 9400 Series Switches.
Cisco Catalyst 9400 Series Switches support the management interface and front-panel ports for application
hosting. Applications can be hosted on C9400-SSD-240GB, C9400-SSD-480GB, and C9400-SSD-960GB
solid state drives (SSDs).
These switches use the M2 SATA module for application hosting. For more information, see the "M2 SATA
Module" chapter in the Interfaces and Hardware Configuration Guide.
On Cisco Catalyst 9400 Series Switches, applications can be hosted only on active supervisors. After a
switchover, the AppGigbitEthernet interface on the newly active supervisor becomes active and can be used
for application hosting.

Application Hosting on Cisco Catalyst 9410 Series Switches

In Cisco IOS XE Bengaluru 17.5.1, application hosting is supported on Cisco Catalyst 9410 Series Switches.
To enable the AppGigabitEthernet interface for application hosting, configure the enable command in interface
configuration mode.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

359
 Application Hosting
Application Hosting on Cisco Catalyst 9410 Series Switches

Note The enable command is available only on Cisco Catalyst 9410 Series Switches.

When using slot 4 of the 48-port linecard for application hosting, the port must be in the default shutdown
mode. If slot 4 of the 48-port linecard is active, application hosting is rejected. If the linecard port is disabled,
slot 4 of the 48-port linecard is marked as inactive.
If slot 4 of the 48-port linecard is populated, the port 4/0/48 will not come up. If linecard 4 is empty or if it is
a 24-port linecard, no ports are disabled.
To enable the port (4/0/48), disable application hosting by using the no iox command. No system messages
are displayed on the console when the port is enabled or disabled.
During an In-Service Software Upgrade (ISSU), the linecard port is not automatically disabled, because the
AppGigabitEthernet interface has to be enabled. Before a software downgrade, the AppGigabitEthernet
interface must be disabled to disable the front-panel port.

Online Insertion and Removal

Table 44: Online Insertion and Removal (OIR) Scenarios

OIR Scenario Action

The linecard on slot 4 is empty, and the No port is disabled.

AppGigabitEthernet interface is enabled.

The linecard on slot 4 is a 48-port linecard, and the Port 48 on slot 4 is disabled. After the port is disabled,
AppGigabitEthernet interface is enabled. no configuration is applied to the port. Port 48 is
marked as inactive.

The linecard on slot 4 is a 24-port linecard. No port on slot 4 is disabled.

The linecard on slot 4 is a 48-port linecard that is No port on slot 4 is disabled.

replaced by a 24-port linecard, and the
AppGigabitEthernet interface is enabled.

The linecard on slot 4 is a 24-port linecard that is Port 48 on slot 4 is disabled.

replaced by a 48-port linecard, and the
AppGigabitEthernet interface is enabled.

During OIR, the standby Supervisor becomes the new No state change will happen to port 48 on slot 4. The
active, and the front-panel port on the new active is standby Supervisor OIR has no effect on the active
used for app hosting. Supervisor front-panel port.

Cisco StackWise Virtual

This section describes the scenarios when uplink ports in a dual Supervisor are used as StackWise Virtual
links:
• When application hosting is enabled, and port 48 on linecard 4 is not up, it is disabled on both the active
and standby chassis.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

360
 Application Hosting
Application Hosting on Cisco Catalyst 9500 Series Switches

• If the link is up on either the active or standby chassis on port 48 linecard 4, then the enable command
is rejected.
• If port 48 on linecard 4 is used as a dual-active detection (DAD) link, remove the DAD link, and configure
it on another port.
• If port 48 on linecard 4 is used as a StackWise Virtual link, and the front-panel port must be enabled,
remove the StackWise Virtual link on port 48 and use another port as the StackWise Virtual link. Port
48 on linecard 4 cannot be used as a StackWise Virtual or DAD link.

Application Hosting on Cisco Catalyst 9500 Series Switches

Cisco Catalyst 9500-High Performance Series Switches support only M2 SATA modules, SSD-240G,
SSD-480G, and SSD-960 (C9k-F1-SSD-240GB). Front-panel USB is not supported.
For more information, see the "M2 SATA Module" of the Interface and Hardware Components Configuration
Guide, Cisco IOS XE Amsterdam 17.2.x (Catalyst 9500 Switches).
In Cisco IOS XE Cupertino 17.7.1, Cisco Catalyst 9500X Series Switches support application hosting on
AppGigabitEthernet interfaces. Application Hosting is supported on the M2 SATA modules: SSD-240G,
SSD-480G, and SSD-960 (C9k-F1-SSD-240GB).

Application Hosting on Cisco Catalyst 9600 Series Switches

Cisco Catalyst 9600 Series Switches support only M2 SATA modules for application hosting; front-panel
USB is not supported. The following M2 SATA modules are supported: SSD-240G, SSD-480G, and SSD-960
(C9k-F2-SSD-240GB)
For more information, see the "M2 SATA Module" of the Interface and Hardware Components Configuration
Guide, Cisco IOS XE Amsterdam 17.2.x (Catalyst 9600 Switches).

Autotransfer and Auto-Install of Apps from Internal Flash to SSD

When IOx is enabled, it chooses the best available media, and starts the IOx service using that media. IOx
also selects the media to run the applications at startup.
When IOx is restarted and a different media is selected, all applications (only Docker applications are
supported.) must be migrated to the new media, and the containers must be restored to the same state as before
the change. All persistent data and volumes attached to an application must also be migrated.
During a restart, IOx selects the media in the following order of precedence:
1. Harddisk
2. Flash
Flash only supports Guest Shell; no other applications are allowed.

Use Cases
This section describes a couple of use cases during autotransfer and auto-install of applications.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

361
 Application Hosting
Native Docker Container: Application Auto-Restart

Table 45: Use Cases for the AutoTransfer and Auto-Install of Applications

Use Case Result

SSD is plugged in while IOx is running on flash. If the SSD is plugged in while IOx is already running,
there is no impact to the running applications or to
IOx. IOx is migrated to the SSD only when IOx is
restarted by disabling and then enabling IOx through
the CLI, or due to a system restart.

System reboots, while IOx data is being copied to the While IOx data is getting migrated from one media
new media. to another, and the system reboots, the migration
process will continue, when the system restarts. The
data from the old media is deleted only when the copy
operation is complete.

Native Docker Container: Application Auto-Restart

The Application Auto-Restart feature helps applications deployed on platforms to retain the last configured
operational state in the event of a system switchover or restart. The underlying hosting framework is also
retained during switchovers. This feature is enabled by default, and cannot be disabled by users.
The persistent data of applications is not synchronized; only secure data storage and persistent data that is
known to Cisco Application Framework (CAF) is synchronized.
IOx media present on the active and standby devices must be in-sync to restart IOx in the same state upon a
switchover or system restart.
Cisco Catalyst 9300 Series Switches only support Solid State Drive (SSD) for application hosting. When a
new SSD is inserted, it needs to be brought up to the same sync state as the others. The standby device must
have an SSD that is compatible with IOx for application auto-restart synchronization to work.
The output of the show iox-service command displays the status of the synchronization.
The Application Auto-Restart feature is supported only on Cisco Catalyst 9300 Series Switches.

Application Auto-Restart Scenarios

This section describes various application auto-restart scenarios:

Table 46: Application Auto-Restart Scenarios

Scenario Single Media in the Active Device Media in the Active and Standby
Devices

System bootup Starts IOx and the application at Starts IOx and the application on
system bootup. The USB SSD is system bootup. Does a bulk
visible immediately because it is a synchronization of the existing
local device. No synchronization information to the standby device.
happens at this time.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

362
 Application Hosting
Application Auto-Restart on Cisco Catalyst 9300 Series Switches

Scenario Single Media in the Active Device Media in the Active and Standby
Devices

Switchover Media is not found on the new Starts IOx and the application in
active device. IOx starts on the the previous state on the new active
system flash with no previously device after the system switchover
installed applications and with (SSO). Does a bulk synchronization
minimum capabilities. of the information to the new
standby device after it boots up.

Bootup or switchover: USB SSD No synchronization of the SSD No synchronization of the SSD
is present on a member device. present in member devices. The present in member devices. The
member SSD is not used to host member SSD is not used to host
IOx and applications. IOx and applications.

Device removal: Local USB SSD When the local USB SSD is IOx takes care of the graceful exit.
is removed from the active device. removed, IOx takes care of the Since IOx operates only on the
graceful exit. local disk, the standby SSD is not
used to start IOx.
User-triggered IOx restart is
required once SSD is plugged back User-triggered IOx restart is
in the active device. required once SSD is plugged back
in the active device.

Device removal: USB SSD is NA IOx synchronization operation fails.

removed from the standby device. IOx is no longer SSO ready.

Device removal: Remote USB SSD IOx does not use any member SSD, IOx does not use any member SSD,
is removed from a remote member and hence, there is no impact. and hence, there is no impact.
device.

Device going down: The active Media is not found on the new Starts IOx and applications in the
device on which IOx is running active device. IOx starts up on the state before the SSO on the new
goes down. system flash with no previously active device. Does a bulk
installed applications and with synchronization of the information
minimum capabilities. to the new standby device once it
boots up.

Designated active-standby device The change is reflected after the The change is reflected after the
change (stack environment 1:1) reboot. IOx starts from the new reboot. IOx starts from the new
active device after the reboot. active device after the reboot.

Application Auto-Restart on Cisco Catalyst 9300 Series Switches

This section describes how application auto-restart works on Cisco Catalyst 9300 Series Switches in a
multimember stack:
On Cisco Catalyst 9300 Series Switches, application auto-restart is supported in 1+1 switch redundancy or
StackWise Virtual modes that assign the active and standby roles to specific devices in the stack.
Application auto-restart is not supported when the switch stack in is N+1 mode. If the device is in N+1 mode,
the following log message is displayed on the console:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

363
 Application Hosting
Supported Network Types

Feb 5 20:29:17.022: %IOX-3-IOX_RESTARTABITLITY: Switch 1 R0/0: run_ioxn_caf:Stack is in N+1

mode,
disabling sync for IOx restartability

IOx uses a Cisco-certified USB3.0 flash drive in the back-panel USB port as storage for application hosting.
This media may not be present in all the stack members.
Data is synced using the rsync utility from the active to the standby device.

Supported Network Types

This section lists the types of networks supported on Cisco Catalyst Switches.

Table 47: Supported Network Types

Network Type Supported Platform and Release

Management port • Catalyst 9300 Series Switches and C9300L in

Cisco IOS XE Gibraltar 16.12.1
• Catalyst 9400 Series Switches in Cisco IOS XE
Amsterdam 17.1.1
• Catalyst 9500 Series Switches and Catalyst
9500-High Performance Series Switches in Cisco
IOS XE Amsterdam 17.2.1
• Catalyst 9600 Series Switches in Cisco IOS XE
Amsterdam 17.2.1

Front-panel port (trunk and VLAN) • Catalyst 9300 Series Switches and C9300L in
Cisco IOS XE Gibraltar 16.12.1
• Catalyst 9400 Series Switches in Cisco IOS XE
Amsterdam 17.1.1
• Catalyst 9500- High Performance Series
Switches in Cisco IOS XE Amsterdam 17.5.1
• Catalyst 9600 Series Switches in Cisco IOS XE
Amsterdam 17.5.1
• Catalyst 9300X Series Switches in Cisco IOS
XE Bengaluru 17.6.1
Note Catalyst 9300X Series Switches
support multiple AppGigabitEthernet
ports.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

364
 Application Hosting
Virtual Network Interface Card

Network Type Supported Platform and Release

Cisco IOS Network Address Translation (NAT) • Catalyst 9300 Series Switches and C9300L in
Cisco IOS XE Gibraltar 16.12.1
• Catalyst 9400 Series Switches in Cisco IOS XE
Amsterdam 17.1.1

On both these platforms, NAT is supported through

the hardware data-port features applied on the
front-panel data ports and on the AppGigabitEthernet
port.

Cisco IOx NAT Not supported

Virtual Network Interface Card

To manage the life cycle of an application container, the Layer 3 routing model that supports one container
per internal logical interface is used. This means that a virtual Ethernet pair is created for each application,
and one interface of this pair, called the Virtual Network Interface Card (vNIC) is part of the application
container.
NIC is the standard Ethernet interface inside the container that connects to the platform data plane for the
sending and receiving of packets. Cisco IOx is responsible for assigning the IP address and unique MAC
address for each vNIC in the container.
The vNICs inside a container are considered as standard Ethernet interfaces.

ERSPAN Support on the AppGigabitEthernet Port

Encapsulated Remote SPAN (ERSPAN) support on the AppGigabitEthernet port enables the mirroring of
data traffic from the device to an application that runs on the AppGigabitEthernet port by using IOx.

Note The IOx process must be running before the IOx virtual application can be hosted on a Cisco device.

How to Configure Application Hosting

The following sections provide information about the various tasks that comprise the configuration of application
hosting.

Enabling Cisco IOx

Perform this task to enable access to Cisco IOx, which provides a CLI-based user interface that you can use
to manage, administer, monitor, and troubleshoot the apps on the host system, and to perform a variety of
related activities.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

365
 Application Hosting
Configuring Application Hosting on Front-Panel VLAN Ports

SUMMARY STEPS
1. enable
2. configure terminal
3. iox
4. username name privilege level password {0 | 7 | user-password}encrypted-password
5. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 iox Enables Cisco IOx.

Example:
Device(config)# iox

Step 4 username name privilege level password {0 | 7 | Establishes a username-based authentication system and
user-password}encrypted-password privilege level for the user.
Example: • The username privilege level must be configured as
Device(config)# username cisco privilege 15 15.
password 0 ciscoI

Step 5 end Exits global configuration mode and returns to privileged

EXEC configuration mode.
Example:
Device(config)# end

Configuring Application Hosting on Front-Panel VLAN Ports

Note This task is applicable to Cisco IOS XE Amsterdam 17.1.1 and later releases.

In application-hosting trunk-configuration mode, all the allowed AppGigabitEthernet VLAN ports are connected
to a container. Native and VLAN-tagged frames are transmitted and received by the container guest interface.
Only one container guest interface can be mapped to the AppGigabitEthernet trunk port.
Concurrent configuration of both trunk and vlan-access ports are supported.

SUMMARY STEPS
1. enable

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

366
 Application Hosting
Configuring Application Hosting on Front-Panel VLAN Ports

2. configure terminal
3. interface AppGigabitEthernet number
4. switchport trunk allowed vlan vlan-ID
5. switchport mode trunk
6. exit
7. app-hosting appid name
8. app-vnic AppGigabitEthernet trunk
9. vlan vlan-ID guest-interface guest-interface-number
10. guest-ipaddress ip-address netmask netmask
11. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 interface AppGigabitEthernet number Configures the AppGigabitEthernet and enters interface
configuration mode.
Example:
Device(config)# interface AppGigabitEthernet 1/0/1 • For stackable switches, the number argument is
switch-number/0/1.

Step 4 switchport trunk allowed vlan vlan-ID Configures the list of VLANs allowed on the trunk.
Example:
Device(config-if)# switchport trunk allowed vlan
10-12,20

Step 5 switchport mode trunk Sets the interface into permanent trunking mode and
negotiates to convert the neighboring link into a trunk link.
Example:
Device(config-if)# switchport mode trunk

Step 6 exit Exits interface configuration mode and returns to global

configuration mode.
Example:
Device(config-if)# exit

Step 7 app-hosting appid name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid iox_app

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

367
 Application Hosting
Configuring Application Hosting on Front-Panel Trunk Ports

Command or Action Purpose

Step 8 app-vnic AppGigabitEthernet trunk Configures a trunk port as the front-panel port for an
application, and enters application-hosting
Example:
trunk-configuration mode.
Device(config-app-hosting)# app-vnic
AppGigabitEthernet trunk

Step 9 vlan vlan-ID guest-interface guest-interface-number Configures a VLAN guest interface and enters
application-hosting VLAN-access IP configuration mode.
Example:
Device(config-config-app-hosting-trunk)# vlan 10 • Multiple VLAN-to-guest interface mapping is
guest-interface 2 supported.

Step 10 guest-ipaddress ip-address netmask netmask (Optional) Configures a static IP address.

Example:
Device(config-config-app-hosting-vlan-access-ip)#
guest-ipaddress 192.168.0.2
netmask 255.255.255.0

Step 11 end Exits application-hosting VLAN-access IP configuration

mode and returns to privileged EXEC mode.
Example:
Device(config-config-app-hosting-vlan-access-ip)#
end

Configuring Application Hosting on Front-Panel Trunk Ports

In application-hosting trunk-configuration mode, all the allowed AppGigabitEthernet VLAN ports are connected
to a container. Native and VLAN-tagged frames are transmitted and received by the container guest interface.
Only one container guest interface can be mapped to the AppGigabitEthernet trunk port.
In Cisco IOS XE Gibraltar 16.2.1, you can configure an app-ID in either application-hosting trunk configuration
mode or application-hosting VLAN-access configuration mode; but not in both modes.
In Cisco IOS XE Amsterdam 17.1.1 and later releases, concurrent configuration of both trunk and vlan-access
ports is supported.

SUMMARY STEPS
1. enable
2. configure terminal
3. interface AppGigabitEthernet number
4. switchport trunk allowed vlan vlan-ID
5. switchport mode trunk
6. exit
7. app-hosting appid name
8. app-vnic AppGigabitEthernet trunk
9. guest-interface guest-interface-number
10. end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

368
 Application Hosting
Configuring Application Hosting on Front-Panel Trunk Ports

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 interface AppGigabitEthernet number Configures the AppGigabitEthernet and enters interface
configuration mode.
Example:
Device(config)# interface AppGigabitEthernet 1/0/1 • For stackable switches, the number argument is
switch-number/0/1.

Step 4 switchport trunk allowed vlan vlan-ID Configures the list of VLANs allowed on the trunk.
Example:
Device(config-if)# switchport trunk allowed vlan
10-12,20

Step 5 switchport mode trunk Sets the interface into permanent trunking mode and
negotiates to convert the neighboring link into a trunk link.
Example:
Device(config-if)# switchport mode trunk

Step 6 exit Exits interface configuration mode and returns to global

configuration mode.
Example:
Device(config-if)# exit

Step 7 app-hosting appid name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid iox_app

Step 8 app-vnic AppGigabitEthernet trunk Configures a trunk port as the front-panel port for an
application, and enters application-hosting
Example:
trunk-configuration mode.
Device(config-app-hosting)# app-vnic
AppGigabitEthernet trunk

Step 9 guest-interface guest-interface-number Configures an application’s interface that is connected to

the AppGigabitEthernet interface trunk.
Example:
Device(config-config-app-hosting-trunk)#
guest-interface 2

Step 10 end Exits application-hosting trunk-configuration mode and

returns to privileged EXEC mode.
Example:
Deviceconfig-config-app-hosting-trunk)# end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

369
 Application Hosting
Starting an Application in Configuration Mode

Starting an Application in Configuration Mode

The start command in application-hosting configuration mode is equivalent to the app-hosting activate
appid and app-hosting start appid commands.
The no start command in application-hosting configuration mode is equivalent to the app-hosting stop appid
and app-hosting deactivate appid commands.

Note If the start command is configured before an application is installed, and then the install command is
configured, Cisco IOx automatically performs internal activate and start actions. This allows the
application to be automatically started by configuring the install command.

SUMMARY STEPS
1. enable
2. configure terminal
3. app-hosting appid application-name
4. start
5. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 app-hosting appid application-name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid iox_app

Step 4 start (Optional) Starts and runs an application.

Example: • Use the no start command to stop the application.
Device(config-app-hosting)# start

Step 5 end Exits application-hosting configuration mode and returns

to privileged EXEC mode.
Example:
Device(config-app-hosting)# end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

370
 Application Hosting
Lifecycle of an Application

Lifecycle of an Application
The following EXEC commands take you through an application's lifecycle.

Note If any configuration changes are made after an application is installed, the application in the running
state will not reflect these changes. The application must be explicitly stopped and deactivated, and then
activated and started again for the configuration changes to take effect.

SUMMARY STEPS
1. enable
2. app-hosting install appid application-name package package-path
3. app-hosting activate appid application-name
4. app-hosting start appid application-name
5. app-hosting stop appid application-name
6. app-hosting deactivate appid application-name
7. app-hosting uninstall appid application-name

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 app-hosting install appid application-name package Installs an application from the specified location.
package-path
• An application can be installed from a local storage
Example: location such as, flash, bootflash, usbflash0, usbflash1,
Device# app-hosting install appid iox_app package and harddisk.
usbflash1:my_iox_app.tar

Step 3 app-hosting activate appid application-name Activates the application.

Example: • This command validates all the application resource
Device# app-hosting activate appid iox_app requests, and if all the resources are available, the
application is activated; if not, the activation fails.

Step 4 app-hosting start appid application-name Starts the application.

Example: • Application start-up scripts are activated.
Device# app-hosting start appid iox_app

Step 5 app-hosting stop appid application-name (Optional) Stops the application.

Example:
Device# app-hosting stop appid iox_app

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

371
 Application Hosting
Configuring Docker Run Time Options

Command or Action Purpose

Step 6 app-hosting deactivate appid application-name (Optional) Deactivates all the resources allocated for the
application.
Example:
Device# app-hosting deactivate appid iox_app

Step 7 app-hosting uninstall appid application-name (Optional) Uninstalls the application.

Example: • Uninstalls all the packaging and images stored. All the
Device# app-hosting uninstall appid iox_app changes and updates to the application are also
removed.

Configuring Docker Run Time Options

You can add a maximum of 30 lines of run time options. The system generates a concatenated string from
line 1 though line 30. A string can have more than one Docker run time option.
When a run time option is changed, stop, deactivate, activate, and start the application for the new run time
options to take effect.

SUMMARY STEPS
1. enable
2. configure terminal
3. app-hosting appid application-name
4. app-resource docker
5. run-opts options
6. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 app-hosting appid application-name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid iox_app

Step 4 app-resource docker Enters application-hosting docker-configuration mode to

specify application resource updates.
Example:
Device(config-app-hosting)# app-resource docker

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

372
 Application Hosting
Configuring a Static IP Address in a Container

Command or Action Purpose

Step 5 run-opts options Specifies the Docker run time options.
Example:
Device(config-app-hosting-docker)# run-opts 1 "-v
$(APP_DATA):/data"

Step 6 end Exits application-hosting docker-configuration mode and

returns to privileged EXEC mode.
Example:
Device(config-app-hosting-docker)# end

Configuring a Static IP Address in a Container

When configuring a static IP address in a container, the following guidelines apply:
• Only the last configured default gateway configuration is used.
• Only the last configured name server configuration is used.

You can configure the IP address of a container through Cisco IOS CLIs.

SUMMARY STEPS
1. enable
2. configure terminal
3. app-hosting appid name
4. name-server# ip-address
5. app-vnic management guest-interface interface-number
6. guest-ipaddress ip-address netmask netmask
7. exit
8. app-default-gateway ip-address guest-interface network-interface
9. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 app-hosting appid name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid iox_app

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

373
 Application Hosting
Configuring Application Hosting on the Management Port

Command or Action Purpose

Step 4 name-server# ip-address Configures the Domain Name System (DNS) server.
Example:
Device(config-app-hosting)# name-server0 10.2.2.2

Step 5 app-vnic management guest-interface interface-number Configures the management gateway of the virtual network
interface and guest interface, and enters application-hosting
Example:
management-gateway configuration mode.
Device(config-app-hosting)# app-vnic management
guest-interface 0

Step 6 guest-ipaddress ip-address netmask netmask Configures the management guest interface details.
Example:
Device(config-app-hosting-mgmt-gateway)#
guest-ipaddress 172.19.0.24
netmask 255.255.255.0

Step 7 exit Exits application-hosting management-gateway

configuration mode and returns to application-hosting
Example:
configuration mode.
Device(config-app-hosting-mgmt-gateway)# exit

Step 8 app-default-gateway ip-address guest-interface Configures the default management gateway.

network-interface
Example:
Device(config-app-hosting)# app-default-gateway
172.19.0.23
guest-interface 0

Step 9 end Exits application-hosting configuration mode and returns

to privileged EXEC mode.
Example:
Device(config-app-hosting)# end

Configuring Application Hosting on the Management Port

SUMMARY STEPS
1. enable
2. configure terminal
3. interface gigabitethernet0/0
4. vrf forwarding vrf-name
5. ip address ip-address mask
6. exit
7. app-hosting appid name
8. app-vnic management guest-interface network-interface
9. end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

374
 Application Hosting
Configuring Application Hosting on the Management Port

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 interface gigabitethernet0/0 Configures an interface and enters interface configuration

mode.
Example:
Device(config)# interface gigabitethernet0/0 • On Cisco Catalyst 9000 Series Switches, the
management interface is GigabitEthernet0/0.

Step 4 vrf forwarding vrf-name Associates a Virtual Routing and Forwarding (VRF)
instance or a virtual network with an interface or
Example:
subinterface.
Device(config-if)# vrf forwarding Mgmt-vrf
• Mgmt-vrf is automatically set for the management
interface on the Cisco Catalyst 9000 Series Switch.

Step 5 ip address ip-address mask Configures an IP address for the interface.

Example:
Device(config-if)# ip address 198.51.100.1
255.255.255.254

Step 6 exit Exits interface configuration mode and returns to global

configuration mode.
Example:
Device(config-if)# exit

Step 7 app-hosting appid name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid iox_app

Step 8 app-vnic management guest-interface network-interface Connects the guest interface to the management port, and
enters application-hosting management-gateway
Example:
configuration mode.
Device(config-app-hosting)# app-vnic management
guest-interface 1 • The management keyword specifies the Cisco IOS
management GigabitEthernet0/0 interface that is
connected to the container.
• The guest-interface network-interface
keyword-argument pair specifies the container's
internal Ethernet interface number that is connected
to the Cisco IOS management interface. The example

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

375
 Application Hosting
Manually Configuring the IP Address for an Application

Command or Action Purpose

provided here uses guest-interface 1 for the container's
Ethernet 1 interface.

Step 9 end Exits application-hosting management-gateway

configuration mode and returns to privileged EXEC mode.
Example:
Device(config-app-hosting-mgmt-gateway)# end

Manually Configuring the IP Address for an Application

You can set up the IP address of a container using the following methods:
• Log into the container, and configure the ifconfig Linux command.
1. Log in to the application by using the following command:
app-hosting connect appid APPID {session | console}

2. Based on the application's Linux support, use the standard Linux interface configuration commands:
- ifconfig dev IFADDR/subnet-mask-length

Or
- ip address {add|change|replace} IFADDR dev IFNAME [ LIFETIME ] [ CONFFLAG-LIST ]

• Enable the Dynamic Host Configuration Protocol (DHCP) in the container, and configure the DHCP
server and relay agent in the Cisco IOS configuration.
• Cisco IOx provides a DHCP client to run within the application container that is used for an
application DHCP interface.

Overriding App Resource Configuration

For resource changes to take effect, you must first stop and deactivate an app using the app-hosting stop and
app-hosting deactivate commands, and then restart the app using the app-hosting activate and app-hosting
start commands.
If you are using the start command in application-hosting configuration mode, configure the no start and
start commands.
You can use these commands to reset both resources and the app-hosting appid iox_app configuration.

SUMMARY STEPS
1. enable
2. configure terminal
3. app-hosting appid name
4. app-resource profile name
5. cpu unit
6. memory memory
7. vcpu number

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

376
 Application Hosting
Configuring ERSPAN Support on the AppGigabitEthernet Port

8. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 app-hosting appid name Enables application hosting and enters application-hosting
configuration mode.
Example:
Device(config)# app-hosting appid iox_app

Step 4 app-resource profile name Configures the custom application resource profile, and
enters custom application resource profile configuration
Example:
mode.
Device(config-app-hosting)# app-resource profile
custom • Only the custom profile name is supported.

Step 5 cpu unit Changes the default CPU allocation for the application.
Example: • Resource values are application specific, and any
Device(config-app-resource-profile-custom)# cpu adjustment to these values must ensure that the
7400 application can run reliably with the changes.

Step 6 memory memory Changes the default memory allocation.

Example:
Device(config-app-resource-profile-custom)# memory
2048

Step 7 vcpu number Changes the virtual CPU (vCPU) allocation for the
application.
Example:
Device(config-app-resource-profile-custom)# vcpu
2

Step 8 end Exits custom application resource profile configuration

mode and returns to privileged EXEC mode.
Example:
Device(config-app-resource-profile-custom)# end

Configuring ERSPAN Support on the AppGigabitEthernet Port

Perform the following tasks to configure ERSPAN through the AppGigabitEthernet Interface.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

377
 Application Hosting
Configuring an ERSPAN Source Session

Note The IOx process must be running before the IOx virtual application can be hosted on a Cisco device.

Configuring an ERSPAN Source Session

SUMMARY STEPS
1. enable
2. configure terminal
3. monitor session span-session-number type erspan-source
4. source interface interface-type interface-id
5. no shutdown
6. ip address ip-address
7. origin ip address ip-address
8. erspan-id erspan-flow-id
9. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 monitor session span-session-number type erspan-source Defines an ERSPAN source session using the session ID
and the session type, and enters ERSPAN monitor source
Example:
session configuration mode.
Device(config)# monitor session 2 type
erspan-source

Step 4 source interface interface-type interface-id Configures the source interface, and the traffic direction to
be monitored.
Example:
Device(config-mon-erspan-src)# source interface
gigabitethernet 1/0/3

Step 5 no shutdown Enables the configured sessions on an interface.

Example:
Device(config-mon-erspan-src)# no shutdown

Step 6 ip address ip-address Configures the IP address that is used as the destination of
the ERSPAN traffic.
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

378
 Application Hosting
Configuring the AppGigabitEthernet Interface for ERSPAN

Command or Action Purpose

Device(config-mon-erspan-src-dst)# ip address
10.1.1.5

Step 7 origin ip address ip-address Configures the IP address used as the source of the
ERSPAN traffic.
Example:
Device(config-mon-erspan-src-dst)# origin ip
address 10.1.1.2

Step 8 erspan-id erspan-flow-id Configures the ID used by source and destination sessions
to identify the ERSPAN traffic, which must also be entered
Example:
in the ERSPAN destination session configuration.
Device(config-mon-erspan-src-dst)# erspan-id 5

Step 9 end Exits ERSPAN monitor source session configuration mode

and returns to privileged EXEC mode.
Example:
Device(config-mon-erspan-src-dst)# end

Configuring the AppGigabitEthernet Interface for ERSPAN

• Configure a VLAN for traffic mirroring. Steps 1 to 9.
• Configure the AppGigabitEthernet interface to transport ERSPAN-mirrored data traffic to the IOx virtual
application. Steps 10 to 14.

You can either use a Layer 2 port or a Layer 3 port from ERSPAN traffic. Use the no switchport mode
command to change the port from a Layer 2 interface to a Layer 3 interface.

SUMMARY STEPS
1. enable
2. configure terminal
3. vtp mode off
4. vlan {vlan-ID | vlan-range}
5. exit
6. interface vlan vlan-ID
7. ip address ip-address mask
8. no shutdown
9. exit
10. interface AppGigabitEthernet number
11. (Optional) no switchport mode
12. (Optional) ip address ip-address mask
13. (Optional) switchport mode trunk
14. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

379
 Application Hosting
Configuring the AppGigabitEthernet Interface for ERSPAN

Command or Action Purpose

Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 vtp mode off Sets the VTP-device mode to off for VLANs.
Example:
Device(config)#vtp mode off

Step 4 vlan {vlan-ID | vlan-range} Adds a VLAN and enters config-VLAN configuration
mode.
Example:
Device(config)# vlan 2508

Step 5 exit Exits config-vlan configuration mode and returns to global

configuration mode.
Example:
Device(config-vlan)# exit

Step 6 interface vlan vlan-ID Creates a dynamic Switch Virtual Interface (SVI) and
enters the interface configuration mode.
Example:
Device(config)# interface vlan 2508

Step 7 ip address ip-address mask Configures an IP address.

Example:
Device(config-if)# ip address 192.0.2.1
255.255.255.252

Step 8 no shutdown Restarts a disabled interface.

Example:
Device(config-if)# no shutdown

Step 9 exit Exits interface configuration mode and returns to global

configuration mode.
Example:
Device(config-if)# exit

Step 10 interface AppGigabitEthernet number Configures the AppGigabitEthernet and enters interface
configuration mode.
Example:
Device(config)# interface AppGigabitEthernet 1/1 • For stackable switches, the number argument is
switch-number/0/1.

Note You can either use a Layer 2 or a Layer 3 port.

Step 11 (Optional) no switchport mode Changes the port from a Layer 2 interface to a Layer 3
interface.
Example:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

380
 Application Hosting
Verifying the Application-Hosting Configuration

Command or Action Purpose

Device(config-if)# no switchport mode

Step 12 (Optional) ip address ip-address mask Configures an IP address for a Layer 3 port.
Example:
Device(config-if)# 10.1.1.2 255.255.255.0

Step 13 (Optional) switchport mode trunk Sets the interface into permanent trunking mode and
negotiates to convert the neighboring link into a trunk link
Example:
for a Layer 2 port.
Device(config-if)# switchport mode trunk

Step 14 end Exits interface configuration mode and returns to privileged

EXEC mode.
Example:
Device(config-if)# end

Verifying the Application-Hosting Configuration

Use these show commands to verify the configuration. These commands can be used in any order.

SUMMARY STEPS
1. enable
2. show iox-service
3. show app-hosting detail
4. show app-hosting device
5. show app-hosting list
6. show interfaces trunk
7. show controller ethernet-controller AppGigabitEthernet interface-number

DETAILED STEPS

Step 1 enable
Enables privileged EXEC mode.
• Enter your password if prompted.

Example:
Device> enable

Step 2 show iox-service

Displays the status of all the Cisco IOx services.
Example:
Device# show iox-service

IOx Infrastructure Summary:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

381
 Application Hosting
Verifying the Application-Hosting Configuration

---------------------------
IOx service (CAF) : Not Running
IOx service (HA) : Not Running
IOx service (IOxman) : Not Running
IOx service (Sec storage) : Not Running
Libvirtd : Running
Dockerd : Not Running
Application DB Sync Info : Not available

Step 3 show app-hosting detail

Displays detailed information about the application.
Example:
Device# show app-hosting detail

State : Running
Author : Cisco Systems, Inc
Application
Type : vm
App id : Wireshark
Name : Wireshark
Version : 3.4
Activated Profile Name : custom
Description : Ubuntu based Wireshark
Resource Reservation
Memory : 1900 MB
Disk : 10 MB
CPU : 4000 units
VCPU : 2
Attached devices
Type Name Alias
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––--
Serial/shell
Serial/aux
Serial/Syslog serial2
Serial/Trace serial3
Network Interfaces
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
eth0:
MAC address : 52:54:dd:80:bd:59
IPv4 address
eth1:
MAC address : 52:54:dd:c7:7c:aa
IPv4 address

Step 4 show app-hosting device

Displays information about the USB device.
Example:
Device# show app-hosting device

USB port Device name Available

1 Front_USB_1 true

app-hosting appid testvm

app-vnic management guest-interface 0
app-device usb-port 1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

382
 Application Hosting
Verifying the Application-Hosting Configuration

Step 5 show app-hosting list

Displays the list of applications and their status.
Example:
Device# show app-hosting list

App id State
–––––––––––––––––––––––––––––––––––––––--
Wireshark Running

Step 6 show interfaces trunk

Displays trunk interface information.
Example:
Device# show interfaces trunk

Port Mode Encapsulation Status Native vlan

Gi3/0/1 on 802.1q trunking 1
Ap3/0/1 on 802.1q trunking 1

Port Vlans allowed on trunk

Gi3/0/1 1-4094
Ap3/0/1 1-4094

Port Vlans allowed and active in management domain

Gi3/0/1 1,8,10,100
Ap3/0/1 1,8,10,100

Port Vlans in spanning tree forwarding state and not pruned

Gi3/0/1 1,8,10,100
Ap3/0/1 1,8,10,100

Device# show runnning-config interface AppGigabitEthernet 3/0/1

Building configuration...

Current configuration : 64 bytes

!
interface AppGigabitEthernet3/0/1
switchport mode trunk
end

Step 7 show controller ethernet-controller AppGigabitEthernet interface-number

Displays the send and receive statistics for the AppGigabitEthernet interface that is read from the hardware.
Example:
Device# show controller ethernet-controller AppGigabitEthernet 1/0/1

Transmit AppGigabitEthernet1/0/1 Receive

0 Total bytes 0 Total bytes
0 Unicast frames 0 Unicast frames
0 Unicast bytes 0 Unicast bytes
0 Multicast frames 0 Multicast frames
0 Multicast bytes 0 Multicast bytes
0 Broadcast frames 0 Broadcast frames
0 Broadcast bytes 0 Broadcast bytes
0 System FCS error frames 0 IpgViolation frames
0 MacUnderrun frames 0 MacOverrun frames

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

383
 Application Hosting
Configuration Examples for Application Hosting

0 Pause frames 0 Pause frames

0 Cos 0 Pause frames 0 Cos 0 Pause frames
0 Cos 1 Pause frames 0 Cos 1 Pause frames
0 Cos 2 Pause frames 0 Cos 2 Pause frames
0 Cos 3 Pause frames 0 Cos 3 Pause frames
0 Cos 4 Pause frames 0 Cos 4 Pause frames
0 Cos 5 Pause frames 0 Cos 5 Pause frames
0 Cos 6 Pause frames 0 Cos 6 Pause frames
0 Cos 7 Pause frames 0 Cos 7 Pause frames
0 Oam frames 0 OamProcessed frames
0 Oam frames 0 OamDropped frames
0 Minimum size frames 0 Minimum size frames
0 65 to 127 byte frames 0 65 to 127 byte frames
0 128 to 255 byte frames 0 128 to 255 byte frames
0 256 to 511 byte frames 0 256 to 511 byte frames
0 512 to 1023 byte frames 0 512 to 1023 byte frames
0 1024 to 1518 byte frames 0 1024 to 1518 byte frames
0 1519 to 2047 byte frames 0 1519 to 2047 byte frames
0 2048 to 4095 byte frames 0 2048 to 4095 byte frames
0 4096 to 8191 byte frames 0 4096 to 8191 byte frames
0 8192 to 16383 byte frames 0 8192 to 16383 byte frames
0 16384 to 32767 byte frame 0 16384 to 32767 byte frame
0 > 32768 byte frames 0 > 32768 byte frames
0 Late collision frames 0 SymbolErr frames
0 Excess Defer frames 0 Collision fragments
0 Good (1 coll) frames 0 ValidUnderSize frames
0 Good (>1 coll) frames 0 InvalidOverSize frames
0 Deferred frames 0 ValidOverSize frames
0 Gold frames dropped 0 FcsErr frames
0 Gold frames truncated
0 Gold frames successful
0 1 collision frames
0 2 collision frames
0 3 collision frames
0 4 collision frames
0 5 collision frames
0 6 collision frames
0 7 collision frames
0 8 collision frames
0 9 collision frames
0 10 collision frames
0 11 collision frames
0 12 collision frames
0 13 collision frames
0 14 collision frames
0 15 collision frames
0 Excess collision frame

Configuration Examples for Application Hosting

The following are the various examples pertaining to the configuration of the Application Hosting feature.

Example: Enabling Cisco IOx

This example shows how to enable Cisco IOx.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

384
 Application Hosting
Example: Configuring Application Hosting on Front-Panel VLAN Ports

Device> enable
Device# configure terminal
Device(config)# iox
Device(config)# username cisco privilege 15 password 0 ciscoI
Device(config)# end

Example: Configuring Application Hosting on Front-Panel VLAN Ports

Note This section is applicable to Cisco IOS XE Amsterdam 17.1.1 and later releases.

This example shows how to configure application hosting on front-panel VLAN ports.
Device# configure terminal
Device(config)# interface AppGigabitEthernet 1/0/1
Device(config-if)# switchport trunk allowed vlan 10-12,20
Device(config-if)# switchport mode trunk
Device(config-if)# exit
Device(config)# app-hosting appid iox_app
Device(config-app-hosting)# app-vnic AppGigabitEthernet trunk
Device(config-config-app-hosting-trunk)# vlan 10 guest-interface 2
Device(config-config-app-hosting-vlan-access-ip)# guest-ipaddress 192.168.0.1
netmask 255.255.255.0
Device(config-config-app-hosting-vlan access-ip)# end

Example: Configuring Application Hosting on Front-Panel Trunk Ports

This example shows how to configure application hosting on front-panel trunk ports.
Device# configure terminal
Device(config)# interface AppGigabitEthernet 3/0/1
Device(config-if)# switchport trunk allowed vlan 10-12,20
Device(config-if)# switchport mode trunk
Device(config-if)# exit
Device(config)# app-hosting appid iox_app
Device(config-app-hosting)# app-vnic AppGigabitEthernet trunk
Device(config-config-app-hosting-trunk)# guest-interface 2
Device(config-config-app-hosting-trunk)# end

Example: Installing an Application from disk0:

The following example shows how to install an application from disk0:
Device> enable
Device# app-hosting install appid iperf3 package disk0:iperf3.tar

Installing package 'disk0:iperf3.tar' for 'iperf3'. Use 'show app-hosting list' for progress.

Device# show app-hosting list

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

385
 Application Hosting
Example: Starting an Application

App id State
---------------------------------------------------------
iperf3 DEPLOYED

Switch#app-hosting activate appid iperf3

iperf3 activated successfully
Current state is: ACTIVATED
Switch#
Switch#show app-hosting list
App id State
---------------------------------------------------------
iperf3 ACTIVATED

Switch#app-hosting start appid iperf3

iperf3 started successfully
Current state is: RUNNING
Switch#show app-hosting list
App id State
---------------------------------------------------------
iperf3 RUNNING

Device#

Example: Starting an Application

This example shows how to start an application.
Device> enable
Device# configure terminal
Device(config)# app-hosting appid iox_app
Device(config-app-hosting)# start
Device(config-app-hosting)# end

Example: Lifecycle for an Application

This example shows how to install and uninstall an application:

Device> enable
Device# app-hosting install appid iox_app package usbflash1:my_iox_app.tar.tar
Device# app-hosting activate appid iox_app
Device# app-hosting start appid iox_app
Device# app-hosting stop appid iox_app
Device# app-hosting deactivate appid iox_app
Device# app-hosting uninstall appid iox_app

Example: Configuring Docker Run Time Options

This example shows how to configure Docker run time options.

Device> enable
Device# configure terminal
Device(config)# app-hosting appid iox_app

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

386
 Application Hosting
Example: Configuring a Static IP Address in a Container

Device(config-app-hosting)# app-resource docker

Device(config-app-hosting-docker)# run-opts 1 "-v $(APP_DATA):/data"
Device(config-app-hosting-docker)# run-opts 3 "--entrypoint '/bin/sleep 1000000'"
Device(config-app-hosting-docker)# end

Example: Configuring a Static IP Address in a Container

This example shows how to configure a static IP address in a container.

Device> enable
Device# configure terminal
Device(config)# app-hosting appid iox_app
Device(config-app-hosting)# name-server0 10.2.2.2
Device(config-app-hosting)# app-vnic management guest-interface 0
Device(config-app-hosting-mgmt-gateway)# guest-ipaddress 172.19.0.24 netmask 255.255.255.0
Device(config-app-hosting-mgmt-gateway)# exit
Device(config-app-hosting)# app-default-gateway 172.19.0.23 guest-interface 0
Device(config-app-hosting)# end

Example: Configuring Application Hosting on the Management Port

This example shows how to manually configure the IP address for an application.
Device# configure terminal
Device(config)# interface gigabitethernet 0/0
Device(config-if)# vrf forwarding Mgmt-vrf
Device(config-if)# ip address 198.51.100.1 255.255.255.254
Device(config-if)# exit
Device(config)# app-hosting appid iox_app
Device(config-app-hosting)# app-vnic management guest-interface 1
Device(config-app-hosting-mgmt-gateway)# end

Example: Overriding App Resource Configuration

This example shows how to override an app resource configuration.

Device# configure terminal
Device(config)# app-hosting appid iox_app
Device(config-app-hosting)# app-resource profile custom
Device(config-app-resource-profile-custom)# cpu 7400
Device(config-app-resource-profile-custom)# memory 2048
Device(config-app-resource-profile-custom)# vcpu 2
Device(config-app-resource-profile-custom)# end

Example: Configuring ERSPAN Support on the AppGigabitEthernet Port

The following example shows how to configure ERSPAN on the AppGigabitEthernet Port.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

387
 Application Hosting
Example: Configuring an ERSPAN Source Session

Example: Configuring an ERSPAN Source Session

Device> enable
Device# configure terminal
Device(config)# monitor session 2 type erspan-source
Device(config-mon-erspan-src)# source interface gigabitethernet 1/0/3
Device(config-mon-erspan-src)# no shutdown
Device(config-mon-erspan-src-dst)# ip address 10.1.1.5
Device(config-mon-erspan-src-dst)# origin ip address 10.1.1.2
Device(config-mon-erspan-src-dst)# erspan-id 5
Device(config-mon-erspan-src-dst)# end

Examples: Configuring ERSPAN Through the AppGigabitEthernet Interface

The following example shows how to configure the AppGigabitEthernet interface to communicate with the
the IOx virtual application:
Layer 3 port used for ERSPAN traffic:
Device> enable
Device# configure terminal
Device(config)# vtp mode off
Device(config)# vlan 2508
Device(config-vlan)# exit
Device(config)# interface vlan 2508
Device(config-if)# ip address 192.0.2.1 255.255.255.252
Device(config-if)# no shutdown
Device(config-if)# exit
Device(config)# interface AppGigabitEthernet 1/1
Device(config-if)# no switchport mode
Device(config-if)# ip address 10.1.1.2 255.255.255.0
Device(config-if)# end

The following example shows a Layer 2 port used for ERSPAN traffic:
Device> enable
Device# configure terminal
Device(config)# vtp mode off
Device(config)# vlan 2508
Device(config-vlan)# exit
Device(config)# interface vlan 2508
Device(config-if)# ip address 192.0.2.1 255.255.255.252
Device(config-if)# no shutdown
Device(config-if)# exit
Device(config)# interface AppGigabitEthernet 1/1
Device(config-if)# switchport mode trunk
Device(config-if)# end

Additional References
Related Documents

Related Topic Document Title

Programmability commands Programmability Command Reference

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

388
 Application Hosting
Feature Information for Application Hosting

Related Topic Document Title

DevNet https://developer.cisco.com/docs/app-hosting/

M2 SATA on Cisco Catalyst 9400 Series Switches M2 SATA Module

M2 SATA on Cisco Catalyst 9500-High Performance Series M2 SATA Module

Switches

M2 SATA on Cisco Catalyst 9600 Series Switches M2 SATA Module

USB3.0 SSD on Cisco Catalyst 9300 Series Switches Configuring USB 3.0 SSD

USB3.0 SSD on Cisco Catalyst 9500 Series Switches Configuring USB 3.0 SSD

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for Application Hosting

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

389
 Application Hosting
Feature Information for Application Hosting

Table 48: Feature Information for Application Hosting

Feature Name Release Feature Information

Application Hosting Cisco IOS XE Gibraltar A hosted application is a software as a service

16.12.1 (SaaS) solution, and users can execute and
operate this solution entirely from the cloud.
Cisco IOS XE Amsterdam
This module describes the Application Hosting
17.1.1
feature and how to enable it.
Cisco IOS XE Amsterdam
• In Cisco IOS XE Gibraltar 16.12.1, this
17.2.1
feature was implemented on Cisco
Cisco IOS XE Bengaluru Catalyst 9300 Series Switches.
17.5.1
• In Cisco IOS XE Amsterdam 17.1.1, this
Cisco IOS XE Cupertino feature was implemented on Cisco
17.7.1 Catalyst 9400 Series Switches.
• In Cisco IOS XE Amsterdam 17.2.1, this
feature was implemented on Cisco
Catalyst 9500-High Performance Series
Switches, and Cisco Catalyst 9600 Series
Switches.
• In Cisco IOS XE Bengaluru 17.5.1, this
feature was implemented on Cisco
Catalyst 9410 Series Switches.
• In Cisco IOS XE Cupertino 17.7.1, this
feature was implemented on Cisco
Catalyst 9500X Series Switches.

Application Hosting: Cisco IOS XE Bengaluru When IOx is restarted and a different media
Autotransfer and Auto-Install 17.6.1 is selected, all applications must be migrated
of Apps from Internal Flash to the new media, and containers must be
to SSD restored to the same state as before the change.
In Cisco IOS XE Bengaluru 17.6.1, this
feature was introduced on the following
platforms:
• Cisco Catalyst 9300 and 9300L Series
Switches
• Cisco Catalyst 9400 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

390
Application Hosting
Feature Information for Application Hosting

Feature Name Release Feature Information

Application Hosting: Cisco IOS XE Gibraltar Introduces datapath connectivity between the
Front-Panel Network Port 16.12.1 Application Hosting container and the
Access front-panel network ports. Also enables ZTP
Cisco IOS XE Amsterdam
functionality on the front-panel network.
17.1.1
• In Cisco IOS XE Gibraltar 16.12.1, this
feature was implemented on Cisco
Catalyst 9300 Series Switches.
• In Cisco IOS XE Amsterdam 17.1.1, this
feature was implemented on Cisco
Catalyst 9400 Series Switches.

Application Hosting: Cisco IOS XE Gibraltar Introduces datapath connectivity between the
Front-Panel USB Port Access 16.12.1 Application Hosting container and the
front-panel USB port.
Cisco IOS XE Amsterdam
17.1.1 • In Cisco IOS XE Gibraltar 16.12.1, this
feature was implemented on Cisco
Catalyst 9300 Series Switches.
• In Cisco IOS XE Amsterdam 17.1.1, this
feature was implemented on Cisco
Catalyst 9400 Series Switches.

ERSPAN Support on the Cisco IOS XE Dublin 17.10.1 ERSPAN support on the AppGigabitEthernet
AppGigabitEthernet Port port enables the mirroring of data traffic from
the device to an application that runs on the
AppGigabitEthernet port by using IOx.

Native Docker Container: Cisco IOS XE Amsterdam The Application Auto-Restart feature helps
Application Auto-Restart 17.2.1 applications deployed on platforms to retain
the last configured operational state in the
Cisco IOS XE Bengaluru
event of a system switchover or restart. This
17.5.1
feature is enabled by default, and cannot be
disabled by users.
• In Cisco IOS XE Amsterdam 17.2.1, this
feature was implemented on Cisco
Catalyst 9300 Series Switches.
• In Cisco IOS XE Bengaluru 17.5.1, this
feature was implemented on Cisco
Catalyst 9410 Series Switches.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

391
 Application Hosting
Feature Information for Application Hosting

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

392
 CHAPTER 16
ThousandEyes Enterprise Agent
ThousandEyes Enterprise Agent is an enterprise network-monitoring tool that provides you an end-to-end
view across networks and services that impact your business. This module describes how to download and
install the Enterprise Agent.
• Prerequisites for the ThousandEyes Enterprise Agent, on page 393
• Information About ThousandEyes Enterprise Agent, on page 394
• How to Install the ThousandEyes Enterprise Agent, on page 397
• Configuration Examples for ThousandEyes Enterprise Agent, on page 402
• Additional References, on page 406
• Feature Information for ThousandEyes Enterprise Agent, on page 406

Prerequisites for the ThousandEyes Enterprise Agent

• The ThousandEyes Enterprise Agent image available at the ThousandEyes site must be signed by the
same certificate authority (CA) that is used by www.cisco.com for HTTPS downloads; without an
username or a password.
• Installation of the Enterprise Agent requires Internet connectivity, or a proxy server. For more information,
see the ThousandEyes documentation at: https://docs.thousandeyes.com/product-documentation/
enterprise-agents.
• The Enterprise Agent application can only be used after the user’s license privileges are validated.
• Only Docker-based applications are supported.
• 1:1 stack mode is a must for ThousandEyes Stateful Switchover (SSO) support.
1:1 mode is when the active and standby roles are assigned to specific devices in a stack. This overrides
the traditional N+1 role selection algorithm, where any device in the stack can be the active or the standby.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

393
 Application Hosting
Information About ThousandEyes Enterprise Agent

Information About ThousandEyes Enterprise Agent

ThousandEyes Enterprise Agent Overview
ThousandEyes Enterprise Agent is an enterprise network-monitoring tool that provides you an end-to-end
view across networks and services that impact your business. It monitors the network traffic paths across
internal, external, carrier, and Internet networks in real time, to provide network performance data. Enterprise
Agents are commonly installed in branch sites and data centers to provide a detailed understanding of WAN
and Internet connectivity.
In previous Cisco IOS XE releases, ThousandEyes was supported as a third-party Kernel-based Virtual
Machine (KVM) appliance on the SSD.
In Cisco IOS XE Amsterdam 17.3.3, a new version of the ThousandEyes Enterprise Agent, Version 3.0 is
introduced. This is an embedded Docker-based application that runs on Cisco devices using the
application-hosting capability. The Enterprise Agent is available on both the SSD and bootflash, and it supports
all tests except browser tests (page load and transaction). The browser tests are available in Cisco IOS XE
Bengaluru 17.6.1 and later releases with Enterprise Agent Version 4.0.
The ThousandEyes Enterprise Agent provides the following:
• Benchmarking the performance of networks and applications.
• Detailed hop-by-hop metrics.
• End-to-end path visualization from branch or campus to data center or cloud.
• Outage detection and resolution.
• User-experience analysis.
• Visualization of the traffic-flow pattern.

ThousandEyes Enterprise Agent Version 4.0 available in Cisco IOS XE Bengaluru 17.6.1, supports the
following additional features that are not available in the ThousandEyes Agent Version 3.0:
• BrowserBot support when back-panel SSD is available.
• DNAC app icon and description.
• Docker health monitoring.
• The app-hosting upgrade URL command to upgrade the ThousandEyes Enterprise Agent.

Resources Required for the ThousandEyes Enterprise Agent

This table describes the required resources for installing the ThousandEyes Enterprise Agent:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

394
 Application Hosting
ThousandEyes Enterprise Agent Download

Table 49: Resources Required for the ThousandEyes Enterprise Agent

App Media Maximum Resource Supported Release

SSD • CPU: 2 vCPU Cisco IOS XE Amsterdam 17.3.3

Note Only 120G SSD is • Memory: 2G RAM • Cisco Catalyst 9300 and
supported. 9300L Series Switches
• Storage: No limit on SSD
Cisco IOS XE Bengaluru 17.5.1
• Cisco Catalyst 9400 Series
Switches

Cisco IOS XE Bengaluru 17.6.1

• Cisco Catalyst 9300X Series
Switches

Flash • CPU: 2 vCPU Cisco IOS XE Amsterdam 17.3.3

• Memory: 2G RAM • Cisco Catalyst 9300 and
9300L Series Switches
• Storage: 1G for persistent
logging by applications, out Cisco IOS XE Bengaluru 17.5.1
of the 4G partition in the flash
file system. The storage is • Cisco Catalyst 9400 Series
shared with the IOx metadata. Switches

Cisco IOS XE Bengaluru 17.6.1

• Cisco Catalyst 9300X Series
Switches

In Cisco IOS XE Bengaluru 17.6.1, add-on mode is supported on Cisco Catalyst 9300, 9300L, and 9300X
Series Switches, and Cisco Catalyst 9400 Series Switches.

ThousandEyes Enterprise Agent Download

BrownField and GreenField are two types of ThousandEyes Enterprise Agents. For existing devices, you can
download the Brownfield version from the ThousandEyes website. However, new devices are shipped with
the Greenfield application loaded in the bootflash.
This table lists the download options available for the agents.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

395
 Application Hosting
ThousandEyes BrowserBot

Table 50: ThousandEyes Enterprise Agent Download Options

BrownField GreenField

• Download the file • Available in the bootflash under the /apps folder.
https://downloads.thousandeyes.com/ Shipped with the device.
enterprise-agent/
thousandeyes-enterprise-agent-3.0.cat9k.tar. The • Use the install command to download and deploy
file is signed by the same certificate authority the application.
(CA) that is used by www.cisco.com for HTTPS
downloads; without an username or a password.
• Use the install command to download and
deploy the application.

This section describes the maximum resources required for the agent to run:
• CPU: 2 vCPUs
• Memory: 2G
• Storage: 1G for persistent logging by applications, out of the 4G partition in the flash file system. This
storage is shared by the IOx metadata.
• Media storage:
• 120G SSD for Cisco Catalyst 9300 and Cat9300 L Series Switches in Cisco IOS XE Amsterdam
17.3.3.
• 240/480/960GB M2-SATA-HDD for Cisco Catalyst 9400 Series Switches in Cisco IOS XE Bengaluru
17.5.1.

After the download of the Enterprise Agent, it initiates a call to create a secure channel to the ThousandEyes
cloud-based portal that provides the required application configuration, and gathers application data. The link
to the TE portal is https://app.thousandeyes.com.

ThousandEyes BrowserBot
ThousandEyes Enterprise Agent Version 4.0 provides a BrowserBot for transaction scripting test. The
BrowserBot is a component of the Enterprise Agent that manages page load and transaction tests. The
BrowserBot allows you to enable customized JavaScript tests which mimic the actions of your web browser
on the ThousandEyes Cloud Portal. To protect the host operating system from any errant JavaScript operations,
the ThousandEyes agent creates sandbox containers to run your JavaScript.
If an unrestricted disk is used by the application, the ThousandEyes agent will dynamically install the
BrowserBot package during initialization that permits portal transaction scripting tests to be configured.

Note The BrowserBot support is not available in ThousandEyes Agent Version 3.0.

BrowserBot consumes a large amount of hardware resources. 2GB system memory and 2 VCPU loads are
the maximum IOx system memory and CPU load allocated for all IOx apps. To allow multiple apps to

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

396
 Application Hosting
ThousandEyes Agent Upgrade and Downgrade

concurrently run in the bootflash, lower the default package.yaml BrowserBot resources before activating the
agent. Use the app-resource profile custom command to override the default package.yaml settings:
• CPU:1850 CPU units (1/4 VCPU)
• Memory: 500MB

For more information on transaction scripting, see the following links:

• https://docs.thousandeyes.com/product-documentation/tests/transaction-scripting-guide
• https://docs.thousandeyes.com/product-documentation/tests/transaction-scripting-reference

For examples of transaction scripting, see https://github.com/thousandeyes/transaction-scripting-examples.

ThousandEyes Agent Upgrade and Downgrade

ThousandEyes Agent Upgrade
The ThousandEyes Enterprise Agent 3.0 available in Cisco IOS XE Amsterdam 17.3.3 and Bengaluru 17.5.1
can be upgraded to Agent 3.0 or Agent 4.0 that is available in Cisco IOS XE Bengaluru17.6.1. Agent 3.0 is
operationally restored after an upgrade.
Agent 4.0 is available in Cisco IOS XE Bengaluru 17.6.1, and the agent auto-upgrade updates to the latest
Agent 4.0 binary on startup. No upgrade is available for Agent 4.0 at present.
Application upgrades can be done using the following methods:
• ThousandEyes agent auto-upgrade: Happens automatically when an application starts up. The agent
binary within the running container is upgraded, but the application package is not upgraded.
• Using the app-hosting upgrade command.
• DNAC app upgrades.

ThousandEyes Agent Downgrade

Agent 3.0 available in Cisco IOS XE Amsterdam 17.3.3, Cisco IOS XE Bengaluru 17.5.1, and Cisco IOS XE
17.6.1 cannot be downgraded.
Agent 4.0 available in Cisco IOS XE Bengaluru 17.6.1 can be downgraded to Agent 3.0 available in Cisco
IOS XE Bengaluru 17.6.1. No other downgrade is possible.
When downgrading, if the application does not come to the same state as the previous release, deactivate or
uninstall the application, and install or restart it.

How to Install the ThousandEyes Enterprise Agent

To install the Enterprise Agent, follow these steps:
1. Configure IOx. For more information, see the "Enabling Ciso IOx" section.
2. Configure AppHosting.
3. Configure the AppGigabitEthernet port.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

397
 Application Hosting
Configuring AppHosting for the ThousandEyes Enterprise Agent

4. Install the ThousandEyes Enterprise Agent.

Configuring AppHosting for the ThousandEyes Enterprise Agent

SUMMARY STEPS
1. enable
2. configure terminal
3. app-hosting appid application-name
4. app-vnic AppGigabitEthernet trunk
5. vlan vlan-ID guest-interface guest-interface-number
6. guest-ip ip-address netmask netmask
7. exit
8. exit
9. app-default-gateway ip-address guest-interface network-interface
10. nameserver# ip-address
11. app-resource docker
12. run-opts options
13. prepend-pkg-opts
14. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enters privileged EXEC mode.
Example:
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 app-hosting appid application-name Configures an application and enters application-hosting

configuration mode.
Example:
Device(config)# app-hosting appid appid 1keyes

Step 4 app-vnic AppGigabitEthernet trunk Configures a trunk port as the front-panel port for an
application, and enters application-hosting
Example:
trunk-configuration mode.
Device(config-app-hosting)# app-vnic
AppGigabitEthernet trunk

Step 5 vlan vlan-ID guest-interface guest-interface-number Configures a VLAN guest interface and enters
application-hosting VLAN-access IP configuration mode.
Example:
Device(config-config-app-hosting-trunk)# vlan 10
guest-interface 2

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

398
 Application Hosting
Configuring AppHosting for the ThousandEyes Enterprise Agent

Command or Action Purpose

Step 6 guest-ip ip-address netmask netmask Configures a static IP address for the guest interface.
Example:
Device(config-config-app-hosting-vlan-access-ip)#
guest-ipaddress 172.19.0.24
netmask 255.255.255.0

Step 7 exit Exits application hosting VLAN-access IP configuration

mode and returns to application-hosting
Example:
trunk-configuration mode.
Device(config-config-app-hosting-vlan-access-ip)#
exit

Step 8 exit Exits application-hosting trunk-configuration mode and

returns to application hosting configuration mode.
Example:
Device(config-config-app-hosting-trunk)# exit

Step 9 app-default-gateway ip-address guest-interface Configures the default management gateway.

network-interface
Example:
Device(config-app-hosting)# app-default-gateway
172.19.0.23
guest-interface 0

Step 10 nameserver# ip-address Configures the DNS server.

Example:
Device(config-app-hosting)# name-server0 10.2.2.2

Step 11 app-resource docker Enters application-hosting docker-configuration mode to

specify application resource updates.
Example:
Device(config-app-hosting)# app-resource docker

Step 12 run-opts options Specifies the Docker run time options.

Example:
Device(config-app-hosting-docker)# run-opts 1
"-e TEAGENT_ACCOUNT_TOKEN=[account-token]"

Step 13 prepend-pkg-opts Merges the package options with the Docker runtime
options.
Example:
Device(config-app-hosting-docker)# • Any duplicate variable is overwritten.
prepend-pkg-opts

Step 14 end Exits application-hosting docker-configuration mode and

returns to privileged EXEC mode.
Example:
Device(config-app-hosting-docker)# end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

399
 Application Hosting
Configuring AppGigabitEthernet Interface for the ThousandEyes Enterprise Agent

Configuring AppGigabitEthernet Interface for the ThousandEyes Enterprise

Agent
SUMMARY STEPS
1. enable
2. configure terminal
3. interface appgigabitethernet number
4. switchport trunk allowed vlan vlan-ID
5. switchport mode trunk
6. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enters privileged EXEC mode.
Example:
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 interface appgigabitethernet number Configures the AppGigabitEthernet and enters interface
configuration mode.
Example:
Device(config)# interface AppGigabitEthernet 1/0/1 • For stackable switches, the number argument is
switch-number/0/1.

Step 4 switchport trunk allowed vlan vlan-ID Configures the list of VLANs allowed on the trunk.
Example:
Device(config-if)# switchport trunk allowed vlan
10-12,20

Step 5 switchport mode trunk Sets the interface into permanent trunking mode and
negotiates to convert the neighboring link into a trunk link.
Example:
Device(config-if)# switchport mode trunk

Step 6 end Exits interface configuration mode and returns to privileged

EXEC mode.
Example:
Device(config-if)# end

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

400
 Application Hosting
Installing the ThousandEyes Enterprise Agent

Installing the ThousandEyes Enterprise Agent

Before you begin
You can install the ThousandEyes Enterprise Agent either from the URL given below or from the flash
filesystem.

SUMMARY STEPS
1. enable
2. app-hosting install appid application-name package package-path
3. app-hosting start appid application-name
4. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enters privileged EXEC mode.
Example:
Device> enable

Step 2 app-hosting install appid application-name package Installs an application from the specified location.
package-path
Example:
Device# app-hosting install 1keyes
https://downloads.thousandeyes.com/
enterprise-agent/thousandeyes-enterprise-agent-3.0.cat9k.tar

Or
Device# app-hosting install appid 1keyes package
flash:/apps/[greenfield-app-tar]

Step 3 app-hosting start appid application-name (Optional) Starts the application.

Example:
Device# app-hosting start appid 1keyes

Step 4 end Exits application hosting configuration mode and returns

to privileged EXEC mode.
Example:
Device# end

The following is sample output from the show app-hosting list command:
Device# show app-hosting list

App id State
---------------------------------------------------------
1keyes RUNNING

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

401
 Application Hosting
Configuration Examples for ThousandEyes Enterprise Agent

Configuration Examples for ThousandEyes Enterprise Agent

Example: Installing ThousandEyes Enterprise Agent
This example shows how to:
• Enable IOx.
• Configure AppHosting.
• Configure the AppGigabitEthernet port.
• Install the ThousandEyes Enterprise Agent.

The following example shows how to enable IOx:

Device> enable
Device# configure terminal
Device(config)# iox
Device(config)# username cisco privilege 15 password 0 ciscoI
Device(config)# end

The following example shows how to configure AppHosting:

Device> enable
Device# configure terminal
Device(config)# app-hosting appid appid 1keyes
Device(config-app-hosting)# app-vnic AppGigabitEthernet trunk
Device(config-config-app-hosting-trunk)# vlan 10 guest-interface 2
Device(config-config-app-hosting-vlan-access-ip)# guest-ipaddress 172.19.0.24
netmask 255.255.255.0
Device(config-config-app-hosting-vlan-access-ip)# exit
Device(config-config-app-hosting-trunk)# exit
Device(config-app-hosting)# app-default-gateway 172.19.0.23
guest-interface 0
Device(config-app-hosting)# name-server0 10.2.2.2
Device(config-app-hosting)# app-resource docker
Device(config-app-hosting-docker)# run-opts 1
"-e TEAGENT_ACCOUNT_TOKEN=[account-token]"
Device(config-app-hosting-docker)# prepend-pkg-opts
Device(config-app-hosting-docker)# end

The following example shows how to configure the Appgigabitethernet interface:

Device> enable
Device# configure terminal
Device(config)# interface AppGigabitEthernet 1/0/1
Device(config-if)# switchport trunk allowed vlan 10-12,20
Device(config-if)# switchport mode trunk
Device(config-if)# end

The following example shows how to install the ThousandEyes Enterprise Agent.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

402
 Application Hosting
Sample Configuration for ThousandEyes Enterprise Agent

Note You can either download the BrownField application from the ThousandEyes website or install the
prepackaged Greenfield application from the flash filesystem.

Device> enable
Device# Device# app-hosting install 1keyes https://downloads.thousandeyes.com/
enterprise-agent/thousandeyes-enterprise-agent-3.0.cat9k.tar
OR
Device# app-hosting install appid 1keyes package flash:/apps/[greenfield-app-tar]
Device# app-hosting start appid 1keyes
Device# end

Sample Configuration for ThousandEyes Enterprise Agent

The following is sample output from the show app-hosting detail command:
Device# show app-hosting detail

App id : 1keyes
Owner : iox
State : RUNNING
Application
Type : docker
Name : thousandeyes/enterprise-agent
Version : 3.0
Description :
Path : flash:thousandeyes-enterprise-agent-3.0.cat9k.tar
URL Path :
Activated profile name : custom

Resource reservation
Memory : 0 MB
Disk : 1 MB
CPU : 1850 units
CPU-percent : 25 %
VCPU : 1

Attached devices
Type Name Alias
---------------------------------------------
serial/shell iox_console_shell serial0
serial/aux iox_console_aux serial1
serial/syslog iox_syslog serial2
serial/trace iox_trace serial3

Network interfaces
---------------------------------------
eth0:
MAC address : 52:54:dd:c0:a2:ab
IPv4 address : 10.0.0.110
IPv6 address : ::
Network name : mgmt-bridge-v14

Docker
------
Run-time information
Command :
Entry-point : /sbin/my_init

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

403
 Application Hosting
Sample Configuration for ThousandEyes Enterprise Agent

Run options in use : -e TEAGENT_ACCOUNT_TOKEN=TOKEN_NOT_SET --hostname=$(SYSTEM_NAME)

--cap-add=NET_ADMIN
--mount type=tmpfs,destination=/var/log/agent,tmpfs-size=140m
--mount type=tmpfs,destination=/var/lib/te-agent/data,tmpfs-size=200m

-v $(APP_DATA)/data:/var/lib/te-agent -e TEAGENT_PROXY_TYPE=DIRECT

-e TEAGENT_PROXY_LOCATION= -e TEAGENT_PROXY_USER= -e
TEAGENT_PROXY_AUTH_TYPE=
-e TEAGENT_PROXY_PASS= -e TEAGENT_PROXY_BYPASS_LIST= -e
TEAGENT_KDC_USER=
-e TEAGENT_KDC_PASS= -e TEAGENT_KDC_REALM= -e TEAGENT_KDC_HOST=
-e TEAGENT_KDC_PORT=88
-e TEAGENT_KERBEROS_WHITELIST= -e TEAGENT_KERBEROS_RDNS=1 -e
PROXY_APT=
-e APT_PROXY_USER= -e APT_PROXY_PASS= -e APT_PROXY_LOCATION= -e
TEAGENT_AUTO_UPDATES=1
-e TEAGENT_ACCOUNT_TOKEN=r3d29srpebr4j845lvnamwhswlori2xs
--hostname=cat9k-9300-usb --memory=1g
Package run options : -e TEAGENT_ACCOUNT_TOKEN=TOKEN_NOT_SET --hostname=$(SYSTEM_NAME)
--cap-add=NET_ADMIN
--mount type=tmpfs,destination=/var/log/agent,tmpfs-size=140m
--mount type=tmpfs,destination=/var/lib/te-agent/data,tmpfs-size=200m

-v $(APP_DATA)/data:/var/lib/te-agent -e TEAGENT_PROXY_TYPE=DIRECT

-e TEAGENT_PROXY_LOCATION= -e TEAGENT_PROXY_USER= -e
TEAGENT_PROXY_AUTH_TYPE=
-e TEAGENT_PROXY_PASS= -e TEAGENT_PROXY_BYPASS_LIST= -e
TEAGENT_KDC_USER=
-e TEAGENT_KDC_PASS= -e TEAGENT_KDC_REALM= -e TEAGENT_KDC_HOST=
-e TEAGENT_KDC_PORT=88 -e TEAGENT_KERBEROS_WHITELIST= -e
TEAGENT_KERBEROS_RDNS=1
-e PROXY_APT= -e APT_PROXY_USER= -e APT_PROXY_PASS= -e
APT_PROXY_LOCATION=
-e TEAGENT_AUTO_UPDATES=1
Application health information
Status : 0
Last probe error :
Last probe output :

The following sample output from the show running-configuration command displays the static IP address
configuration:
Device# show running-config | section app-hosting

app-hosting appid 1keyes

app-vnic AppGigabitEthernet trunk
vlan 14 guest-interface 0
guest-ipaddress 10.0.0.110 netmask 255.255.255.0
app-default-gateway 10.0.0.1 guest-interface 0
app-resource docker
prepend-pkg-opts
run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=r3d29srpebr4j845lvnamwhswlori2xs"
run-opts 2 "--hostname=cat9k-9300-usb --memory=1g"
name-server0 10.0.0.1
start

The following sample output from the show running-configuration command displays the static IP address
configuration and the proxy server information:

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

404
Application Hosting
Sample Configuration for ThousandEyes Enterprise Agent

Device# show running-config | section app-hosting

app-hosting appid 1keyes

app-vnic AppGigabitEthernet trunk
vlan 14 guest-interface 0
guest-ipaddress 172.27.0.137 netmask 255.240.0.0
app-default-gateway 172.27.0.129 guest-interface 0
app-resource docker
run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=r3d29srpebr4j845lvnamwhswlori2xs"
run-opts 3 "-e TEAGENT_PROXY_TYPE=STATIC"
run-opts 4 "-e TEAGENT_PROXY_LOCATION='proxy-wsa.esl.cisco.com:80'"
prepend-pkg-opts
name-server0 172.16.0.2
start

The following is sample output from running the app-resource Docker package merged with the Docker
runtime options:
// Example of "prepend-package-opts" merging
app-hosting appid TEST
app-vnic management guest-interface 3
app-resource docker
prepend-package-opts !!!
run-opts 1 "--entrypoint '/bin/sleep 1000000'"
run-opts 2 "-e TEST=1 "

# Specify runtime and startup

startup:
runtime_options: "--env MYVAR2=foo --cap-add=NET_ADMIN"

Merged docker run-opts passed to CAF's activation payload:

{"auto_deactivate": false, "resources": {"profile": "custom", "cpu":
"1000", "memory": "1024", "rootfs_size": "0", "vcpu": 1, "disk": 10,"network":
[{"interface-name": "eth3", "network-name": "mgmt-bridge100"}, {"interface-name":
"eth4", "network-type": "vlan", "mode": "static", "ipv4": {"ip": "10.2.0.100",
"prefix": "24", "default": false, "gateway": "" },"network-info": { "vlan-id": "10" },
"mac_forwarding": "no", "mirroring": "no"}, {"interface-name": "eth0",
"network-type": "vlan", "network-info": { "vlan-id": "12" }, "mac_forwarding": "no",
"mirroring": "no"}, {"interface-name": "eth2", "network-type": "vlan", "networkinfo":
{"vlan-id": "22" }, "mac_forwarding": "no", "mirroring": "no"},
{"interface-name
": "eth1", "network-type": "vlan", "network-info": {"vlan-id": "all" },
"mac_forwarding": "no", "mirroring": "no"}]},

"startup":{"runtime_options":"--env MYVAR2=foo --cap-add=NET_ADMIN --

entrypoint'/bin/sleep 1000000' -e TEST=1"}}

// Example of no "prepend-package-opts" which is the current behavior since

16.12 where pkg.yml default runoptions are ignored.
app-hosting appid TEST
app-vnic management guest-interface 3
app-resource docker !!!
run-opts 1 "--entrypoint '/bin/sleep 1000000'"
run-opts 2 "-e TEST=1 "

# Specify runtime and startup

startup:
runtime_options: "--env MYVAR2=foo --cap-add=NET_ADMIN"

Merged docker run-opts passed to CAF's activation payload:

{"auto_deactivate": false, "resources": {"profile": "custom", "cpu":
"1000", "memory": "1024", "rootfs_size": "0", "vcpu": 1, "disk": 10,"network":
[{"interface-name": "eth3", "network-name": "mgmt-bridge100"}, {"interface-name":
"eth4", "network-type": "vlan", "mode": "static", "ipv4": {"ip": "10.2.0.100",

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

405
 Application Hosting
Additional References

"prefix": "24", "default": false, "gateway": "" },"network-info": { "vlan-id": "10" },

"mac_forwarding": "no", "mirroring": "no"}, {"interface-name": "eth0",
"network-type": "vlan", "network-info": { "vlan-id": "12" }, "mac_forwarding": "no",
"mirroring": "no"}, {"interface-name": "eth2", "network-type": "vlan", "networkinfo":
{"vlan-id": "22" }, "mac_forwarding": "no", "mirroring": "no"},
{"interface-name": "eth1", "network-type": "vlan", "network-info": {"vlan-id": "all" },
"mac_forwarding": "no", "mirroring": "no"}]},

"startup":{"runtime_options":"--entrypoint '/bin/sleep 1000000' -e

TEST=1"}}

// Config 1 : default behavior when "app-resource docker" is not

configured.
app-hosting appid TEST
app-vnic management guest-interface 3

// Config 2: no docker run-opts specified

app-hosting appid TEST
app-vnic management guest-interface 3
app-resource docker
prepend-package-opts

Additional References
Related Topic Document Title
ThousandEyes URL https://app.thousandeyes.com

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, including http://www.cisco.com/support
documentation and tools for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about your products, you can
subscribe to various services, such as the Product Alert Tool (accessed from
Field Notices), the Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a Cisco.com user
ID and password.

Feature Information for ThousandEyes Enterprise Agent

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

406
Application Hosting
Feature Information for ThousandEyes Enterprise Agent

Table 51: Feature Information for Application Hosting

Feature Name Release Feature Information

ThousandEyes Integration Cisco IOS XE Amsterdam ThousandEyes is a cloud-ready, enterprise

17.3.3 network-monitoring tool that provides an
end-to-end view across networks and services.
Cisco IOS XE Bengaluru
17.5.1 • In Cisco IOS XE Amsterdam 17.3.3, this
feature was implemented on Cisco
Cisco IOS XE Bengaluru
Catalyst 9300 and 9300L Series
17.6.1
Switches.
• In Cisco IOS XE Bengaluru 17.5.1, this
feature was implemented on Cisco
Catalyst 9400 Series Switches.
• In Cisco IOS XE Bengaluru 17.6.1, this
feature was implemented on Cisco
Catalyst 9300X Series Switches.

Note The ThousandEyes Integration

feature is not supported in Cisco
IOS XE Bengaluru 17.4.x release.

ThousandEyes BrowserBot Cisco IOS XE Bengaluru ThousandEyes add-on agent mode is

17.6.1 supported. Add-on mode provides a
BrowserBot for transaction scripting test.
In Cisco IOS XE Bengaluru 17.6.1, this
feature was introduced on the following
platforms:
• Cisco Catalyst 9300, 9300L, and 9300X
Series Switches
• Cisco Catalyst 9400 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

407
 Application Hosting
Feature Information for ThousandEyes Enterprise Agent

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

408
PA R T V
OpenFlow
• OpenFlow , on page 411
• High Availability in OpenFlow Mode, on page 427
 CHAPTER 17
OpenFlow
This module describes how to enable and configure OpenFlow on a device.
• Prerequisites for OpenFlow, on page 411
• Restrictions for OpenFlow, on page 411
• Information About OpenFlow, on page 411
• How to Configure OpenFlow, on page 417
• Verifying OpenFlow, on page 421
• Configuration Examples for OpenFlow, on page 424
• Additional References, on page 424
• Feature Information for OpenFlow, on page 425

Prerequisites for OpenFlow

The device must be booted up in OpenFlow mode. (OpenFlow mode is enabled when you configure the boot
mode openflow command on a device. All ports will be in this mode, and the device will not support any
regular Cisco IOS XE features.)

Restrictions for OpenFlow

• When enabling OpenFlow mode on a device, erase all prior configurations, and delete the vlan.dat and
stby-vlan.dat files from the flash filesystem.
• When the device is in Openflow mode, do not enable other control plane protocols, Border Gateway
Protocol (BGP), Spanning Tree Protocol (STP), Port Channels, StackWise Virtual, and so on that work
when the device is in normal mode.

Information About OpenFlow

The following sections provide more information about the feature.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

411
 OpenFlow
OpenFlow Overview

OpenFlow Overview
OpenFlow is a specification from the Open Networking Foundation (ONF) that defines a flow-based forwarding
infrastructure and a standardized application-programmatic interface. OpenFlow allows a controller to direct
the forwarding functions of a device through a secure channel.
OpenFlow is the protocol between a controller (control plane) and an Ethernet switch (data plane). The switch
has flow tables arranged in a pipeline. Flows are rules to examine packets that reach these tables.
An OpenFlow agent on the switch communicates with the controller using the OpenFlow protocol. The agent
supports both OpenFlow 1.0 (wire protocol 0x1) and OpenFlow 1.3 (wire protocol 0x4). It can have up to
eight controller connections. These connections are not preserved across a switchover, and the controller will
have to reconnect to the agent after a switchover.
The OpenFlow implementation on Cisco Catalyst 9400 Series Switches is stateless, and nonstop forwarding
(NSF) is not supported. The standby supervisor does not synchronize with the flow database.

OpenFlow Controller
The OpenFlow controller is an entity that interacts with an OpenFlow switch using the OpenFlow protocol.
In most cases, a controller is a software that manages many OpenFlow logical switches. Controllers offer a
centralized view of the network, and enable administrators to dictate to the underlying systems (switches and
routers) on how to handle the network traffic. A controller typically runs on a Linux server, and must have
IP connectivity to OpenFlow-capable switches.
A controller manages a switch, and inserts and deletes the flows on the switch. These flows support a subset
of OpenFlow 1.3 and 1.0 match and action criteria.
The switch connects to the controller using the management port. The management port is in the management
virtual routing and forwarding (VRF) instance, and hence provides a secure connection to the controller. To
connect a controller to the switch, configure the IP address and port number on which the controller can be
reached.

Flow Management
A flow entry is an element in a flow table that is used to match and process packets. It contains priority levels
for matching precedence, a set of match fields for matching packets, a set of instructions to apply, and packet
and byte counters. A timeout is also associated with each flow (a hard timeout or an inactivity timeout), which
is used to automatically remove flows.
A maximum of 32 flow tables are supported.
Each flow provides the following information:
• Priority: High-priority flows are matched first. A flow update requires all the flows to be prioritized
based on the configured priority.
• Match fields: A part of a flow entry against which a packet is matched. Match fields can match the various
packet header fields. If no match information is provided for a field, a wildcard is used.
• Action: An operation that acts on a packet.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

412
 OpenFlow
OpenFlow Pipeline

OpenFlow Pipeline
An OpenFlow pipeline is a set of linked flow tables that provide matching, forwarding, and packet modification
in an OpenFlow switch. A port is where packets enter and exit the pipeline.
Packets are received on an ingress port and processed by the OpenFlow pipeline that forwards it to output
ports. The packet ingress port is owned by the packet throughout the pipeline, and represents the port on which
the packet was received into the switch. Note that the ingress port can also be used as a match field in a flow.
Flow actions allow packets to be sent to subsequent tables in the pipeline for further processing, and allow
information to be communicated between tables. Pipeline processing stops when the action associated with
a matching flow entry does not specify the next table. At this point, the packet is usually modified and
forwarded. The packet can also be dropped.
Flow tables of an OpenFlow switch are sequentially numbered, starting from 0. Pipeline processing always
starts by matching the packet against flow entries of flow table 0. Other flow tables can be used depending
on the outcome of the match and actions in the first table, which could result in matching the packet against
flow entries in subsequent tables.

Supported Match Fields and Actions

Match Field is a field against which a packet is matched, including packet headers, and the ingress port. A
match field can be a wildcard (match any value) and have a bit mask to match selected bits of the field.
Action is an operation that forwards a packet to a port or subsequent tables, or modifies a packet field. Actions
can be specified as part of the instructions associated with a flow entry, or an action bucket associated with
a group entry. A group entry is a collection of actions that can be shared by multiple flows.
The action specified in one or more flow entries can direct packets to a base action called a group action. The
purpose of the group action is to share a set of actions among multiple flows. A group consist of one or more
buckets, and in turn, a bucket can have a set of actions (set, pop, or output). Cisco Catalyst 9000 Series Switches
support the group types all and indirect.
The following table lists the supported match fields and actions:

Table 52: Supported Match Fields

Header Field Prerequisite Maskable Entrie Example Value

Ethernet destination MAC — Yes 01:80:c2:00:00:00/

address ff:ff:ff:00:00:00 (with
mask)
de:f3:50:c7:e2:b2 (without
mask)

Ethernet source MAC — Yes 0e:00:00:00:00:019

address (without mask)

Ethernet type — — ARP (0x0806), IPv4

(0x0800), IPv6 (0x86dd),
and so on

VLAN ID — 0x13f

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

413
 OpenFlow
Supported Match Fields and Actions

Header Field Prerequisite Maskable Entrie Example Value

ARP target protocol Ethernet type should be Yes —

address set to 0x0806

IP protocol Ethernet type should be — ICMP (0x01), TCP

set to 0x0800 or 0x86dd (0x06), UDP (0x11), and
so on

IPv4 source address Ethernet type should be Yes 10.0.0.0/24 (with mask)
set to 0x0800

IPv4 destination address Ethernet type should be Yes 10.0.0.254 (without mask)
set to 0x0800

IPv6 source address Ethernet type should be Yes 2001:DB8::1 (without

set to 0x08dd mask)

IPv6 destination address Ethernet type should be Yes 2001:DB8:0:ABCD::1/48

set to 0x08dd (with mask)

Neighbor discovery target Ethernet type should be — ND target

set to 0x08dd and IP
protocol should be set to
0x01

ICMPv6 type Ethernet type should be — —

set to 0x08dd and IP
protocol should be set to
0x01

UDP/TCP source port Ethernet type should be — —

set to 0x0800 or 0x86dd
and protocol should be set
to 0x06 or 0x11

UDP/TCP destination port Ethernet type should be — —

set to 0x0800 or 0x86dd
and protocol should be set
to 0x06 or 0x11

Incoming interface — — —

Supported Actions
A flow can send a packet to:
• The controller.
• Any interface of the switch (including the incoming interface).
• A subsequent flow table (after Table 0) for another lookup.
• A group.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

414
 OpenFlow
Rewrite Fields

• The switch CPU for local processing. Only Cisco Discovery Protocol and Link Layer Discovery Protocol
(LLDP) packets can be sent for local processing.

A flow can add (push) or remove (pop) a VLAN tag. If a packet is an IP packet, the flow can decrement the
Time to Live (TTL) header field.
The ability to modify the packet fields are defined as Set-Field action. A flow can also modify the following
header fields of a packet:

Table 53: Number of Rewrites Supported on Header Fields

Header Field Scale

Ethernet destination MAC address 1k

Ethernet source MAC address 256

VLAN ID 4k

Rewrite Fields
In Cisco IOS XE Bengaluru 17.4.1, the support to rewrite the following fields has been added:

Table 54: Rewrite Fields

Field Scale

ipv4_src 4k

ipv4_dst 4k

icmpv4_type 256

tcp_src/udp_src 4k (shared by both fields)

tcp_dst/udp_dst 4k (shared by both fields)

ip_dscp 64

The IP_DSCP field is part of the IPv4 type of service (ToS) field and the IPv6 traffic class field.

OpenFlow Scale Information

Table 55: Scale Information on Supported Platforms

Cisco Catalyst 9300 Series Cisco Catalyst 9400 Series Cisco Catalyst 9500
Switches Switches, and Cisco High-Performance Series
Catalyst 9500 Series Switches
Switches

Total number of flows 18K/9K 54K/27K 54K/27K

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

415
 OpenFlow
Flow Operations

Flow Operations
This section describes the operations that take place when a flow is sent by the controller to be programmed
in the OpenFlow device.
Typically a device has flow tables arranged in a pipeline. The pipeline capabilities information specifies the
structure of the pipeline, such as the number of tables or stages, what each stage is capable of doing (match
or actions), and the size of each table.
When the controller sends a flow request, the OpenFlow agent verifies whether the flow can be handled by
the hardware. It compares the flow against the capabilities of the hardware that are defined when the switch
is booted up. If the flow is valid, it is programmed in the appropriate flow table.
If the new pipeline is validated (whether the hardware can support the pipeline), it becomes the new set of
capabilities used to check if a flow can be installed or not.
After the pipeline is instantiated and flows are installed, packets are forwarded by the switch. Ingress packets
are matched against the flows in each flow table, until the highest-priority matching flow entry is found. Packet
matching may be exact (match all fields of the table exactly), or partial (match some or all fields, and fields
with bit masks may be partially matched). Packets can be modified or forwarded based on the configured
actions. Actions can be applied in the pipeline at any time. An action can determine the next flow table to
match, the set of egress ports for the packet, and whether the packet should be routed to the controller.

OpenFlow Table Pipeline

OpenFlow table feature request messages allow an OpenFlow controller to query the capabilities of existing
flow tables of an OpenFlow-managed device, or configure these tables to match the supplied configuration.
All the tables can be configured with a subset of the match and action capabilities. Table sizes can also be
modified at runtime. When a new flow table configuration is successfully applied, flow entries from old flow
tables are removed without any notification. Dynamically configured flow tables are not persistent across
reboot. The default pipeline comes up when the device boots up.
While configuring a new flow table based on a request from the OpenFlow controller, ongoing traffic, if any,
flowing through the existing flows are dropped.

Breakout Port Support

Breakout ports enable a single 40G Quad Small Form-Factor Pluggable+ (QSFP+) interface to be split into
four 10G SFP+ interfaces, and a single 100G QSFP28 interface into four 25G SFP28 interfaces. The breakout
port support is available in the OpenFlow mode on platforms that support breakout ports in normal mode. In
Cisco IOS XE Bengaluru 17.5.1, the breakout port support is available on Cisco Catalyst 9500 and 9500 High
Performance Series Switches.
To view the OpenFlow port number associated with the breakout ports, use the show openflow switch 1 ports
command. There are no specific rules to calculate the OpenFlow port number from a breakout interface name.

OpenFlow Power over Ethernet

OpenFlow supports Power over Ethernet (PoE). For PoE to work, configure either Cisco Discovery Protocol
or LLDP on the device so that Cisco Discovery Protocol packets or LLDP packets are processed (and sent)
by the device. Note that no OpenFlow-specific configuration is required for PoE to work with OpenFlow.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

416
 OpenFlow
How to Configure OpenFlow

On the OpenFlow controller, configure a flow with the output-to-local action to ensure that packets are sent
to the device CPU for local processing.
For more information about PoE, see the Configuring POE chapter.

How to Configure OpenFlow

The following sections provide information about the various OpenFlow configuration tasks.

Enabling OpenFlow Mode on a Device

If the switch is operating in normal mode, we recommend that you configure the write erase command to
delete the previous configuration.

SUMMARY STEPS
1. enable
2. configure terminal
3. boot mode openflow
4. exit
5. write erase
6. • delete flash:vlan.dat
• delete flash:stby-vlan.dat
7. reload
8. enable
9. show boot mode

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 boot mode openflow Enables OpenFlow forwarding mode.

Example:
Device(config)# boot mode openflow

Step 4 exit Exits global configuration mode and enters privileged EXEC
mode.
Example:
Device(config)# exit

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

417
 OpenFlow
Configuring OpenFlow

Command or Action Purpose

Step 5 write erase Erases all the files in the NVRAM.
Example: • We recommend erasing all the files, if the device was
Device# write erase operating in normal mode previously.

Step 6 • delete flash:vlan.dat • Deletes the vlan.dat file that stores the VLAN
• delete flash:stby-vlan.dat information.
Example: • Deletes the stby-vlan.dat file, if you have a standby
Device# delete flash:vlan.dat device.
Device# delete flash:stby-vlan.dat

Step 7 reload Reloads the switch and enables OpenFlow forwarding mode
for the switch.
Example:
Device# reload

Step 8 enable Enables privileged EXEC mode.

Example: • Enter your password if prompted.
Device> enable

Step 9 show boot mode Displays information about the device's forwarding mode.
Example:
Device# show boot mode

Example
The following is sample output from the show boot mode command that shows the device in
OpenFlow mode:
Device# show boot mode

System initialized in openflow forwarding mode

System configured to boot in openflow forwarding mode

What to do next
To go back to normal mode, configure the no boot mode openflow command and then reload the device.

Configuring OpenFlow
SUMMARY STEPS
1. enable
2. configure terminal
3. feature openflow
4. openflow

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

418
 OpenFlow
Configuring OpenFlow

5. switch 1 pipeline 1
6. controller ipv4 ip-address port port-number vrf vrf-name security {none | tls}
7. datapath-id ID
8. tls trustpoint local name remote name
9. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 feature openflow Enables the OpenFlow feature.

Example:
Device(config)# feature openflow

Step 4 openflow Enables OpenFlow configuration and enters OpenFlow

configuration mode.
Example:
Device(config)# openflow

Step 5 switch 1 pipeline 1 Configures a logical switch and pipeline, and enters
OpenFlow switch configuration mode.
Example:
Device(config-openflow)# switch 1 pipeline 1

Step 6 controller ipv4 ip-address port port-number vrf vrf-name Connects to a controller.
security {none | tls}
• You must configure the tls trustpoint command if
Example: you have configured TLS as the OpenFlow controller
Device(config-openflow-switch)# controller ipv4 connection security option.
10.2.2.2 port 6633 vrf Mgmt-vrf security tls
• You do not have to configure tls trustpoint command
if you have not configured any security option for the
OpenFlow controller.

Step 7 datapath-id ID (Optional) Sets the OpenFlow logical switch ID.

Example: • The ID argument specifies the switch ID, which is a
Device(config-openflow-switch)# datapath-id hexadecimal value.
0x12345678

Step 8 tls trustpoint local name remote name (Optional) Configures an OpenFlow switch Transport Layer
Security (TLS) trustpoint.
Example:
Device(config-openflow-switch)# tls trustpoint
local trustpoint1 remote trustpoint1

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

419
 OpenFlow
Configuring an Interface in OpenFlow Mode

Command or Action Purpose

Step 9 end Exits OpenFlow switch configuration mode and returns to
privileged EXEC mode.
Example:
Device(config-openflow-switch)# end

Configuring an Interface in OpenFlow Mode

You can configure either a Layer 2 or Layer 3 interface in OpenFlow mode. When using a Layer 3 interface,
configure the no switchport command in interface configuration mode. Perform the following task when
using a Layer 2 interface.

SUMMARY STEPS
1. enable
2. configure terminal
3. feature openflow
4. interface type number
5. switchport mode trunk
6. switchport nonnegotiate
7. no keepalive
8. spanning-tree bpdufilter enable
9. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 feature openflow Enables the OpenFlow feature.

Example:
Device(config)# feature openflow

Step 4 interface type number Configures an interface and enters interface configuration
mode.
Example:
Device(config)# interface gigabitethernet 1/0/3

Step 5 switchport mode trunk Sets the trunking mode of the Layer 2-switched interface
to trunk.
Example:
Device(config-if)# switchport mode trunk

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

420
 OpenFlow
Verifying OpenFlow

Command or Action Purpose

Step 6 switchport nonnegotiate Specifies that the device will not engage in negotiation
protocol on this interface.
Example:
Device(config-if)# switchport nonnegotiate

Step 7 no keepalive Disables keepalive packets.

Example:
Device(config-if)# no keepalive

Step 8 spanning-tree bpdufilter enable Enables bridge protocol data unit (BPDU) filtering on the
interface.
Example:
Device(config-if)# spanning-tree bpdufilter enable

Step 9 end Exits interface configuration mode and returns to privileged

EXEC mode.
Example:
Device(config-if)# end

Verifying OpenFlow
Use these commands to verify your OpenFlow configuration. These commands can be used in any order.

SUMMARY STEPS
1. enable
2. show openflow hardware capabilities
3. show openflow switch 1 controller
4. show openflow switch 1 ports
5. show openflow switch 1 flows list

DETAILED STEPS

Step 1 enable
Enables privileged EXEC mode.
• Enter your password if prompted.

Example:
Device> enable

Step 2 show openflow hardware capabilities

Displays the hardware capabilities of an OpenFlow device.
Example:
Device# show openflow hardware capabilities

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

421
 OpenFlow
Verifying OpenFlow

Max Interfaces: 1000

Aggregated Statistics: YES

Pipeline ID: 1
Pipeline Max Flows: 2322
Max Flow Batch Size: 100
Statistics Max Polling Rate (flows/sec): 10000
Pipeline Default Statistics Collect Interval: 5

Flow table ID: 0

Max Flow Batch Size: 100

Max Flows: 1022
Bind Subintfs: FALSE
Primary Table: TRUE
Table Programmable: TRUE
Miss Programmable: TRUE
Number of goto tables: 1
Goto table id: 1
Number of miss goto tables: 1
Miss Goto table id: 1
Stats collection time for full table (sec): 1

.
.
.

Step 3 show openflow switch 1 controller

Displays information about the controller connected to the switch.
Example:
Device# show openflow switch 1 controller

Logical Switch Id: 1

Total Controllers: 1
Controller: 1
10.10.23.200:6633
Protocol: tcp
VRF: Mgmt-vrf
Connected: Yes
Role: Equal
Negotiated Protocol Version: OpenFlow 1.3
Last Alive Ping: 2018-06-04 17:59:20 PDT
state: ACTIVE
sec_since_connect: 50

Step 4 show openflow switch 1 ports

Displays information about the ports on an OpenFlow switch.
Example:
Device# show openflow switch 1 ports
Logical Switch Id: 1
Port Interface Name Config-State Link-State Features
1 Gi1/0/1 PORT_UP LINK_UP 1GB-FD
2 Gi1/0/2 PORT_UP LINK_UP 1GB-FD
3 Gi1/0/3 PORT_UP LINK_UP 1GB-FD
4 Gi1/0/4 PORT_UP LINK_UP 1GB-FD
5 Gi1/0/5 PORT_UP LINK_DOWN 1GB-HD
6 Gi1/0/6 PORT_UP LINK_DOWN 1GB-HD

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

422
 OpenFlow
Verifying OpenFlow

7 Gi1/0/7 PORT_UP LINK_DOWN 1GB-HD

8 Gi1/0/8 PORT_UP LINK_DOWN 1GB-HD
9 Gi1/0/9 PORT_UP LINK_UP 1GB-FD
10 Gi1/0/10 PORT_UP LINK_UP 1GB-FD
11 Gi1/0/11 PORT_UP LINK_UP 1GB-FD
12 Gi1/0/12 PORT_UP LINK_UP 1GB-FD
13 Gi1/0/13 PORT_UP LINK_DOWN 1GB-HD
14 Gi1/0/14 PORT_UP LINK_DOWN 1GB-HD
15 Gi1/0/15 PORT_UP LINK_DOWN 1GB-HD
16 Gi1/0/16 PORT_UP LINK_DOWN 1GB-HD
17 Gi1/0/17 PORT_UP LINK_DOWN 1GB-HD
18 Gi1/0/18 PORT_UP LINK_DOWN 1GB-HD
19 Gi1/0/19 PORT_UP LINK_UP 1GB-FD
20 Gi1/0/20 PORT_UP LINK_UP 1GB-FD
21 Gi1/0/21 PORT_UP LINK_UP 1GB-FD
22 Gi1/0/22 PORT_UP LINK_UP 1GB-FD
23 Gi1/0/23 PORT_UP LINK_DOWN 1GB-HD
24 Gi1/0/24 PORT_UP LINK_DOWN 1GB-HD
25 Gi1/1/1 PORT_UP LINK_DOWN 1GB-HD
26 Gi1/1/2 PORT_UP LINK_DOWN 1GB-HD
27 Gi1/1/3 PORT_UP LINK_DOWN 1GB-HD
28 Gi1/1/4 PORT_UP LINK_DOWN 1GB-HD
29 Te1/1/1 PORT_UP LINK_DOWN 10GB-FD
30 Te1/1/2 PORT_UP LINK_DOWN 10GB-FD
31 Te1/1/3 PORT_UP LINK_DOWN 10GB-FD
32 Te1/1/4 PORT_UP LINK_DOWN 10GB-FD
33 Te1/1/5 PORT_UP LINK_DOWN 10GB-FD
34 Te1/1/6 PORT_UP LINK_DOWN 10GB-FD
35 Te1/1/7 PORT_UP LINK_DOWN 10GB-FD
36 Te1/1/8 PORT_UP LINK_DOWN 10GB-FD
37 Fo1/1/1 PORT_UP LINK_DOWN 40GB-FD
38 Fo1/1/2 PORT_UP LINK_DOWN 40GB-FD
39 Twe1/1/1 PORT_UP LINK_DOWN 10GB-FD
40 Twe1/1/2 PORT_UP LINK_DOWN 10GB-FD

Step 5 show openflow switch 1 flows list

Displays OpenFlow entries.
The following sample output displays a flow that is available in Table 0, where match any goes to Table 1. (match any
means that all the packets go to Table 1.) In Table 1, the destination MAC address 00:00:01:00:00:01 is matched, and
the output port is set to 36.
Example:
Device# show openflow switch 1 flows list

Logical Switch Id: 1

Total flows: 8

Flow: 1 Match: any Actions: goto_table:1, Priority: 9000, Table: 0, Cookie: 0x1,
Duration: 2382.117s, Packets: 34443, Bytes: 3359315

Flow: 2 Match: any Actions: drop, Priority: 0, Table: 0, Cookie: 0x0,

Duration: 2382.118s, Packets: 294137, Bytes: 28806211

Flow: 3 Match: any Actions: drop, Priority: 0, Table: 1, Cookie: 0x0,

Duration: 2382.118s, Packets: 34443, Bytes: 3359315

Flow: 4 Match: dl_dst=00:00:01:00:00:01 Actions: output:36, Priority: 9000,

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

423
 OpenFlow
Configuration Examples for OpenFlow

Table: 1, Cookie: 0x1, Duration: 2382.116s, Packets: 0, Bytes: 0

Configuration Examples for OpenFlow

Example: Enabling OpenFlow on a Device

The following example shows how to enable OpenFlow:

Device> enable
Device# configure terminal
Device(config)# boot mode openflow
Device(config)# exit
Device# write erase
Device# delete flash:vlan.dat
Device# reload
Device> enable
Device# show boot mode

Example: Configuring OpenFlow

The following example shows how to configure OpenFlow:

Device# configure terminal
Device(config)# feature openflow
Device(config)# openflow
Device(config-openflow)# switch 1 pipeline 1
Device(config-openflow-switch)# controller ipv4 10.2.2.2 port 6633 vrf Mgmt-vrf security
tls
Device(config-openflow-switch)# datapath-id 0x12345678
Device(config-openflow-switch)# tls trustpoint local trustpoint1 remote trustpoint1
Device(config-openflow-switch)# end

Additional References
Related Documents

Related Topic Document Title

OpenFlow commands Programmability Command Reference

Open Network Foundation https://www.opennetworking.org/

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

424
 OpenFlow
Feature Information for OpenFlow

Related Topic Document Title

Faucet OpenFlow controller • https://faucet.nz/
• https://docs.faucet.nz/en/latest/

PoE • "Configuring Power over Ethernet" on Cisco

Catalyst 9300 Series Switches
• "Configuring PoE" on Cisco Catalyst 9400 Series
Switches

Technical Assistance

Description Link
The Cisco Support website provides extensive online resources, http://www.cisco.com/support
including documentation and tools for troubleshooting and resolving
technical issues with Cisco products and technologies.
To receive security and technical information about your products,
you can subscribe to various services, such as the Product Alert
Tool (accessed from Field Notices), the Cisco Technical Services
Newsletter, and Really Simple Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website requires a
Cisco.com user ID and password.

Feature Information for OpenFlow

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

425
 OpenFlow
Feature Information for OpenFlow

Table 56: Feature Information for OpenFlow

Feature Name Release Feature Information

OpenFlow Cisco IOS XE Fuji 16.9.1 OpenFlow is a Software-Defined Network

(SDN) standard. It defines a communication
protocol in SDN environments that enables an
SDN controller to directly interact with the
forwarding plane of network devices such as
switches and routers.
This feature was implemented on the following
platforms:
• Catalyst 9300 Series Switches
• Catalyst 9400 Series Switches
• Catalyst 9500 Series Switches
• Catalyst 9500 Series High Performance
Switches

Cisco IOS XE Gibraltar 16.10.1 Table feature message support on Catalyst

9500 Series High Performance Switches was
implemented.

OpenFlow Power over Cisco IOS XE Gibraltar 16.12.1 PoE is supported on OpenFlow ports.
Ethernet
This feature was implemented on the following
platforms:
• Catalyst 9300 Series Switches
• Catalyst 9400 Series Switches

OpenFlow Breakout Cisco IOS XE Bengaluru 17.5.1 Breakout cables enable a single 40G Quad
Port Support Small Form-Factor Pluggable+ (QSFP+)
interface to be split into four 10G SFP+
interfaces, and a single 100G QSFP28 interface
into four 25G SFP28 interfaces.
This feature was introduced on the following
platforms:
• Catalyst 9500 and 9500 High
Performance Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

426
 CHAPTER 18
High Availability in OpenFlow Mode
High Availability in OpenFlow mode supports Stateful Switchover (SSO) and Nonstop Forwarding (NSO).
SSO works with NSF to minimize the amount of time a network is unavailable to its users following a
switchover.
• Restrictions for High Availability in OpenFlow Mode , on page 427
• Information About OpenFlow, on page 427
• How to Configure High Availability in OpenFlow Mode, on page 429
• Configuration Examples for High Availability in OpenFlow Mode, on page 430
• Feature Information for High Availability in OpenFlow Mode, on page 431

Restrictions for High Availability in OpenFlow Mode

• Stateful switchover (SSO) is not supported with Transport Layer Security (TLS).
• You cannot configure both TCP and Secure Socket Layer (SSL) connections on the OpenFlow controller.

Information About OpenFlow

The following sections provide more information about the feature.

High Availability in OpenFlow Mode

In Cisco IOS XE Bengaluru 17.5.1, Cisco Catalyst 9400 Series Switches support high availability in OpenFlow
mode. A chassis-based platform, the Cisco Catalyst 9400 Series Switch supports dual supervisors. One of the
supervisors act as the active, and the other as the standby.
Prior to the introduction of this feature, during a switchover, the OpenFlow controller deleted all installed
flows on the device before resending all flows that led to the disruption of the forwarding traffic. Also during
a switchover, the OpenFlow controller connection was reset, and re-established, and the controller deleted all
installed flows.
With the high availability feature, the active supervisor establishes a connection with the OpenFlow controller,
and all flows sent by the controller are programmed onto the device by the active supervisor. When the active
supervisor fails due to software or hardware failure, or when a manual switchover from the active to standby
supervisor is triggered, all flows are retained. The OpenFlow agent on the new active supervisor will continue

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

427
 OpenFlow
Stateful Switchover

the TCP session with the OpenFlow controller, and the connection will not be terminated by the OpenFlow
agent.

Stateful Switchover
Stateful switchover (SSO) maintains stateful protocol and application information to retain user session
information during a switchover. The flows sent to the OpenFlow device by the controller are retained during
a switchover from the active supervisor to the standby supervisor, so that the controller does not have to
re-install the flows. It also provides a faster switchover relative to high system availability.
In devices that support dual supervisors, SSO takes advantage of the supervisor redundancy to increase the
network availability. SSO establishes one of the supervisors as the active and the other as the standby, and
then synchronizes critical state information between them. Following an initial synchronization between the
two supervisors, SSO dynamically maintains state information between them.
SSO is used with the Cisco Nonstop Forwarding (NSF) feature.
With NSF, even during a switchover, packets are forwarded based on the flow entries programmed by the
OpenFlow controller.

Symmetric High Availability

Symmetric high availability is when the both the active and standby supervisors are up and running before
the active OpenFlow agent establishes an OpenFlow TCP connection with the OpenFlow controller.
In symmetric high availability mode, both the active and standby supervisors operate independently. Only
the active supervisor exchanges OpenFlow protocol messages with the controller. All TCP packets received
by the active supervisor from the OpenFlow controller are duplicated to the standby supervisor. The OpenFlow
hardware table configuration, group table entries, and flow entries in both the active and standby supervisors
are synchronized.

Asymmetric High Availability

In asymmetric high availability the standby supervisor boots up only after the active OpenFlow agent establishes
an OpenFlow TCP connection with the controller. When the standby boot up, the flows installed by the
controller on the active supervisor, and the TCP controller connection are not synchronized on the standby.
The high availability process on the active supervisor does a bulk sync to synchronize the controller TCP
connection, and sends flows, groups, OpenFlow Table Feature Message installed on the active to the standby
supervisor. The statistics counters on the standby supervisor are synchronized next, so that the standby can
receive the duplicated, controller sent packets.
When the standby supervisor fails to install the Table Feature Message sent by the active, the standby supervisor
notifies the active of the failure. On receiving the failure information, the active supervisor will not initiate
any further synchronization to the standby. The active supervisor will mark the installation failure as a bulk
sync failure, logs an error message, and notifies the standby supervisor. The standby supervisor reloads upon
receiving the message. In case of group mod and flow mod failures, the same process is followed.
Statistics are also synchronized from the active supervisor to the standby during the bulk sync. Statistics
synchronization failure is ignored, because the statistics are synchronized dynamically every few seconds
after the bulk sync.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

428
 OpenFlow
Probe Interval

Probe Interval
The active supervisor maintains the OpenFlow TCP connection with the controller through the management
interface, GigabitEthernet 0/0, and this connection is synchronized with the standby supervisor. The active
supervisor probes the controller-connection based on the configured probe interval.
After a switchover, the management interface on the new active takes a minimum of 13 seconds to become
operational. Packets sent by the controller until then are not received, and this can lead to the disconnecting
of the OpenFlow TCP connection. To avoid the OpenFlow agent timeout due to the probe-interval, a default
value of 40 seconds is automatically configured on active supervisor.

How to Configure High Availability in OpenFlow Mode

Configuring High Availability in OpenFlow Mode
SUMMARY STEPS
1. enable
2. configure terminal
3. openflow
4. switch 1 pipeline 1
5. controller ipv4 ip-address port port-number vrf vrf-name
6. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 openflow Enables OpenFlow configuration and enters OpenFlow

configuration mode.
Example:
Device(config)# openflow

Step 4 switch 1 pipeline 1 Configures a logical switch and pipeline, and enters
OpenFlow switch configuration mode.
Example:
Device(config-openflow)# switch 1 pipeline 1

Step 5 controller ipv4 ip-address port port-number vrf vrf-name Connects to an OpenFlow controller.
Example: Note High Availability is not supported with TLS.

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

429
 OpenFlow
Configuration Examples for High Availability in OpenFlow Mode

Command or Action Purpose

Device(config-openflow-switch)# controller ipv4
10.2.2.2 port 6633 vrf Mgmt-vrf

Step 6 end Exits OpenFlow switch configuration mode and returns to

privileged EXEC mode.
Example:
Device(config-openflow-switch)# end

Configuration Examples for High Availability in OpenFlow Mode

Examples: Configuring High Availability in OpenFlow Mode
The following example shows how to configure high availability in OpenFlow mode:

Device> enable
Device# configure terminal
Device(config)# openflow
Device(config-openflow)# switch 1 pipeline 1
Device(config-openflow-switch)# controller ipv4 10.2.2.2 port 6633 vrf Mgmt-vrf
Device(config-openflow-switch)# end

Verifying the High Availability Configuration

The following is sample output from the show openflow switch switch-number controller command. The
output fields, connected should be yes, state should be active, and the negotiated protocol version should the
same on the standby supervisor.

Device# show openflow switch 1 controller

Logical Switch Id: 1

Total Controllers: 1

Controller: 1
172.16.18.85:6636
Protocol: tcp
VRF: Mgmt-vrf
Connected: Yes
Role: Equal
Negotiated Protocol Version: OpenFlow 1.3
Last Alive Ping: 2021-01-29 08:44:59 UTC
state: ACTIVE
sec_since_connect: 4893

The following is sample output from the show tcp ha connection command. The state should show ESTAB
on both the active and standby supervisors.

Device# show tcp ha connection

SSO enabled for 1 connections

TCB Local Address Foreign Address (state) Conn Id

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

430
 OpenFlow
Feature Information for High Availability in OpenFlow Mode

7F53B1ADE1E0 172.21.18.87.23401 172.16.18.85.6636 ESTAB 1

Feature Information for High Availability in OpenFlow Mode

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Table 57: Feature Information for High Availability in OpenFlow Mode

Feature Name Release Feature Information

High Availability in Cisco IOS XE Bengaluru 17.5.1 High availability in OpenFlow mode supports
OpenFlow Mode SSO and NSO.
In Cisco IOS XE Bengaluru 17.5.1, this feature
was introduced on the following platform:
• Catalyst 9400 Series Switches

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

431
 OpenFlow
Feature Information for High Availability in OpenFlow Mode

Programmability Configuration Guide, Cisco IOS XE Dublin 17.10.x

432