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:
-
If Tomcat is already started, stop it.
-
Specify the
-Dcom.iplanet.services.debug.level=message
option in theCATALINA_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
-
-
Run the AM installation. Debug log files containing troubleshooting information appear in the
/path/to/am/var/debug
directory. -
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:
-
Check you can connect to the DS server by running the following
openssl
command with thehostname: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.
-
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.
-
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.
-
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.