338 lines
39 KiB
HTML
338 lines
39 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<LINK rel="stylesheet" type="text/css" href="../../../rzahg/ic.css">
|
||
|
|
|
||
|
|
<title>The plugin-cfg.xml file</title>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<BODY>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<SCRIPT LANGUAGE="Javascript" SRC="../../../rzahg/synch.js" TYPE="text/javascript"></SCRIPT>
|
||
|
|
|
||
|
|
<h4><a name="admpluginxml"></a>The plugin-cfg.xml file</h4>
|
||
|
|
|
||
|
|
<p>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 <a href="admpluginsamp.htm">Sample plugin-cfg.xml file</a>.</p>
|
||
|
|
|
||
|
|
<p><strong>Config</strong>
|
||
|
|
<br>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:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>IgnoreDNSFailures attribute</strong>
|
||
|
|
<br>This attribute pecifies whether the plug-in ignores DNS failures within a configuration when the plug-in starts. Valid values are <tt>true</tt> and <tt>false</tt>. The default value is false.</p>
|
||
|
|
<ul>
|
||
|
|
<li>If the value is <tt>true</tt>, the plug-in ignores DNS failures within a configuration and starts successfully if at least one server in each ServerCluster is able to resolve the host name. Any server for which the host name can not be resolved is marked unavailable for the duration of the configuration. The plug-in does not make additional attempts to resolve the host name. If a DNS failure occurs, a log message is written to the plug-in log file and the plug-in initialization continues.</li>
|
||
|
|
<li>If the value is <tt>false</tt>, the Web server does not start if any DNS failures are detected.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>RefreshInterval attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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.</p></li>
|
||
|
|
<li><p><strong>ASDisableNagle attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>.</p></li>
|
||
|
|
<li><p><strong>IISDisableNagle attribute</strong>
|
||
|
|
<br>This attribute specifies whether to disable nagle algorithm on Microsoft Internet Informations Services (IIS). By default, nagle algorithm is enabled. Valid values are <tt>true</tt> and <tt>false</tt>.</p></li>
|
||
|
|
<li><p><strong>AppServerPortPreference attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<ul>
|
||
|
|
<li>If you specify a value of webserverPort, the server uses the port number from the host header of the incoming HTTP request.</li>
|
||
|
|
<li>If you specify a value of hostHeader, the server uses the port number on which the Web server received the request.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>VHostMatchingCompat attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>.</p>
|
||
|
|
<ul>
|
||
|
|
<li>If you specify a value of <tt>true</tt>, matching is done based on the port number for which the request was received.</li>
|
||
|
|
<li>If you specify a value of <tt>false</tt>, matching is done based on the port number contained in the host header.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>ResponseChunkSize attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>For a chunk size of <em>n</em> KB, the plug-in reads responses according to these conditions:</p>
|
||
|
|
<ul>
|
||
|
|
<li>If the content length of the response body is unknown, a buffer size of N kilobytes is allocated and the body is read in N kilobyte size chunks, until the entire body is read.</li>
|
||
|
|
<li>If the content length is known, then a buffer size of either content length or N (whichever is less) is used to read the response body.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>AcceptAllContent attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>.</p>
|
||
|
|
<ul>
|
||
|
|
<li>Specify a value of <tt>true</tt> if content is to be expected and read for all requests</li>
|
||
|
|
<li>Specify a value of <tt>false</tt> if content is to be expected and read for only POST and PUT requests.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>ChunkedResponse attribute</strong>
|
||
|
|
<br>This attribute specifies whether or not the plug-in chunks the response to the client when <tt>Transfer-Encoding : Chunked response header</tt> 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 <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>.</p>
|
||
|
|
<ul>
|
||
|
|
<li>If you specify a value of <tt>true</tt>, the plug-in chunks the response to the client.</li>
|
||
|
|
<li>If you specify a value of <tt>false</tt>, the plug-in does not chunk the response.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>IISPluginPriority attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p><strong>NOTES:</strong>
|
||
|
|
<ul>
|
||
|
|
<li>The IIS Web server uses this value during startup. If you change this attribute, you must restart the Web server for the change to take effect.</li>
|
||
|
|
<li>The default value of High ensures that all requests are handled by the Web server plug-in before they are handled by any other filters or extensions. If you experience problems when you set the value to Medium or Low, rearrange the priorities or change the priority of the other filters or extensions.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
|
||
|
|
<li><p><strong>Log element</strong>
|
||
|
|
<br>The Log element describes the location and level of log messages that the plug-in writes.</p>
|
||
|
|
<p>The Log element can include these attributes:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>LogLevel attribute</strong>
|
||
|
|
<br>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:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Trace. All of the steps in the request process are logged in detail.</li>
|
||
|
|
<li>Stats. The server selected for each request and other load balancing information relating to request handling is logged.</li>
|
||
|
|
<li>Warn. All warning and error messages resulting from abnormal request processing are logged.</li>
|
||
|
|
<li>Error. Only error messages resulting from abnormal request processing are logged.</li>
|
||
|
|
</ul>
|
||
|
|
<p>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:</p>
|
||
|
|
<pre><Log LogLevel="Error" Name=
|
||
|
|
"/QIBM/UserData/WebAS51/Base/myInstance/logs/http_plugin.log"/></pre>
|
||
|
|
<p><strong>Note:</strong> The Trace level generates a large amount of messages. It is recommended that you use the Trace level only for troubleshooting purposes.</p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
|
||
|
|
<li><p><strong>Property Name="esiEnable" Value="true/false" element</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. The default value is <tt>true</tt>.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong>Property Name="esiMaxCacheSize" Value="integer" element</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong>Property Name="ESIInvalidationMonitor" Value="true/false" element</strong>
|
||
|
|
<br>This element indicates whether or not the ESI processor receives invalidations from the application server. Valid values are <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong>ServerCluster element</strong>
|
||
|
|
<br>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:</p>
|
||
|
|
<pre><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></pre>
|
||
|
|
|
||
|
|
<p>The ServerCluster element can include these attributes and elements:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>Each ServerCluster element includes exactly one Name attribute. This attribute specifies the logical or administrative name for this group of servers.</p></li>
|
||
|
|
<li><p><strong>LoadBalance attribute</strong>
|
||
|
|
<br>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 <tt>Round Robin</tt> and <tt>Random</tt>. The default value is <tt>Round Robin</tt>. 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.</p></li>
|
||
|
|
<li><p><strong>RetryInterval attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>RemoveSpecialHeaders attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>Valid values are <tt>true</tt> and <tt>false</tt>. The default value is <tt>true</tt>. Setting the attribute to false introduces a potential security exposure by not removing headers from incoming requests.</p></li>
|
||
|
|
<li><p><strong>CloneSeparatorChange attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt></p></li>
|
||
|
|
<li><p><strong>PostSizeLimit attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>Server element</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p><a name="svrlmnt"></a>The Server element can contain these attributes and elements:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>Each Server element includes exactly one Name attribute. This attribute specifies the administrative or logical name for the server.</p></li>
|
||
|
|
<li><p><strong><a name="cloneid"></a>CloneID attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</p></li>
|
||
|
|
<li><p><strong>WaitForContinue attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. 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.</p></li>
|
||
|
|
<li><p><strong>LoadBalanceWeight attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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.</p></li>
|
||
|
|
<li><p><strong>ConnectTimeout attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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.</p></li>
|
||
|
|
<li><p><strong>ExtendedHandshake attribute</strong>
|
||
|
|
<br>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 <tt>true</tt>, 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.</p>
|
||
|
|
<p>Valid values are <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>.</p></li>
|
||
|
|
<li><p><strong>MaxConnections attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<ul>
|
||
|
|
<li>The application server is fronted by 5 nodes that are running an IBM HTTP Server Web server instance.</li>
|
||
|
|
<li>Each node starts 2 processes.</li>
|
||
|
|
<li>The MaxConnections attribute is set to 50.</li>
|
||
|
|
</ul>
|
||
|
|
<p>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.</p></li>
|
||
|
|
<li><p><strong>Transport element</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>The Transport element can include these attributes and elements:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Hostname attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>Port attribute</strong>
|
||
|
|
<br>Each Transport element includes exactly one Port attribute. This attribute specifies the port on which the application server instance listens for incoming requests.</p></li>
|
||
|
|
<li><p><strong>Protocol attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>Property element</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>The Property element can include these attributes:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>Value attribute</strong>
|
||
|
|
<br>Each Property element includes exactly one Value attribute. This attribute specifies the value of the Property.</p></li>
|
||
|
|
</ul><p>For example, this section of the plugin_cfg.xml file might look like this:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
<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>
|
||
|
|
</pre></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>ClusterAddress element</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>Th ClusterAddress element can include the same attributes and elements that the Server element uses. For a description of these attributes and elements, see <a href="#svrlmnt">Server element</a>.</p></li>
|
||
|
|
<li><p><strong>PrimaryServers element</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>BackupServers element</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>VirtualHostGroup element</strong>
|
||
|
|
<br>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:</p>
|
||
|
|
<pre><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></pre>
|
||
|
|
<p>The VirtualHostGroup element includes these attributes and elements:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>The VirtualHostGroup includes exactly one Name attribute. This attribute specifies the logical or administrative name to be used for this group of virtual hosts.</p></li>
|
||
|
|
<li><p><strong>VirtualHost element</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>The VirtualHost element includes this attribute:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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).</p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>UriGroup element</strong>
|
||
|
|
<br>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:</p>
|
||
|
|
<pre><UriGroup Name="Uris">
|
||
|
|
<Uri Name="/servlet/snoop"/>
|
||
|
|
<Uri Name="/webapp/*"/>
|
||
|
|
<Uri Name="*.jsp"/>
|
||
|
|
</UriGroup></pre>
|
||
|
|
<p>The UriGroup element can include these attributes and elements:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>The UriGroup element contains exactly one Name attribute. This attribute specifies the logical or administrative name for this group of URIs.</p></li>
|
||
|
|
<li><p><strong>Uri element</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>The Uri element can include these attributes:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>Name attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>When you assemble your application, you can specify <strong>File Serving Enabled</strong> or <strong>Serve servlets by classname</strong>. If you specify <strong>File Serving Enabled</strong>, then only a wildcard URI is generated for the Web application, regardless of any explicit servlet mappings. If you specify <strong>Serve servlets by classname</strong>, then this URI is generated: <Uri Name="Web_application_URI/servlet/*">.</p></li>
|
||
|
|
<li><p><strong>AffinityCookie attribute</strong>
|
||
|
|
<br>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 <a href="#cloneid">CloneID attribute</a>.</p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>Route element</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<p>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:</p>
|
||
|
|
<pre><Route VirtualHostGroup="Hosts" UriGroup="Uris" ServerCluster="servers/></pre>
|
||
|
|
<p>The Route element can contain these attributes:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>VirtualHostGroup attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>UriGroup attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
<li><p><strong>ServerCluster attribute</strong>
|
||
|
|
<br>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.</p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>RequestMetrics element</strong>
|
||
|
|
<br>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:</p>
|
||
|
|
<pre><RequestMetrics armEnabled="false" newBehavior="false"
|
||
|
|
rmEnabled="false" traceLevel="PERF_DEBUG"></pre>
|
||
|
|
<p>The RequestMetrics element can include these attributes and elements:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>armEnabled attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>. In WebSphere Application Server - Express Version 5.1, the plug-in ignores this attribute.</p>
|
||
|
|
<p><strong>Note:</strong> To enable ARM 4 support for the SunOne (iPlanet) Web server, you must include the <tt>AddLog fn="as_term"</tt> directive in the obj.conf file.</li>
|
||
|
|
<li><p><strong>loggingEnabled attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. When this value is set to <tt>true</tt> and the traceLevel attribute is not set to NONE, request metrics data is logged. When this value is set to <tt>false</tt>, 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 <tt>true</tt>. In WebSphere Application Server - Express Version 5.1, the plug-in ignores this attribute.</p></li>
|
||
|
|
<li><p><strong>rmEnabled attribute</strong>
|
||
|
|
<br>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 <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>.</p>
|
||
|
|
<ul>
|
||
|
|
<li>If the value for this attribute is <tt>true</tt>, the plug-in Request Metrics filters requests. For requests that pass the filters, the plug-in writes the trace record in the plug-in log file.</li>
|
||
|
|
<li>If the value for this attribute is <tt>false</tt>, Request Metrics is disabled, and the other attributes and elements for the RequestMetrics element are ignored.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
<li><p><strong>traceLevel attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<ul>
|
||
|
|
<li>A value of NONE specifies that no trace information is logged.</li>
|
||
|
|
<li>A value of HOPS specifies that trace information is logged only for major process hops.</li>
|
||
|
|
<li>A value of PERF_DEBUG specifies that information is logged in addition to major hops.</li>
|
||
|
|
<li>A value of DEBUG specifies that a full detailed trace is recorded.</li>
|
||
|
|
</ul>
|
||
|
|
<p>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.</p></li>
|
||
|
|
<li><p><strong>filters element</strong>
|
||
|
|
<br>The RequestMetrics element includes no more than two filters elements. The filters control which requests are traced.</p>
|
||
|
|
<p>Each filters element includes these attributes and elements:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>enable attribute</strong>
|
||
|
|
<br>Each filters element includes exactly one enable attribute. Valid values are <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>. If the value is <tt>true</tt>, the type of filter is enabled, and RequestMetrics traces requests that match a filterValues element.</p></li>
|
||
|
|
<li><p><strong>type attribute</strong>
|
||
|
|
<br>Each filters element includes exactly one type attribute. Valid values are SOURCE_IP and URI.</p></li>
|
||
|
|
<li><p><strong>filterValues element</strong>
|
||
|
|
<br>The filters element includes one or more filterValues elements. The filterValues show the detailed filter information.</p>
|
||
|
|
<p>The filterValues element includes these attributes:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p><strong>enable attribute</strong>
|
||
|
|
<br>Each filterValues element includes exactly one enable attribute. Valid values are <tt>true</tt> and <tt>false</tt>. The default value is <tt>false</tt>. If the value is <tt>true</tt>, the filter is enabled, and RequestMetrics traces requests that match the value attribute.</p></li>
|
||
|
|
<li><p><strong>value attribute</strong>
|
||
|
|
<br>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.</p>
|
||
|
|
<ul>
|
||
|
|
<li>For the SOURCE_IP filter type, requests are filtered based on the client IP address. You can specify a mask for an IP address using the asterisk (*). If the asterisk is used, the asterisk must always be the last character of the mask, as in these examples: 127.0.0.*, 127.0.*, 127*. For performance reasons, the pattern matches character by character, until either an asterisk is found in the filter, a mismatch occurs, or the filters are found as an exact match.</li>
|
||
|
|
<li>For the URI filter type, requests are filtered based on the URI of the incoming HTTP request. The rules for pattern matching are the same as matching SOURCE_IP address filters.</li>
|
||
|
|
</ul>
|
||
|
|
<p>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.</p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|