How To

How do I enable debug mode for troubleshooting Amster (All versions)?

Last updated Jan 20, 2019

The purpose of this article is to provide information on enabling debug mode to troubleshoot Amster. It also includes additional debugging options that you can use to increase debug levels and debug SSL issues.


1 reader recommends this article

Enabling debug mode

You can enable debug mode when you start Amster by using the -d option, for example:

$ cd /path/to/amster
$ ./amster -d 

This option outputs debug information to the command line while Amster starts and also when you run any Amster commands within the current session (that is, up until you exit Amster). This output can be quite verbose, so this option should only be used if you are experiencing issues.

Increasing debug output

There are other options you can add when starting Amster to capture additional troubleshooting data. The following options increase the logging level to TRACE to generate more detailed error messages than debug level, adds additional log details such as timestamps and thread names and also redirects the output to a log file (ensure you replace /path/to/logfile.log using the full path to the log file location) :

$ cd /path/to/amster
$ ./amster -d -Dorg.slf4j.simpleLogger.log.org.apache.http=TRACE -Dorg.slf4j.simpleLogger.log.org.forgerock.http=TRACE -Dorg.slf4j.simpleLogger.showThreadName=true -Dorg.slf4j.simpleLogger.showDateTime=true -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE -Dorg.slf4j.simpleLogger.dateTimeFormat="yyyy-MM-dd'T'HH:mm:ss.SSS" -Dorg.slf4j.simpleLogger.logFile=/path/to/logfile.log

The output in the console is even more verbose than the normal debug output, so should only be used when experiencing issues.

Debug level

The debug level (org.slf4j.simpleLogger.defaultLogLevel) is set to DEBUG by default in the Amster script. If you always want the debug level to be TRACE, you can change this option in the script:

  1. Change DEBUG to TRACE for the org.slf4j.simpleLogger.defaultLogLevel option in the Amster script, for example:
    • amster script:
      debug="-agentlib:jdwp=transport=dt_socket,server=y,suspend=$debug_suspend,address=$debug_port -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE"
      
    • amster.bat script:
      debug="-agentlib:jdwp=transport=dt_socket,server=y,suspend=%debug_suspend%,address=%debug_port% -Dorg.slf4j.simpleLogger.defaultLogLevel=TRACE"
      

Now when you start Amster with the -d option, TRACE will be used as the default debug level. 

Enabling SSL debug logging

You can also troubleshoot SSL issues by adding the following line to the Amster script:

SSL="-Djavax.net.debug=all -verbose:class -Djavax.net.ssl.trustStore=/path/to/truststore"

Where /path/to/truststore is the truststore that contains all the SSL certificate chain and server certificates that are used for the SSL/TLS secured connection. For example, this would be $JAVA_HOME/jre/lib/security/cacerts if you are using the default JVM truststore and AM is deployed on Apache Tomcat™ web container.

This line should be added immediately before the final line in the script, for example:

  • amster script:
    SSL="-Djavax.net.debug=all -verbose:class -Djavax.net.ssl.trustStore=/path/to/truststore"
    $JAVA_HOME/bin/java $debug -Djava.awt.headless=true -jar ${DIR}/amster-*.jar $*
    
  • amster.bat script:
    SSL="-Djavax.net.debug=all -verbose:class -Djavax.net.ssl.trustStore=/path/to/truststore"
    "!JAVA_HOME!\bin\java.exe" %debug% -Djava.awt.headless=true -jar %amster_jar% %*
    

Now when you start Amster with the -d option, the debug output will also include SSL debug information. 

Note

You can also use the -Djavax.net.debug=all option when you start Amster if you are experiencing connection issues. See FAQ: Installing and using Amster in AM (Q. How can I troubleshoot my SSL connection if it fails?) for further information.

See Also

FAQ: Installing and using Amster in AM

How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

How do I record troubleshooting information in AM (All versions) and OpenAM 13.x?

Troubleshooting AM/OpenAM and Policy Agents

Using Amster in AM

Amster User Guide

Class SimpleLogger

Related Training

N/A

Related Issue Tracker IDs

N/A



Copyright and TrademarksCopyright © 2019 ForgeRock, all rights reserved.
Loading...