plugin-cfg.xml file

 

Overview

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.

 

<Config...> (required)

First element. Can include one or more of the following elements and attributes.

IgnoreDNSFailures= Specifies whether the plug-in ignores DNS failures within a configuration when starting. When set to true, 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 life of the configuration. No attempts to resolve the host name are made later on during the routing of requests. If a DNS failure occurs, a log message is written to the plug-in log file and the plug-in initialization continues rather than causing the Web server not to start. The default value is false, meaning DNS failures cause the Web server not to start.

RefreshInterval= The time interval (in seconds) at which the plug-in should check the configuration file to see if updates or changes have occurred. The plug-in checks the file for any modifications that have occurred since the last time the plug-in configuration was loaded.

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.

ASDisableNagle= Specifies whether the user wants to disable nagle algorithm for the connection between the plug-in and the appserver. By default, nagle algorithm is enabled.

The value can be true or false.

IISDisableNagle= Specifies whether the user wants to disable nagle algorithm on Microsoft Internet Informations Services (IIS). By default, nagle algorithm is enabled.

The value can be true or false.

ResponseChunkSize= The plug-in reads the response body in 64k chunks until all of the response data is read. This approach causes a performance problem for requests whose response body contains large amounts of data.

The ResponseChunkSize attribute allows the users to 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.

AcceptAllContent= 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. You can specify one of the following values for this attribute:

  • True if content is to be expected and read for all requests

  • False if content only is only to be expected and read for POST and PUT requests.

False is the default.

<Log...> Location and level of log messages that are written by the plug-in. If a log is not specified within the configuration file, then, in some cases, log messages are written to the Web server error log.

For example... 

<Log LogLevel="Error" 
     Name="/opt/WebSphere/AppServer50/logs/http_plugin.log"/>

Name= The fully qualified path to the log file to which the plug-in will write error messages. Exactly one attribute for each 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.

LogLevel The level of detail of the log messages that the plug-in should write to the log. Zero or one attribute for each Log. You can specify one of the following values for this attribute...

  • Trace. All of the steps in the request process are logged in detail.

  • Stats. The server selected for each request and other load balancing information relating to request handling is logged.

  • Warn. All warning and error messages resulting from abnormal request processing are logged.

  • Error. Only error messages resulting from abnormal request processing are logged.

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.

<ServerCluster...> A group of servers that are generally configured to service the same types of requests. One or more elements for each Config

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"/>

    </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"/>

    </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"/>

    </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"/>

    </Server>

    <PrimaryServers>
        <Server Name="Server1"/>
        <Server Name="Server2"/>
    </PrimaryServers>

    <BackupServers>
        <Server Name="Server3"/>
        </BackupServers>
    </ServerCluster>

Name The logical or administrative name to be used for this group of servers. Exactly one attribute for each ServerCluster

LoadBalance The default load balancing type is Round Robin. Zero or one attribute for each 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.

RetryInterval An integer specifying the length of time that should elapse from the time that a server is marked down to the time that the plug-in will retry a connection. The default is 60 seconds. Zero or one attribute for each ServerCluster

RemoveSpecialHeaders The plug-in adds special headers to the request before it is forwarded to the appserver. These headers store information about the request that will need to be used by the application. By default the plug-in will remove these headers from incoming requests before adding the headers it is supposed to add. Zero or one attribute for each ServerCluster.

The value can be true or false. Setting the attribute to false introduces a potential security exposure by not removing headers from incoming requests.

CloneSeparatorChange= Some pervasive devices cannot handle the colon character (:) used to separate clone IDs in conjunction with session affinity. This attribute for the server group tells the plug-in to expect the plus character (+) as the clone separator. You must change appserver configurations so that an application server separates clone IDs with the plus character as well.

Zero or one attribute for each ServerCluster.

The value can be true or false.

PostSizeLimit The maximum number of bytes of request content allowed in order for the plug-in to attempt to send the request to an appserver. If a request is received that is greater than this size, the plug-in fails the request. The default value is 10 million bytes. Zero or one attribute for each ServerCluster

Server A WAS instance that is configured to handle requests routed to it given the routing rules of the plug-in configuration. The Server should correspond to an appserver running on either the local machine or a remote machine. One or more elements for each ServerCluster

Name The administrative or logical name for the server. Exactly one attribute for each Server

