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.

We can create two types of plugin-cfg.xml files:

WAS traditional

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 plugin-cfg.xml. The Config element is required.


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


Ignore 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 is false, meaning DNS failures cause the web server not to start.


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 we made to your 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.


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.

(Windows) IISDisableNagle

Disable the nagle algorithm on Microsoft Internet Information Services (IIS). By default, the nagle algorithm is enabled.

The value can be true or false.


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

The default is false.


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

The default is hostHeader.


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.


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 is True.


Use chunks in the respons 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. Specify one of the following for this attribute:

The default is false.


Allow forwarding of session cookies to WAS 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 created plug-in process to proactively request a partition table from WAS 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. Set the GetDWLMTable property using the check box on the administrative console rather than using the custom property.


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 we use this custom property, we must also use the TrustedProxyList custom property to specify a list of trusted proxy servers and load balancers. Also, we must clear the Remove special headers check box on the Request Routing panel within the administrative console. See documentation on web server plug-in request routing properties.


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.


Compare the setup of each new SSL transport with the setup of other SSL transports that are already defined in the configuration file. When 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, thus optimizing your overall GSkit environment.



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.



Password for the SSL co-processor with which the module, specified for the SSLPKCSDriver custom property, is interfacing. If we are using 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.


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, we might specify the following line of code:


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 disabled with its value set to false.

Property Name="esiMaxCacheSize" Value="integer"

Maximum size of the cache. In 1 KB units. 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"

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"

Federal Information Processing Standard (FIPS) is enabled for making SSL connections to the application server. Set 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"

The installation path for the plug-in. This property is mandatory if using the Global Security Kit (GSKit) because WAS 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.


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


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.

VirtualHostGroup element and associated elements and attributes:


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. UriGroup element and associated elements and attributes:


Request routing rule by which the plug-in determines if an incoming request must be handled by WAS. 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:


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:

WAS Liberty

We can generate plugin-cfg.xml for our Liberty server by calling the WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean from within the same Java SDK as the server.

Topology-centric (global)

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.

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

Use the administrative console to set these properties for each web server definition. Any manual changes we make to the plug-in configuration file for each web server are overridden whenever the file is regenerated.

Deprecated feature: Topology-centric, or global, plug-in configuration is deprecated. Instead, use application-centric configuration as described in Implement a web server plug-in. For any existing topology-centric configuration, we 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, we must delete...

...before updating the global plugin-cfg.xml file. If we do not delete config/cells/plugin-cfg.xml, 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.

Because the GenPluginCfg command runs within its own JVM instead of the WebSphere Application Server JVM, the command might not be able to access other class files. If we encounter this problem when running the GenPluginCfg command, we can instead run the httpPluginManagement.py script to generate application-centric plug-in configuration. This script uses wsadmin to initiate the plug-in generation. For more information, see httpPluginManagement.py script.