1. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 1 November, 2008 David Muñoz (dmunoz@cisco.com)dmunoz@cisco.com XML API

2. © 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

3. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 3  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

4. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 4 API Commands & Expected Responses  POST XML to http:// /bin/xml_agenthttp:// /bin/xml_agent  Just POST one variable called xml_cmd= …  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.dtdhttp://ace-ip_address/ace_appliance.dtd 4710 http://ace-ip_addresscisco_ace.dtdhttp://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.

5. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 5 How To Interpret The DTD  DTD Element: <!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”

6. © 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: <!ATTLIST ip_address senseCDATA #FIXED "no" address NMTOKEN #REQUIRED routing-option (routed) #IMPLIED netmask NMTOKEN #IMPLIED > Attribute list for ip_address

7. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 7 Attributes For Sending Commands  Possible Attributes values CDATAThe value is character data (en1|en2|..)The value must be one from an enumerated list IDThe value is a unique id IDREFThe value is the id of another element IDREFSThe value is a list of other ids NMTOKENThe value is a valid XML name NMTOKENSThe value is a list of valid XML names ENTITYThe value is an entity ENTITIESThe value is a list of entities NOTATIONThe value is a name of a notation xml:The value is a predefined xml value

8. © 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.)

9. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 9 XML Example  Sample request to create a new user account:  XML response: username betabuser password 0 cisco123 expire 2008- 09-20 role Admin

10. © 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 / HTTPS class-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:// /bin/index

11. © 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:// /bin/index

12. © 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 ${command} Preferred ${CLI}  Test using browser or curl

13. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 13 Setup to use the API (continued)  On the 4710 Appliance Use http:// /bin/xml_agent or https:// :10443/bin/xml_agent  For the ACE Module use http:// /bin/xml_agent or https:// :443/bin/xml_agent  Incorporate into your scripts  Debug XML commands with –trace option on Curl

14. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 14 XML Command Example  Command:  DTD Entry <!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:ciscodemo@172.25.91.41/bin/xml_agent " -k -d "xml_cmd= “

15. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 15 XML Command Example Response: [linux] $./xml_show_run_example.sh show running-config. ssh key rsa 1024 force Portions omitted to fit

16. © 2008 Cisco Systems, Inc. All rights reserved.ACE XML API 16 XML Command Example Breakdown Command Line: /usr/bin/curl "http://admin:ciscodemo@172.25.91.41/bin/xml_agent" -k -d "xml_cmd= “ Curl command: /usr/bin/curl URL: http://admin:ciscodemo@172.25.91.41/bin/x ml_agent Curl Options: -k -d Post: "xml_cmd=  XML Command “

17. © 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 method Ensures “atomicity” and makes object parsing easier

18. © 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/http://www.cpan.org/

19. © 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:,  XML API mimic’s CLI funcitionality  Use Curl, Unix/Linux tools and simple scripts to get started.