© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 1 November, 2008 David Muñoz...
-
Upload
marcia-white -
Category
Documents
-
view
212 -
download
0
Transcript of © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 1 November, 2008 David Muñoz...
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 1
November, 2008
David Muñoz ([email protected])
XML API
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 2
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 3
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 4
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.
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 5
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”
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 6
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 7
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 8
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>
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 9
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>
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 10
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 11
Setup to use the API (continued) Download the Device DTD from the device:
http://<Admin Context IP>/bin/index
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 12
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 13
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 14
XML Command Example Command: <show_running-config/>
DTD Entry<!ELEMENT show_running-config EMPTY><!ATTLIST show_running-config info-type (aaa | access-list | class-map | context | dhcp | domain | ft | interface | parameter-map | peer | policy-map | probe | resource class | role | rserver | serverfarm | sticky) #IMPLIED
>
Command Line from BASH
/usr/bin/curl "http://admin:[email protected]/bin/xml_agent" -k -d "xml_cmd=<request_xml context-name=\"Admin\"><show_running-config/></request_xml>“
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 15
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 16
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>“
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 17
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
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 18
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/
© 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 19
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.