IBM HTTP Server: WAS Plugin FAQ

Provide feedback on the IBM HTTP Server forum on IBM developerWorks.

Interactions with Apache

Does the WAS Webserver Plug-in support Apache 2.4?

Yes, the WAS Webserver Plug-in supports Apache 2.4 in 8.5.5.2/8.0.09 and later (PI06036)

How can I log my WebSphere-based authentication in the IHS access log?

If WebSphere is configured to use HTTP Basic Authentication, IHS can only log the userid and password together in base64 encoded form. This is accomplished by adding %{Authorization}i to your LogFormat directive.

If WebSphere is configured to use form-based authentication, IHS cannot log a username. As an exception, if the application code itself sets a cookie or HTTP header based on the logged in userid, this cookie or header can be logged by IHS.

Example LogFormat additions for logging of incoming cookies or response headers (full information is available in the documentation for mod_log_config).

What about mod_dir, mod_rewrite, and the WebSphere plug-in? (IHS 2.0 and above)

    >We would like to know the priority of the following directives.         
    >- mod_dir(dir_module)                                                   
    >- mod_rewrite(rewrite_module)                                           
    >- WebSpherePlugin(ibm_app_server_http_module)   
    

mod_dir only handles objects which can be served by IHS as static files, so it cannot be used to redirect requests to WebSphere. mod_dir has the lowest priority of these modules, and the priority cannot be changed. It will only try to handle a request if the request was for a directory and no other module has decided to serve the request.

With IHS 2.0, mod_rewrite always takes precedence over the WebSphere plug-in and, with the proper configuration, mod_rewrite can first rewrite URLs and then the WebSphere plug-in can see the rewritten URL and decide whether or not to serve it.

