plugin-cfg.xml file

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 by using the administrative console persist to the plugin-cfg.xml file upon generation.

A topology-centric file represents everything that is defined in the environment. Typically, this plugin-cfg.xml file is used when you do not have web servers defined. Consider the following rules when you want to update a topology-centric plugin-cfg.xml file: The design of this file and its related function enable the product to support different types of configurations. For example, web server definitions might not exist. In addition, many web server plug-in properties, such as RefreshInterval, LogLevel, and the Edge Side Include (ESI) processor properties, can be updated manually only. Those values must be maintained through each iteration.

The plugin-cfg.xml file includes the following elements and attributes. Unless indicated otherwise, you can specify each element and attribute only once within the plugin-cfg.xml file.

Avoid trouble Avoid trouble: Use the administrative console to set these properties for each web server definition. Any manual changes you make to the plug-in configuration file for each web server are overridden whenever the file is regenerated.gotcha
Avoid trouble Avoid trouble: You can update the global plugin-cfg.xml file using the administrative console or running the GenPluginCfg command for all of the clusters in a cell. However, you must delete the config/cells/plugin-cfg.xml file before you update the global plugin-cfg.xml file. If you do not delete the config/cells/plugin-cfg.xml file, only the new properties and their values are added to the global plugin-cfg.xml file. Any updates to existing plug-in property values are not added to the global plugin-cfg.xml file.gotcha

Config

This element, which is required, starts the HTTP plug-in configuration file.

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 server cluster is able to resolve the host name. Any server for which the host name cannot be resolved is marked unavailable for the life of the configuration. No attempts to resolve the host name are made 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

Specifies the time interval, in seconds, at which the plug-in checks 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 do 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 the nagle algorithm for the connection between the plug-in and the application server. By default, the nagle algorithm is enabled.

The value can be true or false.

VHostMatchingCompat

Specifies that the port number is to be used for virtual host matching. Specify one of the following values:
  • 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 by using the port number contained in the host header.

The default value is false.

AppServerPortPreference

Specifies which port number the application server uses to build URIs for a sendRedirect() method. 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 value is hostHeader.

ResponseChunkSize

Specifies the maximum chunk size to use when reading the response body. For example, specify Config ResponseChunkSize="N">, where N equals the chunk size in kilobytes.

The plug-in reads the response body in 64 K 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.

If the content length of the response body is unknown, a buffer size of N KBs is allocated and the body is read in N KB 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 64 K.

AcceptAllContent

Specifies whether 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 expected and read for all requests
  • False if content is only expected and read for POST and PUT requests.

The default value is True.

ChunkedResponse

Specifies whether the plug-in must use chunks the response to the client when a Transfer-Encoding: Chunked response header is present in the response.

This attribute applies to the IIS, Oracle iPlanet, and Lotus Domino® web servers only. 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:

The default value is false.

IISPluginPriority

Specifies the priority in which the IIS web server loads the WebSphere® web server plug-in. Specify one of the following values for this attribute:
  • High
  • Medium
  • Low

The default value is High.

Supported configurations Supported configurations: The IIS web server uses this value during startup. Therefore, you must restart the web server before this change takes effect. sptcfg
Supported configurations Supported configurations: 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 or extensions. If problems occur when using a priority of Medium or Low, you must rearrange the order or change the priority of the interfering filter or extension.sptcfg

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. The $WSRA internal header 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.). The $WSRH internal header 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.

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.

TrustedProxyList

Specifies a comma delimited list of all proxy servers or load balancers that have permission to interface with this web server plug-in. You must use this property 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

Describes the location and level of log messages that are written by the plug-in. If a log element 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 line of code:

<Log LogLevel="Error" Name="/log_directory/file_name"/>

Property Name="esiEnable" Value="true/false"

Enables or disables the Edge Side Include (ESI) processor. If the ESI processor is disabled, the other ESI elements in this file are ignored.

You can set Value to true or false. By default, the ESI processor is enabled with its value set to true.

Property Name="esiMaxCacheSize" Value="integer"

Specifies, in 1 KB units, the maximum size of the cache. The default maximum size of the cache is 1024 KB (1 MB). If the cache is full, the first entry deleted from the cache is the entry that is closest its expiration time.

Property Name="ESIInvalidationMonitor" Value="true/false"

Specifies whether the ESI processor receives invalidations from the application server.

You can set Value to true or false. By default, this property is set to false.

Property Name="FIPSEnable" Value="true/false"

Specifies whether the Federal Information Processing Standard (FIPS) is enabled for making Secure Sockets Layer (SSL) connections to the application server. Set this property to true, if FIPS is enabled on the application server.

You can set Value value to true or false. By default, this property is set to false.

Property Name="PluginInstallRoot" Value="C:\IBM\WebSphere\Plugins"

