Administration Guide vA3(1.0), Cisco ACE 4700 Series Application Control Engine Appliance
Configuring the XML Interface
Downloads: This chapterpdf (PDF - 238.0KB) The complete bookPDF (PDF - 5.01MB) | Feedback

Configuring the XML Interface

Table Of Contents

Configuring the XML Interface

XML Overview

XML Usage with the ACE

HTTP and HTTPS Support with the ACE

HTTP Return Codes

Document Type Definition

Sample XML Configuration

XML Configuration Quick Start

Configuring HTTP and HTTPS Management Traffic Services

Creating and Configuring a Class Map

Defining a Class Map Description

Defining HTTP and HTTPS Protocol Match Criteria

Creating a Layer 3 and Layer 4 Policy Map

Creating a Layer 3 and Layer 4 Policy Map for Network Management Traffic Received by the ACE

Specifying a Layer 3 and Layer 4 Traffic Class with the Traffic Policy

Specifying Layer 3 and Layer 4 Policy Actions

Applying a Service Policy

Enabling the Display of Raw XML Request show Command Output in XML Format

Accessing the ACE DTD File


Configuring the XML Interface


This chapter describes how to use Extensible Markup Language (XML) to remotely configure a Cisco 4700 Series Application Control Engine (ACE) appliance from a network management station (NMS). Any command that you can configure from the ACE CLI can be configured remotely from a NMS by exchanging XML documents over HTTP or secure HTTP (HTTPS). You can transmit, exchange, and interpret data among the applications. In addition, you can configure the ACE to transfer show command output to an NMS in XML format for result monitoring and analysis.


Note To use the ACE XML interface, you must have the Admin user role.


This chapter contains the following major sections:

XML Overview

XML Configuration Quick Start

Configuring HTTP and HTTPS Management Traffic Services

Enabling the Display of Raw XML Request show Command Output in XML Format

Accessing the ACE DTD File


Note The ACE creates the following default user accounts at startup: admin, dm, and www. The admin user is the global administrator and cannot be deleted. The dm user is for accessing the Device Manager GUI and cannot be deleted (it is an internal user that is required by the Device Manager GUI and is hidden on the CLI). The ACE uses the www user account for the XML interface and it cannot be deleted.


XML Overview

This section contains the following topics:

XML Usage with the ACE

HTTP and HTTPS Support with the ACE

HTTP Return Codes

Document Type Definition

Sample XML Configuration

XML Usage with the ACE

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 such as HTTP or secure HTTP (HTTPS) as the transfer protocol.

The XML application programming interface (API) allows you to automate the programmatic configuration of the ACE by using a Document Type Definition (DTD). 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.

You can use XML to do the following:

Provide a mechanism using XML to transfer, configure, and monitor objects in the ACE. This XML capability allows you to easily shape or extend the CLI query and reply data in XML format to meet different specific business needs.

Transfer show command output from the ACE CLI interface in an XML format for statistics and status monitoring. This capability allows you to query and extract data from the ACE.

Use the ACE XML DTD schema for formatting CLI queries or parsing the XML results from the ACE to enable third-party software development through XML communications.

Provide remote user authentication through AAA.

Provide session and context management by the global administrator and other users with the Admin user role.

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

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 DTDs that define the XML for requests, queries, and responses.

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 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.1
Authorization: Basic VTpQ
Content-Length: 95
xml_cmd=<request_xml>
<interface type="vlan" number="80">
<access-group access-type="input" name="acl1"/>
<ip_address address="60.0.0.145" netmask="255.255.255.0"/>
<shutdown sense="no"/>
</interface>
<show_running-config/>
</request_xml>

******** Server **************
HTTP/1.1 200 OK
Content-Length: 21
<response_xml>
<config_command>
<command>
interface vlan 80
ip address 60.0.0.145 255.255.255.0
access-group input acl1
no shutdown
</command>
<status code="100" text="XML_CMD_SUCCESS"/>
</config_command>
</response_xml>

******** Client **************
POST /bin/xml_agent HTTP/1.1
Content-Length: 95
xml_cmd=<request_xml>
<show_running-config/>
</request_xml>

******** Server **************
HTTP/1.1 401 Unauthorized
Connection: close
WWW-Authenticate: Basic realm=/xml-config

HTTP 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 8-1 lists the supported HTTP return codes.

Table 8-1 Supported HTTP Return Codes for XML 

Return Code
Description

200

OK

