After attending a webcast on the WebSphere Application Server 6.1 Plug-in, I thought I’d summarize the content I found helpful.

Overview

The plugin is a native module (DLL or .so) that is installed into the Web Server and is offered each HTTP request to determine whether WAS should handle it. It makes this determination based on the contents of the plugin-cfg.xml file which is normally auto-generated by WAS.

I say, “normally”, because it can be manually edited, but doesn’t need to be for most operating scenarios. Note that many of these customizations can now be configured within the Administrative Console as well, which significantly reduces the need for manual file editing. This configuration is located under Servers -> Web Servers -> -> Plug-in Properties. (Visiting this location in the Console is also a useful way to to locate the active plugin configuration file.)

Operation Mechanism

The configuration file specifies virtual hosts (IP names/addresses and ports) and URL paths which are serviced by WAS applications, enabling the plugin to determine which requests it can route to WAS and which it must leave for the HTTP server to handle.

The file also contains values governing performance, maintenance, and failover, such as logging configuration and network timeouts.

Finally, it contains the “transport” information used to forward matched requests to the appropriate Web Containers in WAS. That is, the IP name and port combinations of the different Cluster members’ Web Container “Transport Chains”.

Affinity

“Affinity” is the notion of sending a user to the same Cluster member (application server JVM) for each subsequent request after the initial one, if the application uses HTTP Sessions. This behavior is required by the JEE specification, and in WebSphere is the responsibility of the Web Server plugin. WebSphere maintains this affinity by appending a “Clone ID” or “Partition ID” to the “Session ID”, which the plugin then compares against its configuration to correctly route subsequent requests.

For further detail on the Session ID mechanics, see this post.

New users, those without an existing Session, are distributed to Cluster members in either a weighted round-robin fashion or a random fashion. Round-robin is the default, and it will decrement each cluster member’s “weight” each time it sends it a new request, until all members are less than zero, then they will all be reset to their starting values.

Tips or Items of Note

  1. If the Web Server is a 32-bit program, the plugin must also be 32-bit. Same for 64-bit.
  2. The plugin’s version must be greater than or equal to the WAS version. However, we know of one case where support said otherwise, so I guess this can be overridden at times.
  3. The RefreshInterval attribute of the Config element is the time, in seconds, between cycles where the plugin checks for changes to its configuration and automatically applies them. Its default value is 60.
  4. The attribute can be used to increase the plugin's logging. It defaults to "Error" but can have values of "Warn", "Stats", or "Trace".
  5. LogLevel “Stats” collects a minimal set of statistics, like data on the number of active connections and on affinity.
  6. All plugin logging is written to the same file, even if your Web Server uses multiple processes. Keep this in mind when tracing the log. The format of a log entry is:
    <Date/Time> -
  7. In the log, the strings “Bld version” and “Bld date” can be used to determine which version of the plugin is installed by comparing against this list.
  8. The ConnectTimeout attribute of the Server element controls how many seconds the plugin should wait for an initial connection response from a WAS cluster member. All indications are that this should be very fast. Our current setting is 10 seconds, but the webcast presenter suggested that even 5 seconds should be sufficient.
  9. The ServerIOTimeout attribute of the Server element controls how many seconds the plugin should wait for continued IO once a connection has been established. The default is 0, which means wait indefinitely. In other words, don’t timeout once communication has begun with a particular server.
  10. The plugin should not return a 500 Response Code (Server Error) unless all cluster members fail to respond. (I’m not sure I believe this empirically, but the presenter clearly asserted it.)
  11. This connection from the plugin to a particular Web Container transport is apparently maintained as an available “stream” even after a particular request is complete. I don’t know how quickly it is shut down or refreshed after use, but it’s not immediate. Keep that in mind when, say, counting “netstat -an” connections on a particular port.
  12. If all Cluster members have the same round-robin weight, the plugin will factor them down to the value 1.
  13. Since the weighted round-robin or random distribution mechanism only applies to new Sessions, it’s theoretically possible that Cluster member loads could become unbalanced if long-running Sessions happen to be allocated to one member and shorter ones to another. That is, new requests will be balanced, but that balancing doesn’t take into account existing Sessions allocated to the members. This behavior can be changed by setting the IgnoreAffinityRequests attribute of the ServerCluster element to “false”, although I don’t know what kind of performance implications this change might have.

Resources