Web Server Plugin (pluginConfiguration)

ESIEnable

boolean

true

ESIEnable property enables Edge Side Include processing to cache the responses. This property provides the option to disable ESI in the web server plugin configuration file.

ESIEnableToPassCookies

boolean

false

ESIEnableToPassCookies allows forwarding of session cookies to WebSphere Application Server. This property provides the option to override the value in the web server plugin configuration file.

ESIInvalidationMonitor

boolean

false

ESIInvalidationMonitor specifies if the ESI processor should receive invalidations from the application server. This property provides the option to override the value in the web server plugin configuration file.

ESIMaxCacheSize

int

1024

ESIMaxCacheSize is the maximum size of the cache which defaults to 1MB. This property provides the option to override the value in the web server plugin configuration file.

connectTimeout

A period of time with second precision

5s

Identifies the maximum amount of time that the application server should maintain a connection with the web server. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

httpEndpointRef

A reference to top level httpEndpoint element (string).

defaultHttpEndpoint

Specify the identifier of the http endpoint to include in the generated plugin-cfg.xml file. The endpoint defines the server in the cluster. The default value is 'defaultHttpEndpoint'.

ignoreAffinityRequests

boolean

true

Indicates whether the webserver plug-in ignores affinity requests when it is tracking runtime weight for round-robin load balancing.

ipv6Preferred

boolean

false

Used when resolving an application server host name of {null} or {0}, to prefer the type of address when possible

loadBalanceWeight

int

20

This value is dynamically changed during run time. The weight of a server is lowered each time a request is assigned to that server. When all weights for all servers drop to 0 or a lesser value, the web server plug-in readjusts all the weights so that they are greater than 0.

logDirLocation

Path to a directory

${pluginInstallRoot}/logs/${webserverName}

Deprecated: Identifies the directory where the http_plugin.log file is located. See Log file name.

logFileName

Path to a file

A fully qualified path to to the web server plug-in log file. Directory component must already exist. For Apache-based web servers, a path that begins with a pipe character is interpreted as an external piped logger. If specified, the path overrides logDirLocation.

pluginInstallRoot

string

/opt/IBM/WebSphere/Plugins

Web server plugin installation location in file system of web server host

serverIOTimeout

A period of time with second precision

900s

Identifies the maximum amount of time that the web server plugin waits to send a request or receive a response from the application server. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

serverIOTimeoutRetry

int
Min: -1
Max: 65535

-1

Limits the number of request retries after a read or write timeout. The default value, {-1}, applies no additional limits, so retries are limited by the number of available servers in the cluster. A {0} value indicates there should be no retries. This value is scoped to the server cluster and does not apply to connection failures or timeouts due to the HTTP plug-in Connection timeout, or to web socket timeouts.

serverRole

PRIMARY

The server role identifies a server as primary or backup. When primary servers are available, the web server plug-in uses them for load balance and failover. However, if none of the primary servers are available, the web server plug-in uses only backup servers for load balance and failover.

sslCertlabel

string

Specifies the label of the certificate within the keyring that the plug-in is to use when the web container requests a client certificate from the plug-in.

sslKeyringLocation

string

${pluginInstallRoot}/config/${webserverName}/plugin-key.kdb

The fully qualified path to the SSL keyring file on the web server host

sslStashfileLocation

string

${pluginInstallRoot}/config/${webserverName}/plugin-key.sth

The fully qualified path to the SSL stashfile on the web server host

trustedProxyEnable

boolean

Enables trusted proxies to be used. When specified, this property overrides the value in the web server plug-in configuration file.

trustedProxyGroup

string

A comma-separated list of trusted proxies. When specified, this property overrides the value in the web server plug-in configuration file.

waitForContinue

boolean

false

If false (the default value), the web server plugin sends the "Expect: 100-continue" header with HTTP requests that have a message body. When set to true, the web server plugin sends the "Expect: 100-continue" header with every HTTP request. Consider setting this value to true if you have a firewall between the web server and the application server, and are sensitive to requests retries with no request body.