201

Created

202

Accepted

203

Non-Authoritative Information

206

Partial Content

301

Moved Permanently

302

Found

400

Bad Request

401

Unauthorized (credentials required, but not provided)

403

Forbidden (illegal credentials submitted; syslog also generated)

404

Not Found ("/xml-config" not specified)

405

Method Not Allowed

406

Not Acceptable

408

Request Time-out (more than 30 seconds has passed waiting on receive)

411

Missing Content-Length (missing or zero Content-Length field)

500

Internal Server Error

501

Not Implemented ("POST" not specified)

505

HTTP Version Not Supported ("1.0" or "1.1" not specified)


The following HTTP headers are supported:

Content-Length (nonzero value required for all POSTs)

Connection (close value indicates that a request should not be persistent)

WWW-Authenticate (sent to the client when credentials are required and missing)

Authorization (sent from the client to specify basic credentials in base 64 encoding)

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 20
  no shut
  description xyz
  exit
</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:

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 */

Document Type Definition

A DTD is the basis for XML configuration documents that you create using the ACE. The purpose of a DTD is to define the legal building blocks of an XML document by defining the document structure with a list of legal elements.

DTD 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 DTD can be declared inline in your XML document or as an external reference.

The ACE DTD file, ace_appliance.dtd, 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 DTD File" section for details. You can use a web browser to directly access the ace_appliance.dtd file or open the ace_appliance.dtd file from the Cisco ACE Appliance Management page.


Note 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. 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 ace_appliance.dtd file.


The following example shows the sequence of ACE CLI commands for creating a real server followed by the associated DTD XML 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_rserver
  sense     CDATA     #FIXED    "no"
  probe-name      CDATA      #REQUIRED
> 
 
<!-- 
relocation-str length is 1 to 127
-->
<!ELEMENT webhost-redirection EMPTY>
<!ATTLIST webhost-redirection
  sense      (yes | no)      #IMPLIED
  relocation-string      CDATA      #REQUIRED
  redirection-code      (301 | 302)      #IMPLIED
>

<!-- 
tyep is optional for host.
ip, probe and weight are valid only when type = host.
address-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 rserver
  sense     CDATA     #FIXED    "no"
  type      (redirect | host)      #IMPLIED
  name      CDATA      #REQUIRED
>

Sample XML Configuration

The following example shows a typical VShell (VSH) CLI command configuration and its equivalent XML configuration commands:

##############################
## TO/FROM CP CONFIGURATION ##
##############################
conf t
access-list acl1 extended permit ip any any
int vlan 80
access-group input acl1
ip address 60.0.0.145 255.255.255.0
no shut
exit
ip route 0.0.0.0 0.0.0.0 60.0.0.1
end

<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"/>
<ip_address 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 t

access-list acl1 extended permit ip any any
int vlan 80
access-group input acl1
bridge-group 1
no shut
exit

int vlan 90
access-group input acl1
bridge-group 1
no shut
exit
end

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

XML Configuration Quick Start

Table 8-2 provides a quick overview of the steps required to configure XML usage with the ACE. Each step includes the CLI command required to complete the task.

Table 8-2 ACE XML Configuration Quick Start 

Task and Command Example

1. Enter configuration mode.

host1/Admin# config
Enter configuration commands, one per line. End with CNTL/Z.
host1/Admin(config)#

2. Create a Layer 3 and Layer 4 class map to classify the HTTP or HTTPS management traffic that can be received by the ACE.

host1/Admin(config)# class-map type management match-all 
XML-HTTPS-ALLOW_CLASS
host1/Admin(config-cmap-mgmt)# match protocol xml-https 
source-address 192.168.1.1 255.255.255.255
host1/Admin(config-cmap-mgmt)# exit

3. Configure a Layer 3 and Layer 4 HTTP or HTTPS traffic management policy.

host1/Admin(config) # policy-map type management first-match 
MGMT_XML-HTTPS_POLICY
host1/Admin(config-pmap-mgmt) # class XML-HTTPS-ALLOW_CLASS
host1/Admin(config-pmap-mgmt-c) # permit
host1/Admin(config-pmap-mgmt-c) # exit

4. Attach the traffic policy to a single interface or globally on all VLAN interfaces associated with a context, and specify the direction in which the policy should be applied. For example, to specify an interface VLAN and apply multiple service policies to the VLAN, enter:

