Download - © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 1 November, 2008 David Muñoz ([email protected])[email protected] XML API.

© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 1

November, 2008

David Muñoz ([email protected])

XML API


Session Objectives

At the end of the session, the participants should be able to:

Understand XML API Usage

Understand how to find and use the ACE DTD

Call the XML API from a Shell command

Create a simple API script


ACE XML API

Three ways to control ACE

GUI (ANM)

CLI

XML

XML input can be POSTed to a predefined location

XML output in return

XML API can be used both for configuring and monitoring the operations of the ACE

A robust XML Web Services framework helps reduce the cost of managing complex environments


API Commands & Expected Responses POST XML to http://<ace-ip_address>/bin/xml_agent

Just POST one variable called xml_cmd=<request_xml>…

The list of elements supported is listed in the DTD

Think of the DTD as a lightweight SDK (Software Development Kit)

After enabling HTTP access to the ACE (module or appliance) the DTD is accessible under

http://ace-ip_address/ace_appliance.dtd 4710

http://ace-ip_addresscisco_ace.dtd Module

The DTD describes syntax rules for elements and their attributes

Elements consist of input and output variables (commands and their results), a real server for instance is an element. Attributes contain the IP address or the name of that real server.


How To Interpret The DTD DTD Element:

<!ELEMENT rserver (description, ip_address, conn-limit, probe_rserver, weight, inservice, webhost-redirection)*>

<!ATTLIST rserver sense CDATA #FIXED "no" type (redirect | host) #IMPLIED name CDATA #REQUIRED

Element above describes one item: rserver

This element refers to other optional elements (between parentheses) which are also described in the DTD.

DTD entry also refers to a list of attributes (ATTLIST):

sense (used to negate the command – the ‘no’ form of it)

type (either redirect or host in this case)

name (the name the user has assigned to the rserver).

‘*’ or ‘?’ means “optional”‘+’ means “one or more”


Sending Commands

Based on the previous slide, the very minimal set of information that needs to be sent to ACE C2PI to add a new rserver is

Additional information could include an IP address. Look up the DTD for ip_address:

<request_xml><rserver name='foo'/></request_xml>

<!ELEMENT ip_address EMPTY><!ATTLIST ip_address sense CDATA #FIXED "no" address NMTOKEN #REQUIRED routing-option (routed) #IMPLIED netmask NMTOKEN #IMPLIED>

Attribute listfor ip_address


Attributes For Sending Commands

Possible Attributes values

CDATA The value is character data(en1|en2|..) The value must be one from an enumerated listID The value is a unique id IDREF The value is the id of another elementIDREFS The value is a list of other idsNMTOKEN The value is a valid XML nameNMTOKENS The value is a list of valid XML namesENTITY The value is an entity ENTITIES The value is a list of entitiesNOTATION The value is a name of a notationxml: The value is a predefined xml value


Sending commands: Complex example

Combining the rserver element with several of its attributes which are themselves defined in the DTD, we can create a slightly more complete rserver as follows:

To send this to the ACE, you can use a variety of programming or scripting languages (Perl, Curl, PHP, Java, etc.)

<rserver type=‘host’ name=‘rserver1’><description descr-string=‘R1’/><ip_address address=‘192.168.1.1’/><inservice/>

</rserver>


XML Example

Sample request to create a new user account: <request_xml>

<username name=‘betauser' password_encryp-type='0' password='cisco123' expire='2008-09-30’ role='Admin'/>

</request_xml>

XML response:<response_xml>

<config_command>

<command>

username betabuser password 0 cisco123 expire 2008-09-20 role Admin

</command>

<status code="100" text="XML_CMD_SUCCESS"/>

</config_command>

</response_xml>


Setup to use the API Use XML commands through the Admin Context

Allows you to manipulate other contexts as if you did a “changeto”

Configure Management Policy to allow HTTP / HTTPSclass-map type management match-any remote_access 201 match protocol xml-https any ACE 4710 only 202 match protocol snmp any 203 match protocol telnet any 204 match protocol https any ACE Module 205 match protocol http any 206 match protocol icmp any 207 match protocol ssh any

Download the Device DTD from the device:

http://<Admin Context IP>/bin/index


Setup to use the API (continued) Download the Device DTD from the device:

http://<Admin Context IP>/bin/index


Setup to use the API (continued) Choose the xml command you want from the DTD

Mostly a one-to-one correlation between XML commands and the CLI

Two methods

<request_xml>${command}<request_xml> Preferred

<request_raw>${CLI}<request_raw>

Test using browser or curl


Setup to use the API (continued) On the 4710 Appliance Use

http://<Admin contex>/bin/xml_agentor https://<Admin contex>:10443/bin/xml_agent

For the ACE Module usehttp://<Admin contex>/bin/xml_agentor https://<Admin contex>:443/bin/xml_agent

Incorporate into your scripts

Debug XML commands with –trace option on Curl


XML Command Example Response: <show_running-config/>

[linux] $ ./xml_show_run_example.sh <response_xml context-name='Admin'><exec_command><command>show running-config</command><status code="100" text="XML_CMD_SUCCESS"/><xml_show_result><xml_show_running_config>

<resource-class rsc-class-name='Bronze_Service'> <limit-resource resource-type='all' minimum='5.00' maximum='equal-to-min'/></resource-class>..<username name='admin' password_encryp-type='5'

password='$1$4juRjIjy$SiSZjoGeTa89Sblb4UXpD.' role='Admin' domain='default-domain'/>

<username name='www' password_encryp-type='5' password='$1$0ZGlJXpf$0ZNcw.msB.XONNLftrJ2z1' role='Admin' domain='default-domain'/>

ssh key rsa 1024 force

</xml_show_running_config>

</xml_show_result></exec_command></response_xml>

Portions omitted to fit


XML Command Example BreakdownCommand Line:/usr/bin/curl "http://admin:[email protected]/bin/xml_agent" -k -d "xml_cmd=<request_xml context-name=\"Admin\"><show_running-config/></request_xml>“

Curl command: /usr/bin/curl

URL: http://admin:[email protected]/bin/xml_agent

Curl Options: -k -d

Post:"xml_cmd=

<request_xml context-name=\"Admin\">

<show_running-config/> XML Command

</request_xml>“


Recommendations Use “Curl” for simple scripting

Easy to setup/use

Flexible

Allows https

Excellent tracing capability

Callable from various scripting languages [tcl, perl, bash]

Call curl from Bash, Perl or your favorite scripting language.

Parse using UNIX/Linux tools

Parsing with Perl’s string functions is often easier than using an XML parser like DOM or Xerces

Use <request_xml> method

Ensures “atomicity” and makes object parsing easier


Additional Resources curl – “man curl” or “info curl” from the bash command

line. Check command line options for ssl and ‘trace’ options

Cygwin – Unix environment for Windows PCs

http://www.cygwin.com/

Bash – the “Bourne Again Shell”

http://tldp.org/LDP/abs/html/

Perl -- http://www.cpan.org/


Key Takeaways

The Key Takeaways of this presentation are:

XML API DTD is embedded in the ACE device

XML API DTD describes available functions and expected returns.

Two XML methods: <request_xml>, <request_raw>

XML API mimic’s CLI funcitionality

Use Curl, Unix/Linux tools and simple scripts to get started.