The plugin-cfg.xml file includes the following elements and attributes. Unless indicated otherwise, each element and attribute can be specified only once within the plugin-cfg.xml file. For a sample plugin-cfg.xml file, see Sample plugin-cfg.xml file.
Config
This element is required. It indicates the beginning of the WebSphere HTTP plug-in configuration file, and contains all of the other elements in the file. It can include one or more of the following attributes and elements:
IgnoreDNSFailures attribute
This attribute pecifies whether the plug-in ignores DNS failures within a configuration when the plug-in starts. Valid values are true and false. The default value is false.
RefreshInterval attribute
This attribute specifies the time interval in seconds at which the plug-in should check the configuration file to see if the file is changed. The plug-in checks the file for any modifications that have occurred since the last time the plug-in configuration was loaded. The default value is 60.
In a development environment, where changes can occur frequently, a lower setting is preferable. In production, a higher value than the default is preferable because updates to the configuration do not occur often. If the plug-in fails to reload, a message is written to the plug-in log file and the existing configuration is used until the plug-in configuration file successfully reloads.
ASDisableNagle attribute
This attribute specifies whether to disable nagle algorithm for the connection between the plug-in and the application server. By default, nagle algorithm is enabled. Valid values are true and false.
IISDisableNagle attribute
This attribute specifies whether to disable nagle algorithm on Microsoft Internet Informations Services (IIS). By default, nagle algorithm is enabled. Valid values are true and false.
AppServerPortPreference attribute
This attribute specifies which port number the application server uses to build URIs for a sendRedirect action. Valid values are webserverPort and hostHeader. The default value is webserverPort.
VHostMatchingCompat attribute
The Config element can contain no more than one VHostMatchingCompat attribute. This attribute specifies that the port number is to be used for virtual host matching. Valid values are true and false. The default value is false.
ResponseChunkSize attribute
When a response is returned to the Web server, the plug-in reads the response body in chunks until all of the response data is read. This attribute specifies the maximum size of these chunks in kilobytes. The default value is 64. Note that if the response body contains a large amount of data, you might experience a decrease in performance.
For a chunk size of n KB, the plug-in reads responses according to these conditions:
AcceptAllContent attribute
This attribute specifies whether or not users can include content in POST, PUT, GET, and HEAD requests when a Content-Length or Transfer-encoding header is contained in the request header. Valid values are true and false. The default value is false.
ChunkedResponse attribute
This attribute specifies whether or not the plug-in chunks the response to the client when Transfer-Encoding : Chunked response header is present in the response. This attribute applies only to the IIS, IPlanet, and Domino Web servers. The IHS Web server automatically handles the chunking of the response to the client. Valid values are true and false. The default value is false.
IISPluginPriority attribute
This attribute specifies the priority in which the IIS Web server loads the Web server plug-in. Valid values are High, Medium, and Low. The default value is High.
NOTES:
Log element
The Log element describes the location and level of log messages that the plug-in writes.
The Log element can include these attributes:
Name attribute
The Log element includes exactly one Name attribute. This attribute specifies the fully qualified path to the log file. If the file does not exist, it is created. If the file exists, new log messages are appended to the file.
LogLevel attribute
The Log element can include no more than one LogLevel attribute. This attribute specifies the level of detail of the log messages that the plug-in writes to the log. You can specify one of the following values for this attribute:
The default value is Error, and this value is used if a LogLevel attribute is not specified for the Log element. As an example, you might specify the LogLevel as:
<Log LogLevel="Error" Name=
"/QIBM/UserData/WebAS51/Base/myInstance/logs/http_plugin.log"/>
Note: The Trace level generates a large amount of messages. It is recommended that you use the Trace level only for troubleshooting purposes.
Property Name="esiEnable" Value="true/false" element
This element enables or disables the Edge Side Include (ESI) processor. If the ESI processor is disabled, the other ESI elements in this file are ignored. Valid values are true and false. The default value is true.
Property Name="esiMaxCacheSize" Value="integer" element
The Value attribute of this element specifies the maximum size of the cache, in kilobytes (KB). The default value 1024, which is equivalent to 1 megabyte. When the cache is full, entries are removed based on their expiration times.
Property Name="ESIInvalidationMonitor" Value="true/false" element
This element indicates whether or not the ESI processor receives invalidations from the application server. Valid values are true and false. The default value is false.
ServerCluster element
The Config element can contain one or more ServerCluster elements. The ServerCluster element specifies a group of servers that are generally configured to service the same types of requests. In the simplest case, the cluster contains only one server definition. In the case in which more than one server is defined, the plug-in uses load-balancing across the defined servers. The plug-in can use a round robin algorithm or a random algorithm. The following example is an example of a ServerCluster element:
<ServerCluster Name="Servers">
<ClusterAddress Name="ClusterAddr">
<Transport Hostname="192.168.1.2" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS">
<Property Name="Keyring"
value="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>
</Transport>
</ClusterAddress>
<Server Name="Server1">
<Transport Hostname="192.168.1.3" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.3" Port="9443" Protocol="HTTPS">
<Property Name="Keyring"
value="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>
</Transport>
</Server>
<Server Name="Server2">
<Transport Hostname="192.168.1.4" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.4" Port="9443" Protocol="HTTPS">
<Property Name="Keyring"
value="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>
</Transport>
</Server>
<Server Name="Server3">
<Transport Hostname="192.168.1.5" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.5" Port="9443" Protocol="HTTPS">
<Property Name="Keyring"
value="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>
</Transport>
</Server>
<PrimaryServers>
<Server Name="Server1"/>
<Server Name="Server2"/>
</PrimaryServers>
<BackupServers>
<Server Name="Server3"/>
</BackupServers>
</ServerCluster>
The ServerCluster element can include these attributes and elements:
Name attribute
Each ServerCluster element includes exactly one Name attribute. This attribute specifies the logical or administrative name for this group of servers.
LoadBalance attribute
Each ServerCluster element can include no more than one LoadBalance attribute. This attribute specifies the type of load balancing that the plug-in uses. Valid values are Round Robin and Random. The default value is Round Robin. In round robin load-balancing, the first server is selected randomly. For subsequent requests, servers are selected in a specified order, unless a server is busy. If a server is busy, the next available server in the sequence is selected. This implementation ensures that in multiple process-based Web servers, all of the processes do not send their first request to the same application server.
RetryInterval attribute
Each ServerCluster element can include no more than one RetryInterval attribute. This attribute specifies the length of the interval, in seconds, between attempts to connect to an unavailable server. The default value is 60.
RemoveSpecialHeaders attribute
Each ServerCluster element can include no more than one RemoveSpecialHeaders attribute. The plug-in adds special headers to the request before it forwards the request to the application server. These headers store information that the application needs when it processes the request. If the incoming request contains headers, the plug-in removes the existing headers and adds new headers before it sends the request to an application server.
Valid values are true and false. The default value is true. Setting the attribute to false introduces a potential security exposure by not removing headers from incoming requests.
CloneSeparatorChange attribute
Each ServerCluster element can include no more than one CloneSeparatorChange attribute. Some pervasive devices cannot handle the colon character (:) that is used to separate clone IDs in conjunction with session affinity. This attribute specifies that clone IDs are separated with a plus character (+). You must also change application server configurations so that the application server uses the plus character to separate clone IDs. Valid values are true and false. The default value is false
PostSizeLimit attribute
Each ServerCluster element contains no more than one PostSizeLimit attribute. If a request exceeds a specified size, the plug-in does not send the request to an application server. This attribute specifies the maximum request size in bytes. The default value is -1, which indicates that there is no size limit.
Server element
Each ServerCluster element contains one or more Server elements. This element specifies an application server instance that is configured to handle requests routed to it based on the routing rules of the plug-in configuration. The Server element corresponds to an application server that runs on the local machine or a remote machine.
The Server element can contain these attributes and elements:
Name attribute
Each Server element includes exactly one Name attribute. This attribute specifies the administrative or logical name for the server.
CloneID attribute
Each Server element includes no more than one CloneID attribute. This attribute is used in conjunction with session affinity. If this unique ID is present in the HTTP cookie header of a request or the URL (if you use URL rewriting), the plug-in routes the request to the designated server, provided all other routing rules are met. If a CloneID is not specified in the Server element, then session affinity is not enabled for this server.
If this attribute is specified, the plug-in checks the incoming cookie header or URL for JSESSIONID. If JSESSIONID is found then the plug-in looks for one or more clone IDs. If a clone ID is present, and a matching ID is specified in the plug-in configuration file, then the request is routed to the specified application server, regardless of the load balancing configuration for the cluster.
If you are not using session affinity, it is recommended that you remove the CloneID attributes from the configuration file. If the attribute is specified, the plug-in performs additional request processing. If clone IDs are not specified in the configuration, the plug-in routes the request according to the load balancing configuration for the cluster.
WaitForContinue attribute
Each Server element includes no more than one WaitForContinue attribute. This attribute specifies whether the plug-in uses the HTTP 1.1 100 Continue support before it sends the request content to the application server. Valid values are true and false. The default value is false. The plug-in does not wait for the 100 Continue response from the application server before it sends the request content. For performance reasons, it is recommended that you enable this function only if you are configuring the plug-in to work with certain types of proxy firewalls.
LoadBalanceWeight attribute
Each Server element includes no more than one LoadBalanceWeight attribute. This attribute specifies the weight associated with the application server for weighted round-robin load balancing. The algorithm for this attribute decrements all weights within the server cluster until all of the weights reach zero. When a server's weight reaches zero, no more requests are routed to that server until all of the servers in the cluster have a weight of zero. After all servers reach zero, the weights for all servers in the cluster are reset and the algorithm starts over.
When an application server is shut down, it is recommended that you set the weight for that server to zero. The plug-in can maintain proper load balancing among the remaining servers.
ConnectTimeout attribute
Each Server element includes no more than one ConnectTimout attribute. The ConnectTimeout attribute of a Server element enables the plug-in to perform non-blocking connections with the application server. Non-blocking connections are beneficial when the plug-in is unable to contact the destination to determine if the port is available or unavailable.
If no ConnectTimeout value is specified, the plug-in performs a blocking connect in which the plug-in sits until an operating system times out and allows the plug-in to designate the server as unavailable. A value of 0 causes the plug-in to perform a blocking connect. A value greater than 0 specifies the number of seconds you want the plug-in to wait for a successful connection. If a connection does not occur after that time interval, the plug-in marks the server unavailable and fails over to one of the other servers defined in the cluster.
ExtendedHandshake attribute
Each Server element includes no more than one ExtendedHandshake attribute. If a proxy firewall is between the Web server plug-in and the application server, and an application server fails, the plug-in can still connect successfully with the firewall. As a result, the plug-in does not detect that the application server is not running. If you set the ExtendedHandshake attribute to true, the plug-in performs some communication with the application server to ensure that the application server is running. If the application server is not running, the plug-in can route the request to a different server.
Valid values are true and false. The default value is false.
MaxConnections attribute
Each Server element includes one MaxConnections attribute. This attribute specifies the maximum number of pending connections to an application server that can be flowing through a Web server process at any point in time. For example, in the following situation, the application server could receive up to 500 connections. The application server can receive 50 connections from each process, and there are 10 processes.
The default value for this attribute is -1. If this attribute is set to either zero or -1, there is no limit to the number of pending connections to the Application Servers.
Transport element
Each Server element contains one or more Transport elements. This element specifies the transport for reading and writing requests to a particular application server instance. The transport provides the information needed to determine the location of the application server to which the request is sent. If multiple transports are configured to use the same protocol, the first one is used.
It is possible to configure the server to have one non-secure transport and one that uses SSL. In this configuration, a match of the incoming request protocol is performed to determine the appropriate transport to use to send the request to the application server.
The Transport element can include these attributes and elements:
Hostname attribute
Each Transport element includes exactly one Hostname attribute. This attribute specifies the host name or IP address of the machine where the application server instance is running.
Port attribute
Each Transport element includes exactly one Port attribute. This attribute specifies the port on which the application server instance listens for incoming requests.
Protocol attribute
Each Transport element includes exactly one Protocol attribute. This attribute specifies the protocol that the plug-in uses to communicate over this transport. Valid values are HTTP and HTTPS.
Property element
Each Transport element can contain zero or more Property elements. If the protocol for the transport is HTTPS, the Property element specifies initialization parameters, such as password and keyring.
The Property element can include these attributes:
Name attribute
Each Property element includes exactly one Name attribute. This attribute specifies the name of the Property being defined. Valid values are password, keyring, and stashfile.
Value attribute
Each Property element includes exactly one Value attribute. This attribute specifies the value of the Property.
For example, this section of the plugin_cfg.xml file might look like this:
<Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS">
<Property Name="keyring"
value="/QIBM/UserData/WebAS51/Base/myInstance/etc/keyring.kdb"/>
<Property Name="stashfile"
svalue="QIBM/UserData/WebAS51/Base/instance/etc/keyring.sth"/>
<Property Name="password" value="WebAS"/>
</Transport>
ClusterAddress element
Each ServerCluster element contains no more than one ClusterAddress element. Use a ClusterAddress if you do not want the plug-in to perform any type of load balancing because you have a separate type of load balancing between the plug-in and the application server.
If you include the ClusterAddress, requests that do not have affinity established are routed to the ClusterAddress. If affinity has been established, the plug-in bypasses the ClusterAddress and routes the request to the appropriate application server. If no ClusterAddress is defined for the ServerCluster, the plug-in distributes uses its load balancing configuration to distribute requests among the servers listed in the PrimaryServers element.
Th ClusterAddress element can include the same attributes and elements that the Server element uses. For a description of these attributes and elements, see Server element.
PrimaryServers element
Each ServerCluster element contains no more than one PrimaryServers element. This element lists application servers to which the plug-in routes requests for this cluster. If a list of PrimaryServers is not specified, the plug-in routes requests to the servers that are defined for the ServerCluster.
BackupServers element
Each ServerCluster element contains no more than one BackupServers element. This element lists servers to which the plug-in routes requests if all of the servers that are specified in the PrimaryServers list are unavailable. The plug-in does not use load balancing for the servers in the BackupServers list. Instead, the plug-in attempts to send the request to each backup server in the order that they appear in this list. The plug-in routes requests to the first available application server from the BackupServers list. If no backup servers are available, the plug-in returns an error.
VirtualHostGroup element
The VirtualHostGroup element specifies a group of virtual host names that are included in the HTTP Host header. You can use this element to group virtual host definitions that are configured to handle similar types of requests. The following example is an example of a VirtualHost Group element and associated elements and attributes:
<VirtualHostGroup Name="Hosts">
<VirtualHost Name="www.x.com"/>
<VirtualHost Name="www.x.com:443"/>
<VirtualHost Name="*:8080"/>
<VirtualHost Name="www.x.com:*"/>
<VirtualHost Name="*:*"/>
</VirtualHostGroup>
The VirtualHostGroup element includes these attributes and elements:
Name attribute
The VirtualHostGroup includes exactly one Name attribute. This attribute specifies the logical or administrative name to be used for this group of virtual hosts.
VirtualHost element
The VirtualHostGroup element contains one or more VirtualHost elements. This element specifies the host name that determines whether incoming requests are routed to an application server. The host names are part of the HTTP Host header.
The VirtualHost element includes this attribute:
Name attribute
Each VirtualHost element includes exactly one Name attribute. This attribute specifies the host name and port number that is specified in the HTTP Host header to match successfully with this VirtualHost. The value is a host name or IP address and port combination, separated by a colon.
You can specify host names and ports, or you can specify an asterisk (*) for the host name, port, or both. If you specify an asterisk for both the host and the port number, any request matches this rule. If no port is specified in the definition, the plug-in uses the default HTTP port (80).
UriGroup element
The UriGroup element specifies a group of URIs that can be specified on the HTTP request line. The plug-in compares the incoming URI with the URIs in the group to determine whether or not the application server can process the request. The Route element links the URI group to a server cluster and a virtual host group that are eligible to serve this group of URIs. The following example is an example of a UriGroup element and associated elements and attributes:
<UriGroup Name="Uris">
<Uri Name="/servlet/snoop"/>
<Uri Name="/webapp/*"/>
<Uri Name="*.jsp"/>
</UriGroup>
The UriGroup element can include these attributes and elements:
Name attribute
The UriGroup element contains exactly one Name attribute. This attribute specifies the logical or administrative name for this group of URIs.
Uri element
The UriGroup element contains one or more Uri elements. This element specifies the virtual path to the resource that you want the application server to process. Each URI specifies the incoming URLs that the application server can process.
The Uri element can include these attributes:
Name attribute
Each Uri element includes exactly one Name attribute. To access the URI, the HTTP request line must include the string that is specified for this attribute. You can use an asterisk (*) as a wildcard character within the URI definition. For example, you can specify that URIs such as *.jsp or /servlet/* are to be routed to the application server.
When you assemble your application, you can specify File Serving Enabled or Serve servlets by classname. If you specify File Serving Enabled, then only a wildcard URI is generated for the Web application, regardless of any explicit servlet mappings. If you specify Serve servlets by classname, then this URI is generated: <Uri Name="Web_application_URI/servlet/*">.
AffinityCookie attribute
The Uri element includes no more than one AffinityCookie attribute. This attribute specifies the name of the cookie that the plug-in uses when it determines if the inbound request has session affinity to a particular cluster member. The default value is JSESSIONID. For more information about session affinity, see the CloneID attribute.
Route element
This attribute specifies a request routing rule. The plug-in uses this rule to determine if an incoming request should be sent to an application server. The Route element specifies how the plug-in handles requests based on certain characteristics of the request. The route definition refers to the other main elements of the plugin-cfg.xml file: a required ServerCluster, and either a VirtualHostGroup, UriGroup, or both.
Using the information that is defined in the VirtualHostGroup and the UriGroup for the route, the plug-in determines if the incoming request to the Web server should be sent on to the ServerCluster defined in this route. The following example is an example of this element:
<Route VirtualHostGroup="Hosts" UriGroup="Uris" ServerCluster="servers/>
The Route element can contain these attributes:
VirtualHostGroup attribute
The Route element includes no more than one VirtualHostGroup attribute. This attribute specifies the group of virtual hosts that the plug-in uses to determine the route. To determine if this request should be handled by the application server, the plug-in compares the incoming host header and server port to the virtual hosts in the specified group. If this attribute is not included in the configuration file, then every request is a successful match.
UriGroup attribute
The Route element includes no more than one UriGroup attribute. This attribute specifies the group of URIs that the plug-in uses to determine the route. The plug-in compares the incoming URI for the request to the defined URIs in the specified URI group to determine if this request should be handled by the application server. If this attribute is not included in the configuration file, then every request is a successful match.
ServerCluster attribute
The Route element includes exactly one ServerCluster attribute. This attribute specifies the cluster to which the plug-in sends requests that match the route. If both the URI matching and the virtual host matching are successful for this route, the request is sent to one of the servers defined within the specified cluster.
RequestMetrics element
This element specifies whether or not Request Metrics is enabled, and how to filter the requests based on the Internet protocol (IP) and Uniform Resource Identifiers (URI) filters. The following example is an example of this element:
<RequestMetrics armEnabled="false" newBehavior="false" rmEnabled="false" traceLevel="PERF_DEBUG">
The RequestMetrics element can include these attributes and elements:
armEnabled attribute
The RequestMetrics element includes no more than one armEnabled attribute. This attribute indicates whether or not the ARM 4 agent is enabled in the plug-in. Valid values are true and false. The default value is false. In WebSphere Application Server - Express Version 5.1, the plug-in ignores this attribute.
Note: To enable ARM 4 support for the SunOne (iPlanet) Web server, you must include the AddLog fn="as_term" directive in the obj.conf file.
loggingEnabled attribute
The RequestMetrics element includes exactly one newBehavior attribute. This attribute indicates whether or not request metrics logging is enabled in the plug-in. Valid values are true and false. When this value is set to true and the traceLevel attribute is not set to NONE, request metrics data is logged. When this value is set to false, request logging is disabled. The value of loggingEnabled depends on the value specified for the system property com.ibm.websphere.pmi.reqmetrics.loggingEnabled. When this system property is not present, loggingEnable is set to true. In WebSphere Application Server - Express Version 5.1, the plug-in ignores this attribute.
rmEnabled attribute
The RequestMetrics element includes exactly one rmEnabled attribute. This attribute specifies whether or not Request Metrics is enabled in the plug-in. Valid values are true and false. The default value is false.
traceLevel attribute
The RequestMetrics element includes exactly one traceLevel attribute. This attribute indicates how much information is logged. Valid values are NONE, HOPS, PERF_DEBUG, and DEBUG.
When this attribute is set to NONE, there is request logging is disabled. When this attribute is not set to NONE, request information is logged after the request is processed.
filters element
The RequestMetrics element includes no more than two filters elements. The filters control which requests are traced.
Each filters element includes these attributes and elements:
enable attribute
Each filters element includes exactly one enable attribute. Valid values are true and false. The default value is false. If the value is true, the type of filter is enabled, and RequestMetrics traces requests that match a filterValues element.
type attribute
Each filters element includes exactly one type attribute. Valid values are SOURCE_IP and URI.
filterValues element
The filters element includes one or more filterValues elements. The filterValues show the detailed filter information.
The filterValues element includes these attributes:
enable attribute
Each filterValues element includes exactly one enable attribute. Valid values are true and false. The default value is false. If the value is true, the filter is enabled, and RequestMetrics traces requests that match the value attribute.
value attribute
Each filterValues element includes exactly one value attribute. This attribute specifies the filter value for the corresponding filter type. Specify either an IP address or a URI.
If URI and client IP address filters are enabled, Request Metrics requires a match for both filter types. If neither is enabled, all requests are considered a match.