host1/Admin(config)# interface vlan50
host1/Admin(config-if)# ip address 192.168.10.1 255.255.0.0
host1/Admin(config-if)# service-policy input 
MGMT_XML-HTTPS_POLICY
host1/Admin(config-if)# exit
host1/Admin(config)# exit

5. (Optional) Enable the display of raw XML request show command output in XML format.

Note True XML responses always automatically appear in XML format.

host1/Admin# xml-show on

6. (Optional) Save your configuration changes to Flash memory.

host1/Admin# copy running-config startup-config

Configuring HTTP and HTTPS Management Traffic Services

The ACE provides support for remote management using XML over either HTTP or HTTP to configure, monitor, and manage software objects. You configure HTTP and HTTPS remote management traffic to the ACE through class maps, policy maps, and service policies.

The following items summarize the role of each function in configuring HTTP or HTTPS network management access to the ACE:

Class map—Provides the remote network traffic match criteria to permit HTTP and HTTPS management traffic based on HTTP or HTTPS network management protocols or host source IP addresses.

Policy map—Enables remote network management access for a traffic classification that matches the criteria listed the class map.

Service policy—Activates the policy map and attaches the traffic policy to an interface or globally on all interfaces.

HTTP or HTTPS sessions are established to the ACE per context. For details on creating contexts and users, see the Cisco 4700 Series Application Control Engine Appliance Virtualization Configuration Guide.

This section contains the following topics:

Creating and Configuring a Class Map

Creating a Layer 3 and Layer 4 Policy Map

Applying a Service Policy

Creating and Configuring a Class Map

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, use the class-map type management configuration command. This command 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 and HTTPS.

A class map can have multiple match commands in a class map. 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.

The syntax of this command is:

class-map type management [match-all | match-any] map_name

The keywords, arguments, and options are:

match-all | match-any—(Optional) Determines how the ACE evaluates Layer 3 and Layer 4 network traffic when multiple match criteria exist in a class map. The class map is considered a match if the match commands meet one of the following conditions:

match-all —All of the match criteria listed in the class map match the network traffic class in the class map.

match-any—Only one of the match criteria listed in the class map matches the network traffic class in the class map.

The default setting is to meet all of the match criteria (match-all) in a class map.

map_name—Name assigned to the class map. Enter an unquoted text string with no spaces and a maximum of 64 alphanumeric characters. The class name is used for both the class map and to configure a policy for the class in the policy map.

The CLI displays the class map management configuration mode. To classify the remote HTTP or HTTPS management traffic received by the ACE, include one or more of the following commands to configure the match criteria for the class map:

description—Se the "Defining a Class Map Description" section

match protocol—See the "Defining HTTP and HTTPS Protocol Match Criteria" section

You may include multiple match protocol commands in a class map.

For example, to allow HTTPS access between the ACE HTTP server and the management client located at IP address 192.168.1.1 255.255.255.255, enter:

host1/Admin(config)# class-map type management match-all 
XML-HTTPS-ALLOW_CLASS
host1/Admin(config-cmap-mgmt)# match protocol xml-https source-address 
192.168.1.1 255.255.255.255

To remove a Layer 3 and Layer 4 network management class map from the ACE, enter:

host1/Admin(config)# no class-map type management match-all 
XML-HTTPS-ALLOW_CLASS

Defining a Class Map Description

Use the description command to provide a brief summary about the Layer 3 and Layer 4 class map.

Access the class map configuration mode to specify the description command.

The syntax of this command is:

description text

Use the text argument to enter an unquoted text string with a maximum of 240 alphanumeric characters.

For example, to specify a description that the class map is to allow HTTPS access, enter:

host1/Admin(config)# class-map type management match-all 
XML-HTTPS-ALLOW_CLASS
host1/Admin(config-cmap-mgmt)# description Allow HTTPS as the XML 
transfer protocol

To remove the description from the class map, enter:

host1/Admin(config-cmap-mgmt)# no description

Defining HTTP and HTTPS Protocol Match Criteria

Use the match protocol command to configure the class map to specify that the HTTP or HTTPS remote network management protocol can be received by the ACE. You configure the associated policy map to permit access to ACE for the specified management protocol. For XML support, a class map of type management allows IP protocols such as HTTP and HTTPS. As part of the network management access traffic classification, you also specify either a client source host IP address and subnet mask as the matching criteria or instruct the ACE to allow any client source address for the management traffic classification.

You must access the class map configuration mode to specify the match protocol command.

