CA API Gateway 9.1

9.4 9.1

Input/Output Cluster Properties

The following cluster properties configure input/output behavior on the  node or node cluster.
gateway83
The following cluster properties configure input/output behavior on the 
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. This is the number of concurrent threads normally 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.
Default:
false
Restart the Gateway for changes to take effect.
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
API Gateway
, outbound from the 
API Gateway
 to the backend system, and inbound from the backend system to the 
API Gateway
). It has no effect on the size of response messages returned to the client via the
API 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 Route via HTTP(S) and Scan Using ICAP-Enabled Antivirus assertions.
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.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:
185
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 value is configure for this cluster property and the
API 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.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.
Default:
215
For a detailed discussion on how to best use this property along with
io.httpCoreConcurrency
, see "tip'" below.
The value of
io.httpMaxConcurrency
 is closely linked to the c3p0DataSource.maxPoolSize setting within the node.properties file.
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
    API 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
    API Gateway
    . When streaming is in effect, the response body is not buffered by the
    API 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
    API Gateway
     always buffers the entire response before returning it to the client, regardless of whether the policy requires an examination of the response. This setting restores pre-v6.1.5 behavior.
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.https.response
.truncationProtection.disable
Disables response truncation attack protection for outbound HTTPS. Value is a Boolean.
  • true
    : A "possible truncation attack?" exception while reading a response from a TLS server will be treated as an end-of-file indication.
  • false
    : Truncation attacks will be handled normally. This setting is the default.
Do not change this property unless directed by CA Support.
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 have not been signed 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 '0' (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
API Gateway
, outbound from the 
API Gateway
 to the backend system, and inbound from the backend system to the 
API Gateway
). It has no effect on the size of response messages returned to the client via the
API 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.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
API Gateway
, outbound from the 
API Gateway
 to the backend system, and inbound from the backend system to the 
API Gateway
). It has no effect on the size of response messages returned to the client via the
API 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 Return Template Response to Requestor or Copy Request Message to Response assertions that exceeds the size specified by
    io.xmlPartMaxBytes
     will not trigger an error.
Use the setting to constrain the use of
API 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. Value must 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
API Gateway
 restart to take effect. To restart the listener, edit and save the MQ Native configuration.
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 [
Inbound Options
] tab of MQ Native Queue Properties. (2) Changes require a listener or
API 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
API 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. Value must be >= 5.
Default:
25
Changes require a
API 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 requires a listener or
API 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 restarting SFTP polling listeners.
sftpPolling.listenerThreadLimit
The global limit on the number of processing threads that can be created to work off all SFTP polling listeners. Value must be greater 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
    API 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 Gateway starts. You need a sufficient number of HTTP listeners running at initialization time for good performance. However too many listeners will 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 traffice for the system.
Maximum concurrency (set by io.httpMaxConcurrency) specified the maximum number of HTTP listeners. The Gateway will not allow more HTTP listeners to be created, which will result in queued requests if there are insufficient HTTP listeners. However, creating additional listeners will 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 will offset 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 will use more system resources are used 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.

Content feedback and comments