Cisco CRS-1 Series Carrier Routing System XML API Guide Cisco IOS XR Software Release 3.0
Total Page:16
File Type:pdf, Size:1020Kb
Cisco CRS-1 Series Carrier Routing System XML API Guide Cisco IOS XR Software Release 3.0 Corporate 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 526-4100 Text Part Number: OL-4596-02 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. CCSP, the Cisco Square Bridge logo, Cisco Unity, Follow Me Browsing, FormShare, and StackWise are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn, and iQuick Study are service marks of Cisco Systems, Inc.; and Aironet, ASIST, BPX, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Empowering the Internet Generation, Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Fast Step, GigaDrive, GigaStack, HomeLink, Internet Quotient, IOS, IP/TV, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, LightStream, Linksys, MeetingPlace, MGX, the Networkers logo, Networking Academy, Network Registrar, Packet, PIX, Post-Routing, Pre-Routing, ProConnect, RateMUX, Registrar, ScriptShare, SlideCast, SMARTnet, StrataView Plus, SwitchProbe, TeleRouter, The Fastest Way to Increase Your Internet Quotient, TransPath, and VCO are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. All other trademarks mentioned in this document or Website 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. (0406R) Cisco CRS-1 Series Carrier Routing System XML API Guide Copyright © 2004 Cisco Systems, Inc. All rights reserved. CONTENTS Preface vii About This Document vii Intended Audience viii Organization of the Document viii Related Documentation viii Document Conventions ix Obtaining Documentation ix Cisco.com x Ordering Documentation x Documentation Feedback x Obtaining Technical Assistance x Cisco Technical Support Website xi Submitting a Service Request xi Definitions of Service Request Severity xi Obtaining Additional Publications and Information xii CHAPTER 1 Cisco CRS-1 Series XML API Overview 1-13 Introduction 1-13 Definition of Terms 1-14 Cisco CRS-1 Series Management XML Interface 1-14 Cisco CRS-1 Series XML API and Cisco CRS-1 Series Router System Features 1-15 Cisco CRS-1 Series XML API Tags 1-16 Basic XML Request Content 1-16 XML Declaration Tag 1-17 Operation Type Tags 1-19 XML Request Batching 1-21 CHAPTER 2 Cisco CRS-1 Series XML Router Configuration and Management 2-23 Target Configuration Overview 2-23 Configuration Operations 2-24 Additional Configuration Options Using XML 2-24 Locking the Running Configuration 2-25 Browsing the Target or Running Configuration 2-25 Cisco CRS-1 Series Carrier Routing System XML API Guide OL-4596-02 iii Contents Browsing the Changed Configuration 2-27 Loading the Target Configuration 2-29 Setting the Target Configuration Explicitly 2-29 Saving the Target Configuration 2-31 Committing the Target Configuration 2-31 Unlocking the Running Configuration 2-35 Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML 2-36 Getting Commit Changes 2-36 Clearing a Target Session 2-38 Rolling Back Configuration Changes to a Specified Commit Identifier 2-38 Rolling Back Configuration Changes to a Specified Number of Commits 2-39 Getting Rollback Changes 2-40 Getting Configuration History 2-41 Getting Configuration Session Information 2-43 Replacing the Current Running Configuration 2-44 CHAPTER 3 Cisco CRS-1 Series XML Operational Requests and Fault Management 3-47 Operational Get Requests 3-47 Action Requests 3-48 Cisco CRS-1 Series XML and Fault Management 3-49 CHAPTER 4 Cisco CRS-1 Series XML and Native Data Operations 4-51 Native Data Operation Content 4-51 Request Type Tag and Namespaces 4-52 Object Hierarchy 4-52 Dependencies Between Configuration Items 4-55 Null Value Representations 4-56 Operation Triggering 4-56 Native Data Operation Examples 4-57 CHAPTER 5 Cisco CRS-1 Series XML and Native Data Access Techniques 5-63 Available Set of Native Data Access Techniques 5-63 XML Request for All Configuration Data 5-64 XML Request for All Configuration Data per Component 5-64 XML Request for All Data Within a Container 5-65 XML Request for Specific Data Items 5-66 XML Request with Combined Object Class Hierarchies 5-67 XML Request Using Wildcarding (Match Attribute) 5-70 XML Request for Specific Object Instances (Repeated Naming Information) 5-72 Cisco CRS-1 Series Carrier Routing System XML API Guide iv OL-4596-02 Contents XML Request Using Operation Scope (Content Attribute) 5-74 Limiting the Number of Table Entries Returned (Count Attribute) 5-76 Custom Filtering (Filter Element) 5-77 CHAPTER 6 Cisco CRS-1 Series XML and Encapsulated CLI Operations 6-81 XML CLI Command Tags 6-81 CLI Command Limitations 6-82 CHAPTER 7 Cisco CRS-1 Series XML and Large Data Retrieval (Iterators) 7-85 Terminating an Iterator 7-88 CHAPTER 8 Cisco CRS-1 Series XML Security 8-91 Authentication 8-91 Authorization 8-91 Retrieving Task Permissions 8-92 Task Privileges 8-93 Task Names 8-93 Authorization Failure 8-94 CHAPTER 9 Cisco CRS-1 Series XML Schema Versioning 9-95 Major and Minor Version Numbers 9-95 Run-Time Use of Version Information 9-96 Placement of Version Information 9-97 Version Lag 9-97 Version Creep 9-98 Retrieving Version Information 9-99 CHAPTER 10 Error Reporting in Cisco CRS-1 Series XML Responses 10-101 Types of Reported Errors 10-101 Error Attributes 10-102 Transport Errors 10-102 XML Parse Errors 10-102 XML Schema Errors 10-103 Operation Processing Errors 10-105 Error Codes and Messages 10-105 CHAPTER 11 XML Transport and Event Notifications 11-107 Cisco CRS-1 Series XML Transport and CORBA IDL 11-107 Cisco CRS-1 Series Carrier Routing System XML API Guide OL-4596-02 v Contents IDL Interface 11-108 Authentication 11-109 CORBA NameServer 11-110 Client Access to the Root Naming Context 11-110 LR Name Server Tree 11-111 Event Notifications and Alarms 11-111 CORBA Notification Structure 11-111 CORBA XML Agent Initiative 11-112 CORBA XML Limitations 11-113 XML Agent Errors 11-113 CHAPTER 12 Summary of Cisco CRS-1 Series XML API Configuration Tags 12-115 CHAPTER 13 Cisco CRS-1 Series XML Schemas 13-117 XML Schema Retrieval 13-117 Common XML Schemas 13-117 Component XML Schemas 13-118 APPENDIX A Sample BGP Configuration A-119 G LOSSARY I NDEX Cisco CRS-1 Series Carrier Routing System XML API Guide vi OL-4596-02 Preface This document describes the extensible markup language (XML) application programming interface (API) provided by the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) to developers of external management applications. The Cisco CRS-1 Series XML interface provides a mechanism for Cisco CRS-1 Series router configuration and monitoring using XML formatted request and response streams. The XML schemas referenced in this guide are used by the management application developer to integrate client applications with the Cisco CRS-1 Series programmable interface. The Cisco CRS-1 Series XML API is also available for use on any Cisco platform running Cisco IOS XR software. Note The XML API code is available for use on any Cisco platform that runs Cisco IOS XR software. The preface contains the following sections: • About This Document, page vii • Related Documentation, page viii • Document Conventions, page ix • Obtaining Documentation, page ix • Documentation Feedback, page x • Obtaining Technical Assistance, page x • Obtaining Additional Publications and Information, page xii About This Document This document provides a comprehensive description of the XML interface to the Cisco CRS-1 Series router. The goal of this guide is to help Cisco CRS-1 Series customers write client applications to interact with the Cisco CRS-1 Series XML infrastructure on the router, and to also use the Cisco CRS-1 Series XML API to build custom end-user interfaces for configuration and information retrieval and display. Cisco CRS-1 Carrier Routing System XML API Guide OL-4596-02 vii Preface Related Documentation Intended Audience This document’s audience is expected to have background knowledge and information about XML, Common Object Request Broker Architecture (CORBA), and network management.