The syntax of this command is:

[line_number] match protocol {http | xml-https} {any | source-address ip_address mask}

The keywords, arguments, and options are:

line_number—(Optional) Allows you to edit or delete individual match commands. Enter an integer from 2 to 255 as the line number. For example, you can enter no line_number to delete long match commands instead of entering the entire line.

http—Specifies Hypertext Transfer Protocol (HTTP) as transfer protocol to send and receive XML documents between the ACE and an NMS.

xml-https—Specifies secure (SSL) Hypertext Transfer Protocol (HTTP) as transfer protocol to send and receive XML documents between the ACE and an NMS. Communication is performed using port 10443.


Note The https keyword specifies secure (SSL) Hypertext Transfer Protocol (HTTP) for connectivity with the Device Manager GUI on the ACE using port 443. You can enable both https and xml-https in a Layer 3 and Layer 4 network management class map.


any—Specifies any client source address for the management traffic classification.

source-address—Specifies a client source host IP address and subnet mask as the network traffic matching criteria. As part of the classification, the ACE implicitly obtains the destination IP address from the interface on which you apply the policy map.

ip_address—Source IP address of the client. Enter the IP address in dotted-decimal notation (for example, 192.168.11.1).

mask—The subnet mask of the client in dotted-decimal notation (for example, 255.255.255.0).

For example, to specify that the class map allows HTTPS access to the ACE, enter:

(config)# class-map type management XML-HTTPS-ALLOW_CLASS
(config-cmap-mgmt)# match protocol xml-https source-address 
192.168.10.1 255.255.0.0

To deselect the specified network management protocol match criteria from the class map, enter:

host1/Admin(config-cmap-mgmt)# no match protocol https source-address 
192.168.10.1 255.255.0.0

Creating a Layer 3 and Layer 4 Policy Map

A Layer 3 and Layer 4 policy map defines the actions executed on HTTP or HTTPS management traffic that matches the specified classifications. This section contains the following topics:

Creating a Layer 3 and Layer 4 Policy Map for Network Management Traffic Received by the ACE

Specifying a Layer 3 and Layer 4 Traffic Class with the Traffic Policy

Specifying Layer 3 and Layer 4 Policy Actions

Creating a Layer 3 and Layer 4 Policy Map for Network Management Traffic Received by the ACE

To configure a Layer 3 and Layer 4 policy map that permits the management traffic received by the ACE use the policy-map type management command in configuration mode. The ACE executes the action for the first matching classification. The ACE does not execute any additional actions.

The syntax of this command is as follows:

policy-map type management first-match map_name

The map_name argument specifies the name assigned to the Layer 3 and Layer 4 network management policy map. Enter an unquoted text string with no spaces and a maximum of 64 alphanumeric characters.

When you use this command, you will access policy map management configuration mode.

For example, to create a Layer 3 and Layer 4 network traffic management policy map, enter:

host1/Admin(config)# policy-map type management first-match 
MGMT_XML-HTTPS_POLICY
host1/Admin(config-pmap-mgmt)# 

To remove a policy map from the ACE, enter:

host1/Admin(config)# no policy-map type management first-match 
MGMT_XML-HTTPS_POLICY

Specifying a Layer 3 and Layer 4 Traffic Class with the Traffic Policy

To specify the HTTP or HTTPS traffic management traffic class created with the class-map command to associate traffic with the traffic policy buse the class command. his command enters the policy map management class configuration mode.

The syntax of this command is as follows:

class {name1 [insert-before name2] | class-default}

The arguments and keywords, and options are as follows:

name1—The name of a previously defined Layer 3 and Layer 4 traffic class, configured with the class-map command, to associate traffic to the traffic policy. Enter an unquoted text string with no spaces and a maximum of 64 alphanumeric characters.

insert-before name2—(Optional) Places the current class map ahead of an existing class map or inline match condition specified by the name2 argument in the policy map configuration. The ACE does not save the sequence reordering as part of the configuration. Enter an unquoted text string with no spaces and a maximum of 64 alphanumeric characters.

class-default—Specifies the class-default class map for the Layer 3 and Layer 4 traffic policy. This class map is a reserved class map created by the ACE. You cannot delete or modify this class. All network traffic that fails to meet the other matching criteria in the named class map belongs to the default traffic class. If none of the specified classifications match, the ACE then matches the action specified under the class class-default command. The class-default class map has an implicit match any statement in it and is used to match any traffic classification. The class-default class map has an implicit match any statement that matches all traffic.

