Cisco ACE XML Gateways

Cisco ACE XML Gateway Release Note (Software Version 5.2)

  • Viewing Options

  • PDF (438.7 KB)
  • Feedback
Release Note for the Cisco ACE XML Gateway

Table Of Contents

Release Note for the Cisco ACE XML Gateway


New Features in this Release

Integration with Cisco ACE Module and Appliance

Disk Management Improvements

Outbound HTTP Proxy

Response GZIP Compression

Flex Path Assignment by Service

New WSS UsernameToken Encryption and Role Options

MTOM-Encoded Message Handling


Content Screening Rules Enhancements

Support for HTTP HEAD Method Requests for Static Page Served on a Port

Important Notes

Licensing Changes

SNMP Error after Upgrade to Software Version 5.2

ACE Application Switch Integration Design Considerations

Generated WSDL Changes

HTTP Proxy Exclusion

Terminology Changes

Open Caveats

Resolved Caveats

Related Documentation

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

This release note contains the following sections:

New Features in this Release

Important Notes

Open Caveats

Resolved Caveats

Related Documentation

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

Disk Management Improvements

Outbound HTTP Proxy

Response GZIP Compression

Flex Path Assignment by Service

New WSS UsernameToken Encryption and Role Options

MTOM-Encoded Message Handling


Content Screening Rules Enhancements

Support for HTTP HEAD Method Requests for Static Page Served on a Port

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.


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.

Important Notes

This section describes behavior changes, software update notes, and other information for this release. It includes the following sections:

Licensing Changes

SNMP Error after Upgrade to Software Version 5.2

ACE Application Switch Integration Design Considerations

HTTP Proxy Exclusion

Terminology Changes

Licensing Changes

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:

After upgrade, this OID returns 3 (disabled) instead of 1 (up).

I/O Process status; OID:

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

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 message name and portType name. For example, for software version earlier than 5.2, the automatically generated name attribute value for a message element 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)

Terminology Changes

The term "proxy service" has been changed to "virtual service" in the documentation and product user interfaces.

Open Caveats

The following table lists open caveats.

Issue ID


Fault responses generated by the ACE XML Gateway differs between the Reactor processor and the Flex Path handling. This difference affects the faultactor element, as follows:

For a message processed on the Flex Path:


For a message processed by the Reactor:

<soap:faultactor xmlns="">internal</soap:faultactor>

Workaround: None.

CSCsl48089, CSCsl48144

The ACE XML Gateway does not accept chunked HTTP requests. The ACE XML Gateway drops the requests and returns an error response with HTTP status code 411, Length Required. Workaround: None.


With message logging enabled and the ACE XML Gateway under heavy traffic load, the Dashboard page of the ACE XML Manager web console takes a long time to load, possibly up to several minutes. Workaround: None.


The WSDL delete operation in the ACE XML Manager results in the removal of policy objects not created by the original import of the WSDL. Only objects created by the WSDL import should be removed, and only if no manually created objects rely on the object. However, an issue exists that causes manually created backend server objects to be removed in some cases. For backend servers that are overridden by an echo server at WSDL import time, a WSDL update followed by a WSDL delete causes the echo server to be removed from the policy, if no other virtual services rely on the server object. Workaround: None.


The traffic statistics in the ACE XML Manager can be exported as XML data. However, an XML schema that describes the format of the statistical information is not currently available. Workaround: None.


If the Cisco ACE XML Manager is off for an extended period of time (generally at least several weeks), during which the ACE XML Gateways in its control handle a significant workload, once the Manager starts up the transfer of log information from the Gateways to the Manager may fail. The failure appears as an internal error message when visiting the Dashboard page in the ACE XML Manager web console.

Workaround: For administrative purposes, the ACE XML Manager should generally not be off for an extended period of time.

Nevertheless, if this issue occurs, follow these steps to recover operability of the ACE XML Manager. Note that by following these steps you will lose the historical performance statistics, but you will get new statistics going forward.

1. Access the shell menu on the ACE XML Gateway appliance by ssh connection.

2. From the menu, choose Advanced Options, and then Run bash.

3. Change directories as follows:

cd /usr/local/reactivity/log/approuter

4. Delete statistics information as follows:

rm *.stats

Resolved Caveats

This table lists caveats resolved in release 5.2.

Issue ID


The ACE XML Manager may take an extremely long time to perform service discovery on UDDI systems that contain more than a few WSDLs.


The ACE XML Gateway lacks support for generation and validation of non-WSS digital signatures.


The ACE XML Gateway fails to decrypt inbound SOAP responses that were encrypted with a security certificate without a subject KeyIdentifier. Certificates typically contain a copy of the value of the certificate's Subject KeyIdentifier in an extension. However, if absent, the value must be computed from the public key value of the certificate. The ACE XML Gateway does not compute this value correctly.


