Intelligent Management: controlling the generation of plugin-cfg.xml
We can override the default attribute values of the plugin-cfg.xml file that is automatically generated by the on demand router.
The following elements are formatted as...
-
com.ibm.ws.odr.plugincfg.<element>.<attributeName>
...where <element> is the name of the configuration file keyword that denotes the element containing an attribute, and <attributeName> is the name of the attribute located within that element. Configure the elements as JVM system properties...
- Servers > On demand routers > on_demand_router > Java and Process Management > Process definition > Java Virtual Machine > Custom properties > New
Config
This element starts the plug-in configuration file. It can include one or more of the following elements and attributes.
- com.ibm.ws.odr.plugincfg.config.ASDisableNagle
- Disable Nagle's algorithm for the connection between the plug-in and the server.
Default is false.
- com.ibm.ws.odr.plugincfg.config.AcceptAllContent
- Specifies whether or not we 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:
- True if the content is to be expected, and read for all requests.
- False if the content is to be expected and read only for POST and PUT requests.
Default is false.
Default is true.
- com.ibm.ws.odr.plugincfg.config.AppServerPortPreference
- Port number used to build URI's for a sendRedirect.
Default is HostHeader.
- com.ibm.ws.odr.plugincfg.config.ChunkedResponse
- Specifies whether the plug-in groups the response to the client when a Transfer-Encoding :
Chunked response header is present in the response.
Specify one of the following for this attribute:
- True if the plug-in is to chunk the response to the client when a Transfer-Encoding : Chunked response header is present in the response.
- false if the response is not to be chunked.
Default is false.
- com.ibm.ws.odr.plugincfg.config.IISDisableNagle
- Disable nagle algorithm.
Default is false.
- com.ibm.ws.odr.plugincfg.config.IISPluginPriority
- Priority in which the Web server loads the plug-in. Specify one of the following for this attribute:
- High
- Medium
- Low
Default is High.
- com.ibm.ws.odr.plugincfg.config.IgnoreDNSFailures
- Specifies if the plug-in ignores DNS failures within a configuration when started. When set to true, the plug-in ignores DNS failures within a configuration and starts successfully if at
least one server in each ServerCluster resolves the host name. Any server for which the host name is not resolved is marked unavailable for the life of the configuration. The host name is not
resolved later 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 continues initializing instead of the Web server not
starting.
Default is false.
- com.ibm.ws.odr.plugincfg.config.RefreshInterval
- The time interval, in seconds, at which the plug-in should check the configuration file for
updates or changes. The plug-in checks the file for any modifications that occur since the plug-in
configuration was loaded.
Default is 60. In a development environment in which changes are frequent, set the time interval to less than 60 seconds. In production, set a higher value than the default, because updates to the configuration do not occur as often. If the plug-in reload is not successful, the plug-in log file contains a message, and the previous configuration is used until the plug-in configuration file successfully reloads. Refer to the plug-in log file for more information if an error occurs.
- com.ibm.ws.odr.plugincfg.config.ResponseChunkSize
- The plug-in file reads the response body in 64k chunks until all of the response data is read,
which causes a performance problem for requests whose response body contains large amounts of data.
Use this attribute to specify the maximum chunk size to use when reading the response body. For example, Config ResponseChunkSize="N">, where N equals the chunk size in kilobytes.
If the content length of the response body is unknown, a buffer size of N kilobytes is allocated and the body is read in N kilobyte size chunks, until the entire body is read. If the content length is known, then a buffer size of either content length or N is used to read the response body.
The default chunk size is 64k.
- com.ibm.ws.odr.plugincfg.config.VHostMatchingCompat
- To use the port number for virtual host matching. The following values can be
specified:
- True for physically matching using the port number for which the request is received.
- False for logically matching using the port number contained in the host header.
The default is False.
- com.ibm.ws.odr.plugincfg.odrIncludeStopped
- Allow the inclusion of stopped ODRs. The following values can be specified:
- True for including stopped ODRs.
- False for not including stopped ODRs.
The default is False.
- com.ibm.ws.odr.plugincfg.config.TrustedProxyEnable
- Trusted proxies. The following values can be specified:
- True for including trusted proxies.
- False for not including trusted proxies.
The default is False. The trusted proxies are collected from the defined trusted security proxies on the page...
-
On demand router properties > On demand router settings
Log
The log describes the location and level of log messages that are written by the plug-in. If a log is not specified within the configuration file, the log messages might be written to the error log.
- com.ibm.ws.odr.plugincfg.log.Name
- The fully qualified path to the log file to which the plug-in writes error messages.
Default is profileRoot/logs/http_plugin.log.
- com.ibm.ws.odr.plugincfg.log.LogLevel
- The level of detail of the log messages that the plug-in writes to the log. We can specify one
of the following values for this attribute:
- Trace. All of the steps in the request process are logged in detail.
- Stats. The server selected for each request and other load balancing information relating to request handling is logged.
- Warn. All warning and error messages resulting from abnormal request processing are logged.
- Error. Only error messages resulting from abnormal request processing are logged.
- Debug. All of the critical steps performed in processing requests are logged.
- Detail. All of the information about requests and responses are logged.
Default is Error.
CAUTION:
A lot of messages are logged at the trace level, which can cause the file system to fill up very quickly. Never use a trace setting in a normally functioning environment as it adversely affects performance.
ServerCluster
This element is a group of servers that are generally configured to service the same type of requests.
In the simplest case, the cluster contains only one server definition. When defining more than one server, the plug-in completes a load balance across the defined servers using either a Round Robin or a Random algorithm. The default is Round Robin.
- com.ibm.ws.odr.plugincfg.cluster.CloneSeparatorChange
- Some pervasive devices cannot handle the colon character (:) used to separate clone IDs
in conjunction with session affinity. This attribute tells the plug-in to expect the plus character
(+) as the clone separator. We must change the server configurations so that the server separates
clone IDs with the plus character as well.
Default is false.
- com.ibm.ws.odr.plugincfg.cluster.LoadBalance
- The Round Robin implementation has a random starting point. The first server is selected
randomly, and the Round Robin value is used to select servers from that point forward. This implementation ensures that in multiple process-based Web servers, all of the processes do not start
by sending the first request to the same server.
The default load balancing type is Round Robin.
- com.ibm.ws.odr.plugincfg.cluster.PostSizeLimit
- The maximum number of bytes of request content allowed for the plug-in to attempt to send the request to a server. If a request is received that is greater than this size, the plug-in ends the request.
Default is -1 bytes, which indicates that there is no limit for the post size.
- com.ibm.ws.odr.plugincfg.cluster.RemoveSpecialHeaders
- The plug-in adds special headers to the request before it is forwarded to the server. These
headers store information about the request that the application then uses. By default, the plug-in
removes these headers from incoming requests before adding the required headers.
Default is true. If we set the attribute to false, we introduce a potential security exposure by not removing headers from incoming requests.
- com.ibm.ws.odr.plugincfg.cluster.RetryInterval
- An integer that specifies the length of time that elapses from the time a server is marked down
to the time that the plug-in reattempts to make a connection.
Default is 60 seconds.
Server
This element is a server instance configured to handle requests routed to it based on the routing rules of the plug-in configuration. The server element corresponds to an application server running on either the local workstation or a remote workstation.
- com.ibm.ws.odr.plugincfg.server.ServerIOTimeout
- Enable the plug-in to set a timeout value, in seconds, for sending requests to and reading
responses from the server.
When we select a value for this attribute, consider the following:
- It might take several minutes for a server to process a request. Setting the value of the ServerIOTimeout attribute too low might cause the plug-in to send a false server error response to the client.
- If a value is not set, the plug-in, uses the default value to write requests to the server, and to read responses from the server until the TCP connection times out. Default is 900.
- For older product versions, the default value is 0. If the plug-in uses a default timeout value of 0, an error might occur.
For more information on how to configure the ServerIOTimeout attribute, see the web server plug-in configuration technote.
- com.ibm.ws.odr.plugincfg.server.ConnectTimeout
- Enable the plug-in to perform non-blocking connections with the application server, which are beneficial when the plug-in is unable to contact the destination to determine if the port is available or unavailable.
If no value is specified, the plug-in performs a blocking connect in which the plug-in waits until an operating system times out and allows the plug-in to mark the server unavailable. A value greater than 0 specifies the number of seconds the plug-in waits for a successful connection. If a connection does not occur after that time interval, the plug-in marks the server unavailable, and proceeds with one of the other servers defined in the cluster.
Default is 0.
- com.ibm.ws.odr.plugincfg.server.ExtendedHandShake
- Used when a proxy firewall is between the plug-in and the application server. In such a case,
the plug-in is not failing over, as expected.
The plug-in marks a server as stopped when the connect() ends. However, when a proxy firewall is in between the plug-in and the application server, the connect() succeeds, even though the back-end application server is stopped. This causes the plug-in to not failover correctly to other application servers.
The plug-in contains this attribute to ensure that it is started before sending the request.
Default is false.
- com.ibm.ws.odr.plugincfg.server.MaxConnections
- Maximum number of pending connections to a server that flows through a Web server process at any point in time.
Default is set to -1.
- com.ibm.ws.odr.plugincfg.cluster.WaitForContinue
- Specifies whether to use the HTTP 1.1 100 Continue support before sending the request content to the application server. Default is false. The plug-in does not wait for the 100
Continue response from the application server before sending the request content.
This property is ignored for POST requests to prevent a failure from occurring if the application server closes a connection because of a time-out.
Enable this function when configuring the plug-in to work with certain types of proxy firewalls.
Property
- com.ibm.ws.odr.plugincfg.property.ESIEnable
- Used to enable or disable the Edge Side Include (ESI) processor. If the ESI processor is disabled, the other ESI elements in the file are ignored.
Default is true.
- com.ibm.ws.odr.plugincfg.property.ESIMaxCacheSize
- An integer specifying, in 1K byte units, the maximum size of the cache. The default maximum size of the cache is 1024K bytes (1 megabyte). If the cache is full, the first entry to be evicted from the cache is the entry that is closest to its expiration time.
- com.ibm.ws.odr.plugincfg.property.ESIInvalidationMonitor
- Indicates whether or not the ESI processor receives invalidations from the application server.
Default is false.
- com.ibm.ws.odr.plugincfg.property.https.keyring
- Use this element to specify the initialization parameters when the protocol of the transport is set to HTTPS.
This attribute is a supported name that is recognized by the transport. The default value for the keyring element is profileRoot/etc/plugin-key.kdb.
- com.ibm.ws.odr.plugincfg.property.https.stashfile
- The default value for the stash file is profileRoot/node/etc/plugin-key.sth
- com.ibm.ws.odr.plugincfg.property.PluginInstallRoot
- The installation path for the plug-in. Default is "". Set the value, however, to the fully qualified path of the plug-in installation root, or the property is not displayed in plugin-cfg.xml.
plugin-cfg.xml file generation considerations
To generate HAPluginCfgGeneration definitions on demand:
- Disable automatic generation.
Set the cell custom property ODCPluginCfgDisabled_<genDefID> to true.
- Generate a new plug-in...
- <WAS_HOME>/bin/wsadmin.sh -lang jython -f <WAS_HOME>/bin/manageODC.py generateHAPluginCfgs <generationDefinitionIDs> nodeName serverName
where:
- generationDefinitionIDs
- is a list of HAPluginCfgGeneration IDs separated by commas of the form ODCPluginCfg_<genDef>.
- nodeName
- is the name of the node that performs the generation.
- serverName
- is the process name that performs the generation. Any Intelligent Management augmented process can generate the HAPluginCfgs configuration on demand, except for XDAGENT processes. For example:
- <WAS_HOME>/bin/wsadmin.sh -lang jython -f <WAS_HOME>/bin/manageODC.py generateHAPluginCfgs
ODCPluginCfg_1,ODCPluginCfg_2 dmgrNodeName dmgr
To limit how often the HAPluginCfgGeneration definitions are regenerated, set the cell custom property ODCPluginCfgMinGenerationDelay with a value that represents the time in minutes between possible generations. For example:
- ODCPluginCfgMinGenerationDelay = 10
The configured HAPluginCfgGeneration definitions are regenerated every 10 minutes at the most. If the generator receives notification to rebuild the pluginCfgs, it delays the generation of pluginCfgs written within the last 10 minutes.
To limit how often an ODR generated plugin-cfg.xml file is regenerated, set the JVM property com.ibm.ws.odr.plugincfg.minGenerationDelay to a value that represents the time in minutes between possible generations and then cycle the ODR.
By default, the configured static runtime weight value is used to include stopped ODR processes in a generated plugin-cfg.xml file.
To include stopped ODR processes in a generated plugin-cfg.xml file based on the current runtime weight value (always 0), configure the following settings:
- For the HAPluginCfgGenerator, set the cell custom property ODCPluginCfgOdrIncludeStoppedStatic to false.
- For ODR generated plugin-cfg.xml files, set the JVM property com.ibm.ws.odr.plugincfg.odrIncludeStoppedStatic to false, and then cycle the ODR.
Related: