Configuration parameters

To accommodate varied workloads and deployments of IBM® z/OS® Connect , the default configuration parameters might need to be changed.

For optimum performance of IBM z/OS Connect , consider the following configuration parameters:

Java heap size, MEMLIMIT, and REGION

Refer to Threads, Java heap, MEMLIMIT, REGION for advice on sizing the heap, and setting the MEMLIMIT and REGION values.

Connections

It is important to configure connections between components carefully to provide optimum performance. For example,
  • Persistent connections
  • Client connections into IBM z/OS Connect
  • Connections from IBM z/OS Connect to SORs for API provider
  • Connections from CICS®, IMS, or a z/OS application to IBM z/OS Connect for API requester
  • Connections from IBM z/OS Connect to remote API endpoints for API requester
Persistent connections
Establishing connections between components, for example, a client and a IBM z/OS Connect server, or a IBM z/OS Connect server and Db2®, can be costly, particularly if a TLS/SSL handshake is involved. However, with persistent connections (also known as keep-alive), subsequent requests on the same connection are much cheaper because persistent connections reduce the need for regular handshakes.

Client connections into IBM z/OS Connect
Most clients that connect to a IBM z/OS Connect server support HTTP/HTTPS 1.1, which has the HTTP option keepAliveEnabled set to true by default to enable persistent connections. In an HA environment, consider setting the HTTP option maxKeepAliveRequests in your server.xml file to a value such as 1000. This setting will force the connection to drop after 1000 requests and create a new one to allow workload balancing to happen across multiple servers. The default for maxKeepAliveRequests is -1, which means that the maximum number of persistent requests on a single HTTP connection is unlimited. This default setting might impact your workload balancing. For very low workload volumes, you might want to set the HTTP option persistTimeout value in your server.xml file to a value longer than the default of 30 seconds. This value sets the time that a connection is allowed to remain idle between requests on a persistent connection. Increasing this value allows the socket to remain idle for longer between requests, saving setup and tear down costs of connections. For more information about configuring HTTP options, see https://www.ibm.com/docs/en/was-liberty/base?topic=configuration-httpoptions in the WebSphere Application Server Liberty documentation.

Connections from IBM z/OS Connect to SORs for API provider
All connections to an SOR are persistent by default. For CICS, IMS, IMS DB, and IBM MQ, this persistence cannot be overridden. For Db2 connections, you can override persistent connections by setting the Java keepAlive property to false. However, this setting impacts performance because a new connection must be acquired for each request. The establishment of a connection during the initial request to an SOR is always more costly compared to subsequent requests. This difference is due to acquiring a socket and negotiating security. SORs might also handle connections differently. For example,
  • IPIC connections to CICS remain established unless explicitly released by using a CICS command.
  • Connections to IMS remain established unless agedTimeout is configured. When you configure your connection to IMS, the maxPoolSize in the Connection Factory definition in the IMS connection profile Connection Factory must not exceed the maximum number of sockets (MAXSOC) configured in IMS Connect as described in Managing the number of sockets to avoid possible socket errors and performance problems. You should consider all the connections to IMS Connect, including those from your IBM z/OS Connect servers, when configuring these values. The default value for maxPoolSize in the IMS connection profile Connection Factory definition is 50.
  • For connections to Db2, you can use the Java override http.maxConnections to set the number of cached keep-alive connections per outbound destination. If connections remain idle, you should also be aware of the idle timeout that is hardcoded in Db2:
    • With Db2 V12 PTF PH29621 applied, an idle connection will time out after 15 seconds of inactivity.
    • Without Db2 V12 PTF PH29621 applied, an idle connection will time out after just 5 seconds of inactivity.
  • The IBM MQ service provider uses a pool of JMS connections to connect to queue managers. To avoid performance problems, ensure that the pool is sized correctly for the number of requests that are sent to IBM MQ. For more information, see Configuring connection pooling for JMS connections in the WebSphere® Application Server Liberty documentation.
Connections from CICS, IMS, or z/OS applications to IBM z/OS Connect for API requester
Connections from CICS, z/OS applications, and IMS batch are persistent. Persistent connections are not supported for other IMS environments. This restriction is because the static storage used by the BAQCSTUB to keep the connection handle cannot be reused between different invocations of the same program in a single address space.

Connections from IBM z/OS Connect to remote API endpoints for API requester
For outbound HTTP/1.1 connections from IBM z/OS Connect to a remote API endpoint, you can use the Java override, http.maxConnections, to set the number of cached keep-alive connections per outbound destination. The default value for http.maxConnections is 5 per destination, and can be set as a JVM option for the server. For most installations this default value is sufficient. Do not use a value lower than 5. It requires http.keepalive to be enabled to support persistent connections. The default for http.keepalive is true for outbound requests from IBM z/OS Connect , but requires the remote API endpoint to also have http.keepalive set to true for persistent connections to be supported.