Specifies the installation path for the plug-in. This property is mandatory if using the Global Security Kit (GSKit) because WebSphere Application Server supports the local installation of the GSKit instead of a global installation. The attribute value is set to a fully qualified path to the plug-in installation root.

Supported names recognized by the transport are keyring, stashfile, and password. By default, this property is set to none.

ServerCluster

Specifies a group of servers that are generally configured to service the same types of requests. Specify one or more clusters for each configuration.

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 load balances across the defined servers by using either a Round Robin or a Random algorithm. The default algorithm is Round Robin.

The following code is an example of a ServerCluster element.

[Updated in July 2011]
<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="safkeyring:///mzjring1"/"/>
<Property Name="Stashfile" value=""/>
<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="safkeyring:///mzjring1"/>
<Property Name="Stashfile" value=""/>
<Property Name="certLabel" Value="selfsigned"/>
</Transport>
</Server>
<PrimaryServers>
<Server Name="SY1_ClusterMember1"/>
<Server Name="SY1_ClusterMember2"/>
</PrimaryServers>
</ServerCluster>
[Updated in July 2011]
jul2011
For transitioning users For transitioning users: The web server plug-in for the IBM HTTP Server for z/OS, 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 IBM HTTP Serve for z/OS, Version 5.3 and an application server now works 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 file are no longer ignored and are not affected by the SSL environment that is set up in the IBM HTTP Server for z/OS, Version 5.3.trns

The z/OS PTF UK35083 package includes the SSL interface change for the z/OS HTTP Server, Version 5.3, that corresponds to this web server plug-in change. Therefore, you must apply this PTF to your system before the new web server plug-in SSL interface can function properly.

[Updated in July 2011] You must also include the SSLMODE=MULTI option in the httpd.conf file for the IBM HTTP Server for z/OS, Version 5.3. The SSLMODE=ON option is not supported in Version 7.0 or higher. [Updated in July 2011]

jul2011

If the SSLMode multi option is not specified in the httpd.conf file, or if you do not have the z/OS PTF UK35083 package applied to your system, you might receive error message IMW0584W. This message indicates that the SSL mode, which is specified for the HTTP Server, is not compatible with the SSL mode for the web server plug-in that is used with the IBM HTTP Server for z/OS, Version 5.3. In either of these situations, unpredictable results might occur.

For the web server plug-ins for both the IBM HTTP Server for z/OS, 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.
    Avoid trouble Avoid trouble: [Updated in July 2011] The format of the values you specify for these elements is different from what you specified in earlier versions of the product. [Updated in July 2011]
    jul2011
    gotcha
  • 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
    Specify the directory location of the SAF keyring as the value for this property. When you save this configuration change, this directory location becomes the value of the keyring property in the plugin-cfg.xml file.
    StashfileLocation
    Specify "" (null) as the value for this property. When you save this configuration change, "" (null) becomes the value of the stashfile property in the plugin-cfg.xml file

    See Web server plug-in configuration properties for instructions on how to create KeyringLocation and StashfileLocation from the administrative console.

    Use the following example for the SAF keyring:
    <Transport Hostname="appserver.example.com" Port="9443" Protocol="https">
    <Property name="keyring" value="safkeyring:///SAF_keyring_name"/>
    <Property Name="stashfile" value=""/>
    </Transport>

VirtualHostGroup

Specifies a group of virtual host names that are specified in the HTTP Host header. Use this property to group virtual host definitions together that are configured to handle similar types of requests.

The following example shows a VirtualHostGroup 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>

UriGroup

Specifies a group of URIs that are specified on the HTTP request line. The same application server must be able to handle the URIs. The route compares the incoming URI with the URIs in the group to determine if the application server handles the request.

The following example shows a UriGroup element and associated elements and attributes:

<UriGroup Name="Uris">
<Uri Name="/servlet/snoop"/>
<Uri Name="/webapp/*"/>
<Uri Name="*.jsp"/>
</UriGroup>

Route

Specifies a request routing rule by which the plug-in determines if an incoming request must be handled by WebSphere Application Server.

The route definition is the central element of the plug-in configuration. It specifies how the plug-in handles 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 is sent on to the ServerCluster element that is defined in this route.

See the following example of this element:

<Route VirtualHostGroup="Hosts" UriGroup="Uris" ServerCluster="servers/>

RequestMetrics

Used to determine whether request metrics are enabled, and how to filter the requests based on the Internet Protocol (IP) and Uniform Resource Identifiers (URI) filters when request metrics are enabled.

See the following example of this element:

<RequestMetrics armEnabled="false"  loggingEnabled="true"
			rmEnabled="false" traceLevel="PERF_DEBUG">



Related tasks
Implementing a web server plug-in
Reference topic Reference topic    

Terms of Use | Feedback

Last updatedLast updated: Sep 19, 2011 3:08:41 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=matt&product=was-nd-zos&topic=rwsv_plugincfg
File name: rwsv_plugincfg.html