There are two types of plugin-cfg.xml files: application-centric and topology-centric.
An application-centric file has an application that is mapped to both Web server and application server definitions. Changes that you make to the plug-in using the administrative console persist to the plugin-cfg.xml file upon generation.
The plugin-cfg.xml file includes the following elements and attributes. Unless indicated otherwise, each element and attribute can only be specified once within the plugin-cfg.xml file.
This element starts the WebSphere HTTP plug-in configuration file. It can include one or more of the following elements and attributes.
In a development environment in which changes are frequent, a lower setting than the default setting of 60 is preferable. In production, a higher value than the default is preferable because updates to the configuration will not occur so often. If the plug-in reload fails for some reason, a message is written to the plug-in log file and the previous configuration is used until the plug-in configuration file successfully reloads. If you are not seeing the changes you made to your plug-in configuration, check the plug-in log file for indications of the problem.
The value can be true or false.
The value can be true or false.
The default is false.
The default is hostHeader.
The ResponseChunkSize attribute lets you specify the maximum chunk size to use when reading the response body. For example, Config ResponseChunkSize="N">, where N equals the chunk size in kilobytes.
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. 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.
The default chunk size is 64k.
False is the default.
This attribute only applies to the IIS, IPlanet, and Domino Web servers. The IBM HTTP Server automatically handles the chunking of the response to the client.
You can specify one of the following values for this attribute:
false is the default.
The default value is High.
For example, you might specify the following:
<Log LogLevel="Error" Name="/opt/WebSphere/AppServer60/logs/http_plugin.log"/>
If the file does not exist then it will be created. If the file already exists then it will be opened in append mode and the previous plug-in log messages will remain.
If a LogLevel is not specified for the Log element, the default value Error is used.
Be careful when setting the level to Trace. A lot of messages are logged at this level which can cause the disk space to fill up very quickly. A Trace setting should never be used in a normally functioning environment as it adversely affects performance.
Value can be set to true or false. By default, the ESI processor is enabled (set to true).
Value can be set to true or false. By default, this property is set to false.
Value can be set to true or false. By default, this property is set to false.
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 will load balance across the defined servers using either a Round Robin or a Random algorithm. The default is Round Robin.
Following 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="c:/WebSphere/AppServer/keys/keyring.kdb"/> <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/> </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="c:/WebSphere/AppServer/keys/keyring.kdb"/> <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/> </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="c:/WebSphere/AppServer/keys/keyring.kdb"/> <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/> </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="c:/WebSphere/AppServer/keys/keyring.kdb"/> <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/> </Transport> </Server> <PrimaryServers> <Server Name="Server1"/> <Server Name="Server2"/> </PrimaryServers> <BackupServers> <Server Name="Server3"/> </BackupServers> </ServerCluster>
The Round Robin implementation has a random starting point. The first server will be picked randomly. Round Robin will be used to pick servers from that point forward. This implementation ensures that in multiple process based Web servers, all of the processes don't start up by sending the first request to the same Application Server.
The value can be true or false. Setting the attribute to false introduces a potential security exposure by not removing headers from incoming requests.
The value can be true or false.
This option improves the availability of the plug-in. The requests in flight having content are now retried if the selected application server is not responding. If the value is set to zero, the requests having content are not buffered and are not retried. The default value is 64.
This attribute is used in conjunction with session affinity. When this attribute is set, 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 clone IDs are found, and a match is made to the value specified for this attribute, then the request is sent to this server rather than load balanced across the cluster.
If you are not using session affinity then it is best to remove these clone IDs from the configuration because there is added request processing in the plug-in when these are set. If clone IDs are not in the plug-in then it is assumed that session affinity is not on and the request is load balanced across the cluster.
This property will be ignored for POST requests in order to prevent a failure from occurring if the Application server closes a connection because of a keep alive time-out.
Enable this function (set to true) when configuring the plug-in to work with certain types of proxy firewalls.
The LoadBalanceWeight for each server is decremented for each request processed by that server. After the weight for a particular server in a server cluster reaches zero, only requests with session affinity are routed to that server. When all servers in the cluster reach a weight of zero, the weights for all servers in the cluster are reset, and the algorithm starts over.
When a server is shut down, it is recommended that you set the weight for that server to zero. The plug-in can then reset the weights of the servers that are still running, and maintain proper load balancing.
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 (as long as 2 minutes depending on the platform) and allows the plug-in to mark the server 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.
The plug-in marks a server as down when the connect() fails. However, when a proxy firewall is in between the plug-in and the application server, the connect() will succeed, even though the back end application server is down. This causes the plug-in to not failover correctly to other application servers.
The plug-in performs some handshaking with the application server to ensure that it is started before sending the request. This enables the plug-in to failover in the event the application server is down.
The value can be true or false.
In this example, the application server could potentially get up to 500 connections. (You take the number of nodes, 5, multiply it by the number of processes, 2, and then multiply that number by the number specified for the MaxConnections attribute, 50, for a total of 500 connections.)
By default, MaxConnections is set to -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.
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 will be performed to determine the appropriate transport to use to send the request to the application server.
<Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS"> <Property Name="keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/> <Property Name="stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/> <Property Name="password" value="WebAS"/>
If you set the ServerIOTimeout attribute to a positive value, this attempt to contact the server ends when the timeout occurs. However, the server is not considered to be down and future requests are still sent to the server on which the timeout occurred..
If you set the ServerIOTimeout attribute to a negative value, the server is considered to be down whenever a timeout occurs, and no future requests are sent to the server on which the timeout occurred.
<Server Name="server1" ServerIOTimeout=300>
In this situation, if an application server stops responding to requests, the plug-in waits 300 seconds (5 minutes) before timing out the TCP connection. Setting the ServerIOTimeout attribute to a reasonable value enables the plug-in to time out the connection sooner, and transfer requests to another application server when possible.
When selecting a value for this attribute, remember that sometimes it might take a couple of minutes for an application server to process a request. Setting the value of the ServerIOTimeout attribute too low could cause the plug-in to send a false server error response to the client.
<ClusterAddress Name="MyClusterAddr"> <Transport Hostname="192.168.1.2" Port="9080" Protocol="HTTP"/> <Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS"> </ClusterAddress>
If a request comes in that does not have affinity established, the plug-in routes it to the cluster address, if defined. If affinity has been established, then the plug-in routes the request directly to the clone, bypassing the cluster address entirely. If no cluster address is defined for the server cluster, then the plug-in load balances across the servers in the primary servers list.
Following 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 value is a host name or IP address and port combination, separated by a colon.
You can configure the plug-in to route requests to the application server based on the incoming HTTP Host header and port for the request. The Name attribute specifies what those combinations are.
You can use a wildcard for this attribute. The only acceptable solutions are either an asterisk (*) for the host name, an asterisk for the port, or an asterisk for both. An asterisk for both means that any request will match this rule. If no port is specified in the definition the default HTTP port of 80 is assumed.
Following 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>
See the description of the CloneID attribute for additional session affinity information.
See the description of the CloneID attribute for additional session affinity information.
The route definition is the central element of the plug-in configuration. It specifies how the plug-in will handle requests based on certain characteristics of the request. The route definition contains the other main elements: 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.
Following is an example of this element:
<Route VirtualHostGroup="Hosts" UriGroup="Uris" ServerCluster="servers/>
It is possible to omit this from the route definition. If it is not present then every request will match during the virtual host match portion of route determination.
It is possible to omit this from the route definition. If it is not present than every request will match during the URI match portion of route determination.
The cluster that should be used to handle this request. If both the URI and the virtual host matching is successful for this route then the request is sent to one of the servers defined within this cluster.
Following is an example of this element:
<RequestMetrics armEnabled="false" loggingEnabled="true" rmEnabled="false" traceLevel="PERF_DEBUG">
AddLog fn="as_term"If this directive is not included, the arm_stop procedure will never be called.
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.
If both 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.