PingAM

Troubleshoot installations

Debug logging

AM can capture information in debug log files that are useful when troubleshooting AM problems. Debug logging describes how to enable debug logging after AM has been started.

It’s also possible to capture debug logs while installing AM. This can be useful if you need to troubleshoot an installation problem.

Follow these steps to capture debug logs while installing AM on Tomcat:

  1. If Tomcat is already started, stop it.

  2. Specify the -Dcom.iplanet.services.debug.level=message option in the CATALINA_OPTS environment variable:

    $ export CATALINA_OPTS=-Dcom.iplanet.services.debug.level=message

    There are several ways that you can specify the CATALINA_OPTS environment variable. You can set the variable:

    • In the /path/to/tomcat/bin/setenv.sh file

    • In the login shell of the user who runs Tomcat

  3. Run the AM installation. Debug log files containing troubleshooting information appear in the /path/to/am/var/debug directory.

  4. When you have completed the AM installation and no longer need to capture debug logs, stop Tomcat, revert the debug logging options, and restart Tomcat.

SSL connection issues

Connection issues during an AM installation are often caused by certificate or truststore misconfigurations.

Example connection error

The following error is seen when AM can’t connect to DS during the installation:

AMSetupServlet.processRequest: error com.sun.identity.setup.ConfiguratorException: Cannot connect to Directory Server, the error was: Client-Side Timeout

Perform the following steps to troubleshoot connection issues:

  1. Check you can connect to the DS server by running the following openssl command with the hostname:port of your DS server:

    $ openssl s_client -connect ds.example.com:1636 -showcerts

    The output from this command confirms that you can establish a secure connection to the DS server independent of AM. If you can connect, the command returns the entire certificate chain for DS.

  2. Check the AM truststore contains the DS CA certificate by running the following keytool command:

    $ keytool -list -v -keystore /path/to/truststore -storetype jks -storepass password

    This command returns the contents of the truststore so you can check it includes the DS CA certificate.

  3. Enable SSL debugging on Tomcat by adding the -Djavax.net.debug=SSL,handshake,trustmanager JVM option.

    To do this, add the following debug option to the setenv.sh file and restart Tomcat:

    export CATALINA_OPTS="$CATALINA_OPTS -Djavax.net.debug=ssl,handshake,trustmanager"

    The SSL debug logs are written to catalina.out. They provide detailed information about the SSL handshake process to help you identify where the issue is occurring.

    Learn more about this option in Debugging Utilities in the Java documentation.

  4. When you have completed the AM installation and no longer need to capture SSL debug logs, stop Tomcat, revert the SSL debugging option, and restart Tomcat.