+

Search Tips   |   Advanced Search

plugin-cfg.xml file

The plugin-cfg.xml file contains configuration information that determines how the web server plug-in forwards requests.


Full profile

For the WAS full profile, 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 we make to the plug-in using the console persist to the plugin-cfg.xml file upon generation.

A topology-centric file represents everything defined in the environment. Typically, this plugin-cfg.xml file is used when we do not have web servers defined. Consider the following rules when 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.

Avoid trouble: Use the console to set these properties for each web server definition. Any manual changes made to the plug-in configuration file for each web server are overridden whenever the file is regenerated.gotcha

Avoid trouble: We can update the global plugin-cfg.xml file using the 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 we 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


Liberty profile

We can generate the plugin-cfg.xml file for the Liberty profile server by calling the WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean from within the same Java SDK as the server. For more information, see Configure a web server plug-in for the Liberty profile.


Elements and attributes

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


Config

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


IgnoreDNSFailures

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 we are not seeing the changes you made to the plug-in configuration, check the plug-in log file for indications of the problem.

Also, on Microsoft, UNIX, and Linux platforms, we can disable automatic reload by setting RefreshInterval to -1 in plugin-cfg.xml.


ASDisableNagle

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.


IISDisableNagle

Whether the user wants to disable the nagle algorithm on Microsoft Internet Information Services (IIS). By default, the nagle algorithm is enabled.

The value can be true or false.


VHostMatchingCompat

The port number is to be used for virtual host matching. Specify one of the following values:

The default value is false.


AppServerPortPreference

Port number the application server uses to build URIs for a sendRedirect() method. The following values can be specified:

The default value is hostHeader.


ResponseChunkSize

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

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

The default value is True.


ChunkedResponse

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.

We can specify one of the following values for this attribute:

The default value is false.

(iseries) OS400ConvertQueryStringToJobCCSID

Whether the query string for an HTTP request is converted to the Code Page of the IBM HTTP Server Job or EBCDIC Code Page 37 for internal processing. The default value is false, which causes the query string to be converted to EBCDIC Code Page 37.


TrustedProxyEnable

Permits the web server plug-in to interface with the proxy servers and load balancers listed for the TrustedProxyList custom property. When 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 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. We 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

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 set 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 the overall GSkit environment.


SSLPKCSDriver

Fully qualified name of the loadable module that interfaces with an optional SSL co-processor. The fully qualified name must include the directory path and the module name.


SSLPKCSPassword

Password for the SSL co-processor with which the module, specified for the SSLPKCSDriver custom property, is interfacing.

For an IBM HTTP Server, we can use the sslstash program to create a file containing this password. In this situation, we can specify the fully-qualified name of that file, instead of the actual password, as the value for this custom property.


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:
(dist)(iseries)


(zos)


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.

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

Whether the ESI processor receives invalidations from the application server.

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


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

Whether the FIPS is enabled for making SSL connections to the application server. Set this property to true, if FIPS is enabled on the application server.

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


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

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.
(dist)(iseries) 

<ServerCluster Name="Servers">
<ClusterAddress Name="ClusterAddr">
<Transport Hostname="192.168.1.2" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS">
<Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
<Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
</Transport>
</ClusterAddress>
<Server Name="Server1">
<Transport Hostname="192.168.1.3" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.3" Port="9443" Protocol="HTTPS">
<Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
<Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
</Transport>
</Server>
<Server Name=Server2>
<Transport Hostname="192.168.1.4" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.4" Port="9443" Protocol="HTTPS">
<Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
<Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
</Transport>
</Server>
<Server Name="Server3">
<Transport Hostname="192.168.1.5" Port="9080" Protocol="HTTP"/>
<Transport Hostname="192.168.1.5" Port="9443" Protocol="HTTPS">
<Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
<Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
</Transport>
</Server>
<PrimaryServers>
<Server Name="Server1"/>
<Server Name="Server2"/>
</PrimaryServers>
<BackupServers>
<Server Name="Server3"/>
</BackupServers>
</ServerCluster>

(zos) 
<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>

(zos)

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 versions of this plug-in prior to version 7. 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 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 the system before the new web server plug-in SSL interface can function properly.

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

If the SSLMode multi option is not specified in the httpd.conf file, or if we do not have the z/OS PTF UK35083 package applied to the system, you might receive error message IMW0584W. This message indicates the SSL mode, which is specified for the HTTP Server, is not compatible with the SSL mode for the web server plug-in 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:


VirtualHostGroup

Specifies a group of virtual host names specified in the HTTP Host header. Use this property to group virtual host definitions together 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 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.

Use the information 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 defined in this route.

See the following example of this element:


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

Reference topic