Example: Customer wants to use mod_rewrite to change URL /home to /servlet/home/, and customer has configured the WebSphere plug-in to handle /servlet/*.

Here is a mod_rewrite directive to map /home to /servlet/home, and at the same time pass it through to the WebSphere plug-in to allow it to see the rewritten URL. The PT flag on the RewriteRule is what allows the WebSphere plug-in to process the rewritten URL.

    RewriteRule ^/home /servlet/home [PT]
    

Note: In IHS 1.3, the actual order of the LoadModule or AddModule directives also makes a difference. The LoadModule or AddModule for mod_rewrite needs to come after the WebSphere plug-in is activated to allow mod_rewrite to rewrite URLs and then have the WebSphere plug-in process the rewritten URL. This is not the case with IHS 2.0, where mod_rewrite always takes precedence.

How does mod_cache interact with the WebSphere Plugin?

mod_cache can cache content generated by the WebSphere Plugin if it has the appropriate HTTP headers in the response, however this cache does not interact with the Plugin ESI cache. When mod_cache is cacheing content generated by the WebSphere Plugin you will not see evidence of the WebSphere Plugin being called for the cached request.

How can I change requests to affect how the plugin handles them?

Changing or hideing a URL from the WAS Plug-in is documented extensively in this page.

To hide a URL from the WAS Plug-in, set the per-request environment variable "skipwas" to any value:

# The unusual /+ matches one or more slashes. This prevents input like /app1//BlockMe from being sent to the backend, 
# even though WebSphere will generally not map it to the same place as /app1/BlockMe, 
# a servlet filter might treat them the same.
SetEnvIf Request_URI ^/+app1/+BlockMe skipwas=1

Header related questions

Requests handled by the plugin/WAS have the wrong Content-Type

The solution to this is almost always to configure WebSphere Application Server to provide the correct Content-Type with the response, not to try to "fix" it in IHS or the plugin.

If WAS is providing no Content-type in the response, then IHS will add the DefaultType, usually text/plain. mod_mime is not applied to requests handled by the plugin, so none of those directives can be used to apply a different Content-type.

If WAS sends the wrong Content-type, then IHS will not override it. Even ForceType is not applied to plugin responses.

Why does the WAS Plugin send a different encoding then the incoming request used?

By default, the WAS Plugin uses the URL that has been decoded by Apache and split into various sub-components. It can then re-encode the components in unexpected ways. After PM31189, you can have the Plugin start with the URl the way the client encoded it and do no further decoding or encoding. The apache environment variable websphere-nocanon turns this feature on.

If the character you're having trouble with is '/' (%2f), you'll also need the IHS portion of PM31189 to pass through %2f un-decoded with AllowEncodedSlashes NoDecode.

Retries, timeouts, markdowns, etc

When will the WAS Plug-in retry a request?

A number of conditions prevent a request from being retried by the WAS Plug-in.

Provided none of the above conditions are met, the following conditions result in a retry:

What happens during an unplanned application server outtage?

If an application server terminates unexpectedly, several things unfold. This is largely WebSphere edition independent.

What flexibility around timeouts is available?

APAR PM94198 enhances the WAS Plug-in timeouts in a few different ways, mostly limited to Apache-based webservers.

Note, conditional setting of per-request environment variables in Apache can be accomplished with the SetEnvIf or RewriteRule directive.

Backend connection management

Why does it sometimes take 1-2x the ServerIOTimeout setting to report 'ServerIOTimeout fired'?

If the plugin is waiting for I/O while the webserver is sent a signal, such as during a webserver stop or some types of child process exit such as MaxRequestsPerChild or MinSpareThreads, the poll() system call that waits for I/O with the specified timeout will be restarted. The pluin will have only waited for a portion of ServerIOTimeout, and continues to wait for a full ServerIOTimeout.

What's the story with 100-Continue?

How does MaxConnections work?

MaxConnections limits the number of connections the WAS Plug-in will open to a single application server from a single webserver child process. In practice, the per-process limitation severely limits the ability to pick a useful number.

Misc FAQS

Why are my OSGI context roots not present in plugin-cfg.xml?

OSGI applications need to be mapped/targetted to a webserver just as a normal web module, however the WAS admin console interface is slightly different.

Why might the plugin not reload plugin-cfg.xml on the fly / require a restart?

Does IHS support websockets? Does the WebSphere Plug-in support websockets?

What are known limitations in large POST requests?

Note that only WebSphere Liberty with servlet-3.1 can parse requests with a 2GB or greater Content-Length header.

What are known ESI limitations?

The ESi processor has a number of known limitations:

What maintenance do I need to see milliseconds in the http_plugin.log?

PM76364 (6.1.0.47, 7.0.0.28, 8.0.0.6, 8.5.0.2) adds milliseconds on z/OS and unix platforms.

Session Management questions

What controls whether the Plug-in switches back after a failover?

By default, affinity switches back when the original affinity server comes back. This switch back occurs because new clones are appended to the session cookie, and the Plugin tries them left to right. WAS session management can prepend the cookie instead, causing requests to NOT switch back. This is recommended when any persistence with time-based writes is used. See property "NoAffinitySwitchBack" in topic "rprs_custom_properties".

How can I avoid having the JSESSIONID cookie blown away when going between different applications

By default, a cookie path of '/' is specified and sessions are unique to each application. The JSESSIONID, as opposed to the session itself, can be shared by setting the Session management custom property "HttpSessionIdReuse".

When you access the 2nd application, it will add its clone ID (according to "NoAffinitySwitchBack") but will not change the rest of the session cookie.

How can IHS ignore URL parameters inserted by WebSphere URL session rewriting?

IBM HTTP Server treats the URL rewriting as part of the filesystem path of static resources being requested. mod_rewrite can be used to remove this information from URL's, but care has to be taken to only change requests that really will not be sent to WebSphere.

The first method involves putting the rewrite rules in existing <Directory> containers, because these will never affect WebSpehre Requests.

The second method puts the mod_rewrite rules in <VirtualHost> context, which simplifies configuration in one way but complicates it in that the user-supplied pattern must be used to restrict the rewrite to static (local IHS) content. This effectively needs to mimic the WebSphere Plugin processing to determine which URLs to remove the URL-rewritten session info from.

What's options are there for removing a server from load balancing?

SSL Questions

What's the deal with SSL breakage when moving past 8.5.5.6/8.0.0.11?

After APAR PI39126 (8.5.5.7, 8.0.0.12, 9.0.0.0), the WAS WebServer Plugin uses modern defaults for SSL/TLS processing. This includes disabling legacy protocols, ciphers, and certificate validation. This may cause problems if WAS has been explicitly configured to use only weak/export ciphers, or has been configured with a certificate chain that does not meet contemporary standards.

In practice, problems observed after PI39126 have fit into the following certificate processing related categories (See RFC5280 for complete details):

  1. BasicConstraints extension: All certificates used to validate digital signatures (AKA issuers, signers, or CA's) must contain a BasicConstraints extension with the "criticality" field set to TRUE.

  2. CertificatePolicies extension: The CertificatePolicies extension must be RFC5280 conformant across the certificate chain. The algorithm is quite complex, but in a simplifed form an intermediate signer cannot assert policies not also asserted by its own signer.

The certificate validation changes in PI39126 can be disabled, after PI49893 (8.0.0.12, 8.5.5.8, 9.0.0.0) by setting the WAS Plugin custom property "certificate_validation_strict_rfc5280=false".

PI39126 can be disabled in its entirety by setting the WAS Plugin custom property "AutoSecurity=false".

What SSL/TLS protocols does the Plug-in support?

GSK_ERROR_SOCKET_CLOSED(420) can be caused by the server not having any protocols in common with the Plug-in.

What does GSK_ERROR_BAD_CERT (gsk rc = 414) mean?

GSK_ERROR_BAD_CERT has multiple causes/solutions, listed below in order of frequency:

Intelligent Management for webservers ("ODR in the Plug-in")

Where can I learn more about IM for webservers, plug-in based ODR?

The best references for now is this topic and its children combined with existing IM information and this EA module

How do traditional configuration elements work once IM is enabled?

When I enable global security, IM is no longer able to handshake with WAS for the control/REST connection(GSK 420 eror)

There is a limitation that prevents the IM-enabled Plugin from using the "default keystore certificate" to communicate with the XD_AGENT port when that port requires TLS client authentication.

Here is what works:

What are the firewall requirements/issues around "Intelligent Management for WebServers?"

In original Intelligent Management topologies where IHS uses a static plugin-cfg.xml generated by the On Demand Router (ODR), IHS only needs to be able to access the ODR HTTP/HTTPS ports.
The ODR needs access to all of the individual application servers on their web container ports AND the XD_AGENT_PORT on the node agents and dmgrs.

In topologies with an IM-enabled IHS (i.e. using ODRLIB), the IM-enabled IHS needs to be able to talk to all of the individual application servers on their web container ports AND the XD_AGENT_PORT on the node agents and dmgrs. There are several ways to manage this requirement:

Logging FAQs

Can I rotate the http_plugin.log?

PI16910 and later allows http_plugin.log to be rotated if running in an Apache-based server.

Liberty-specific questions

How can the liberty-generated plugin-cfg.xml be customized?

Some elements of plugin-cfg.xml can be specified in server.xml in the <pluginConfiguration> element. See the KC for details

Keys can be changed or added to the top-level <Config> element of plugin-cfg.xml:

<pluginConfiguration pluginInstallRoot="/opt/PLG">
  <extraConfigProperties certificate_validation_strict_rfc5280="false" IgnoreDNSFailures="true"/>
</pluginConfiguration>

What options are available for plugin-cfg.xml generation in Liberty?

Historically, plugin-cfg.xml generation was problematic under liberty, but it improved greatly in late 2016.

More information about the WAS Plugin on Liberty is available here: http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-dist&topic=twlp_admin_webserver_plugin

What options are available for plugin-cfg.xml merging in Liberty?

What options are available for plugin-cfg.xml merging in Liberty?

More information about the WAS Plugin on Liberty is available here: http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-dist&topic=twlp_admin_webserver_plugin

Alternatives to the WAS WebServer Plug-in

While the typical configuration uses a WAS-aware reverse proxy tier for load balancing, failover, and offload (like IHS + the WAS WebServer Plug-in), generic HTTP reverse proxies can be used with only a handful of functional differences.

These generic proxies range from appliance-based HTTP load balancers to open source reverse proxy servers. Some might even have explicit WAS exploitation, but the depth of that exploitation would need to be discussed with the vendor. The info below assumes the server is backend-agnostic.

Directly fronting WebSphere with a layer 3 or layer 4 device ("IP sprayer" or NAT forwarding load balancer) that doesn't even terminate HTTP is also an option, albeit not a very flexible one.

Information about specific alternatives

What's missing in a generic HTTP reverse proxy?

What is likely to work?

What's better?

Some contemporary dedicated proxies are highly vertically scalable and use very low memory. There is also a benefit to standardization if there already exists a preferred enterprise proxy solution.

If an HTTP proxy is built into a Platform as a Service, or part of an otherwise orchestrated container technology, it may already know how to deal with the dynamic registration and deregistration of HTTP servers.

What's worse?


Provide feedback on the IBM HTTP Server forum on IBM developerWorks.