Table Of Contents
Release Note for the Cisco ACE XML Gateway
Updated: March 21, 2008
This release note applies to software version 5.2 for the Cisco Application Control Engine (ACE) XML Gateway. For information on product features, refer to the ACE XML Gateway documentation located in http://www.cisco.com.
This release note contains the following sections:
New Features in this Release
This section lists important new features and feature enhancements in this release, including:
Integration with Cisco ACE Module and Appliance
ACE XML Manager enhancements allow for rapid integration between the ACE XML Gateway and the Cisco ACE Application Switch, the high-performance, application-level load balancer engine. Tools have been added to the ACE XML Manager web console that automate policy development tasks for routing traffic to backend servers through a Cisco ACE Application Switch.
At policy development time, you can direct the ACE XML Manager to inspect the Cisco ACE Application Switch configuration to acquire information on the virtual IP addresses (VIPs) it exposes. The ACE XML Manager can then generate policy objects for the connections to the VIPs.
The integration capabilities are supported for these versions of the ACE Application Switch:
•Cisco ACE module 2.0
•Cisco ACE appliance, software version A1(7) and later
The new integration capabilities accelerate and ease the task of deploying the ACE XML Gateway alongside the Cisco ACE Application Switch. For information on using the Cisco ACE Application Switch with the ACE XML Gateway, see ACE Application Switch Integration Design Considerations.
Disk Management Improvements
This release incorporates disk management improvements that were originally made in software release 4.4.2 of the ACE XML Gateway. The improvements are designed to reduce the possibility of disk exhaustion on the appliance and prevent problems if disk exhaustion occurs.
The improvements include:
•Internal log rotation activity increased—Previously, the log rotation process was designed to retain up to 20 files in the internal system and user logs and to rotate them when they exceeded 100 megabytes in size. The process executed every five minutes. Under heavy traffic, it was possible for the log file size to grow to over a gigabyte in a few minutes and potentially consume all available disk space on the appliance. The log rotate process configuration has been modified so that it runs every minute instead of five, rolls files at 200 megabytes, and retains only ten files instead of twenty.
•Unneeded artifacts deleted—Previously, the ACE XML Manager retained several types of unneeded policy artifacts (in particular, compiled versions of old policies). If policies were frequently deployed from the Manager, it was possible for these artifacts to consume a large amount of disk space. They are now regularly removed from disk by automated processes.
•Startup prevention if disk full—If the disk on the ACE XML Manager approaches capacity, it shuts down and prevents subsequent startup of its primary processes until disk space has been cleared. (Previously, it was possible for the Manager to continue operating, which could result in file corruption errors.) If an attempt is made to start a Manager in this condition, the following message appears: "detected full disk, cannot start" To restart the Manager, you must first access the appliance by SSH and clear disk space by removing unneeded files. If you encounter this condition, contact your Cisco support representative for more information.
Outbound HTTP Proxy
The ACE XML Gateway and Manager can now be configured to make outbound connections through an HTTP proxy. In many networks where the ACE XML appliances are installed (especially for the ACE XML Manager), access to external networks is permitted only through an HTTP proxy.
You can now configure an outbound HTTP proxy connection for the ACE XML Gateway and Manager. They can be configured separately, enabling different HTTP proxy configurations for the Manager and Gateway. With this feature enabled, all outbound HTTP connections are made through the HTTP proxy you specify, including connections for administrative traffic and service traffic from the ACE XML Gateway.
Response GZIP Compression
The ACE XML Gateway can now compress qualifying responses in GZIP format. Response compression is configurable by port. The ACE XML Gateway compresses a response only for requests that indicate by HTTP header the acceptance of a compressed response and if the response exceeds the configured size threshold.
Also note that only messages handled on the Flex Path are compressed. That is, the Reactor processor does not perform response compression. However, enabling response compression alone does not cause handling for a given service to be pushed to the Flex Path (unlike other message processing features that are not supported by the Reactor). Enabling compression on the port enables response compression only for the services on the port that, for other reasons, are already subject to Flex Path processing.
If it is important for a given service to have qualifying responses compressed, you should enable compression on its port and also ensure that the service is handled on the Flex Path. If it is not, you can force Flex Path handling by selecting the Flex Path option on either the port object (to force Flex Path handling to all services that use the listening port) or on the individual virtual service object (to force Flex Path handling only for that service).
Flex Path Assignment by Service
A particular message can be processed at the ACE XML Gateway by either the Flex Path processor or the Reactor engine. The ACE XML Gateway policy automatically associates a virtual service to the appropriate processor given the service's settings. A virtual service that defines processing or validation measures not supported by the Reactor (such as protocol mediation) are automatically assigned to the Flex Path.
In some cases, you may want to directly set Flex Path processing for certain traffic. This may be useful, for example, to preserve service compatibility or to ensure that qualifying responses are compressed at the Gateway (since the Reactor does not support response compression).
Previously, you could only set Flex Path processing by port, which meant that all service traffic on the port was subject to the setting. Now, you can configure the option by virtual service. This provides a greater level of control on manual Flex Path assignment.
New WSS UsernameToken Encryption and Role Options
Configuration settings have been added to the ACE XML Manager web console to facilitate passing WS-Security UsernameToken credentials between remote ACE XML Gateways. The "AXG-only" option in the UsernameToken settings are used to mark tokens for processing by another ACE XML Gateway (through the use of the role attribute).
The new options are specifically intended to ease policy configuration for scenarios in which an ACE XML Gateway receives a message with an WSS UsernameToken from the originating endpoint, associates the token with the AXG-only role, encrypts the token, and then sends the message to the remote ACE XML Gateway, usually over an insecure network. The receiving ACE XML Gateway recognizes the AXG-only role, and passes through the decrypted header for transmission to the destination.
MTOM-Encoded Message Handling
This release provides enhanced support for processing messages in MTOM (Message Transmission Optimization Mechanism) format. MTOM is a message encoding protocol designed to optimize XML data. Previously, the ACE XML Gateway could only pass through MTOM data. It can now reconstitute MTOM-optimized message, so that the optimized data can be validated or processed like any XML data. In reconstituting an MTOM-optimized message, the ACE XML Gateway converts the data from binary to Base64-encoded form, and restores it to the SOAP envelope portion of the message.
BPEL WSDL Support
For imported WSDLs that contain BPEL (or Business Process Execution Language) information, the ACE XML Manager can now retain this information and propagate it to the WSDLs it generates. BPEL is a protocol for describing complex business interactions between different processes. BPEL-related rules that apply to a service can be included in a WSDL that describes the service.
When you import a WSDL with BPEL information, the ACE XML Manager recognizes and retains that information. When the ACE XML Manager later generates a WSDL for the services as exposed at the ACE XML Gateway, it includes the BPEL information in the WSDL, making it available to the users of the WSDL.
Content Screening Rules Enhancements
The built-in content screening rules have been enhanced with additional rules focussed upon protecting against SQL injection attacks and cross-site scripting attacks.
Support for HTTP HEAD Method Requests for Static Page Served on a Port
The ACE XML Gateway now supports HTTP HEAD method requests as well as GET requests for the health check request on HTTP port objects. There are no special configuration requirements for this capability. If a request is sent with this method, the ACE XML Gateway returns a response that is identical to one for the GET request, except that the HTTP body is not returned.
This section describes behavior changes, software update notes, and other information for this release. It includes the following sections:
The product licensing mechanism for the ACE XML Gateway and Manager has been changed. In the new licensing scheme, a license is associated with a particular hardware-based host identifier and a Product Authorization Key (PAK). To acquire a license for your appliance, use your PAK and the host ID to complete the Cisco product license registration processing using the form at the following address:
After you complete the registration, the license file will be sent to you by email.
The license format change also applies to existing systems being upgraded from version 5.1 to 5.2. After performing the upgrade, you will need to install a new license on the appliance. As with new systems, to get a license you first need to retrieve the host identifier for the target system. The 5.2 updater tool can discover and report the host identifier for your appliance. Therefore, before attempting the upgrade, start the 5.2 upgrade script on the target appliance and proceed with the upgrade process until it reports your host identifier. Once you get the host identifier, cancel the upgrade and submit the reported identifier in a license request email to the following address:
You will subsequently receive a response containing a PAK for your appliance. You can then submit the PAK to the Cisco product license registration form, as described above.
To avoid extended system downtime, do not complete the 5.2 upgrade process until you have received a license for the appliance. Also, be sure to initiate the license request process well in advance of the time allotted for performing the software version upgrade.
SNMP Error after Upgrade to Software Version 5.2
An SNMP reporting issue is known to affect ACE XML Gateway appliances after a software upgrade to version 5.2. After the upgrade, an SNMP query on the Gateway incorrectly reports processes as disabled.
This issue causes the following MIB objects to incorrectly report a status of disabled:
•Core process status; OID:126.96.36.199.4.1.14709.1.10.20.10.1.0
After upgrade, this OID returns 3 (disabled) instead of 1 (up).
•I/O Process status; OID:188.8.131.52.4.1.14709.1.10.20.10.2.0
After upgrade, this OID returns 4 (disabled) instead of 1 (up).
The processes are reported down even though they are typically functioning correctly after the upgrade. To confirm their status, you can check the System Management page in the Manager web console, which indicates the operational status of the various processes for managed Gateways.
You can correct this issue after upgrading to the 5.2 software by reapplying the operating mode configuration for the appliance, as described in the following procedures. After performing these steps, querying the affected SNMP objects will result in their status being reported correctly.
Note You need to perform these steps only if the appliance will continue operating with the 5.2 software; that is, if you have performed the upgrade to 5.2 only in order to apply a subsequent software version, you do not need to perform the workaround.
On each upgraded appliance:
1. Connect by SSH to the appliance.
2. In the Main menu of the appliance configuration interface, select item 3, ACE XML Gateway Cluster Configuration.
3. Choose the current operating mode of the appliance, such as item 1, ACE XML Gateway Cluster Member.
4. For all subsequent configuration screens, accept the default, existing configuration settings by clicking OK.
5. When prompted to restart the services, select Yes to restart the services.
When finished, the SNMP module will correctly report the status of the I/O and core processes. To verify that it does, use an SNMP client to check the core process and I/O process status MIB objects. For instance, from the appliance command line, you can quickly check that the core process is operational by entering the snmpwalk command as follows:
snmpwalk -v 1 -c reactivity -m /etc/reactivity/snmp/REACTIVITY-MIB.txt localhost 184.108.40.206.4.1.14709.1.10.20.10.1.0
ACE Application Switch Integration Design Considerations
This release includes enhancements that ease the task of integrating the ACE XML Gateway with Cisco ACE Application Switches in the backend network. As listed here, there are several policy configuration considerations applicable to routing traffic through a backend ACE Application Switch, apart from specifying its connection settings.
Note Several of the policy design considerations listed here may be applicable for other types of backend devices as well. Whenever backend traffic must pass through an intervening load balancer, web server, or other type of network device, the behavior of those devices (and its effect on the message received by the ACE XML Gateway) should be considered. Special policy configuration requirements may exist for HTTP header processing or error mapping, for example.
When using the ACE XML Gateway to direct traffic through a backend ACE Application Switch, note the following policy design considerations:
•In performing layer 4 load balancing, the Cisco ACE Application Switch passes redirect responses back to the client. Therefore, for virtual services that route traffic through a backend Cisco ACE Application Switch, the ACE XML Gateway policy should be configured to pass through responses with the HTTP redirection status codes 302 and 304.
•The Delta Optimization feature of the ACE Application Switch provides the benefits of caching to web pages that are highly dynamic. After the initial request, only the parts of a page that are changed for subsequent requests are sent to the client, with static parts served from the browser's cache.
If the ACE XML Gateway routes traffic to a web application for which a backend ACE Application Switch provides Delta Optimization, the virtual service needs to be configured to accommodate the URL rewriting performed by the ACE Application Switch for this feature, as follows:
1. In the consumer interface settings for the HTTP Get virtual service, enable regular expression matching on the local path and set the path to the following regular expression: (.*)
Note It's possible for a "match any" regular expression in a local path, (.*), to introduce request matching ambiguity errors at the ACE XML Gateway, if there are other services that need to be configured in a similar fashion. However, in most cases, different web applications proxied at the gateway would already be differentiated by virtual hostname, which serve to distinguish requests. Also note that this configuration does not introduce ambiguity for other services with a more specific local path URL than "match any" (that is, a local path that contains both constant values and regular expressions).
2. In the Service Interface, enable back-reference replacement and for the Path on Server value use the back-reference, /1
3. In the Content Screening Defaults configuration, create a custom content screening rule that replaces the ACE IP string in the body of the messages to the ACE XML Gateway IP address. For example, the regular expression required to match an IP address would be similar to: http://192\.168\.0\.11
As the rule action, be sure to enable Allow the message to continue being processed, and specify the replacement string as the address of the ACE XML Gateway.
•NTLM is a challenge-response-based authentication mechanism. If the backend application requires NTLM authentication, or any other challenge-response authentication method (such as Kerberos), you must ensure that challenge and response messages are correctly passed through the ACE XML Gateway. To do so, configure HTTP header passthrough as follows:
–In the Response Processing settings, specify passthrough for the "WWW-Authenticate" header.
–In the Request Processing settings, specify passthrough for the "Authorization" header.
Passthrough settings are configured in the Routes section of the virtual service settings page. In the Header Name field, use the value "Authorization" for the request and "WWW-Authenticate" for the response, with pass through as the action. Also, in the Custom Route Exception configuration, configure pass through for exception responses that have HTTP status code 401, unauthorized.
•By default, the ACE XML Gateway removes what are considered single-hop HTTP headers from messages before passing them on. Among this type of header is Accept-Encoding. If the backend system, such as the ACE Application Switch, is intended to perform response compression, you need to configure HTTP header passthrough for the Accept-Encoding header for the request. Also note that, if using backend response compression, you should configure the ACE XML Gateway to pass through the response as binary data with no validation or processing.
Generated WSDL Changes
The format of certain attribute values in the WSDL files generated by the ACE XML Manager have changed. If using the generated WSDLs to create client code, this change may affect the compatibility of components that rely upon the interface specifications defined by the WSDL.
Value formats have changed for
portTypename. For example, for software version earlier than 5.2, the automatically generated name attribute value for a
messageelement followed the format illustrated by the following example:
For 5.2, the same attribute value would be:
HTTP Proxy Exclusion
The HTTP Proxy feature introduced in software version 5.2 allows you to configure an HTTP proxy for the ACE XML Manager or ACE XML Gateway. With this option enabled on an Gateway, all outbound HTTP traffic is passed through the proxy, including outbound service traffic. Settings for the feature include an exclusion list, which lets you specify the destinations for messages that should bypass the HTTP proxy.
Note that the exclusion setting does not work for service traffic if the excluded server is specified in the HTTP proxy configuration by IP address, while the virtual service specifies the same server destination by host name. For outbound service traffic, the exclusion list should specify the destination to exclude from proxy handling in the same form as the backend service object for the virtual service. (CSCsm41604)
The term "proxy service" has been changed to "virtual service" in the documentation and product user interfaces.
The following table lists open caveats.
This table lists caveats resolved in release 5.2.
For more information on the ACE XML Gateway system, see the following documents:
•ACE XML Gateway User Guide
•ACE XML Gateway Quick Start Guide
•ACE XML Gateway Administration Guide
This document is to be used in conjunction with the documents listed in the "Related Documentation" section.
CCDE, CCENT, Cisco Eos, Cisco StadiumVision, the Cisco logo, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn is a service mark; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iPhone, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, iQuick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace, MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise, The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.
All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0803R)
Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.
© 2008 Cisco Systems, Inc. All rights reserved.