XML API

1. XML API November, 2008 David Muñoz (dmunoz@cisco.com)

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

4. API Commands & Expected Responses • POST XML to http://<ace-ip_address>/bin/xml_agent • Just POST one variable calledxml_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.

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”

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 list for ip_address

7. Attributes For Sending Commands • Possible Attributes values • CDATA The value is character data • (en1|en2|..) The value must be one from an enumerated list • ID The value is a unique id • IDREF The value is the id of another element • IDREFS The value is a list of other ids • NMTOKEN The value is a valid XML name • NMTOKENS The value is a list of valid XML names • ENTITY The value is an entity • ENTITIES The value is a list of entities • NOTATION The value is a name of a notation • xml: The value is a predefined xml value

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> 

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>

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://<Admin Context IP>/bin/index

11. Setup to use the API (continued) • Download the Device DTD from the device: • http://<Admin Context IP>/bin/index

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

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 use • http://<Admin contex>/bin/xml_agentor https://<Admin contex>:443/bin/xml_agent • Incorporate into your scripts • Debug XML commands with –trace option on Curl

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:ciscodemo@172.25.91.41/bin/xml_agent" -k -d "xml_cmd=<request_xml context-name=\"Admin\"><show_running-config/></request_xml>“

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

16. XML Command Example Breakdown Command Line: /usr/bin/curl"http://admin:ciscodemo@172.25.91.41/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:ciscodemo@172.25.91.41/bin/xml_agent Curl Options:-k -d Post:"xml_cmd= <request_xml context-name=\"Admin\"> <show_running-config/> XML Command </request_xml>“

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

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/

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.