For example, to specify an existing class map within the Layer 3 and Layer 4 remote access policy map, enter:

host1/Admin(config-pmap-mgmt)# class XML-HTTPS-ALLOW_CLASS 
host1/Admin(config-pmap-mgmt-c)# 

To use the insert-before command to define the sequential order of two class maps in the policy map, enter:

host1/Admin(config-pmap-mgmt)# class XML-HTTPS-ALLOW_CLASS 
insert-before L4_REMOTE_ACCESS_CLASS

To specify the class-default class map for the Layer 3 and Layer 4 traffic policy, enter:

host1/Admin(config-pmap-mgmt)# class class-default
host1/Admin(config-pmap-mgmt-c)# 

To remove a class map from a Layer 3 and Layer 4 policy map, enter:

host1/Admin(config-pmap-mgmt)# no class XML-HTTPS-ALLOW_CLASS

Specifying Layer 3 and Layer 4 Policy Actions

To allow the network management traffic listed in the Layer 3 and Layer 4 class map to be received or rejected by the ACE, specify either the permit or deny command in policy map class configuration mode.

Use the permit command in policy map class configuration mode to allow the HTTP or HTTPS management traffic listed in the class map to be received by the ACE.

Use the deny command in policy map class configuration mode to refuse the HTTP or HTTPS management traffic listed in the class map to be received by the ACE.

For example, to specify the permit action for the Layer 3 and Layer 4 policy map, enter:

host1/Admin(config-pmap-mgmt-c)# permit
host1/Admin(config-pmap-mgmt-c)# exit

Applying a Service Policy

Use the service-policy command to do the following:

Apply a previously created policy map.

Attach the traffic policy to a specific VLAN interface or globally to all VLAN interfaces in the same context.

Specify that the traffic policy is to be attached to the input direction of an interface.

The service-policy command is available at both the VLAN interface configuration mode and at the configuration mode. Specifying a policy map in the interface configuration mode applies the policy map to a specific VLAN interface. Specifying a policy map in the configuration mode applies the policy to all of the VLAN interfaces associated with a context.

The syntax of this command is:

service-policy input policy_name

The keywords, arguments, and options are:

input—Specifies that the traffic policy is to be attached to the input direction of an interface. The traffic policy evaluates all traffic received by that interface.

policy_name—Name of a previously defined policy map, configured with a previously created policy-map command. The name can be a maximum of 40 alphanumeric characters.

For example, to specify an interface VLAN and apply an XML HTTPS management policy to the VLAN, enter:

host1/Admin(config)# interface vlan 50
host1/Admin(config-if)# ip address 192.168.10.1 255.255.0.0
host1/Admin(config-if)# service-policy input MGMT_XML-HTTPS_POLICY

For example, to globally apply an XML HTTPS management policy to all of the VLANs associated with a context, enter:

host1/Admin(config)# service-policy input MGMT_XML-HTTPS_POLICY

To detach the XML HTTPS management policy from an interface, enter:

host1/Admin(config-if)# service-policy input MGMT_XML-HTTPS_POLICY

To detach the XML HTTPS management policy from an interface, enter:

host1/Admin(config-if)# no service-policy input MGMT_XML-HTTPS_POLICY

To globally detach the XML HTTPS management policy from all VLANs associated with a context, enter:

host1/Admin(config)# no service-policy input MGMT_XML-HTTPS_POLICY

When you detach a traffic policy either individually from the last VLAN interface on which you applied the service policy or globally from all VLAN interfaces in the same context, the ACE automatically resets the associated service policy statistics. The ACE performs this action to provide a new starting point for the service policy statistics the next time that you attach a traffic policy to a specific VLAN interface or globally to all VLAN interfaces in the same context.

Follow these guidelines when you create a service policy:

Policy maps, applied globally in a context, are internally applied on all interfaces existing in the context.

A policy activated on an interface overwrites any specified global policies for overlapping classification and actions.

The ACE allows only one policy of a specific feature type to be activated on a given interface.

To display service policy statistics for a Layer 3 and Layer 4 HTTP or HTTPS traffic management policy map, use the show service-policy command in Exec mode.

The syntax of this command is:

show service-policy policy_name [detail]

The keywords, options, and arguments are as follows:

policy_name—Identifier of an existing policy map that is currently in service (applied to an interface) as an unquoted text string with a maximum of 64 alphanumeric characters.