webserverName

string

webserver1

Name of the web server where this configuration will be used. Used to generate the plugin log file location if that is not specified explicitly by Log file name or directory.

webserverPort

int
Min: -1
Max: 65535

80

Web server HTTP port

webserverSecurePort

int
Min: -1
Max: 65535

443

Web server HTTPS port

wsServerIOTimeout

A period of time with second precision

Identifies the maximum amount of time that the web server plugin waits to send a request or receive a websocket response from the application server. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

wsServerIdleTimeout

A period of time with second precision

Identifies the maximum amount of time that the web server plugin waits to terminate an idle websocket connection. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

accessLoggingRef

A reference to top level httpAccessLogging element (string).

HTTP access logging configuration for the endpoint.

compressionRef

A reference to top level compression element (string).

defaultCompression

Compression options for the endpoint.

enabled

boolean

true

Toggle the availability of an endpoint. When true, this endpoint will be activated by the dispatcher to handle HTTP requests.

headersRef

A reference to top level headers element (string).

defaultHeaders

Header options for the endpoint.

host

string

localhost

IP address, domain name server (DNS) host name with domain name suffix, or just the DNS host name, used by a client to request a resource. Use '*' for all available network interfaces.

httpOptionsRef

A reference to top level httpOptions element (string).

defaultHttpOptions

HTTP protocol options for the endpoint.

httpPort

int
Min: -1
Max: 65535

The port used for client HTTP requests. Use -1 to disable this port.

httpsPort

int
Min: -1
Max: 65535

The port used for client HTTP requests secured with SSL (https). Use -1 to disable this port.

onError

WARN

Action to take after a failure to start an endpoint.
FAIL
Server will issue a warning or error message on the first error occurrence and then stop the server.
IGNORE
Server will not issue any warning and error messages when it incurs a configuration error.
WARN
Server will issue warning and error messages when it incurs a configuration error.

protocolVersion

string

When Servlet 4.0 API is enabled as a feature, set this attribute to http/1.1 to disable HTTP/2 processing for the ports that were defined for the httpEndpoint element. When Servlet 3.1 API is enabled as a feature, set this attribute to http/2 to enable HTTP/2 processing for the ports that are defined for the httpEndpoint element.

remoteIpRef

A reference to top level remoteIp element (string).

defaultRemoteIp

Remote IP options for the endpoint.

samesiteRef

A reference to top level samesite element (string).

defaultSameSite

SameSite options for the endpoint.

sslOptionsRef

A reference to top level sslOptions element (string).

SSL protocol options for the endpoint.

tcpOptionsRef

A reference to top level tcpOptions element (string).

defaultTCPOptions

TCP protocol options for the endpoint.

enabled

boolean

true

Enables access logging when the accessLogging configuration element is defined. Note: Access logging must be configured for this attribute to take effect.

filePath

Path to a file

${server.output.dir}/logs/http_access.log

Directory path and name of the access log file. Standard variable substitutions, such as ${server.output.dir}, can be used when specifying the directory path.

logFormat

string

%h %u %{t}W "%r" %s %b

Specifies the log format that is used when logging client access information.

maxFileSize

int
Min: 0

20

Maximum size of a log file, in megabytes, before being rolled over; a value of 0 means no limit.

maxFiles

int
Min: 0

2

Maximum number of log files that will be kept, before the oldest file is removed; a value of 0 means no limit.

rolloverInterval

A period of time with minute precision

-1

The time interval in between log rollovers, in minutes if a unit of time is not specified. Specify a positive integer followed by a unit of time, which can be days (d), hours (h), or minutes (m). For example, specify 5 hours as 5h. You can include multiple values in a single entry. For example, 1d5h is equivalent to 1 day and 5 hours. If rolloverStartTime is specified, the default value of rolloverInterval is 1 day. If both rolloverInterval and rolloverStartTime are unspecified, time based log rollover is disabled. Specify a positive integer followed by a unit of time, which can be hours (h) or minutes (m). For example, specify 30 minutes as 30m. You can include multiple values in a single entry. For example, 1h30m is equivalent to 90 minutes.

