Introduction
Cisco customers use a variety of vendor-specific CLI scripts to manage their routers because no alternative programmatic mechanism is available. In addition, a common framework is also not there to develop CLI scripts. In response to this need, ASR 9000 BU (Edge Routing Business Unit) has come up with the XML API which provides the necessary common framework for development, deployment, and maintenance of router management.
The goal of this white paper is to help ASR9000 customers to write client applications to interact with the Cisco XML (eXtensible Markup Language) infrastructure on the ASR9000, and to use the Management XML API to build custom end-user interfaces for configuration and information retrieval and display.
The XML(eXtensible Markup Language) application programming interface (API) provided by the router is an interface used for development of client applications to manage and monitor the router. The XML interface is specified by the XML schemas.
All the XML schemas are listed on CCO for necessary use and reference by Cisco customers:
Cisco ASR 9000 Series Aggregation Services Router XML Schema Object Documentation:
http://www.cisco.com/en/US/docs/routers/asr9000/software/xml/reference/guide/asr9k_all_schemas.html
In a nutshell, XML API provides a mechanism for router configuration and monitoring, which uses an exchange of XML formatted request and response streams.
General XML Introduction
An XML schema is the definition of the XML document. It provides a means for defining the structure, content and semantics of XML documents. This can be customized as per need.
XML interaction starts with an XML request (the file we create) and ends with an XML response (what the router returns).
Sample of a request:
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Get>
<Configuration Source="CurrentConfig">
<FrequencySynchronization/>
</Configuration>
</Get>
</Request>
The types of objects are container, container w/ naming, and leaf.
Core Issue
This section describes the ASR9K Specific XML information
Resolution
XML on ASR9K
- Install, activate, and commit the manageability pie (asr9k-mgbl-p.pie)
- Enable XML agent:
Note : By default, the XML agent is not running. You must enable it using the CLI. The agent receives XML requests from external clients and return XML responses.
Example: RP/0/RSP0/CPU0:ios(config)#xml agent tty
RP/0/RSP0/CPU0:ios(config)#commit
To look at the supported schema on your current IOS-XR version, use the following command:
RP/0/RSP0/CPU0:RO2#show xml schema
Username:root
Password:
Enter 'help' or '?' for help
xml-schema[config]:>
Cisco XML API and Router System Features
Using the XML API, an external client application can send XML encoded management requests to an XML agent running on the router. The XML API readily supports available transport layers including the terminal-based protocols like Telnet, Secure Shell (SSH), dedicated-TCP connection, and Secure Sockets Layer (SSL) dedicated TCP connection.
Before an XML session is established, the XML transport and XML agent must be enabled on the router.
A client request sent to the router must specify the different types of operations to be carried out.
The three general types of management operations supported through XML are:
- Native data access (get, set, delete, and so on) using the native management data model.
- Configuration services for more advanced configuration management through the Configuration Manager.
- Traditional CLI access where the CLI commands and command responses are encapsulated in XML.
When a client request is received by an XML agent on the router, the request is routed to the appropriate XML operation provider in the internal Cisco XML API library for processing. After all the requested operations are processed, the XML agent receives the result and then sends the XML encoded response stream on to the client.
Cisco XML and Native Data Operations
Native data operations <Get>, <Set>, and <Delete> provide basic access to configuration and operational data residing on the router.
Sample XML Client Native Data Operation Request
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Operation>
<Request Type>
.
object hierarchy goes here
.
</Request Type>
</Operation>
</Request>
Sample XML Response from the Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<Operation>
<Request Type>
.
response content returned here
.
</Request Type>
</Operation>
</Response>
Note : For examples refer to the following CCO link :
http://www.cisco.com/en/US/docs/ios_xr_sw/iosxr_r4.0/xml/programming/guide/xl40nati.html#wp1042404
Using the Configuration Services Methods
Various techniques are provided to enable the standard configuration services operations to be performed without knowledge of the underlying XML. These are the operations that are usually performed at the start or end of a configuration session, such as locking the running configuration or saving the configuration to a file.
Committing the Target Configuration
The config_commit() function takes the following optional arguments:
- mode
- label
- comment
- Replace
- KeepFailedConfig
- IgnoreOtherSessions
- Confirmed
For more information, please refer the following CCO link :
http://www.cisco.com/en/US/docs/ios_xr_sw/iosxr_r4.0/xml/programming/guide/xl40petk.html#wp1014524
Cisco XML and Encapsulated CLI Operations
XML interface for the router provides support for XML encapsulated CLI commands and responses. A client application can request a CLI command by encoding the text for the command within a pair of <CLI> start and </CLI> end tags, <Configuration> tags, and <EXEC> tags. The router responds with the uninterpreted CLI text result.
Note : XML encapsulated CLI commands use the same target configuration as the corresponding XML operations <Get>, <Set>, and <Delete>.
The following example uses the <CLI> operation tag:
Sample XML Client Request for CLI Command Using CLI Tags
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<CLI>
<Configuration>
router bgp 3
default-metric 10
timers bgp 80 160
exit
</Configuration>
</CLI>
<Commit/>
<CLI>
<Exec>
sh config commit changes last 1
</Exec>
</CLI>
</Request>
Sample XML Response from the Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<CLI>
<Configuration/>
</CLI>
<Commit CommitID="1000000041"/>
<CLI>
<EXEC>
Building configuration...
router bgp 3
timers bgp 80 160
default-metric 10
end
<EXEC>
</CLI>
</Response>
Note : Refer CCO for command limitations :
http://www.cisco.com/en/US/docs/ios_xr_sw/iosxr_r4.0/xml/programming/guide/xl40cli.html#wp1039202
Related Information
Cisco IOS XR XML API Guide, Cisco IOS XR Release 4.0
http://www.cisco.com/en/US/docs/ios_xr_sw/iosxr_r4.0/xml/programming/guide/xl40api.html
Cisco IOS XR Software Release 3.9 : Schemas
http://www.cisco.com/en/US/docs/routers/asr9000/software/asr9k_r3.9/xml/schemas/asr9k_all_schemas.zip
Cisco IOS XR Software Release 3.7.2
http://www.cisco.com/en/US/docs/routers/asr9000/software/xml/reference/guide/asr9k_all_schemas.html
Parikshit Sharma
NCE -Advanced Services
Cisco Systems