When viewing the event log in the ACE XML Manager web console and filtering the view for Public (non-authenticated) services, backend error responses are not correctly identified in the event log viewer.


Actional Agent does not start up automatically across a reboot of the ACE XML appliance. If the Actional Agent is manually started and the appliance is subsequently rebooted, the Actional Agent needs to be manually started.


When performing SSL encryption on the client side, the Reactor processor sometimes truncates the outgoing response, particularly when sending large messages.


When WS-Addressing is configured as a required SOAP header for a service, messages with WS-Addressing headers are incorrectly rejected due to header-not-found error.


ebXML messages with Reference elements that do not include a type attribute are not permitted by the ACE XML Gateway.

Software version 5.2 release incorporates hot fix HF0027, which permits ebXML messages with Reference elements that do not include a type attribute.


If log-in authentication to the ACE XML Manager web console relies upon an LDAP system, users who are assigned specific roles (other than "administrator") and/or specific subpolicies are not able to log in. The problem affects the web console if it uses LDAP authentication in which different users are assigned to roles other than "administrator" or to specific subpolicies instead of "all subpolicies".


The message traffic log viewer in the ACE XML Manager web console does not correctly order message log items by time of day. Multiple message log items for a single day may appear out of order.


ACE XML appliances in manager-only mode incorrectly generate SNMP traps that report gateway processes as down. The traps should be generated only if the appliance is configured to operate in gateway mode and the processes are down.


The message traffic log displays message content for traffic associated with all subpolicies, regardless of which subpolicy is currently active in the web console. This makes the message content associated with services in a particular subpolicy visible to console users who may not have privileges to that subpolicy.


With a large number of saved policy versions in the Policy Manager page of the ACE XML Manager web console, the console becomes unusably slow.

In software version 5.2, this issue has been addressed by the automated removal of unneeded policy artifacts on the ACE XML Manager. In addition, policy versions are loaded into the Policy Manager only as needed, instead of all at once. As part of this resolution, only the 5 most recent policy versions are now displayed in the policy history of the Policy Manager instead of all.


Stack trace occurs in the ACE XML Manager web console when performing WSDL update. There error occurs whenever the WSDL contains an XSD with "service" in its name.


With debug logging or message logging on error enabled, a null pointer exception message may appear when the message log is opened if the ACE XML Gateway has received a message with an empty body or an attachment with headers but no body.


The backup/restore tool allows you to create a file that completely represents the state of the ACE XML appliance system, and to apply that representation on another ACE XML appliance. The restore operation failed in some cases in which a backup file that originated on an older system was attempted to be restored on a new system.


Incorporate software HotFix 23, which modified the ACE XML Gateway software to enable verification of XML signatures that reference the ResponseID attribute of the response (in addition to wsu:ID and SAML AssertionID attributes).


The content screening feature incorrectly forbids content replacement of a found string in a message with an empty string.


Passwords for external systems specified in an SDK extension configuration appear in the policy deployment page of the ACE XML Manager web console that shows the policy differences between the current and proposed policy.


A segmentation fault may occur on the ACE XML Gateway while it is performing XML Schema validation on an incoming message processed by the Reactor.


The WS-Addressing feature introduces the possibility of a circular message forwarding loop condition. The Gateway can determine the backend destination for a request dynamically based on the value of a WS-Addressing header in the request. If the service interface is not configured to prevent the possibility, it's possible to have the Gateway forward a message to itself or to a load balancer that directs the request back to the Gateway, resulting in a forwarding loop.

In software version 5.2, an exclusion list field has been added to the configuration setting for the handler. In the field, specify the IP address of the ACE XML Gateways in the cluster and any upstream load balancer or other forwarding devices as excluded destinations. Also, as a best practice, WS-Addressing requests should only be accepted from authenticated, trusted sources.


When you import a PPF file that was generated by exporting a single handler group, the proposed changes list may include options for deleting the "Public" and "Default HTTP Port" objects. Both proposed changes should be disabled, so that the objects are retained.


When deleting a WSDL that was previously updated from the Imported WSDL Files page, incorrect broken references for Public access provisioning may appear. This error occurs only when working in a sub-policy on a new (previously undeployed) policy. Also, the original services need to have been assigned to Public access control upon import.


The ACE XML Gateway allows you to use variables in your XSL Transformation scripts. Variables can be used to access HTTP headers from the message (MSGSRC-Header). As specified, HTTP headers are regarded by the Gateway in a case-insensitive manner. The case of the header value as received by the Gateway is preserved in the populated XSLT variable. However, within an XSLT, these variables are treated in case-sensitive manner. XSLT logic that relies on header names should take into account the possibility of unreliable letter casing for the HTTP header.


Basic authentication credentials are not generated correctly in the ACE XML Manager test browser for messages addressed directly to the backend service. (This issue does not affect requests addressed to the consumer interface.) If the service requires basic authentication credentials, it cannot be addressed directly from the test browser.

Related Documentation

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