rolloverStartTime

string

The scheduled time of day for logs to first roll over. The rollover interval duration begins at rollover start time. Valid values follow a 24-hour ISO-8601 datetime format of HH:MM, where 00:00 represents midnight. Padding zeros are required. If rolloverInterval is specified, the default value of rolloverStartTime is 00:00, midnight. If both rolloverInterval and rolloverStartTime are unspecified, time based log rollover is disabled.

serverPreferredAlgorithm

string

none

The configured compression algorithm is used to compress the body of responses when it is specified with a non-zero quality value in the request's Accept-Encoding header. The valid compression algorithms include: deflate, gzip, x-gzip, zlib, and identity.

types

string
This is specified as a child element rather than as an XML attribute (maximum occurrences 5000).

text/*

To include a content type in addition to the default values, affix the add (+) character as a prefix to that content type. To exclude a content type from compression, affix the remove (-) character as a prefix to that content type. Note: The wildcard (*) character is supported only as a content subtype, such as text/*.

add

string

Specifies the header names and values that are added to each HTTP response. Header values are optionally included by using a colon (:) delimiter. Any header name that is defined by using this attribute must not be empty or present in the 'remove', 'set', or 'setIfMissing' header configurations.

remove

string

Specifies the header names that are removed from each HTTP response. Any header name that is defined by using this attribute must not be empty. No header values are expected. Any header name that is defined by using this attribute must not be present in the 'add', 'set', or 'setIfMissing' header configurations.

set

string

Specifies the header names and values that are set to each HTTP response. Header values are optionally included by using a colon (:) delimiter. Any header name that is defined by using this attribute must not be empty, defined more than once, or present in the 'remove', 'add', or 'setIfEmpty' header configurations. If the header is already present on the response, existing values are overwritten in favor of this configuration.

setIfMissing

string

Specifies the header names and values that are set to each HTTP response if not already present. Header values are optionally included by using a colon (:) delimiter. Any header name that is defined by using this attribute must not be empty, defined more than once, or present in the 'remove', 'add', or 'set' header configurations.

AutoDecompression

boolean

true

Specifies whether the HTTP Channel automatically decompresses incoming request body data.

DoNotAllowDuplicateSetCookies

string

false

Prevents the HTTP Channel from sending multiple Set-Cookie headers with the same name.

MessageSizeLimit

long

-1

Limits the acceptable size of an incoming message. If a message arrives with a size larger than this value, then an error is returned to the remote client.

NoCacheCookiesControl

boolean

true

Allows the user to control whether or not the presence of a Set-Cookie header should update the Cache-Control header with a matching no-cache value. This also adds the Expires header.

ThrowIOEForInboundConnections

boolean

Specifies whether the HTTP channel creates an I/O exception when an inbound connection is closed while still in use by the servlet. The default value is set according to the configured servlet feature. Prior to Servlet 4.0, the default value is false; starting with Servlet 4.0, the default value is true.

connectionWindowSize

int
Min: 65535
Max: 2147483647

65535

Specifies the window size in octets for HTTP/2 connection-level flow control. This value can be configured to any size within the range of 65,535 to 2,147,483,647 octets, inclusive. If no value is specified, the default value is 65,535 octets.

decompressionRatioLimit

int
Min: 1

200

Specifies the maximum ratio of decompressed to compressed request body payload. The HTTP channel reads the request body and verifies the ratio as the body decompresses. The channel stops decompression of the request body if the decompression ratio remains above the configured value and the decompressionTolerance is reached.

decompressionTolerance

int
Min: 0

3

Specifies the maximum number of times the HTTP channel tolerates a decompression ratio above the configured ratio, depicted by the decompressionRatioLimit httpOption attribute. If this number reaches, and the next decompression cycle still contains a decompression ratio above the ratio limit, then the HTTP channel stops decompressing the request body.

http2ConnectionIdleTimeout

A period of time with second precision

0

Specifies the amount of time, in seconds, that an HTTP/2 connection will be allowed to remain idle between socket IO operations. If not specified, or set to a value of 0, there is no connection timeout set. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

incomingBodyBufferSize

int
Min: 1024
Max: 1048576

32768

Specifies the size of each buffer used when reading the body of an incoming HTTP message.

keepAliveEnabled

boolean

true

Enables persistent connections (HTTP keepalive). If true, connections are kept alive for reuse by multiple sequential requests and responses. If false, connections are closed after the response is sent.

limitFieldSize

int
Min: 50
Max: 32768

32768

Enforces the size limits on various HTTP fields, such as request URLs, or individual header names or values. Enforcing the size limits of these fields guards against possible Denial of Service attacks. An error is returned to the remote client, if a field exceeds the allowed size.

limitNumHeaders

int
Min: 50
Max: 500

500

Limits the number of HTTP headers that can exist in an incoming message. When this limit is exceeded, an error is returned to the remote client.

limitWindowUpdateFrames

boolean

false

Specifies whether the server waits until half of the HTTP/2 connection-level and stream-level windows are exhausted before it sends WINDOW_UPDATE frames. Valid values are true or false. If no value is specified, the default value is false.

maxConcurrentStreams

int

200

Specifies the maximum number of streams that an HTTP/2 connection can have active at any given point. Opening streams over the limit, will result on a REFUSED_STREAM (0x7). If not specified, the default value of concurrent streams will be set to 200.

maxFrameSize

int
Min: 16384
Max: 16777215

57344

Specifies the maximum allowed size of a frame payload the server will advertise in the SETTINGS_MAX_FRAME_SIZE HTTP/2 settings frame. This can be configured to any size within the range of 16,384 to 16,777,215 bytes, inclusive. If not specified, the default is set to 57,344 bytes.

maxKeepAliveRequests

int
Min: -1

-1

Maximum number of persistent requests that are allowed on a single HTTP connection if persistent connections are enabled. A value of -1 means unlimited. This option supports low latency or high throughput applications, and SSL connections for use in situations where building up a new connection can be costly.

persistTimeout

A period of time with second precision

30s

Amount of time that a socket will be allowed to remain idle between requests. This setting only applies if persistent connections are enabled. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

readTimeout

A period of time with second precision

60s

Amount of time to wait for a read request to complete on a socket after the first read occurs. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

removeServerHeader

boolean

false

Removes server implementation information from HTTP headers.

settingsInitialWindowSize

int
Min: 1
Max: 2147483647

65535

Specifies the initial window size in octets for HTTP/2 stream-level flow control. This value can be configured to any size within the range of 1 to 2,147,483,647 octets, inclusive. If no value is specified, the default value is 65,535 octets.

writeTimeout

A period of time with second precision

60s

Amount of time to wait on a socket for each portion of the response data to be transmitted. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

proxies

string

10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254\.\d{1,3}\.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.1[6-9]{1}\.\d{1,3}\.\d{1,3}|172\.2[0-9]{1}\.\d{1,3}\.\d{1,3}|172\.3[0-1]{1}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1|::1

A regular expression that defines trusted proxies.

useRemoteIpInAccessLog

boolean

false

If this property is set to true and the remote client information was verified by the HTTP Channel, the NCSA access log reflects the Forwarded or X-Forwarded-* headers. These headers are reflected when one or more of the following items are recorded: the remote client IP, the host, or the request protocol.

lax

string

List of cookie names or patterns for which the SameSite attribute is set to a value of Lax, if not already defined. A single wildcard (*) character is supported as a stand-alone value, or following cookie name prefixes. Any cookie name or pattern that is defined by this list must be unique and not present in the 'none' nor 'strict' configurations.

none

string

List of cookie names or patterns for which the SameSite attribute is set to a value of None, if not already defined. A single wildcard (*) character is supported as a stand-alone value, or following cookie name prefixes. Any cookie name or pattern that is defined by this list must be unique and not present in the 'lax' nor 'strict' configurations. Each cookie that is modified to contain a SameSite value of None as a result of this configuration is also set to Secure.

strict

string

List of cookie names or patterns for which the SameSite attribute is set to a value of Strict, if not already defined. A single wildcard (*) character is supported as a stand-alone value, or following cookie name prefixes. Any cookie name or pattern that is defined by this list must be unique and not present in the 'lax' nor 'none' configurations.

sessionTimeout

A period of time with second precision

1d

Amount of time to wait for a read or write request to complete on a socket. This value is overridden by protocol-specific timeouts. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

sslRef

A reference to top level ssl element (string).

The default SSL configuration repertoire. The default value is defaultSSLConfig.

sslSessionTimeout

A period of time with millisecond precision

86400s

The timeout limit for an SSL session that is established by the SSL Channel. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

suppressHandshakeErrors

boolean

false

Disable logging of SSL handshake errors. SSL handshake errors can occur during normal operation, however these messages can be useful when SSL is behaving unexpectedly. If disabled, the message and console logs do not record handshake errors, and the trace log records handshake errors when SSL Channel tracing is on.

acceptThread

boolean

false

If true, then listening ports do not share the same thread for accepting connections. Otherwise, they share the same thread.

addressExcludeList

string

A comma-separated list of addresses that are not allowed to make inbound connections on this endpoint. You can specify IPv4 or IPv6 addresses. All values in an IPv4 or IPv6 address must be represented by a number or by an asterisk wildcard character. As examples, valid IPv4 addresses for this list include "*.1.255.0", "254.*.*.9", and "1.*.*.*", and valid IPv6 addresses include "0:*:*:0:007F:0:0001:0001", "F:FF:FFF:FFFF:1:01:001:0001", and "1234:*:4321:*:9F9f:*:*:0000".

addressIncludeList

string

A comma-separated list of addresses that are allowed to make inbound connections on this endpoint. You can specify IPv4 or IPv6 addresses. All values in an IPv4 or IPv6 address must be represented by a number or by an asterisk wildcard character. As examples, valid IPv4 addresses for this list include "*.1.255.0", "254.*.*.9", and "1.*.*.*", and valid IPv6 addresses include "0:*:*:0:007F:0:0001:0001", "F:FF:FFF:FFFF:1:01:001:0001", and "1234:*:4321:*:9F9f:*:*:0000".

hostNameExcludeList

string

A comma-separated list of host names that are not allowed to make inbound connections on this endpoint. Host names are not case-sensitive and can start with an asterisk, which is used as a wildcard character. However, asterisks cannot be elsewhere in the host name. For example, *.abc.com is valid, but *.abc.* is not valid.

hostNameIncludeList

string

A comma-separated list of host names that are allowed to make inbound connections on this endpoint. Host names are not case-sensitive and can start with an asterisk, which is used as a wildcard character. However, asterisks cannot be elsewhere in the host name. For example, *.abc.com is valid, but *.abc.* is not valid.

inactivityTimeout

A period of time with millisecond precision

60s

Amount of time to wait for a read or write request to complete on a socket. This value is overridden by protocol-specific timeouts. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

maxOpenConnections

int

128000

Defines the maximum number of connections allowed to be open on this endpoint.

portOpenRetries

int
Min: 0
Max: 100000

0

Number of retries to open a TCP/IP port during server startup. There will be a one second delay between retries, until the opening is successful or the port open retry number is reached.

soReuseAddr

boolean

true

Enables immediate rebind to a port with no active listener.

waitToAccept

boolean

false

Queries whether this TCP Channel will delay accepting connections until the server starts. If false, connections are closed until the server starts. If true, the value for the acceptThread tcpOption is also set to true, and connections are delayed until the server starts.