Input/Output Cluster Properties

The following cluster properties configure input/output behavior on the gateway node or node cluster.
gateway92
The following cluster properties configure input/output behavior on the 
Layer7 API Gateway
node or node cluster.
Refer to "Time Units" under Cluster Properties for a list of the valid time units that you can use for time-related properties.
Property
Description
concall.globalCoreConcurrency
Number of assertions that can execute concurrently when using the  Run All Assertions Concurrently Assertion. The value is the number of concurrent threads typically available to the assertion.
Default:
32
concall.globalMaxConcurrency
Maximum number of assertions that can execute concurrently when using the Run All Assertions Concurrently assertion. This is a global limit across all such assertions.
Default:
64
The value of
concall.globalMaxConcurrency
should not exceed twice that of
concall.globalCoreConcurrency
.
concall.globalMaxWorkQueue
Maximum number of assertions that are waiting to execute concurrently. When this limit is reached, and the
concall.globalMaxConcurrency
value is already reached, assertions are run serially (non-concurrently) until the system catches up.
Default:
64
The value of
concall.globalMaxWorkQueue
should not exceed twice that of
concall.globalMaxConcurrency
.
io.debugSsl
Controls whether to log debug information for SSL and TLS operations. Value is a Boolean. Restart the Gateway for changes to take effect.
Default:
false
The SSL/TLS debugging for all the Java security JCE providers might not be enabled by setting the
io.debugSsl
cluster-wide property to "true". Instead, define
javax.net.debug
property with the appropriate level (example,ssl, all, and so on) in the system.properties file of Gateway.
Do not to use the level
help
, as it causes some providers to terminate the JVM.
io.EmailListenerMessageMaxBytes
Maximum size of an email message, including all MIME parts. A value of zero indicates unlimited size.
This property affects only request messages (inbound from the client to the Gateway, outbound from the Gateway to the backend system, and inbound from the backend system to the Gateway). It has no effect on the size of response messages returned to the client via the Gateway.
Default:
2621440
(bytes)
io.failoverServerRetryDelay
Time before retrying a failed server when using a "Round-Robin" or "Ordered Sticky with Failover" failover strategy. This setting is used by assertions with a failover strategy such as the Scan Using ICAP-Enabled Antivirus Assertion.
A value of zero indicates delays for these failover strategies:
  • "Ordered Sticky with Failover":
    15m
  • "Round Robin":
    5m