CloneID If this unique ID is present in the HTTP cookie header of a request (or the URL if using URL rewriting), the plug-in routes the request to this particular server, provided all other routing rules are met. If a CloneID is not specified in the Server, then session affinity is not enabled for this server.

Zero or one attribute for each Server

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.

WaitForContinue Specifies whether to use the HTTP 1.1 100 Continue support before sending the request content to the appserver. Possible attribute values are true or false. The default value is false; the plug-in does not wait for the 100 Continue response from the appserver before sending the request content because it is a performance hit.

Zero or one attribute for each Server

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.

LoadBalanceWeight The weight associated with this server when the plug-in does weighted Round Robin load balancing. The algorithm for this attribute decrements all weights within the server cluster until all weights reach zero. Once a particular server's weight reaches zero, no more requests are routed to that server until all 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.

Zero or one attribute for each Server)

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.

ConnectTimeout The ConnectTimeout attribute of a Server element enables the plug-in to perform non-blocking connections with the appserver. Non-blocking connections are beneficial when the plug-in is unable to contact the destination to determine if the port is available or unavailable.

Zero or one attribute for each Server.

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.

ExtendedHandshake The ExtendedHandshake attribute is used when a proxy firewall is between the plug-in and the appserver. In such a case, the plug-in is not failing over, as expected.

Zero or one attribute for each Server.

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 appserver 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 appserver is down.

The value can be true or false.

MaxConnections The MaxConnections attribute is used to specify the maximum number of pending connections to an Application Server that can be flowing through a Web server process at any point in time.

One element for each Server.

For example, assuming that...

  • The appserver is fronted by 5 nodes that are running an IHS Web server.

  • Each node starts 2 processes.

  • The MaxConnections attribute is set to 50.

In this example, the appserver 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.)

This attribute is not necessary on the z/OS platform. The z/OS control region, working in conjunction with WLM, handles new connections dynamically.

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.

<Transport...> The transport for reading and writing requests to a particular WebSphere appserver instance. The transport provides the information needed to determine the location of the appserver to which the request will be sent. If the Server has multiple transports defined to use the same protocol, the first one will be used. One or more elements for each Server

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 appserver.

Hostname The host name or IP address of the machine on which the WebSphere application server instance is running. Exactly one attribute for each Transport

Port The port on which the WebSphere appserver instance is listening. Exactly one attribute for each Transport

Protocol The protocol to use when communicating over this transport -- either HTTP or HTTPS. Exactly one attribute for each Transport

<Property...> When the Protocol of the Transport is set to HTTPS, use this element to supply the various initialization parameters, such as password, keyring and stashfile. Zero, one, or more elements for each Transport

Name The name of the Property being defined. Supported names recognized by the transport are keyring, stashfile, and password. Exactly one attribute for each Property

Note that password is the only name that can be specified for the WebSphere HTTP Plug-in for z/OS. keyring, and stashfile, if specified, will be ignored.

Value The value of the Property being defined. Exactly one attribute for each Property

<ClusterAddress...> A ClusterAddress is like a Server element in that you can specify the same attributes and elements as for a Server element. The difference is that you can only define one of them within a ServerCluster. Use a ClusterAddress when you do not want the plug-in to perform any type of load balancing because you already have some type of load balancer in between the plug-in and the appserver.

Zero or one element for each ServerCluster)

If a request comes in that does not have affinity established, the plug-in routes it to the ClusterAddress, if defined. If affinity has been established, then the plug-in routes the request directly to the clone, bypassing the ClusterAddress entirely. If no ClusterAddress is defined for the ServerCluster, then the plug-in load balances across the PrimaryServers list.

<PrimaryServers...> Lists defined 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 servers defined for the ServerCluster.

Zero or one element for each ServerCluster

<BackupServers...> Lists servers to which requests should be sent to if all servers specified in the PrimaryServers list are unavailable. The plug-in does not load balance across the BackupServers list but traverses the list in order until no servers are left in the list or until a request is successfully sent and a response received from an appserver.

Zero or one element for each ServerCluster.

<VirtualHostGroup...> A group of virtual host names that will be specified in the HTTP Host header. Enables you to group virtual host definitions together that are configured to handle similar types of requests.

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>

Name The logical or administrative name to be used for this group of virtual hosts. Exactly one attribute for each VirtualHostGroup

