IBM Support

MustGather: SSL problems on WebSphere Liberty

Troubleshooting


Problem

This document describes the process for collecting data for problems with the IBM WebSphere® Application Server Liberty SSL component. Gathering this MustGather information before you call IBM support can help you understand the problem and save time analyzing the data.

Resolving The Problem


Runtime:
This document describes how to obtain the following troubleshooting data for the SSL component:
image-20240227081129-1 Trace from server startup and Liberty configuration (server dump zip file)
image-20240227081129-1 Java configuration information (java.security)
image-20240227081129-1 Diagnostic questions
image-20240227081129-1 JSSE client-side trace (if requested)
 This document is for collecting data for LIBERTY. If you want to collect data for WebSphere traditional, see MustGather: SSL problems on WebSphere traditional or click on the WebSphere traditional tab above.
   SSL on Liberty trace specifications
image-20240227081209-2 Add the following string to the traceSpecification attribute of the <logging> element in your server.xml file:
SSLChannel=all:com.ibm.ws.ssl.*=all:com.ibm.websphere.ssl=all:com.ibm.wsspi.ssl.*=all
image-20240227081214-3 Insert the following JVM argument in your jvm.options file:
-Djavax.net.debug=all

Avoid Trouble: The jvm.options file requires one entry per line.
  • Collect data for Liberty (step-by-step)

    This section is for collecting data for LIBERTY. If you want to collect data for WebSphere traditional click here or see the WebSphere traditional tab above.

    Before you collect data, be sure to answer the Diagnostic questions in the section above.

    You can choose to follow this step-by-step document or you can watch the video in the Collect data for Liberty (Video) section below.

    SSL issues on Liberty might be difficult to troubleshoot. Make sure to collect all the information below. When all the information for your issue is ready, follow the instructions on Exchanging information with IBM Technical Support for problem determination to send the information and files that you collected.

     

    SET UP LIBERTY FOR SSL TRACING

    1. Set up the JVM for SSL tracing
      1. Locate your jvm.options file
        1. The jvm.options files can be found under the following path:
          <LIBERTY_HOME>/usr/servers/<server name>/jvm.options
          • If the jvm.options file does not exist, create it with a text editor.
        2. Insert the following generic JVM arguments to the jvm.options file:
          -Djavax.net.debug=all
          • Avoid Trouble: There is one entry per line in this file. Make sure you do not have any extra white space in your jvm.options file.
        3. Save the changes to your jvm.options file.
          • Your changes are not be picked up by the JVM until the server is restarted.
    2. Set up the Liberty server for SSL tracing
    3. Verify that your tracing is working as intended
      1. Stop the Liberty Server
      2. Delete any existing logs files found under the logs directory:
        <LIBERTY_HOME>/usr/servers/<serverName>/logs
      3. Restart the Liberty Server and review the logs to confirm that they are recent.
      4. Verify that the new Liberty trace setting are picked up by reviewing the upper part of the trace.log file.
       

      COLLECT LIBERTY SSL TRACES

      Avoid trouble: SSL traces must be gathered from Liberty server startup.
       
      1. Stop the Liberty server
      2. Restart the Liberty server
      3. Reproduce the problem, making note of time when the problem occurs
       

      GATHER LIBERTY DATA TO SEND TO IBM SUPPORT

        • Use the "dump" command to generate a .zip file containing the logs and config files which can be sent to support.
          For Windows platforms, run:
          <LIBERTY_HOME>\bin\server.bat dump <serverName>

          For UNIX platforms, run:
          <LIBERTY_HOME>/bin/server dump <serverName>
        • Collect the resulting dump .zip file with date & time. These files can be found under the following path:
          <LIBERTY_HOME>/usr/servers/<serverName>

          File name example:
          (myserver.dump-17.03.20_22.20.57.zip)
        • Collect the java.security file from your JDK. This file can be found under the following path:
          JAVA_HOME\lib\security\java.security

       
    • Collect data for WebSphere Liberty (video)

      This section is for collecting data for LIBERTY. If you want to collect data for WebSphere traditional click here or see the WebSphere traditional tab above.

      Before you collect data, be sure to answer the Diagnostic questions in the section above.

      You can choose to watch this video or follow the step-by-step instructions in the Collect data for Liberty (step-by-step) section above.

      SSL issues on Liberty might be difficult to troubleshoot. Make sure to collect all the information described in the video. When all the information for your issue is ready, follow the instructions on Exchanging information with IBM Technical Support for problem determination to send the information and files that you collected.

      The following video goes over the necessary steps to collect data for an SSL problem on Liberty.

    •  Diagnostic questions
      Provide answers to the following diagnostic questions:
      1. Are you using the default Java Secure Socket Extension (JSSE) providers?
      2. Are you using any third-party JCE framework with your application?
      3. Where is the SSL issue occurring?
        image-20240227081209-2 When you are using SSL to connect to to a directory server (like LDAP)?
        image-20240227081209-2 When you are using your own application to make an SSL connection?
        If so, provide the exact URL or remote server hostname that is called by your application.
        image-20240227081209-2 Between the client (browser) and the web server?
        For example, when you attempt to access a Web resource on the web server over HTTPS.
        image-20240227081209-2 Between the client (browser) and the Application Server built-in web server?
        For example, when you attempt to access the Application Server administrative console.
        image-20240227081209-2 Between the web server plug-in and the Application Server?
        For example, when you attempt to access a Web resource on the Application Server over HTTPS.
    • image-20240227083647-1 Collect JSSE client-side trace

      JSSE client-side traces are required when you are observing SSL issues with a Java application that is interacting with a running WebSphere Application Server process.

      See the instructions in the Collect JSSE client-side trace section on Setting up a trace in WebSphere Application Server to collect a JSSE client-side trace. 

     
    • Exchange data with IBM Support

      To diagnose or identify a problem, it is sometimes necessary to provide Technical Support with data and information from your system. In addition, Technical Support might also need to provide you with tools or utilities for you to use during problem determination. You can submit files by using one of the following methods to help speed problem diagnosis:

      • Service Request (SR)
      • Email
      • FTP to the Enhanced Customer Data Repository (ECuRep)

      Exchanging information with IBM Technical Support for problem determination

     

    Disclaimer: Remember to revert back the trace once troubleshooting is done, as it may affect the application performance.

    [{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Component":"Security","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF013","label":"Inspur K-UX"},{"code":"PF016","label":"Linux"},{"code":"PF022","label":"OS X"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"9.0;8.5.5;16.0.0.x;17.0.0.x;18.0.0.x;19.0.0.x","Edition":"Liberty","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"}}]

    Document Information

    Modified date:
    27 February 2024

    UID

    swg22003654

    Page Feedback