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.
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.
C O N T E N T S Preface vii About This Document vii Intended Audience viii Organization of the Document Related Documentation viii Document Conventions ix viii Obtaining Documentation ix Cisco.
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 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
Contents XML Request Using Operation Scope (Content Attribute) 5-74 Limiting the Number of Table Entries Returned (Count Attribute) Custom Filtering (Filter Element) 5-77 CHAPTER 6 Cisco CRS-1 Series XML and Encapsulated CLI Operations 5-76 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) Terminating an Iterator CHAPTER 8 7-88 Cisco CRS-1 Series XML Security Authentication Authorization Task Names 8-91 9 8-92
Contents IDL Interface 11-108 Authentication 11-109 CORBA NameServer 11-110 Client Access to the Root Naming Context LR Name Server Tree 11-111 Event Notifications and Alarms 11-111 CORBA Notification Structure CORBA XML Agent Initiative CORBA XML Limitations XML Agent Errors 11-110 11-111 11-112 11-113 11-113 CHAPTER 12 Summary of Cisco CRS-1 Series XML API Configuration Tags CHAPTER 13 Cisco CRS-1 Series XML Schemas XML Schema Retrieval 12-115 13-117 13-117 Common XML Schemas 13-117 Compone
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.
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. This document will be of particular use to those who want to build management client applications.
Preface Document Conventions Document Conventions This publication uses the following conventions: • The symbol ^ represents the key labeled Ctrl. For example, the key combination ^z means “hold down the Ctrl key while you press the Z key.” Command descriptions use these conventions: • Examples that contain system prompts denote interactive sessions, indicating the commands that you should enter at the prompt. The system prompt indicates the current level of the EXEC command interpreter.
Preface Documentation Feedback Cisco.com You can access the most current Cisco documentation at this URL: http://www.cisco.com/univercd/home/home.htm You can access the Cisco website at this URL: http://www.cisco.com You can access international Cisco websites at this URL: http://www.cisco.com/public/countries_languages.shtml Ordering Documentation You can find instructions for ordering documentation at this URL: http://www.cisco.com/univercd/cc/td/doc/es_inpck/pdi.
Preface Obtaining Technical Assistance Cisco Technical Support Website The Cisco Technical Support Website provides online documents and tools for troubleshooting and resolving technical issues with Cisco products and technologies. The website is available 24 hours a day, 365 days a year at this URL: http://www.cisco.com/techsupport Access to all tools on the Cisco Technical Support Website requires a Cisco.com user ID and password.
Preface Obtaining Additional Publications and Information Obtaining Additional Publications and Information Information about Cisco products, technologies, and network solutions is available from various online and printed sources. • Cisco Marketplace provides a variety of Cisco books, reference guides, and logo merchandise. Visit Cisco Marketplace, the company store, at this URL: http://www.cisco.
C H A P T E R 1 Cisco CRS-1 Series XML API Overview This chapter contains the following sections: • Introduction, page 1-13 • Cisco CRS-1 Series Management XML Interface, page 1-14 • Cisco CRS-1 Series XML API and Cisco CRS-1 Series Router System Features, page 1-15 • Cisco CRS-1 Series XML API Tags, page 1-16 Introduction The Cisco CRS-1 Series Carrier Routing System XML API Guide explains how to use the Cisco CRS-1 Series XML API to configure Cisco CRS-1 Series routers or request information abo
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series Management XML Interface Note The XML API code is available for use on any Cisco platform that runs Cisco IOS XR software. Definition of Terms Table 1-1 defines the words, acronyms, and actions used throughout this guide.
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API and Cisco CRS-1 Series Router System Features • How to use Cisco CRS-1 Series XML to configure the Cisco CRS-1 Series router: – Using the two–stage “target configuration” mechanism provided by the Cisco CRS-1 Series configuration manager – Using features such as locking, loading, browsing, modifying, saving, and committing the configuration • Accessing the Cisco CRS-1 Series router’s operational data with XML • Working with the
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API Tags Figure 1-1 presents a high level view of the XML manageability-related components along with the request and response flows between the client application and the Cisco CRS-1 Series router.
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API Tags Operation-specific content goes here . . . Sample XML Response from Router . . . Operation response data returned here . . . Note All examples in this document are formatted with new lines and white space to aid readability.
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API Tags Request and Response Tags Following the XML declaration tag a client application must enclose each request stream within a set of start and end tags. Also, the Cisco CRS-1 Series system encloses each XML response within a set of start and end tags.
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API Tags Operation Type Tags Following the tag, the client application must specify the operation types to be carried out by the Cisco CRS-1 Series router. There are three general types of operations supported along with the operation for large responses. Each of these operation types is described in the following sections.
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API Tags Table 1-4 Configuration Services Operation Tags (continued) Tags Description Get a list of commits made to the running configuration. Get a list of the user sessions currently configuring the box. Note The XML schema definitions for the configuration services operation type tags are contained in the schema file cfgmgr_operations.
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API Tags XML Request Batching The Cisco CRS-1 Series XML interface supports the combining of several requests or operations into a single request. When multiple operations are specified in a single request, the response contains the same operation tags and in the same order as they appeared in the request. Batched requests are performed “best effort.
Chapter 1 Cisco CRS-1 Series XML API Overview Cisco CRS-1 Series XML API Tags . . . . . . . . . Get response content returned here . . . . . . . . . . . . . . . . . . Get response content returned here . . . . . . . . .
C H A P T E R 2 Cisco CRS-1 Series XML Router Configuration and Management This chapter reviews the basic extensible markup language (XML) requests and responses used to configure and manage the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) router. Note The XML application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations be promoted (that is, committed) to the running configuration explicitly by the client application in order to replace or become the running configuration. If the client session breaks, the current target configuration is aborted and any outstanding locks are released. Note Only the syntax of the target configuration is checked and verified to be compatible with the installed software image on the router.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Locking the Running Configuration The client application uses the operation to obtain an exclusive lock on the running configuration in order to prevent modification by other users or applications. If the lock operation is successful, the response contains only the tag.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Getting Configuration Data Table 2-1 describes the Source options. Table 2-1 Source Options Name Description ChangedConfig Read only from the changes made to the target configuration for the current session. This option effectively gets the configuration changes made from the current session since the last configuration commit. This option corresponds to the CLI command show configuration.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Browsing the Changed Configuration When a client application issues a request with a Source type of ChangedConfig, the response contains the OperationType attribute to indicate whether the returned changes to the target configuration were a result of or operations. Use to browse uncommitted target configuration changes.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Sample XML Response from the Cisco CRS-1 Series Router Sample XML Client Request to Browse Uncommitted Target Configuration Changes
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Loading the Target Configuration The client application uses the operation along with the tag to populate the target configuration with the contents of a binary configuration file previously saved on the router using the operation. Use the tag to name the file from which the configuration is to be loaded.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations A syntax check is performed whenever the client application writes to the target configuration. A successful write to the target configuration, however, does not guarantee that the configuration change can succeed when a subsequent commit of the target configuration is attempted. For example, errors resulting from failed verifications may be returned from the commit.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Saving the Target Configuration The client application uses the operation along with the tag to save the contents of the target configuration to a binary file on the Cisco CRS-1 Series router. Use the tag to name the file to which the configuration is to be saved. You must specify the complete path of the file to be saved when you use the tag.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Commit Operation Table 2-2 describes the four optional attributes that are specified with the operation. Table 2-2 Commit Operation Attributes Name Description Mode Use the Mode attribute in the request to specify whether the target configuration should be committed on an Atomic or BestEffort basis.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations Sample XML Response from the Cisco CRS-1 Series Router
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations 4 10 Sample XML Response from the Cisco CRS-1 Series Router Sample Request to Commit the Target Configuration
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Configuration Operations The following example shows a request to load and display the failed configuration from the last operation. This request corresponds to the CLI command show configuration failed. Sample XML Client Request to Load the Failed Configuration from the Last Operation
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML The following sections describe the optional configuration and router management tasks available to the client application: • Getting Commit Changes, page 2-36 • Clearing a Target Session, page 2-38 • Rolling Back Configuration Changes to a Speci
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML The client application can read a set of commit changes using the operation along with the request type tag when it includes the Source attribute option CommitChanges.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML Clearing a Target Session Prior to committing the target configuration to the active running configuration, the client application can use the operation to clear the target configuration session.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML The following example shows a request to roll back the configuration changes to a specified commit identifier. This request corresponds to the CLI command rollback configuration to 1000000072. Sample XML Request to Roll Back the Configuration Changes to a Specified Commit Identifier
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML The following example shows a request to roll back the configuration changes made during the previous three commits. This request corresponds to the CLI command rollback configuration last 3. Sample XML Request to Roll Back Configuration Changes to a Specified Number of Commits
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML The following example shows the use of the PreviousCommits attribute to get the roll back changes for rolling back a specified number of commits. This request corresponds to the CLI command show rollback-changes last 4. Sample XML Client Request to Get Roll Back Changes Using the PreviousCommits Attribute
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML Table 2-7 describes the optional attributes available with the operation. Table 2-7 Optional Attributes to Get Configuration History Name Description Maximum Use the Maximum attribute to specify the maximum number of entries to return from the commit history file.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML Tue June 17 11:07:55 2003 My CDP config update Getting Configuration Session Information The client application uses the operation to get the list of all users configuring the Cisco CRS-1 Series router.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML false Replacing the Current Running Configuration A client application replaces the current running configuration on the router with an off-the-box configuration file by performing the following operations in sequence: 1. Lock the configuration. 2.
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML . configuration data goes here . . . Sample XML Response from the Cisco CRS-1 Series Router
Chapter 2 Cisco CRS-1 Series XML Router Configuration and Management Additional Cisco CRS-1 Series Router Configuration and Management Options Using XML Cisco CRS-1 Series Carrier Routing System XML API Guide 2-46 OL-4596-02
C H A P T E R 3 Cisco CRS-1 Series XML Operational Requests and Fault Management A client application can send an extensible markup language (XML) request to get the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) router operational information using either a native data request along with the tag, or the equivalent command-line interface (CLI) command.
Chapter 3 Cisco CRS-1 Series XML Operational Requests and Fault Management Action Requests Sample XML Response from the Cisco CRS-1 Series Router true 10.1.0.1 33.67.205.171 3 1 . . .
Chapter 3 Cisco CRS-1 Series XML Operational Requests and Fault Management Action Requests The following is an additional example showing an action request to clear the peer drop information for all BGP neighbors. This request is equivalent to the CLI command clear ip bgp peer-drops *. Sample XML Request to Clear Peer Drop Information for All BGP Neighbors
Chapter 3 Cisco CRS-1 Series XML Operational Requests and Fault Management Action Requests Upon receiving the configuration change notification, a client application can then use the and operations to load and browse the changed configuration.
C H A P T E R 4 Cisco CRS-1 Series XML and Native Data Operations Native data operations , , and provide basic access to configuration and operational data residing on the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) router. This chapter describes the content of the native data operations and provides an example of each operation type. Note The XML application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software.
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content . . Sample XML Response from the Cisco CRS-1 Series Router . . . response content returned here . . .
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content Note You should use only the supported XML schema objects; therefore, do not attempt to write a request for other objects. The Cisco CRS-1 Series XML schema information is mapped to the XML instance. Main Hierarchy Structure The main structure of the hierarchy consists of the native data model organized as a tree of nodes, where related data items appear in the same branch of the tree.
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content Hierarchy Tables One special type of container element is a table. Tables can hold any number of keyed entries, and are used when there can be multiple instances of an entity. For example, BGP has a table of multiple neighbors, each of which has a unique IP address "key" to identify it. In this case, the table element is , and its child element signifying a particular neighbor is .
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content The following example shows table filtering: IPv4Unicast Leaf Nodes The leaf nodes hold values and are generally simple one-value items where the element representing the leaf node uses character data to specify the value (as in "10" in the example in th
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content Null Value Representations The standard attribute “xsi:nil” is used with a value of “true” when a null value is specified for an element in an XML request or response document.
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content 1 60 180 Native Data Operation Examples These sections provide examples of the basic , , and operations: • Set Configuration Data Request: Example, page 4-57 • Get Request: Example,
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content 10.0.101.
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content 10.0.101.6 Sample XML Response from the Cisco CRS-1 Series Router
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content Get Request of Nonexistent Data: Example The following example shows a native data request to get the configuration values for a particular BGP neighbor similar to the previous example. However, in this example the client application is requesting the configuration for a nonexistent neighbor.
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content . . . Delete Request: Example The following example shows a native data request to delete the address-independent configuration for a particular BGP neighbor. Note that if a request is made to delete an item that does not exist in the current configuration, an error is not returned to the client application.
Chapter 4 Cisco CRS-1 Series XML and Native Data Operations Native Data Operation Content Cisco CRS-1 Series Carrier Routing System XML API Guide 4-62 OL-4596-02
C H A P T E R 5 Cisco CRS-1 Series XML and Native Data Access Techniques This chapter describes the various techniques or strategies you can use to structure native data operation requests to access the information needed within the extensible markup language (XML) schema object class hierarchy. Note The XML application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques The actual data returned in a request depends on the value of the Source attribute as defined in the “Getting Configuration Data” section on page 2-26. Note The term “container” is used in this document as a general reference to any grouping of related data, for example, all of the configuration data for a particular Border Gateway Protocol (BGP) neighbor.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample XML Response from the Cisco CRS-1 Series Router . . . response data goes here . . .
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample XML Response from the Cisco CRS-1 Series Router 3 10.0.101.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques 3 10.0.101.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques The object class hierarchy may also be compressed into the most “efficient” XML. In other words, it is not necessary to repeat hierarchies within a request. Before combining multiple operations inside one tag, the following limitations should be noted for Release 3.0. Any operations that request multiple items of data must be sent in a separate XML request.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques 3 10.0.101.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques 3 10.0.101.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques Note Although partial wildcarding of NodeIDs is not available in XML, each element of the NodeID has to be wildcarded, similar to the support on the CLI of */*/* as the only wildcards supported for locations. The following example shows how to use the Match attribute to get the value for all configured BGP neighbors.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques 10.0.101.3 3 . . . data for more neighbors returned here . . .
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques 10.0.101.8 Sample XML Response from the Cisco CRS-1 Series Router
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques 10.0.101.6 . . . data returned for 3rd neighbor . . . XML Request Using Operation Scope (Content Attribute) The Content attribute is used on any table element in order to specify the scope of a operation.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques Sample XML Response from the Cisco CRS-1 Series Router 3 10.0.101.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques Limiting the Number of Table Entries Returned (Count Attribute) The Count attribute is used on any table element within a operation to specify the maximum number of table entries to be returned in a response.
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques 10.0.101.1 . . . data for 1st neighbor returned here . . . 10.0.101.2 . . . data returned for 2nd neighbor here . . . . . . data returned for remaining neighbors here . . .
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques In the following example, the filter is used to retrieve operational information for all neighbors in autonomous system 6: Sample XML Client Request Using Filtering
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques Cisco CRS-1 Series Carrier Routing System XML API Guide OL-4596-02 5-79
Chapter 5 Cisco CRS-1 Series XML and Native Data Access Techniques Available Set of Native Data Access Techniques Cisco CRS-1 Series Carrier Routing System XML API Guide 5-80 OL-4596-02
C H A P T E R 6 Cisco CRS-1 Series XML and Encapsulated CLI Operations The extensible markup language (XML) interface for the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) provides support for XML encapsulated command-line interface (CLI) commands and responses. This chapter provides information on XML CLI command tags. Note The XML application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software.
Chapter 6 Cisco CRS-1 Series XML and Encapsulated CLI Operations XML CLI Command Tags Table 6-1 Operational Attribute Values (continued) Help Gets help on the last command in the list of commands sent in the request. There should not be any empty lines after the last command (because the last command is considered to be the one on the last line) CommandCompletion Completes the last keyword of the last command.
Chapter 6 Cisco CRS-1 Series XML and Encapsulated CLI Operations XML CLI Command Tags • Iterators in responses to CLI commands such as the show run and show configuration commands. • Multiple simultaneous CLI requests; that is, only one XML request can be issued at a time across all client sessions on the router.
Chapter 6 Cisco CRS-1 Series XML and Encapsulated CLI Operations XML CLI Command Tags Cisco CRS-1 Series Carrier Routing System XML API Guide 6-84 OL-4596-02
C H A P T E R 7 Cisco CRS-1 Series XML and Large Data Retrieval (Iterators) The extensible markup language (XML) for the Cisco CRS-1 Series router supports the retrieval of large XML responses in blocks (that is, in chunks or sections). Note The XML application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software. This chapter provides information on large data retrieval.
Chapter 7 Cisco CRS-1 Series XML and Large Data Retrieval (Iterators) To reduce memory overhead and avoid memory starvation of the router, the following limitations are placed on the number of allowed iterators: Note • 10—Maximum number of iterators allowed at any one time on a given client session. • 100—Maximum number of iterators allowed at any one time for all client sessions.
Chapter 7 Cisco CRS-1 Series XML and Large Data Retrieval (Iterators) Second XML Client Request Using the Iterator to Retrieve the Next Block of BGP Configuration Data Sample XML Response from the Cisco CRS-1 Series Router Containing the Second Block of Retrieved Data
Chapter 7 Cisco CRS-1 Series XML and Large Data Retrieval (Iterators) Terminating an Iterator Final XML Client Request Using the Iterator to Retrieve the Last Block of BGP Configuration Data Final XML Response from the Cisco CRS-1 Series Router Containing the Final Block of Retrieved Data
Chapter 7 Cisco CRS-1 Series XML and Large Data Retrieval (Iterators) Terminating an Iterator Sample XML Response from the Cisco CRS-1 Series Router 3 . . . 1st block of data returned here . . .
Chapter 7 Cisco CRS-1 Series XML and Large Data Retrieval (Iterators) Terminating an Iterator Cisco CRS-1 Series Carrier Routing System XML API Guide 7-90 OL-4596-02
C H A P T E R 8 Cisco CRS-1 Series XML Security Specific security privileges are required for a client application requesting information from the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) router. Note The extensible markup language (XML) application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software.
Chapter 8 Cisco CRS-1 Series XML Security Retrieving Task Permissions A client application requesting an operation through the XML interface must have the appropriate task privileges enabled/assigned for any objects accessed in the operation: • operations require AAA “read” privileges. • and operations require AAA “write” privileges. The “configuration services” operations through configuration manager can also require the appropriate predefined task privileges.
Chapter 8 Cisco CRS-1 Series XML Security Task Privileges Task Privileges A client application requesting a native data operation through the XML interface must have the appropriate task privileges enabled/assigned for any items accessed in the operation, as follows: • , , and operations require AAA “read” privileges. • and operations require AAA “write” privileges.
Chapter 8 Cisco CRS-1 Series XML Security Authorization Failure Authorization Failure If an operation requested by a client application fails authorization, an appropriate element is returned in the response sent to the client. For “native data” operations, the element is associated with the specific element or object where the authorization error occurred.
C H A P T E R 9 Cisco CRS-1 Series XML Schema Versioning Before the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) can carry out a client application request, it must verify version compatibility between the client request and router component versions.
Chapter 9 Cisco CRS-1 Series XML Schema Versioning Run-Time Use of Version Information The following example shows the relevant portion of the complex type definition for an element that carries version information: Global BGP config 1 0 bgp
Chapter 9 Cisco CRS-1 Series XML Schema Versioning Run-Time Use of Version Information Placement of Version Information The following example shows the placement of the MajorVersion and MinorVersion attributes within a client request to retrieve the global BGP configuration data for a specified autonomous system: Sample Client Request Showing Placement of Version Information
Chapter 9 Cisco CRS-1 Series XML Schema Versioning Run-Time Use of Version Information Sample XML Client Request with a Version Mismatch 3 Sample XML Response from the Cisco CRS-1 Series Router
Chapter 9 Cisco CRS-1 Series XML Schema Versioning Retrieving Version Information Sample XML Response from the Cisco CRS-1 Series Router PAGE 100Chapter 9 Cisco CRS-1 Series XML Schema Versioning Retrieving Version Information Sample XML Response from the Cisco CRS-1 Series Router . . .
C H A P T E R 10 Error Reporting in Cisco CRS-1 Series XML Responses The extensible markup language (XML) responses returned by the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) router contains error information as appropriate, including the operation, object, and cause of the error when possible.
Chapter 10 Error Reporting in Cisco CRS-1 Series XML Responses Types of Reported Errors These error categories are described in the following sections: • Error Attributes, page 10-102 • Transport Errors, page 10-102 • XML Parse Errors, page 10-102 • XML Schema Errors, page 10-103 • Operation Processing Errors, page 10-105 • Error Codes and Messages, page 10-105 Error Attributes If one or more errors occur during the processing of a requested operation, the corresponding XML response includes
Chapter 10 Error Reporting in Cisco CRS-1 Series XML Responses Types of Reported Errors 3 Sample XML Response from the Cisco CRS-1 Series Router PAGE 104Chapter 10 Error Reporting in Cisco CRS-1 Series XML Responses Types of Reported Errors Sample XML Response from the Cisco CRS-1 Series Router PAGE 105Chapter 10 Error Reporting in Cisco CRS-1 Series XML Responses Types of Reported Errors 3
Chapter 10 Error Reporting in Cisco CRS-1 Series XML Responses Types of Reported Errors Cisco CRS-1 Series Carrier Routing System XML API Guide 10-106 OL-4596-02
C H A P T E R 11 XML Transport and Event Notifications This chapter discusses the Common Object Request Broker Architecture (CORBA) as the extensible markup language (XML) transport mechanism for the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series), and its Internet Inter-ORB Protocol (IIOP), the protocol used for accessing objects across the Internet. CORBA-based event notifications are also discussed in this chapter.
Chapter 11 XML Transport and Event Notifications Cisco CRS-1 Series XML Transport and CORBA IDL When the CORBA XML agent receives the XML request, it uses the XML infrastructure on the router to parse and process the request. The agent then obtains the XML response from the XML infrastructure and passes this back to the client as a response parameter on the “invoke()” method return. IDL Interface The following IDL example defines the interfaces used to make Cisco CRS-1 Series XML API requests.
Chapter 11 XML Transport and Event Notifications Cisco CRS-1 Series XML Transport and CORBA IDL * * IN - internally generated context for a given valid login session. * Clients pass this as it is obtained in login method. * * Argument: request * * IN - XML request string. Passed to XML Infra for processing * * Argument: response * * OUT - contain response obtained from XML Infra or error code * and error message string in case of response failure from XML Infra.
Chapter 11 XML Transport and Event Notifications CORBA NameServer Table 11-1 describes the “login()” implementation in the CORBA XML agent that uses AAA options as part of the Authentication API. Table 11-1 Authentication, Authorization, and Accounting Options Name Description default Determines the authentication method. ASCII authentication Determines the username and password. As a result, the username and password supplied in the “login()” method call should be unencrypted ASCII text.
Chapter 11 XML Transport and Event Notifications CORBA Notification Structure The Naming Service IOR file can be obtained from the router through HTTP at: https:///cwi/ns_ssl.ior Note Connection to the Naming Service through an IP address is not supported. LR Name Server Tree The name hierarchy for the Cisco CRS-1 Series router is shown in Figure 11-1. The root naming context identifies the particular logical router (LR) on which the Name Server is running.
Chapter 11 XML Transport and Event Notifications CORBA XML Agent Initiative The complete definition of the structured event is as follows: Fixed header: .alarm. Filterable data: filter:SourceID : filter:Category : filter:Severity : Variable header: variable:SourceID : variable:Category : variable:Severity : Payload: PAGE 113Chapter 11 XML Transport and Event Notifications CORBA XML Limitations The CORBA XML agent is started as follows: router# configure terminal router(config)# xml agent corba ssl router(config)# commit router(config)# exit CORBA XML Limitations The following limitations apply to the XML transport over CORBA: • The maximum size of the response data returned to the client application is 32 KB.
Chapter 11 XML Transport and Event Notifications XML Agent Errors Cisco CRS-1 Series Carrier Routing System XML API Guide 11-114 OL-4596-02
C H A P T E R 12 Summary of Cisco CRS-1 Series XML API Configuration Tags Table 12-1 provides the command-line interface (CLI) to extensible markup language (XML) application programming interface (API) tag mapping for the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) router target configuration.
Chapter 12 Summary of Cisco CRS-1 Series XML API Configuration Tags 2. This XML tag releases the lock on a running configuration but does not end the configuration session. 3. This CLI command starts a new configuration session and locks the running configuration. 4. This XML tag locks the running configuration from a configuration session that is already in progress.
C H A P T E R 13 Cisco CRS-1 Series XML Schemas This chapter contains information about common XML schemas. The structure and allowable content of the extensible markup language (XML) request and response instances supported by the Cisco IOS XR XML application programming interface (API) are documented by means of XML schemas (.xsd files).
Chapter 13 Cisco CRS-1 Series XML Schemas Common XML Schemas Component XML Schemas In addition to the common XML schemas, component XML schemas (such as native data) are provided and contain the data model for each feature. There is typically one component XML schema for each major type of data supported by the component—configuration, operational, action, administration operational, and administration action data—plus any complex data type definitions in the operational space.
A P P E N D I X A Sample BGP Configuration The following is an excerpt of the relevant portions of the command-line interface (CLI) configuration used as a basis for the Border Gateway Protocol (BGP) examples contained within this document: router bgp 3 timers bgp 60 180 bgp router-id 10.1.0.1 bgp update-delay 55 bgp cluster-id 10.1.0.
Appendix A Sample BGP Configuration address-family ipv4 unicast send-community-ebgp route-map EBGP_IN_1 in exit address-family ipv4 multicast send-community-ebgp route-map EBGP_IN_1 in exit exit neighbor 10.0.101.2 remote-as 2 ebgp-multihop 255 address-family ipv4 unicast send-community-ebgp capability orf prefix-list receive route-map EBGP_IN_1 in exit address-family ipv4 multicast send-community-ebgp route-map EBGP_IN_1 in exit exit neighbor 10.0.101.
Appendix A Sample BGP Configuration ebgp-multihop 255 address-family ipv4 unicast prefix-list orf in capability orf prefix-list send exit address-family ipv4 multicast prefix-list orf in exit exit neighbor 10.0.101.8 remote-as 8 ebgp-multihop 255 address-family ipv4 multicast exit exit . . .
Appendix A Sample BGP Configuration Cisco CRS-1 Series Carrier Routing System XML API Guide A-122 OL-4596-02
G L O S S A RY A AAA authentication, authorization, and accounting. A network security service that provides the primary framework to set up access control on a Cisco CRS-1 Series router or access server. AAA is an architectural framework and modular means of configuring three independent, but closely related security functions in a consistent manner. B BGP Border Gateway Protocol. A routing protocol used between autonomous systems. It is the routing protocol that makes the internet work.
Glossary G Gigabits per second. The amount of data that can be sent in a fixed amount of time. 1 gigabit = 230 bits, 1,073,741,824 bits. Gbps H HTTP Hypertext Transfer Protocol. Used by web browsers and web servers to transfer files, such as text and graphic files. The Hypertext Transfer Protocol (HTTP) is the set of rules for exchanging files (text, graphic images, sound, video, and other multimedia files) on the World Wide Web.
Glossary MPLS-TE Multiprotocol Label Switching traffic engineering MSC See modular services card. N node A card installed and running in a Cisco CRS-1 Series routing system. In the Cisco 12000 series Internet router, nodes are identified by slot number (for example, node 1). R router Network layer device that uses one or more routing metrics to determine the optimal path along which network traffic should be forwarded.
Glossary target configuration The current Cisco IOS XR running configuration plus the autonomous changes made to that configuration by a user. The target configuration is promoted to the running configuration by means of the commit command. Tbps Terabits per second = 1,000,000,000,000 (1 trillion) bits per second. The amount of data that can be sent in a fixed amount of time. Telnet Standard terminal emulation protocol in the TCP/IP protocol stack.
I N D EX Symbols 1-20 4-52 4-52 1-20 tag
Index commit A AAA 1-14, 8-91 AAA login alarms 2-23 3-49 Atomic mode 2-32 changes 2-36 database 2-33 identifier 2-39 Commit tag 1-19 common_types.
Index E M element Match attribute null value MergedConfig 4-56 encoding (UTF-8), XML 13-117 error attributes 10-102, 10-103 ErrorMsg N 10-102 namespace 10-102 13-117 native data nonexistent data 4-60 access techniques 10-101 event notification model, types of 3-49 operations extensible markup language See XML 4-52 namespace_types.xsd error reporting types of 2-26 1-17 error_types.
Index (continued) P target configuration commit privileges, security 8-91 unlocking R 2-31 2-24, 2-35 S read privileges 8-92 Save tag repeat naming information 5-63, 5-72 schema file organization request schemas, XML Set tag ChangedConfig batching 2-27 SSH 1-14 maximum size 2-25 1-14 1-18 T 5-72 1-16 tag top level structure of Request Type tag 1-16 Cisco CRS-1 Series XML API 4-52 XML response 7-85 definition 1-14 error reporting Tags 7-85 1-18 1-18 4-56 comm
Index U Unlock tag 1-19 upgrades, schema file 13-118 V version, XML 1-17 W wildcards 5-63 World Wide Web Consortium (W3C) XML Schema Language 13-117 write privileges 8-92 X XML (extensible markup language) agent 1-14, 1-15 client 1-14 instance 4-56 operation 1-14 operation provider parse errors schema 1-14 10-101, 10-102 1-14 definitions for the native data operation type tags 1-19 errors session 10-101, 10-103 1-18 XML schemas 13-117 Cisco CRS-1 Series Carrier Routing System XML
Index Cisco CRS-1 Series Carrier Routing System XML API Guide IN-132 OL-4596-02