VirtualHost The name used for a virtual or real machine used to determine if incoming requests should be handled by WAS or not. Use this element to specify host names that will be in the HTTP Host header which should be seen for requests that need to be handled by the application server. You can specify specific host names and ports that incoming requests will have or specify an * for either the host name, port, or both. One or more elements for each VirtualHostGroup

Name The actual name that should be specified in the HTTP Host header in order to match successfully with this VirtualHost.

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 appserver based on the incoming HTTP Host header and port for the request. The Name attribute specifies what those combinations are.

Use a wildcard for this attribute. The only acceptable solutions are either an * for the host name, a * for the port, or a * for both. A * 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. Exactly one attribute for each VirtualHost

UriGroup A group of URIs that will be specified on the HTTP request line. The same appserver must be able to handle the URIs. The route will compare the incoming URI with the URIs in the group to determine if the application server will handle the request.

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>

Name The logical or administrative name for this group of URIs. Exactly one attribute for each UriGroup

Uri The virtual path to the resource that will be serviced by WebSphere Application Server. One or more elements for each UriGroup. Each URI specifies the incoming URLs that need to be handled by the appserver. Use a wildcard in these definitions.

Name The actual string that should be specified in the HTTP request line in order to match successfully with this URI. Use a wildcard within the URI definition. You can specify rules such as *.jsp or /servlet/* to be handled by WAS. When you assemble your application, if you specify File Serving Enabled then only a wildcard URI is generated for the web application (.war), regardless of any explicit servlet mappings. If you specify Serve servlets by classname then a URI having <Uri Name="Web_application_URI/servlet/*"> is generated. Exactly one attribute for each Uri

AffinityCookie The name of the cookie the plug-in should use when trying to determine if the inbound request has session affinity to a particular clone. The default value is JSESSIONID. (See the description of the CloneID attribute for additional session affinity information.)

Zero or one attribute for each Uri

Route A request routing rule by which the plug-in will determine if an incoming request should be handled by a WebSphere appserver.

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/>

<VirtualHostGroup...> The group of virtual hosts that should be used in route determination. The incoming host header and server port are matched to determine if this request should be handled by the appserver.

Zero or one attribute for each Route.

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.

UriGroup The group of URIs to use for determining the route. The incoming URI for the request is matched to the defined URIs in this group to determine if this request should be handled by the appserver.

Zero or one attribute for each Route

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.

ServerCluster The cluster to which to send request that successfully match the route. Exactly one attribute for each Route

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.

<RequestMetrics...> Determine if request metrics is enabled, and how to filter the requests based on the Internet protocol (IP) and Uniform Resource Identifiers (URI) filters when request metrics is enabled.

Following is an example of this element 

<RequestMetrics armEnabled="false" 
                newBehavior="false" 
                rmEnabled="false" 
                traceLevel="PERF_DEBUG">

armEnabled This attribute is currently ignored by the plug-in. It is for the future usage. Zero or one attribute for RequestMetrics)

newBehavior This attribute is currently ignored by the plug-in. It is for the future usage. Zero or one attribute for RequestMetrics
rmEnabled This attribute indicates whether or not the request metrics is enabled in the plug-in. When it is true, the plug-in request metrics will look at the filters and log the request trace record in the plug-in log file. This is performed if a request passes the filters. Exactly one attribute for RequestMetrics
traceLevel When rmEnabled is true, this attribute indicates how much information is logged. When it is NONE, there is no request logging. When it is not NONE, the request response time (and other request information) is logged when the request is done. Exactly one attribute for RequestMetrics
filters When rmEnabled is true, the filters control which requests are traced. Zero, one, or two attributes for RequestMetrics.
enable When enable is true, the type of filter is on and requests must pass the filter. Exactly one attribute for each filter
type There are two types of filters: SOURCE_IP (for example, client IP address) and URI. For the SOURCE_IP filter type, requests are filtered based on a known 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, for example 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.

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.

Exactly one attribute for each filter

filterValues The filterValues show the detailed filter information.

One or multiple attribute for each filter.

value Specifies the filter value for the corresponding filter type. This could be either a client IP address or a URI. Exactly one attribute for each filterValue

 

See Also

Manually editing the plug-in configuration
Configuring Web server plug-ins