How to confirm that a TLS connection is persistent
To confirm whether your configuration is using persistent TLS connections, in a test environment, enable debug trace by adding the following line in the Java options for your IBM z/OS Connect server 
-Djavax.net.debug=ssl,handshake,verbose
then make a couple of requests (the first to establish the connection and run the request, the second to make a request), and review the output (either STDOUT or messages.log file) searching for %% trace messages. For example, for requests coming into IBM z/OS Connect , the initial call shows the following trace messages:
%% No cached client session
%% Initialized: [Session-1, SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384]
%% Cached client session: [Session-1, SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384]
The second call is made before the cached connection times out and shows the following trace messages:
%% Client cached [Session-1, SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384]
%% Try resuming [Session-1, SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384] from port 41293
%% Server resumed [Session-1, SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384]
This trace extract shows that the second call reused ("resumed") a cached connection, proving that the TLS connection is persistent.

Executor threads
You can limit the requests coming into IBM z/OS Connect by configuring the number of Liberty executor threads in server.xml. For more information about executor threads, see Threads, Java heap, MEMLIMIT, REGION.

AsyncIO
By default, the IBM z/OS Connect server uses a Java™ implementation to handle incoming TCPIP requests. To obtain improvements in performance and scalability in many environments, you can enable the Asynchronous TCP/IP sockets I/O for Liberty (AsyncIO) on z/OS service to take advantage of native z/OS services. Enable the Angel process, and issue a RACF® (or equivalent) command to permit your IBM z/OS Connect server to use the authorized AsyncIO service (ZOSAIO). For more information, see Configuring the Liberty Angel process and z/OS authorized services. When enabled, the following messages are written to the IBM z/OS Connect messages log:
CWWKB0103I: Authorized service group ZOSAIO is available.
CWWKO0229I: Native Asynchronous I/O support for z/OS has been activated.

LPA libraries

To improve performance, some IBM MQ load modules need to be added to the Link Pack Area (LPA). These modules are: SCSQAUTH and SCSQANLx (where x is the language letter, e.g. E).

For more information, see https://www.ibm.com/docs/en/ibm-mq/9.2?topic=mq-update-zos-link-list-lpa in the IBM MQ documentation.

Other configuration settings

To avoid impacting the performance of your IBM z/OS Connect server, be aware of the following configuration settings:
Security authentication
By default, IBM z/OS Connect uses client certificate authentication and attempts to map the provided client certificate to a user ID. If requests to this server require basic authentication and not client certificate authentication, the default authentication method can be overridden by configuring <webAppSecurity overrideHttpAuthMethod="BASIC"/> in the server.xml file. Third-party authentication requests are not affected by this configuration setting as these take precedence over basic authentication and client certificate authentication. For more information, see API provider authentication and identification and API requester basic authentication to IBM z/OS Connect.

Lightweight Third-Party Authentication (LTPA) tokens
LTPA is a proprietary authentication technology that is used by Liberty z/OS and other IBM products. When multiple Liberty z/OS servers are configured to use LTPA, it is possible to enable SSO so that clients can reuse their login to access all the servers.
When LTPA is used, a token is created that contains the user information, an expiration time, and the signature of an LTPA key. The LTPA token passes between the client application and the Liberty server as a cookie when SSO is enabled. IBM z/OS Connect supports the use of LTPA for authentication and SSO. However, it is more common to use an open authentication token such as a JWT.
Warning: The default expiration time of an LTPA token is 2 hours. If the user is then re-authenticated, a new LTPA token is created. If you use the same default expiration time for multiple servers that were all started at the same time, the LTPA tokens will all expire at the same time, possibly causing a degradation in performance as the user is re-authenticated and a new token created. Consider setting expiration times so that when a token expires, this re-authentication process occurs at a suitable time for your environment. Also, it is not advisable to set a long expiry time as it could cause a security exposure. For more information, see Configuring LTPA in Liberty.

Polling
IBM z/OS Connect supports the polling of resources for updates such as APIs, services, API requesters, and other configuration changes. Depending on your polling rate, polling can use high levels of CPU, so disable polling in a production system. If you need to update your server.xml file in a production environment, use the modify refresh command. For more information, see Configuration updates on demand. Furthermore, by default, Liberty makes a poll request every 500 ms. To disable continuous polling, include the following lines in the server.xml configuration file:
<!-- applicationMonitor is not applicable for z/OS Connect servers -->
<applicationMonitor updateTrigger="disabled" dropinsEnabled="false"/>

Trace
Running with trace enabled impacts performance. In a production system, do not configure or enable trace. If you need trace to help debug a problem, then consider binary trace, which has less impact to performance than standard trace. For more information, see Enabling trace in IBM z/OS Connect server.