Feedback
Table Of Contents
HTTP and HTTPS Support with the ACE
Configuring HTTP and HTTPS Management Traffic Services
Creating and Configuring a Class Map
Creating a Layer 3 and Layer 4 Policy Map
Applying a Service Policy Globally to All VLAN Interfaces in the Same Context
Applying a Service Policy to a Specific VLAN Interface
Enabling the Display of Raw XML Request show Command Output in XML Format
Accessing the ACE XML Schema File
Displaying or Clearing XML Service Policy Statistics
Example of ACE CLI Command and the XML Equivalent
Configuring the XML Interface
Note
The information in this chapter applies to both the ACE module and the ACE appliance unless otherwise noted.
This chapter describes how to use Extensible Markup Language (XML) to remotely configure an ACE from a network management station (NMS). You can transmit, exchange, and interpret data among the applications.
This chapter contains the following major sections:
•
•
•
Information About XML
Web services provide network-based software applications that use XML to transmit, exchange, and interpret data among applications that would otherwise have difficulty interoperating together.
XML provides an application-independent way of sharing data between computer systems. Similar to HTML, XML consists of text delimited by tags so it is easily conveyed over the Internet. In XML, the tags define the meaning and structure of the information, enabling computer applications to use the information directly. Unlike HTML, XML tags identify the data, rather than specifying how to display it. An XML tag acts like a field name in your program; it puts a label on a piece of data that identifies it (for example: <message>...</message>).
An XML document that contains configuration commands and output results is easily transformed between the devices by using standard Internet protocols. A network management station (NMS), such as the CiscoWorks Hosting Solution Engine (HSE), can connect to the ACE and push new configurations to it over HTTP or secure HTTP (HTTPS). Any command that you can configure from the ACE CLI can be configured remotely from a NMS by exchanging XML documents over HTTP or HTTPS.
The XML application programming interface (API) allows you to automate the programmatic configuration of the ACE by using an XML schema. The XML format is a translation of the CLI commands into an equivalent XML syntax. Each ACE CLI command has an equivalent XML tag, and all of the parameters of the CLI command are attributes of that element. The ACE uses an Apache HTTP server to provide the XML management interface and to provide HTTP services between the ACE and the management client. To use the ACE XML API, you must have the Admin user role.
There are three categories of commands as follows:
•
•
•
Ping and traceroute are executable commands. All executable commands are treated by the XML agent as follows:
•
•
You can use XML to do the following:
•
•
•
•
•
This section contains the following topics:
•
HTTP and HTTPS Support with the ACE
The ACE and an NMS can easily send and receive an XML document containing configuration commands or output results by using standard Internet protocols, such as HTTP or secure HTTP (HTTPS), as the transfer protocol. HTTPS uses Secure Sockets Layer (SSL) to provide encrypted communication between the management client and the ACE.
The administrator of the system designates a website as the entry point to the API, and all requests and queries are made through those URLs. This website also provides the XMl schemas that define the XML for requests, queries, and responses. There is one XML schema for the ACE module and one for the ACE appliance.
The XML input is submitted through the data portion of an HTTP POST request. A field named "xml" contains the XML string that defines the request or query. The response to this HTTP POST represents a pure XML response with either a success or failure indicator for a request or the response to a query.
When you use XML to transfer configuration data and results, the NMS connects to the ACE and sends a new configuration in an XML document to the ACE over HTTP or HTTPS. The ACE then applies the new configuration. The XML agent on the ACE checks the XML output that the ACE generates before sending it to the client. If the output contains incorrect syntax including unsupported characters, the agent displays the following error message:
Generated XML was not well-formed. Possible workaround: retry XML request using text mode response instead.The following example shows the HTTP conversation between the client and the server, as related to the XML implementation on the ACE:
******** Client **************POST /bin/xml_agent HTTP/1.1Authorization: Basic VTpQContent-Length: 95xml_cmd=<request_xml><interface type="vlan" number="80"><access-group access-type="input" name="acl1"/><ip_address ="60.0.0.145" netmask="255.255.255.0"/><shutdown sense="no"/></interface><show_running-config/></request_xml>******** Server **************HTTP/1.1 200 OKContent-Length: 21<response_xml><config_command><command>interface vlan 80ip address 60.0.0.145 255.255.255.0access-group input acl1no shutdown</command><status code="100" text="XML_CMD_SUCCESS"/></config_command></response_xml>******** Client **************POST /bin/xml_agent HTTP/1.1Content-Length: 95xml_cmd=<request_xml><show_running-config/></request_xml>******** Server **************HTTP/1.1 401 UnauthorizedConnection: closeWWW-Authenticate: Basic realm=/xml-configHTTP Return Codes
HTTP return codes indicate the status of the request and reports errors between the server and the client. The Apache HTTP server return status codes follow the standards outlined in RFC 2616. Table 9-1 lists the supported HTTP return codes.
The following HTTP headers are supported:
•
•
•
•
For example, when an XML error occurs, the HTTP response contains a 200 return code. The portion of the original XML document with the error is returned with an error element that contains the error type and description.
The following is a typical example of an XML error response:
<response_xml><config_command><command>interface vlan 20no shutdescription xyzexit</command><status code = `200' text='XML_CMD_FAILURE'><error_command> description xyz </error_command><error_message> unrecognized element - description </error_message></status></config_command></response_xml>The returned error codes correspond to the attributes of the configuration element. The possible returned XML error can include any of the following:
XML_ERR_WELLFORMEDNESS /* not a well formed xml document */XML_ERR_ATTR_INVALID /* found invalid value attribute */XML_ERR_ELEM_INVALID /* found invalid value unrecognized */XML_ERR_CDL_NOT_FOUN /* parser cdl file not found */XML_ERR_INTERNAL /* internal memory or coding error */XML_ERR_COMM_FAILURE /* communication failure */XML_ERR_VSH_PARSER /* vsh parse error on the given command */XML_ERR_VSH_CONF_APPLY /* vsh unable to apply the configuration */XML Schema
A n XML schema is the basis for XML configuration documents that you create using the ACE. The purpose of an XML schema is to define the legal building blocks of an XML document by defining the document structure with a list of legal elements.
The schema designates an XML list that specifies precisely which elements can appear in a request, query, or response document. It also specifies the contents and attributes of the elements. A schema can be declared inline in your XML document or as an external reference.
The ACE XML schema file, schema.xsd, is included as part of the software image and is accessible from a web browser using either HTTP or HTTPS. See the "Accessing the ACE XML Schema File" section for details.
You can use a web browser to access the ACE XML schema file as follows:
•
•
The following example shows the sequence of ACE CLI commands for creating a real server followed by the associated XML schema rserver elements for the commands:
[no] rserver [host | redirect] name
[no] conn-limit max maxconns [min minconns]
[no] description string
[no] inservice
[no] ip address {ip_address}
[no] probe name
[no] weight number
**********************************************************************Elements, Attributes and Entities required for rserver**********************************************************************--><!--probe-name is a string of length 1 to 32.--><!ELEMENT probe_rserver EMPTY><!ATTLIST probe_rserversense CDATA #FIXED "no"probe-name CDATA #REQUIRED><!--relocation-str length is 1 to 127--><!ELEMENT webhost-redirection EMPTY><!ATTLIST webhost-redirectionsense (yes | no) #IMPLIEDrelocation-string CDATA #REQUIREDredirection-code (301 | 302) #IMPLIED><!--type is optional for host.ipaddress, probe and weight are valid only when type = host.-type is valid only when type=host.name length is 1 to 32.webhost-redirection is valid only if type=redirect.--><!ELEMENT rserver (description, ip_address, conn-limit, probe_rserver,weight, inservice, webhost-redirection)*><!ATTLIST rserversense CDATA #FIXED "no"type (redirect | host) #IMPLIEDname CDATA #REQUIRED>Guidelines and Restrictions
This topic includes the following guidelines and restrictions:
•
•
•
•
Caution
- (ACE module only) to version A2(1.1) or higher
- (ACE appliance only) to version A3(1.0) or higher
Otherwise, after you upgrade the ACE software, the www user will be disabled and you will not be able to use XML to remotely configure an ACE until you change the default www user password. See Chapter 2, Configuring Virtualization, in the Virtualization Guide, Cisco ACE Application Control Engine for details on changing a user account password. In this case, the user would be www.
Default Settings
XML responses automatically appear in XML format if the corresponding CLI show command output supports the XML format. However, if you are running commands on the CLI console or you are running raw XML responses from NMS, the XML responses appear in regular CLI display format. See the "Enabling the Display of Raw XML Request show Command Output in XML Format" section for details. For details on the show command output supported in XML format, consult the schema.xsd file.
Configuring the XML Interface
This section describes how to configure the XML interface and contains the following topics:
•
•
•
•
Task Flow for Configuring XML
Follow these steps to configure XML usage with the ACE:
Step 1
host1/Admin# changeto C1host1/C1#The rest of the examples in this table use the Admin context, unless otherwise specified. For details on creating contexts, see the Virtualization Guide, Cisco ACE Application Control Engine.
Step 2
host1/Admin# configEnter configuration commands, one per line. End with CNTL/Z.host1/Admin(config)#Step 3
(ACE module only)host1/Admin(config)# class-map type management match-all HTTPS-ALLOW_CLASShost1/Admin(config-cmap-mgmt)# match protocol https source-address 192.168.1.1 255.255.255.255host1/Admin(config-cmap-mgmt)# exit(ACE appliance only)host1/Admin(config)# class-map type management match-all XML-HTTPS-ALLOW_CLASShost1/Admin(config-cmap-mgmt)# match protocol xml-https source-address 192.168.1.1 255.255.255.255host1/Admin(config-cmap-mgmt)# exitStep 4
(ACE module only)host1/Admin(config) # policy-map type management first-match MGMT_HTTPS_POLICYhost1/Admin(config-pmap-mgmt) # class HTTPS-ALLOW_CLASShost1/Admin(config-pmap-mgmt-c) # permithost1/Admin(config-pmap-mgmt-c) # exit(ACE appliance only)host1/Admin(config) # policy-map type management first-match MGMT_XML-HTTPS_POLICYhost1/Admin(config-pmap-mgmt) # class XML-HTTPS-ALLOW_CLASShost1/Admin(config-pmap-mgmt-c) # permithost1/Admin(config-pmap-mgmt-c) # exitStep 5
(ACE module only)host1/Admin(config)# interface vlan50host1/Admin(config-if)# ip address 192.168.10.1 255.255.0.0host1/Admin(config-if)# service-policy input MGMT_HTTPS_POLICYhost1/Admin(config-if)# exithost1/Admin(config)# exit(ACE appliance only)host1/Admin(config)# interface vlan50host1/Admin(config-if)# ip address 192.168.10.1 255.255.0.0host1/Admin(config-if)# service-policy input MGMT_XML-HTTPS_POLICYhost1/Admin(config-if)# exithost1/Admin(config)# exitStep 6
Note
host1/Admin# xml-show onStep 7
host1/Admin# copy running-config startup-config
Configuring HTTP and HTTPS Management Traffic Services
This section describes how to configure HTTP and HTTPS remote management traffic to the ACE through class maps, policy maps, and service policies. The ACE provides support for remote management using XML over either HTTP or HTTPS to configure, monitor, and manage software objects.
The following items summarize the role of each function in configuring HTTP or HTTPS network management access to the ACE:
•
•
•
HTTP or HTTPS sessions are established to the ACE per context. For details on creating contexts and users, see the Virtualization Guide, Cisco ACE Application Control Engine.
This section contains the following topics:
•
•
•
•
Creating and Configuring a Class Map
This section describes how to create a Layer 3 and Layer 4 class map to classify the HTTP or HTTPS management traffic that can be received by the ACE. This process allows network management traffic by identifying the incoming IP protocols that the ACE can receive and the client source host IP address and subnet mask as the matching criteria.
A class map of type management defines the allowed network traffic as a form of management security for protocols such as HTTP or HTTPS. A class map can include multiple match commands. You can configure class maps to define multiple HTTP or HTTPS management protocol or source IP address match commands in a group that you then associate with a traffic policy. The match-all and match-any keywords determine how the ACE evaluates multiple match statements operations when multiple match criteria exist in a class map.
Detailed Steps
Creating a Layer 3 and Layer 4 Policy Map
This section describes how to create a Layer 3 and Layer 4 policy map, associate a class map with the policy map, and specify the policy map actions. A Layer 3 and Layer 4 policy map defines the actions executed on HTTP or HTTPS management traffic that matches the specified classifications.
Detailed Steps
Examples
The following examples shows how to use the insert-before command to define the sequential order of two class maps in the policy map:
(ACE module only)host1/Admin(config-pmap-mgmt)# class HTTPS-ALLOW_CLASS insert-before L4_REMOTE_ACCESS_CLASS(ACE appliance only)host1/Admin(config-pmap-mgmt)# class XML-HTTPS-ALLOW_CLASS insert-before L4_REMOTE_ACCESS_CLASSIPv6 Example
The following example shows how to specify the IPv6 class-default-v6 class map for the Layer 3 and Layer 4 traffic policy:
host1/Admin(config-pmap-mgmt)# class class-default-v6host1/Admin(config-pmap-mgmt-c)#IPv4 Example
The following example shows how to specify the IPv4 class-default class map for the Layer 3 and Layer 4 traffic policy:
host1/Admin(config-pmap-mgmt)# class class-defaulthost1/Admin(config-pmap-mgmt-c)#Applying a Service Policy Globally to All VLAN Interfaces in the Same Context
This section describes how to apply an existing policy map globally to all VLAN interfaces in the same context.
Note the following guidelines when applying a service policy:
•
•
Note
Guidelines and Restrictions
The ACE allows only one policy of a specific feature type to be activated on an interface.
Detailed Steps
Applying a Service Policy to a Specific VLAN Interface
This section describes how to apply an existing policy map to a specific VLN interface. A policy activated on an interface overwrites any specified global policies for overlapping classification and actions.
Note
Guidelines and Restrictions
The ACE allows only one policy of a specific feature type to be activated on an interface.
Detailed Steps
Enabling the Display of Raw XML Request show Command Output in XML Format
This section describes how to enable the display of raw XML request show command output in XML format. By default, XML responses will automatically appear in XML format if the corresponding CLI show command output supports the XML format. However, if you are running commands on the CLI console or you are running raw XML responses from NMS, the XML responses appear in regular CLI display format.
You can enable the display of raw XML request show command output in XML format by performing one of the following actions:
•
•
Selection of the xml-show on command is not required if you are running true XML (as shown in the example below).
For details on the show command output supported in XML format, consult the ACE XML schema file, schema.xsd, that is included as part of the software image (see the "Accessing the ACE XML Schema File" section). The ACE XML schema file contains the information on the XML attributes for those show commands that have output that supports the XML format.
For example, if you specify the show interface vlan 10 command, the XML schema for the show interface command appears as follows:
<!--interface-number is req for show-type vlan | bvi.interface-number is between 1 and 4095 for vlan and 8191 for bvi.--><!ENTITY % show-interface"interface-type (vlan | bvi | eobc) #IMPLIEDinterface-number CDATA #IMPLIED">The XML representation of the show interface command appears as follows:
<show_interface interface-type='vlan' interface-number='10'/>The following example illustrates the XML representation of the show interface command output:
<response_xml><exec_command><command>show interface vlan 10</command><status code="100" text="XML_CMD_SUCCESS"/><xml_show_result><xml_show_interface><xml_interface_entry><xml_interface><interface_name>vlan10</interface_name><interface_status>up</interface_status><interface_hardware>VLAN</interface_hardware><interface_mac><macaddress>00:05:9a:3b:92:b1</macaddress></interface_mac><interface_mode>routed</interface_mode><interface_ip><ipaddress>10.20.105.101</ipaddress><ipmask>255.255.255.0</ipmask></interface_ip><interface_ft_status>non-redundant</interface_ft_status><interface_description><interface_description>not set</interface_description></interface_description><interface_mtu>1500</interface_mtu><interface_last_cleared>never</interface_last_cleared><interface_alias><ipaddress>not set</ipaddress></interface_alias><interface_standby><ipaddress>not set</ipaddress></interface_standby><interface_sup_enabled>Assigned</interface_sup_enabled><interface_auto_status>up</interface_auto_status></xml_interface><interface_stats><ifs_input><ifs_unicast>50</ifs_unicast><ifs_bytes>8963</ifs_bytes><ifs_multicast>26</ifs_multicast><ifs_broadcast>1</ifs_broadcast><ifs_errors>0</ifs_errors><ifs_unknown>0</ifs_unknown><ifs_ignored>0</ifs_ignored><ifs_unicast_rpf>0</ifs_unicast_rpf></ifs_input><ifs_output><ifs_unicast>45</ifs_unicast><ifs_bytes>5723</ifs_bytes><ifs_multicast>0</ifs_multicast><ifs_broadcast>1</ifs_broadcast><ifs_errors>0</ifs_errors><ifs_ignored>0</ifs_ignored></ifs_output></interface_stats></xml_interface_entry></xml_show_interface></xml_show_result></exec_command></response_xml>Details
Example:
host1/Admin# xml-show onEnables the display of raw XML request show command output in XML format.
The keywords are as follows:
•
•
•
Accessing the ACE XML Schema File
This section describes how to access the ACE XML schema file, which is included as part of the ACE software image and is accessible from a web browser using either HTTP or HTTPS.
The ACE XML schema file name for both the module and the appliance is schema.xsd.
You can access the ACE XML schema file directly or by using the Cisco ACE Module Management or Cisco ACE Appliance Management page.
Details
Perform these steps to access and display the ACE XML schema file:
Step 1
Step 2
Step 3
Direct Access Method
To directly access the ACE XML schema file, specify the HTTP or secure HTTP (HTTPS) of your ACE in the address field of your Web browser, followed by schema.xsd. For example, enter:
https://ace_ip_address/schema.xsdhttp://ace_ip_address/schema.xsdYou can choose to either open the ACE XML schema file or save it to your computer.
Cisco ACE Module or Appliance Management Page Method
To access the ACE XML schema file from the Cisco ACE Module Management or Cisco ACE Appliance Management page, perform the following steps:
a.
https://ace_ip_addresshttp://ace_ip_addressb.
–
–
c.
d.
Displaying or Clearing XML Service Policy Statistics
To display or clear the statistical information of the service policies associated with your XML configuration, perform the following tasks:
Examples
The following examples shows the output for the MGMT_HTTPS_POLICY (ACE module) and MGMT_XML-HTTPS_POLICY (ACE appliance) policy maps by using the show service-policy command:
(ACE module only)host1/Admin# show service-policy MGMT_HTTPS_POLICYStatus : ACTIVEDescription: Allow mgmt protocols-----------------------------------------Context Global Policy:service-policy: MGMT_HTTPS_POLICY(ACE appliance only)host1/Admin# show service-policy MGMT_XML-HTTPS_POLICYStatus : ACTIVEDescription: Allow mgmt protocols-----------------------------------------Context Global Policy:service-policy: MGMT_XML-HTTPS_POLICYExample of ACE CLI Command and the XML Equivalent
The following example shows a typical VShell (VSH) CLI command configuration and its equivalent XML configuration commands:
################################ TO/FROM CP CONFIGURATION ################################conf taccess-list acl1 extended permit ip any anyint vlan 80access-group input acl1ip address 60.0.0.145 255.255.255.0no shutexitip route 0.0.0.0 0.0.0.0 60.0.0.1end<access-list id="acl1" config-type="extended" perm-value="permit"protocol-name="ip" src-address type="any" dest-type="any"/><interface type="vlan" number="80"><access-group type="input" name="acl1"/><ip_address ="60.0.0.145" netmask="255.255.255.0"/><shutdown sense="no"/></interface><ip_route dest-address="0.0.0.0" dest-mask="0.0.0.0"gateway="60.0.0.1"/>############################## BRIDGING CONFIGURATION ##############################conf taccess-list acl1 extended permit ip any anyint vlan 80access-group input acl1bridge-group 1no shutexitint vlan 90access-group input acl1bridge-group 1no shutexitend<access-list id="acl1" config-type="extended" perm-value="permit"protocol-name="ip" src-type="any" dest-type="any"/><interface type="vlan" number="80"><access-group type="input" name="acl1"/><bridge-group value="1"/><shutdown sense="no"/></interface><interface type="vlan" number="90"><access-group type="input" name="acl1"/><bridge-group value="1"/><shutdown sense="no"/></interface>
