IBM Support

Collecting "TLS" traces for App Connect Enterprise

How To


Summary

App Connect Enterprise (ACE) uses OpenSSL and Java™ Secure Socket Extension (JSSE) for the securing connectivity over HTTP, SOAP and general TCP.
The Integration Node HTTP listener and the embedded listener in the Integration Servers use OpenSSL for inbound (server) connections.
The HTTPRequest and SOAPRequest nodes use JSSE for outbound (client) connections.

Use these processes to capture a "TLS" trace of OpenSSL to provide to IBM Support for analysis.
For outbound connections, please use a JSSE trace, instead.

Steps

For an Integration Server's embedded HTTP Listener, TLS tracing is configured from the setting 'EnableTLSTrace' in the 'server.conf.yaml' file.
  1. Locate the Integration Server's server.conf.yaml file.
  2. Locate the section 'ResourceManagers'.
  3. Locate the subsection 'HTTPSConnector'.
  4. Locate the setting 'EnableTLSTrace'. 
    ResourceManagers:
  ...
  HTTPSConnector:
    ...
    # EnableTLSTrace: false # Enables tracing of TLS handshake messages to the console
  5. Update the line by setting the value from "false" to "true" and unsetting any comment characters. 
    ResourceManagers:
  ...
  HTTPSConnector:
    ...
    EnableTLSTrace: true # Enables tracing of TLS handshake messages to the console
  6. Save the updated file.
  7. Restart the Integration Server to pick up the new setting.
The trace can be disabled by changing the value back to 'false', saving the file, and restarting the Integration Server.
For an Integration Node's HTTP Listener, TLS tracing is configured from the setting 'EnableTLSTrace' in the 'node.conf.yaml' file.
  1. Locate the Integration Node's node.conf.yaml file.
  2. Locate the section 'NodeHttpListener'.
  3. Locate the subsection 'HTTPSConnector'.
  4. Locate or add the setting 'EnableTLSTrace'. 
    NodeHttpListener:
  ...
  HTTPSConnector:
    ...
    # EnableTLSTrace: false # Enables tracing of TLS handshake messages to the console
  5. Update the line by setting the value from "false" to "true" and unsetting any comment characters. 
    NodeHttpListener:
   ...
   HTTPSConnector:
     ... 
     EnableTLSTrace: true # Enables tracing of TLS handshake messages to the console
  6. Save the updated file.
  7. Restart the Integration Node to pick up the new setting.
The trace can be disabled by changing the value back to 'false', saving the file, and restarting the Integration Node.
Output location
TLS trace is written to the standard output location or console output in the object's work directory:
(Standalone Integration Server) {WORK-DIR}/
(Node-owned Integration Server) {MQSI_WORKPATH}/components/{Int.Node}/{Int.Server}/
(Integration Node Listener) {MQSI_WORKPATH}/components/{Int.Node}/
On Linux and UNIX®, the file is named 'biphttplistener.stdout' for the Node level or 'stdout' for the Server level.
On Windows, the file is named 'console.txt'.
In a container, the trace is written to the container or pod logs.

Additional Information

SSL and TLS are protocols for authentication of servers and clients and serve as a means to encrypt communication using public key encryption.  These protocols involve a 'handshake' between the two machines.  This handshake can encounter errors, commonly referred to as a handshake failure.  The failure can occur for different reasons and the error message may not clarify what the problem was.  This trace will show the various steps in the handshake which can be used to find the cause of the failure.
JSSE is the only implementation for IBM Integration Bus.  
In App Connect Enterprise, JSSE only applies to outbound connections through request nodes, and some times client defined connections in Java.  
This does not apply to inbound connections through input nodes which use OpenSSL.  
For outbound connections, please use a JSSE trace, instead.

Document Location

Worldwide

[{"Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSDR5J","label":"IBM App Connect Enterprise"},"ARM Category":[{"code":"a8m0z0000001jNSAAY","label":"ACE-\u003ESecurity"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions","Type":"MASTER"}]

Document Information

Modified date:
31 March 2023

UID

ibm16204907

Page Feedback