Network Deployment (Distributed operating systems), v8.0 > Reference > Configuration file descriptions


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 admin 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 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. Use the admin 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. We can update the global plugin-cfg.xml file using the admin console or running the GenPluginCfg command for all of the clusters in a cell. However, 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.

The file can include one or more of the following elements and attributes. 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 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.


IISDisableNagle (Windows)

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

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

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:

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

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

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.

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

The default value is false.


IISPluginPriority

Priority in which the IIS web server loads the WebSphere web server plug-in. Specify one of the following values for this attribute:

The default value is High.

The IIS web server uses this value during startup. Therefore, restart the web server before this change takes 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 or extensions. If problems occur when using a priority of Medium or Low, rearrange the order or change the priority of the interfering filter or 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. 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, clear the Remove special headers check box on the Request Routing panel within the admin console. 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

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.


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.

If you are using an IBM HTTP Server, you can use the sslstash program to create a file that contains this password. In this situation, you 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: 

<Log LogLevel="Error" Name="/opt/WebSphere/AppServer60/logs/http_plugin.log"/>



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 Federal Information Processing Standard (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 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.


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. 

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

The z/OS PTF UK35083 package includes the SSL interface change for the z/OS HTTP Server, v5.3, that corresponds to this web server plug-in change. Therefore, 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, v5.3. The SSLMODE=ON option is not supported in v7.0 or higher.

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 the 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 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, v5.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 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 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 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 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">


Implement a web server plug-in

+

Search Tips   |   Advanced Search