InfoCenter Home >
6: Administer applications >
6.6: Tools and resources quick reference >
6.6.45: Administering WebSphere plug-ins for Web servers (overview) >
6.6.45.0: Properties of WebSphere plug-ins for Web servers
6.6.45.0: Properties of WebSphere plug-ins for Web servers
The working or active versions of the HTTP plugin-cfg.xml file reside in the
directory:
product_installation_root/config
The plugin-cfg.xml file includes the following elements and attributes:
Config (exactly one)
This element starts the WebSphere HTTP plug-in configuration file.
It contains all other elements and attributes of the configuration.
This section resembles the following in the file:
<Config IgnoreDNSFailures="true" RefreshInterval="240">
- VHostMatchingCompat (zero or one attribute for each Config)
- This attribute decides the port number used for Virtual Host matching. When this attribute is enabled,
matching is done physically by using the port number for which the request was received. Otherwise, matching
is done logically by using the port number from the host header. The default is false. The value can be true
or false.
- IgnoreDNSFailures (zero or one attribute for each Config)
- 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
ServerGroup is able to resolve the host name. The server is marked unavailble
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.
- Refresh interval (zero or one attribute for each Config)
- The time interval (in seconds) at which the plug-in should check the
configuration file to see if updates or changes have occured. 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 then 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 config reloads successfully.
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.
- Log (zero or one element for each Config)
- The log describes the location and level of log messages that should
be written by the plug-in. If a Log is not specified within the Config,
then in some cases log messages will be written to the Web server error log.
This section resembles the following in the file:
<Log LogLevel="Error" Name="/opt/WebSphere/AppServer/logs/native.log"/>
- Name (exactly one attribute for each Log)
- The fully qualified path to the log file to which the plug-in will
write error messages.
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 (zero or one attribute for each Log)
- The level of detail of the log messages that the plug-in should
write to the log. Values for this attribute are one of the following:
If a LogLevel is not specified with the Log, then the default value is Error.
Trace allows you to see the steps in the request process in detail.
Warn and Error means that only information about abnormal request processing
will be logged.
Be careful when setting the level to Trace. A lot of error 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 affects performance.
- ServerGroup (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 server group 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.
This section resembles the following in the file:
<ServerGroup 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>
</ServerGroup>
- Name (exactly one attribute for each ServerGroup)
- The logical or administrative name to be used for this group of servers.
- LoadBalance (zero or one attribute for each ServerGroup)
- The default load balancing type is Round Robin.
The Round Robin implementation has a random starting point. This means
that the first server picked will be done so randomly and then round robin
will be used from that point forward. This is so 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 (zero or one attribute for each ServerGroup)
- 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 ServerGroup)
- 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 ServerGroup)
- 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 ServerGroup)
- The maximum number of bytes 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 10 million bytes.
- Server (one or more elements for each ServerGroup)
- 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 the 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 this attribute
then the request is sent to this server rather than load balanced across
the server group.
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 server group.
- 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.
Enable this function (set to true) when configuring the plug-in to work
with certain types of proxy firewalls.
- ConnectTimeout (zero or one attribute for each Server)
- The ConnectTimeout attribute of a Server element allows 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 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 sucessful 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
server group.
- 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 keyring and
stashfile.
- 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.
- Value (exactly one attribute for each Property)
- The value of the Property being defined.
- ClusterAddress (zero or one element for each ServerGroup)
- 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 ServerGroup.
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.
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 ServerGroup, then the plug-in load balances across the
PrimaryServers list.
- VirtualHostGroup (zero, one, or more elements for each Config)
- 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.
This section resembles the following in the file:
<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 VirtualHost)
- 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 a
* 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 a * 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.
- UriGroup (zero, one or more elements for each Config)
- 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.
This section resembles the following in the file:
<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 inboud request has affinity to a particular clone. The default value
is JSESSIONID.
- Route (one or more elements for each Config)
- 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 ServerGroup, 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 ServerGroup defined in this route.
This section resembles the following in the file:
<Route VirtualHostGroup="Hosts" UriGroup="Uris" ServerGroup="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.
- ServerGroup (exactly one attribute for each Route)
- The server group to which to send request that successfully match the route.
The server group 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 server group.
|
|