- 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 application server. 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.
- VHostMatchingCompat (zero or one attribute for each Config)
- This attribute specifies that the port number is to be used for
virtual host matching. The following values can be specified:
- true if matching is to be done physically
by using the port number for which the request was received.
- false if matching is to be done logically
using the port number contained in the host header.
The default is false.
- AppServerPortPreference
- This attribute is used to specify which port number the Application
Server should use to build URI's for a sendRedirect. The following
values can be specified:
- hostHeader if the port number from the host
header of the HTTP request coming in is to be used.
- webserverPort if the port number on which
the Web server received the request is to be used.
The default is hostHeader.
- 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 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.
- 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.
- ChunkedResponse
- Specifies whether the plug-in should chunk the response to the
client when a Transfer-Encoding : Chunked response header is present
in the response.
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:
- true if the plug-in is to chunk the response
to the client when a Transfer-Encoding : Chunked response header is
present in the response.
- false if the response is not to be chunked.
false is the default.
- IISPluginPriority
- Specifies the priority in which the IIS Web server loads the WebSphere Web server plug-in. You can specify
one of the following values for this attribute:
The default value is High.
NOTES:
- The IIS Web server uses this value during startup. Therefore,
the Web server must be restarted before this change will take effect.
- The default value of High ensures that all requests are handled
by the WebSphere Web server plug-in before they are handled by any
other filter/extensions. If problems occur while using a priority
of Medium or Low, you will have to rearrange the order or change the
priority of the interfering filter/extension.
- TrustedProxyEnable
Permits the web server
plug-in to interface with the proxy servers and load balancers that
are listed for the TrustedProxyList custom property. When this property
is set to true, the proxy servers and load balancers in this trusted
proxy list can set values for the $WSRA and $WSRH internal headers.
$WSRA is the IP address of the remote host, which is typically the
browser, or an internal address that is obtained by Network Address
Translation (N.A.T.). $WSRH is the host name of the remote host. This
header information enables the web server plug-in to interface with
that specific proxy server or load balancer. ![[jul2010]](../../deltaend.gif)
jul2010
When you use this custom
property you must also use the TrustedProxyList custom property to
specify a list of trusted proxy servers and load balancers. Also,
you must clear the Remove special headers check box on the Request
Routing panel within the administrative console. For more information,
see the documentation on web server plug-in request routing properties. ![[jul2010]](../../deltaend.gif)
jul2010
- TrustedProxyList
Specifies a comma delimited list of all
proxy servers or load balancers that have permission to interface
with this Web server plug-in. This property must be used in conjunction
with the TrustedProxyEnable=true custom property
setting. If the TrustedProxyEnable custom property is set to false,
this list is ignored.
- SSLConsolidate
Specifies whether the Web server plug-in
is to compare the setup of each new SSL transport with the setup of
other SSL transports that are already defined in the configuration
file. When you set this property to true, and
the plug-in determines that the keyring and CertLabel values specified
for the new SSL transport match the values specified for an already
defined SSL transport, the plug-in uses the existing SSL environment
instead of creating a new SSL environment. Creating fewer SSL environments
means that the plug-in requires less memory, and the plug-in initialization
time decreases, thereby optimizing your overall GSkit environment.
- Log
- The log describes the 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, you might specify the following:
<Log LogLevel="Error" Name="/log_directory/filename"/>
- Name (exactly one attribute for each Log)
- The fully qualified path to the log file to which the plug-in
will write error messages.
Note: A date and
time stamp, and the process ID are no longer appended to the name
you specify for the plug-in log file. Therefore, a single Web server
plug-in log file is created instead of multiple log files that are
distinguished by date. This behavior is different from Version 5.x
behavior.
- LogLevel (zero or one attribute for each Log)
- The level of detail of the log messages that the plug-in should
write to the 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.
- Debug. All of the critical steps performed in processing requests
are logged.
- Detail. All of the information about requests and responses 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 file system to fill up very quickly. A Trace setting
should never be used in a normally functioning environment as it adversely
affects performance.
- Property Name="esiEnable" Value="true/false"
- Used to enable or disable the Edge Side Include (ESI) processor.
If the ESI processor is disabled, the other ESI elements in this file
are ignored.
Value can be set to true or false.
By default, the ESI processor is enabled (set to true).
- Property Name="esiMaxCacheSize" Value="integer"
- An integer specifying, in 1K byte units, the maximum size of the
cache. The default maximum size of the cache is 1024K bytes (1 megabyte).
If the cache is full, the first entry to be evicted from the cache
is the entry that is closest its expiration time.
- Property Name="ESIInvalidationMonitor" Value="true/false"
- Used to indicate whether or not the ESI processor should receive
invalidations from the Application Server.
Value can
be set to true or false.
By default, this property is set to false.
- Property Name="FIPSEnable" Value="true/false"
- Used to indicate whether or not the Federal Information Processing
Standard (FIPS) is enabled for making secure (SSL) connections to
the Application Server. This property should be set to true, if FIPS
is enabled on the Application Server..
Value can
be set to true or false.
By default, this property is set to false.
- Property Name="PluginInstallRoot" Value="C:\IBM\WebSphere\Plugins"
- This property provides the install path for the plugin. This is
mandatory if using the Global Security Kit (GSKit) because WebSphere Application Server supports the local
install of the GSKit instead of a global install. The attribute value
is set to a fully qualified path to the plugin install root.
Supported
names recognized by the transport are keyring, stashfile, and password.
By default, this property is set to none.
- ServerCluster (one or more elements for each Config)
- 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 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 CloneSeparatorChange="false"
LoadBalance="Round Robin" Name="Cluster1"
PostSizeLimit="10000000" RemoveSpecialHeaders="true"
RetryInterval="60">
<Server
CloneID="BA36BEC1EB243D8B000000E4000000030926301B"
ConnectTimeout="0" ExtendedHandshake="false"
LoadBalanceWeight="2" MaxConnections="0"
Name="SY1_ClusterMember1" WaitForContinue="false">
<Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="9084" Protocol="http"/>
<Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="0" Protocol="https">
<Property Name="Keyring" value="/WebSphere/V6R0M0/DeploymentManager/etc/
plugin-key.kdb"/>
<Property Name="Stashfile" value=""/WebSphere/V6R0M0/DeploymentManager/etc/
plugin-key.sth"/>
<Property Name="certLabel" Value="selfsigned"/>
</Transport>
</Server>
<Server CloneID="BA36BED017FDF40E000000E4000000030926301B"
ConnectTimeout="0" ExtendedHandshake="false"
LoadBalanceWeight="2" MaxConnections="0"
Name="SY1_ClusterMember2" WaitForContinue="false">
<Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="9085" Protocol="http"/>
<Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="0" Protocol="https">
<Property Name="Keyring" value="/WebSphere/V6R0M0/DeploymentManager/etc/
plugin-key.kdb"/
<Property Name="Stashfile" value="/WebSphere/V6R0M0/DeploymentManager/etc/
plugin-key.sth"/>
<Property Name="certLabel" Value="selfsigned"/>
</Transport>
</Server>
<PrimaryServers>
<Server Name="Server Name="SY1_ClusterMember1"/>
<Server Name="Server Name="SY1_ClusterMember2"/>
</PrimaryServers>
</ServerCluster>
For transitioning users: The Web server plug-in for the z/OS HTTP Server, Version
5.3, uses an SSL interface that is different from the SSL interface
that was used in previous versions of this plug-in. The SSL connections
between the plug-in for the z/OS HTTP Server, Version 5.3, and an
application server now works exactly the same way as the SSL connections
between an IBM HTTP Server powered by Apache, and an application server.
The values specified for the keyring and stashfile elements in the
plugin-cfg.xml are no longer ignored, and are not impacted by the
SSL environment that is set up in the z/OS HTTP Server, Version 5.3.
z/OS
PTF UK35083 includes the SSL interface change for the z/OS HTTP Server,
Version 5.3, that corresponds to this Web server plug-in change. Therefore,
this PTF must be applied to your system before the new Web server
plug-in SSL interface can function properly.
You must also
include the SSLMode multi option in the httpd.conf
file for the z/OS HTTP Server, Version 5.3. If the SSLMode
multi option is not specified in the httpd.conf file,
or if you do not have z/OS PTF UK35083 applied to your system, you
might receive error message IMW0584W, that indicates that the SSL
mode that is specified for the HTTP Server is not compatible with
the SSL mode for the Web server plug-in that is used with the z/OS
HTTP Server, Version 5.3. In either of these situations, unpredictable
results might occur
For the Web server plug-ins for both the
z/OS HTTP Server, Version 5.3 and the IBM HTTP
Server on z/OS powered by Apache:
- If you use a kdb file with a stashfile in the hierarchical file
system (HFS), specify both the Property Name=keyring and
the Property Name=stashfile elements, as shown
in the preceding example.
- If you use a System Authorization Facility (SAF) keyring, instead
of a kdb file, you must create the following two custom plug-in properties
from the administrative console: KeyringLocation and StashfileLocation.
Set the KeyringLocation to the directory location of the SAF keyring,
and set StashfileLocation to "" (null). See Web server plug-in configuration properties for instructions
on how to create KeyringLocation and StashfileLocation from the administrative
console.
The following is an example for using the SAF keyring:
<Transport Hostname="appserver.example.com" Port="9443" Protocol="https">
<Property name="KeyringLocation" value="safkeyring:///SAF_keyring_name"/>
<Property Name="StashfileLocation" value=""/>
</Transport>
trns
- Name (exactly one attribute for each ServerCluster)
- The logical or administrative name to be used for this group of
servers.
- LoadBalance (zero or one attribute for each ServerCluster)
- The default load balancing type is Round Robin.
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.
- IgnoreAffinityRequests (zero or one attribute for each ServerCluster)
- Specifies whether the plug-in ignores the number of affinity
requests made to a server when selecting servers based on the Round
Robin algorithm. The value can be true or false.
If the value is set to false, the number of
affinity requests made is also taken into account in the server selection
process.
The default value is true, which
means the number of affinity requests made are not used in the Round
Robin algorithm.
- RetryInterval (zero or one attribute for each ServerCluster)
- 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.
- RemoveSpecialHeaders (zero or one attribute for each ServerCluster)
- The plug-in adds special headers to the request before it is forwarded
to the application server. 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.
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 (zero or one attribute for each ServerCluster)
- 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 application server
configurations so that an application server separates clone IDs with
the plus character as well.
The value can be true or false.
- PostSizeLimit (zero or one attribute for each ServerCluster)
- The maximum number of kilobytes (1024 byte blocks) of request
content allowed in order for the plug-in to attempt to send the request
to an application server. If a request is received that is greater
than this size, the plug-in fails the request. The default value is
-1 bytes, which indicates that there is no limit for the post size.
- PostBufferSize (zero or one attribute for each ServerCluster)
- Specifies, in kilobytes, the maximum buffer size that is used
when the content of an HTTP request is read. If the application server
that initially receives a request cannot process that request, the
data contained in this buffer is sent to another application server
in an attempt to have that application server process the request.
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.
- Server (one or more elements for each ServerCluster)
- A WebSphere Application Server 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 application server running on either the local machine or
a remote machine.
- Name (exactly one attribute for each Server)
- The administrative or logical name for the server.
- CloneID (zero or one attribute for each Server)
- 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.
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 (zero or one attribute for each Server)
- Specifies whether to use the HTTP 1.1 100 Continue support before
sending the request content to the application server. 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 application server before sending the request
content because it is a performance hit.
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 (zero or one attribute for each Server)
- Specifies the weight associated with this server when the plug-in
does weighted Round Robin load balancing. The starting value for a
server can be any integer between 0 and 20.
However, zero should be specified only for a server that is shut down.
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.
- ConnectTimeout (zero or one attribute for each Server)
- 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 (as long as two 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
default value is 5 seconds.
- ExtendedHandshake (zero or one attribute for each Server)
- The ExtendedHandshake attribute is used when a proxy firewall
is between the plug-in and the application server. In such a case,
the plug-in is not failing over, as expected.
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.
- MaxConnections (one element for each Server)
- The MaxConnections attribute is used to specify the maximum number
of
pending ![[jul2010]](../../deltaend.gif)
jul2010
connections to an Application Server
that can be flowing through a Web server process at any point in time. For
example, assuming that:
- The application server is fronted by 5 nodes that are running
an IBM HTTP Server.
- Each node starts 2 processes.
- The MaxConnections attribute is set to 50.
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.)
This attribute is not necessary
on the z/OS platform. The z/OS controller 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 (one or more elements for each Server)
- The transport for reading and writing requests to a particular
WebSphere Application Server instance.
The transport provides the information needed to determine the location
of the application server 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.
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.
- Hostname (exactly one attribute for each Transport)
- The host name or IP address of the machine on which the WebSphere
application server instance is running.
- Port (exactly one attribute for each Transport)
- The port on which the WebSphere Application Server instance is listening.
- Protocol (exactly one attribute for each Transport)
- The protocol to use when communicating over this transport --
either HTTP or HTTPS.
- Property (zero, one, or more elements for each Transport)
- 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. for example, the portion of the plugin_cfg.xml
file containing these elements might look like the following:
<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"/>
Note: The
default password for viewing the plugin-key.kdb file using iKeyMan
is WebAS.
- Name (exactly one attribute for each Property)
- The name of the Property being defined. Supported names recognized
by the transport are keyring, stashfile, and password.
Avoid trouble: 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.
gotcha
- Value (exactly one attribute for each Property)
- The value of the Property being defined.
- ServerIOTimeout
- The ServerIOTimeout attribute of a server element enables the
plug-in to set a time out value, in seconds, for sending requests
to and reading responses from the application server.
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.
If a value is not set
for the ServerIOTimeout attribute, the plug-in, by default, uses blocked
I/O to write request to and read response from the application server
until the TCP connection times out. For example, if you specify:
<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. The
default value is 60 seconds.
Important: ![[jul2010]](../../delta.gif)
The ServerIOTimeout limits the amount
of time the plug-in will wait for each individual read or write operation
to return. ServerIOTimeout
does not represent a timeout for
the overall request.
![[jul2010]](../../deltaend.gif)
jul2010
- ClusterAddress (zero or one element for each ServerCluster)
- 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 application server.
Important: If you include a ClusterAddress tag, you must include
the Name attribute on that tag. The plug-in uses the name attribute
to associate the cluster address with the correct host and port. If
you do not specify the Name attribute, the plug-in assigns the cluster
address the name that is specified for the server that is using the
same host and port.
<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.
- PrimaryServers (zero or one element for each server cluster)
- Specifies a list of servers to which the plug-in routes requests
for this cluster. If a list of primary servers is not specified,
the plug-in routes requests to servers defined for the server cluster.
- BackupServers (zero or one element for each server cluster)
- Specifies a list of servers to which requests should be sent to
if all servers specified in the primary servers list are unavailable.
The plug-in does not load balance across the backup servers, 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 application
server.
- 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 (exactly one attribute for each VirtualHostGroup)
- The logical or administrative name to be used for this group of
virtual hosts.
- VirtualHost (one or more elements for each VirtualHostGroup)
- The name used for a virtual or real machine used to determine
if incoming requests should be handled by WebSphere Application Server
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 asterisk
(*) for either the host name, port, or both.
- Name (exactly one attribute for each VirtualHost)
- 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
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.
- UriGroup
- A group of URIs that will be specified on the HTTP request line.
The same application server 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 (exactly one attribute for each UriGroup)
- The logical or administrative name for this group of URIs.
- Uri (one or more elements for each UriGroup)
- The virtual path to the resource that will be serviced by WebSphere Application Server. Each URI specifies
the incoming URLs that need to be handled by the application server.
You can use a wildcard in these definitions.
- Name (exactly one attribute for each Uri)
- The actual string that should be specified in the HTTP request
line in order to match successfully with this URI. You can use a wildcard
within the URI definition. You can specify rules such as *.jsp or
/servlet/* to be handled by WebSphere Application Server. When you assemble
your application, 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 a URI having <Uri Name="Web_application_URI/servlet/*"> is
generated.
- AffinityCookie (zero or one attribute for each Uri)
- The name of the cookie the plug-in should use when trying to determine
if the inbound request has session affinity. The default value is JSESSIONID.
See the description
of the CloneID attribute for additional session affinity information.
- AffinityURLIdentifier (zero or one attribute for each Uri)
- The name of the identifier the plug-in should use when trying
to determine if the inbound request has affinity specified in the
URL to a particular clone. The default value is jsessionid.
See the description
of the CloneID attribute for additional session affinity information.
- Route
- A request routing rule by which the plug-in will determine if
an incoming request should be handled by a WebSphere application
server.
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 (zero or one attribute for each Route)
- 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 application server.
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 (zero or one attribute for each Route)
- 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 application
server.
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 (exactly one attribute for each Route)
- The cluster to which to send request that successfully match the
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
- This element is used to 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" loggingEnabled="true"
rmEnabled="false" traceLevel="PERF_DEBUG">
- armEnabled (zero or one attribute for RequestMetrics)
- This attribute indicates whether the ARM 4 agent is enabled in
the plug-in. When it is set to true, the ARM
4 agent will be called.
Note: For the SunOne (iPlanet)
Web server the following directive must be included in the obj.conf
file to enable ARM 4 support:
AddLog fn="as_term"
If this
directive is not included, the arm_stop procedure will never be called.
- loggingEnabled (exactly one attribute for RequestMetrics)
- This attribute indicates whether request metrics logging is enabled
in the plug-in. When it is set to true and the
traceLevel is not set to NONE, the request response time (and other
request information) is logged. When it is set to false,
there is no request logging. 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.
- rmEnabled (exactly one attribute for RequestMetrics)
- This attribute indicates whether or not the request metrics is
enabled in the plug-in. When it is set to true,
the plug-in request metrics will look at the filters and log the request
trace record in the plug-in log file. This action is performed if
a request passes the filters. When this attribute is set to false,
the rest of the request metrics attributes will be ignored..
- traceLevel (exactly one attribute for RequestMetrics)
- When rmEnabled is true, this attribute indicates
how much information is logged. When this attribute is set to NONE,
no request logging is performed. When this attribute is not set to NONE,
and loggingEnabled is set to true, the request
response time (and other request information) is logged when the request
is done.
- filters (zero, one, or two attributes for RequestMetrics)
- When rmEnabled is true, the filters control
which requests are traced.
- enable (exactly one attribute for each filter)
- When enable is true, the type of filter is
on and requests must pass the filter.
- type (exactly one attribute for each filter)
- 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.
- filterValues (one or multiple attribute for each filter)
- The filterValues show the detailed filter information.
- value (exactly one attribute for each filterValue)
- Specifies the filter value for the corresponding filter type.
This could be either a client IP address or a URI.
- enableESIToPassCookies
- Specifies whether to allow forwarding of session cookies to WebSphere Application Server when processing
ESI include requests. If the value is set to true,
this custom property is enabled. If the value is set to false,
the custom property is disabled. By default, the value is set to false.
- GetDWLMTable
- Specifies whether to allow a newly spawned plug-in process to
proactively request a partition table from WebSphere Application Server
before it handles any HTTP requests. This custom property is used
only when memory-to-memory session management is configured. If the
value is set to true, this custom property
is enabled. If the value is set to false, the
custom property is disabled. By default, the value is set to false.