The maximum server retry delay is 2^63-1 milliseconds.
Default:
0
(milliseconds)
io.httpAllowBackslash
Determines whether the backslash ('\') character is permitted URLs. Values is a Boolean.
Default:
false
io.httpChallengeOrder
Controls whether the legacy order is used in HTTP response challenges. The valid values are:
  • reverse
    : Use the legacy challenge order (NTLM, Negotiate, Digest, Basic)
  • windows
    : Use the Windows challenge order (Negotiate, NTLM, Digest, Basic).
Default:
windows
io.httpConcurrencyWarning.repeatDelay
 
Controls how frequently audit messages warning about HTTP(S) thread pool concurrency exceeding a threshold should repeat. Changes take effect immediately.
For more information, see "Advanced Properties" in Listen Port Properties.
Default:
60
(seconds)
io.httpConnectionIdleTimeout
Maximum time that an HTTP connection may remain idle before it times out. Value is in seconds. A value of zero means the connection never times out.
Default:
0
(seconds)
This is a hidden property that is editable by typing in its name in the
Key
field and then pressing [Tab]. (It
cannot
be located using the drop-down list.)
For improved performance, consider setting this property to 5 seconds. This preservesperformance, while ensuring that resources are not being consumed unnecessarily by leaving connections open when no shutdownacknowledgement is received
io.httpCoreConcurrency
Number of concurrent active HTTP connections per node. A negative number means to use a fraction of
io.httpMaxConcurrenc
y. For example, "-5" would mean 1/5 of the maximum.
Default:
500
For a detailed discussion on how to best use this property along with
io.httpMaxConcurrency
, see "Increasing 'io.httpCoreConcurrency' and 'io.httpMaxConcurrency'" below.
io.httpDefaultContentType
Value of the "Content-Type" HTTP header to use if a response does not have a "Content-Type" header.
If a valueis configurefor this cluster property and the Gateway encounters a response without a "Content-Type" header, audit message 4049 is generated.
The value can include parameters, such as "text/xml; charset=utf-8". If the value is not valid, it is ignored and a warning is logged.
Default:
none
io.httpDisableKeepAlive
Disables the HTTP Keep-Alive connections for outbound HTTP connections (other than routing assertions). Value is a Boolean.
Default:
false
io.httpEnableAutoChallenge
Enables Auto Challenge when preemptive authenticate is used.
Default:
false
This is a hidden property that is editable by typing in its name in the
Key
field and then pressing [Tab]. (It
cannot
be located via the drop-down list.)
io.httpExpectContinue
Uses an "Expect: 100-continue" header during HTTP routing to improve efficiency when authenticating. Value is a Boolean.
Default:
false
io.httpMaxConcurrency
Maximum number of concurrent HTTP and HTTPS connections (per node) that can be active simultaneously without causing delays. Changes to this setting take effect within 30 seconds. This value is shared across all listen ports that are not configured to use their own private thread pool.
Default:
750
 
Technical Note:
The value of
io.httpMaxConcurrency
is closely linked to the
c3p0DataSource.maxPoolSize
setting within the
node.properties
file.
Additional Information
Increasing the concurrency limit permits more in-flight requests to be handled simultaneously. This increases throughput in situations where the performance bottleneck is inbound requests waiting for a handler thread. For example, this may occur when many threads are busy inside  Route via HTTP(S) Assertions waiting for a slowback end server. The drawback of increasing concurrency is that it increases the Gateway’s working set size: each in-flight request requires some amount of memory in order to do its job.
The memory required by a Gateway under peak load depends on a variety of factors:
  • the mix of requests and their sizes
  • the assertions being used (for example, if DOM parsing of large XML requires substantially more memory than simply passing through message bodies)
  • the request size limits (such as the value of the
    io.xmlPartMaxBytes
    cluster property).
For a detailed discussion on how to best use this property, see "Increasing io.httpCoreConcurrency and io.httpMaxConcurrency" below.
io.httpParamsMaxFormPostBytes
Maximum number of bytes to buffer when processing an HTTP form post (application/x-www-form-urlencoded).
Default:
5242880
Technical Note:
The
io.httpParamsMaxFormPostBytes
cluster property replaces the former
com.l7tech.message.httpParamsMaxFormPost
system property.However if the system property is set, it will override this cluster property.
io.httpResponseStreamUnlimited
Ignores message size limit when streaming HTTP responses. Value is a Boolean.
Default:
true
io.httpResponseStreaming
Streams responses back to the client. Value is a Boolean.
  • true
    : The Gateway streams a response to a request that arrived over HTTP if the response is produced by a routing assertion that supports streaming (such as HTTP or SSH routing) and there is nothing in the service policy that requires examination of the response by the Gateway. When streaming is in effect, the response body is not buffered by the Gateway before being returned to the client. This can greatly reduce the overall latency, especially for large responses.This setting is the default.
Observe the following issues when enabling streaming: (1) streamed responses may not be accessible by the Audit Sink policy, and (2) the client should have its own provisions for protecting itself if your service policy contains no logic for checking the response.
  • false
    : The Gateway always buffers the entire response before returning it to the client, regardless of whether the policy requires an examination of the response.
io.httpVersion
Sets the HTTP version used by the routing assertions. If set to "1.0", the cluster property
io.httpExpectContinue
 is ignored.
Default:
1.1
The default value may be overridden during HTTP(S) routing though the [
Request HTTP Rules
] tab in the Route via HTTP(S) assertion.
io.httpsHostAllowWildcard
Determines whether wildcards are permitted when verifying hostnames:
  • true
    = the wildcard character '*' is permitted when verifying server hostnames against the certificate name
  • false
    = the wildcard character is not permitted; the server hostname must be explicit
Default:
false
For details, see  Wildcard Matching of Hostnames.
io.httpsHostVerify
Enables verification of server names against certificates, for certificates that are not trusted and which are unsigned by another trusted certificate.
  • true
    = server name is verified against the name on the certificate. A mismatch causes a validation failure.
  • false
    = server name is not verified against the name on the certificate. A mismatch does not result in a validation failure.
Default:
true
This setting works with the "Verify Hostnames for Outbound SSL Connections" setting for a certificate. For details, see  Edit a Certificate.
io.jmsConnectionCacheMaxAge
Maximum age for a cached JMS connection. Enter zero for no time limit. Value is a time unit.
Default:
10m 
io.jmsConnectionCacheMaxIdleTime
Maximum time that an idle JMS connection is cached. Enter zero for no time limit. Value is a time unit.
Default:
5m
io.jmsConnectionCacheMaxSize
Number of JMS connections to cache. Enter zero to disable caching for JMS connections, and for WebLogic JMS destinations. The cache size is a soft limit that can be exceeded under the following conditions
  • There are hundreds of concurrent requests using JMS routing, each with a distinct connection. In this case, there would be as many JMS connections are there are requests, even if this exceeds the io.jmsConnectionCacheMaxSize property.
  • If template outbound destinations are used, it is possible to create new queue connections dynamically (one per request). In this case, the cache size may be exceeded until eligible cached connections are removed.
Default:
100
io.jmsConsumerConnections
Number of inbound JMS consumer connections allowed for a JMS destination across the cluster. This value can be overridden for individual JMS destinations via the [Inbound Options] tab of the  JMS Destination Properties.
Default:
1
io.jmsMessageMaxBytes
 
Maximum size of a JMS message, including all MIME parts. A value of zero indicates unlimited size. This property affects only request messages (inbound from the client to the Gateway, outbound from the Gateway to the back-end system, and inbound from the back-end system to the Gateway). It has no effect on the size of response messages returned to the client via the Gateway.
Default:
2621440
(bytes)
io.jmsRoutingMaxRetries
Maximum number of connection attempts for an outbound JMS Queue.
Default: 
5
io.jmsRoutingRetrySleep
Time to sleep after a connection error for an outbound JMS Queue.
Default:
1s
io.mqConnectionCacheMaxAge
Maximum age for a cached MQ native connection. Enter zero for no time limit. Value is a time unit.
Default:
10m
io.mqConnectionCacheMaxIdleTime
Maximum time an idle MQ native connection is cached. Enter zero for no time limit. Value is a time unit.
Default:
5m
io.mqConnectionCacheSize
Number of MQ native connections to cache. Enter zero to disable caching for MQ native connections. The cache size is a "soft" limit that may be exceeded under the following conditions:
  • There are hundreds of concurrent requests using MQ native routing, each with a distinct connection. In this case, there would be as many MQ connections are there are requests, even if this exceeds the
    io.mqConnectionCacheMaxSize
    property.
  • If template outbound queues are used, it is possible to create new queue connections dynamically (one per request). In this case, the cache size may be exceeded until eligible cached connections are removed.
Default:
100
io.mqConvertMessageApplicationDataFormat
(available only in versions 9.2 CR4 and higher)
Convert the MQ Message application data to a format specified by the queue manager.Value is a Boolean.
The conversion occurs when:
Default:
true
io.mqForceReturnPropertiesInMQRFH2Header
(
available only in versions 9.2 CR4 and higher
)
Force the properties in an MQ Message to be returned in the MQRFH2 header when reading a message from a queue. This occurs when:
  • a MQ listener gets a message from a queue, or
  • the MQ Native routing assertion gets a message from a queue, or
  • the MQ Native routing assertions gets a reply message after writing a message to a queue
Default:
false
When this cluster property is enabled, you must reference the message properties using different context variables. For example, to look up the value of the “myMessageProperty” property in a request message:
  • Use this:
    ${request.mqnative.additionalheader.myMessageProperty}
  • Instead of this:
    ${request.mqnative.property.myMessageProperty}
io.mqMessageMaxBytes
Maximum size of an MQ Native message, including all MIME parts. A value of zero indicates unlimited size. This property affects only request messages (inbound from the client to the Gateway, outbound from the Gateway to the back-end system, and inbound from the back-end system to the Gateway). It has no effect on the size of response messages returned to the client via the Gateway.
Default:
2621440 bytes
io.mqResponseTimeout
Time the Route via MQ Native Assertion waits for a response on the replyTo queue before timing out. This value can be overridden in the "MQ response timeout" field in the assertion's properties.
Default:
10000
(milliseconds)
io.mqRoutingMaxRetries
Maximum number of connection attempts for an outbound MQ Queue.
Default: 
5
io.mqRoutingRetrySleep
Time to sleep after a connection error for an outbound MQ Queue.
Default:
1s
io.mqRoutingSetAllContext
Controls which MQ message descriptors can be set. Value is a Boolean.
  • true
    = All MQ message descriptors can be set, with the exception of the following: false = When adding a new message descriptor, only the MQ message descriptors visible in the “Name” drop-down list can be set (see Customizing MQ Messages). This setting is the default.
    • backoutCount
    • messageSequenceNumber
    • originalLength
For a list of MQ message descriptors, see “Class MQMessage” on the IBM WebSphere web site.
io.outConnectTimeout
Maximum time to wait for a connection to be established for routing. If exceeded, routing fails (or fails over). This timeout can be overridden for a specific routing assertion through the HTTP(S) Routing Properties.
Default:
30000
(milliseconds)
io.outTimeout
Maximum time for response data to be read for the outbound request. If exceeded, routing fails (or fails over). This timeout can be overridden for a specific routing assertion through the HTTP(S) Routing Properties.
Default:
60000
(milliseconds)
io.rateLimit
Minimum rate for incoming requests.
Default:
1024
(bytes per second)
io.rateTimeout
IO timeout period for incoming request rate checking.
Default:
60000
(milliseconds)
io.signedPartMaxBytes
Maximum size of attachments permitted for signature processing. A value of zero indicates unlimited size. This property is enforced for any signed message part that is processed for security.
Default:
5242880
(bytes)
io.staleCheckCount
Number of stale checked connections per interval.
Default:
1
io.staleCheckHosts
Maximum number of stale checked hosts.
Default:
10
io.timeout
IO timeout for incoming requests from the client before timing out. This is the amount of time the Gateway will wait for data from the client before timing out.
Default:
60000
(milliseconds)
io.xmlPartMaxBytes
Maximum size of the XML part of a message (part 1). When the maximum message size is reached, a SOAP fault '500' is returned. A value of zero indicates unlimited size.
  • Enforced for any message (if not MIME), or the first part of a MIME message if XML.
  • Not enforced for responses or requests set within the policy. For example, a response created by the Copy Request Message to Response Assertion that exceeds the size specified by
    io.xmlPartMaxBytes
    will not trigger an error.
Use the setting to constrain the use of Gateway resources. Rather than enforcing an arbitrary size limit, use the Limit Message Size Assertion. Do not use with small values.
Default:
2621440
(bytes)
1) If compression is in effect, this property applies to the uncompressed message size. 2) The Route via Raw TCP Assertion uses a different method of restricting message size. 3) If
io.xmlPartMaxBytes
is not returning correct results, try setting
io.httpResponseStreamUnlimited
to "false."
jms.connectErrorSleep
Time to wait after an inbound JMS connection error before attempting a reconnection. Value is a time unit.
Default:
60s 
jms.listenerThreadLimit
Number of processing threads that can be created to work off all JMS endpoints.Valuemust be >= 5.
Default:
25
jms.ResponseTimeout
Time the Route via JMS assertion waits for a response on the
replyTo
queue before timing out. This value can be overridden in the "JMS response timeout" field in the assertion's properties.
Default:
10000
(milliseconds)
mq.connectErrorSleep
Time to wait after an inbound MQ Native connection error before attempting to connect again. Value is a time unit.
Default:
60s
Changes to this cluster property require a listener or Gateway restart to take effect. To restart the listener, edit and save the MQ Native configuration.
mq.ConnectionPool.maxActive
(Available i
n v9.2 CR3 and higher)
)
Maximum number of active connections per MQ Native connection pool. Enter "0" (zero) to allow no active connections. Any negative value indicates unlimited active connections.
This property is used in the [Outbound Options] tab of the MQ Native Queue Properties.
Default:
20
mq.ConnectionPool.maxIdle
(Available in v9.2 CR3 and higher)
The maximum number of idle connections that are allowed ina MQNative connection pool. Enter "0" (zero) to allow no idle connection. Any negative value indicates unlimited idle connections.
This property is used in the [Outbound Options] tab of the MQ Native Queue Properties.
Default:
20
For best performance, set mq.ConnectionPool.maxIdle to the same value as mq.ConnectionPool.maxActive.
mq.ConnectionPool.maxWait
(Available i
n v9.2 CR3 and higher)
Maximum amount of time to wait for an MQ Native connection to become available. Value is in milliseconds. Enter "0" (zero) or a negative value to wait indefinitely.
This property is used in the [Outbound Options] tab of the MQ Native Queue Properties.
Default:
-1
mq.listenerMaxConcurrentConnections
Maximum number of concurrent connections allowed for any inbound MQ Native queue.
Default:
1000
(1) The limit specified here overrides any larger value specified in the queue properties (in the [nbound Options] tab of the  MQ Native Queue Properties. (2) Changes require a listener or Gateway restart.
mq.listenerPollingInterval
Time to wait when polling for messages on an empty queue. Value is a time unit.
Default:
5s
Changes to this cluster property require a listener or Gateway restart to take effect. To restart the listener, edit and save the MQ Native configuration.
mq.listenerThreadLimit
Number of processing threads that can be created to work off all MQ endpoints.Valuemust be >= 5.
Default:
25
Changes require a Gateway restart.
mq.preventAuditFloodPeriod
Time to prevent audit message flooding by the MQ Native listener. If the most recent listener audit message occurred within this period, the next listener message is be logged (no audit record is created). A value of zero indicates no audit flood throttling. Value is a time unit.
Default:
0s
Changes requiresa listener or Gateway restart. To restart the listener, edit and save the MQ Native configuration.
sftpPolling.connectErrorSleep
Time to sleep after a connection error for an SFTP polling listener. Value is a time unit.
Default:
10s
sftpPolling.downloadThreadWait
Maximum wait time limit for file download thread to run (in seconds)
Default:
3
(seconds)
sftpPolling.ignoredFileExtensionList
File extensions to ignore during SFTP polling.
Default:
.filepart
Changes to this property requires restartingSFTP polling listeners.
sftpPolling.listenerThreadLimit
The global limit on the number of processing threads that can be created to work off allSFTPpolling listeners.Valuemustbegreater than or equal to 5.
Default:
25
sftpPolling.messageMaxBytes
Maximum number of bytes permitted for an SFTP message. A value of zero indicates unlimited size.
Default:
5242880
(bytes)
ssh.routingEnabledCiphers
Ciphers to enable for SSH2 routing (comma separated). Valid values:
aes128-ctr
aes192-ctr
aes256-ctr
aes128-cbc
aes192-cbc
aes256-cbc
blowfish-cbc
3des-cbc
Default:
aes128-ctr, aes128-cbc, 3des-cbc, blowfish-cbc, aes192-ctr, aes192-cbc, aes256-ctr, aes256-cbc
ssh.routingExplicitlyValidateDeleteFile
Validation during file deletion for SSH routing. Value is a Boolean.
  • true
    : Verifies that a file for deletion exists and is a file. This setting is the default.
  • false
    : No verification that the file for deletion exists.
ssh.routingExplicitlyValidateDeleteDir
Validation during directory deletion for SSH routing. Value is a Boolean.
  • true
    : The Gateway verifies that a directory to be deleted actually exists and that is a directory. This setting is the default.
  • false
    : No verification is performed on whether or not a directory being deleted actually exists.
ssh.session.pool.maxActive
Maximum number of sessions (per key) that can be allocated by the pool (checked out to client threads) at one time. Set to -1 for no limit to the number of sessions per key.
After the maximum number of sessions is reached, the session pool is exhausted, and the assertion fails. The maximum value is 1000.
Default:
10
ssh.session.pool.
minEvictableIdleTimeMillis
Minimum time an object can remain idle in the pool before it is eligible for eviction.
Default:
600000
(milliseconds)
ssh.session.pool.
timeBetweenEvictionRunsMillis
Time to sleep between examining idle objects for eviction. Set to 0 or -1 to have the session remain idle forever.
Default:
1800000
(milliseconds)
ssh.sftpRoutingExplicitlyValidateMkdir
Determines that a directory of the same name does not exist before attempting to create it during SSH routing. Value is a Boolean.
  • true
    : Verifies that a directory or file of the same name does not exist. This setting is the default.
  • false
    : No verification that a directory of the same name exists.
Increasing io.httpCoreConcurrency and io.httpMaxConcurrency
Core concurrency (set by
io.httpCoreConcurrency
) specifies how many initial HTTP listeners are created when the
Layer7 API Gateway
starts. You need enough HTTP listeners running at initialization time for good performance. However too many listeners impact performance adversely, as starting HTTP listeners require time and resources. The ideal is to set the core concurrency based on the expected level of traffic for the system.
Maximum concurrency (set by
io.httpMaxConcurrency
) specifies the maximum number of HTTP listeners. The Gateway does not allow more HTTP listeners to be created, which results in queued requests if there are insufficient HTTP listeners. However, creating additional listeners require more CPU and RAM to manage and keep open.
Tip:
The maximum concurrency must be greater than the core concurrency, but only by a small amount.
CA Technologies does not recommend increasing these concurrency properties to overly large values, as the drain in system resources offsets any performance gains. Gateways equipped with more RAM and CPUs can keep more listeners open, but resources are finite.
How to find the correct values?
Determining the correct values for your Gateway's concurrency requires a certain amount of trial and error. The factory settings are designed to avoid inundating your production environment with too many concurrent requests. However for non-production environments, you are free to experiment to see what works best. Increase the cluster properties by 50%, then perform a load test, and then repeat. Performance should gradually increase, but you use more system resources as concurrency increases. Monitor the Gateway's resources carefully (specifically RAM and CPU) during the load tests to determine the best values for your environment.