detail—(Optional) Displays a more detailed listing of policy map statistics and status information.


Note The ACE updates the counters that the show service-policy command displays after the applicable connections are closed.


For example, to display service policy statistics for the MGMT_XML-HTTPS_POLICY policy map, enter:

host1/Admin# show service-policy MGMT_XML-HTTPS_POLICY
Status     : ACTIVE
Description: Allow mgmt protocols
-----------------------------------------
Context Global Policy:
  service-policy: MGMT_XML-HTTPS_POLICY 

To clear the service policy statistics, use the clear service-policy command. The syntax of this command is:

clear service-policy policy_name

For the policy_name argument, enter the identifier of an existing policy map that is currently in service (applied to an interface) as an unquoted text string with a maximum of 64 alphanumeric characters.

For example, to clear the statistics for the policy map MGMT_XML-HTTPS_POLICY that is currently in service, enter:

host1/Admin# clear service-policy MGMT_XML-HTTPS_POLICY 

Enabling 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:

Specifying the xml-show on command in Exec mode from the CLI, or

Including the xml-show on command in the raw XML request itself (CLI commands included in an XML wrapper).

Specification 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 DTD file, ace_appliance.dtd, that is included as part of the software image (see the "Accessing the ACE DTD File" section). The ACE DTD File contains the information on the XML attributes for those show commands whose output supports XML format.

For example, if you specify the show interface vlan 10 command, the DTD 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)      #IMPLIED
     interface-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>
<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_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>

The syntax of this command is:

xml-show {off | on | status}

The keywords are:

off—Displays CLI show command output in regular CLI display output, not in XML format.

on—Displays CLI show command output in XML format unless a specific show command is not implemented to display its output in XML format. For details on the show command output supported in XML format, consult the the ACE DTD file, ace_appliance.dtd, that is included as part of the software image (see the "Accessing the ACE DTD File" section).

status—Displays the results of the xml show command status: on or off. The status keyword allows you to determine the status of the xml show command setting.

For example, to enable the display of raw XML request show command output in XML format from the CLI, enter:

host1/Admin# xml-show on

To return to displaying CLI show command output in regular CLI output, enter:

host1/Admin# xml-show off

Accessing the ACE DTD File

The ACE DTD file, ace_appliance.dtd, is included as part of the software image and is accessible from a web browser using either HTTP or HTTPS. The ACE DTD file, ace_appliance.dtd, is included as part of the software image and is accessible from a Web browser using either HTTP or HTTPS. To access the ace_appliance.dtd file, use a Web browser to either:

Directly access the ace_appliance.dtd file.

Open the ace_appliance.dtd file from the Cisco ACE appliance Management page.

To access and view the ace_appliance.dtd file, perform the following steps:


Step 1 If you have not done so, create a Layer 3 and Layer 4 class map and policy map to classify the HTTP or HTTPS management traffic that can be received by the ACE. See the "Configuring HTTP and HTTPS Management Traffic Services" section.

Step 2 Open your preferred Internet web browser application, such as Microsoft Internet Explorer or Netscape Navigator.

Step 3 To directly access the ace_appliance.dtd file, specify the HTTP or secure HTTP (HTTPS) address of your ACE in the address field, followed by ace_appliance.dtd. For example:

https://ace_ip_address/ace_appliance.dtd 

http://ace_ip_address/ace_appliance.dtd

You can choose to either open the ace_appliance.dtd file or save it to your computer.

Step 4 To access the ace_appliance.dtd file from the Cisco ACE appliance Management page, perform the following procedure:

a. Specify the HTTP or secure HTTP (HTTPS) address of your ACE in the address field:

https://ace_ip_address

http://ace_ip_address

b. Click Yes at the prompt to accept (trust) and install the signed certificate from Cisco. To install the signed certificate, do one of the following:

If you are using Microsoft Internet Explorer, in the Security Alert dialog box, click View Certificate, choose the Install Certificate option, and follow the prompts of the Certificate Manager Import Wizard.

If you are using Netscape Navigator, in the New Site Certificate dialog box, click Next and follow the prompts of the New Site Certificate Wizard.

c. Enter your username and password in the fields provided, and then click OK. The Cisco ACE appliance Management page appears.

d. Click the link under the Resources column of the Cisco ACE appliance Management page to access the ace_appliance.dtd file. You can choose to either open the ace_appliance.dtd file or save it to your computer.