How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I use the Support Extract tool in DS 5.x and 6 to capture troubleshooting data?

Last updated Apr 14, 2022

The purpose of this article is to provide information on using the Support Extract tool to capture troubleshooting information from external and AM embedded instances of DS which includes: all log files, monitoring information (cn=monitor), stack thread dumps, process thread information (top/prstat output), configuration details (including keystore aliases) and system node information. This tool and the provided alternate scripts for DS 5.x and 6 can be used on Linux®, Unix®, Solaris®, and Microsoft® Windows® systems.


Overview

The external Support Extract tool is available for pre-DS 6.5 and can be used for collecting troubleshooting information for DS across Linux, Unix, Solaris and Microsoft Windows systems. In addition, alternative scripts and manual commands are provided in case you experience issues using the Support Extract tool.

In summary, the following tools, scripts and commands are available:

Option Command Version Language Operating System Description
External Support Extract tool supportextract 4.0.4 Java Linux, Unix, Solaris and Microsoft Windows

Preferred option since the data it collects is the most comprehensive for troubleshooting:

Support Extract script opendj-support-script.sh  2.8 Shell Linux, Unix and Solaris

Can be used if you're having issues collecting data using the Java-based Support Extract. Collects a subset of the data collected by the Java-based Support Extract:

Support Extract PowerShell script opendj-support-powershell.ps1  1.5 PowerShell Microsoft Windows

Can be used if you're having issues collecting data using the Java-based Support Extract. Collects a subset of the data collected by the Java-based Support Extract:

Manual Commands -- 2.1 -- Linux, Unix, Solaris and Microsoft Windows

Commands used by the script, which can be run manually to collect data. Use instead of the Java tool or scripts If you are prevented from running third-party tools in your environment or need to know what commands are used prior to executing the scripts:

For DS 6.5 and later, refer to: How do I use the Support Extract tool in DS 6.5.x and 7.x to capture troubleshooting data? for information on using the Support Extract tool. 

About the Support Extract tools, scripts and commands

  External Support Extract tool

  • Your system must have zip or tar/gz tools installed.
  • The Support Extract tool does not alter the current DS install; it only adds a new jar file and scripts.
  • The setup command generates two files in opendj -support-extract-tool/lib _config.sh (Linux, Unix and Solaris) and _config.ps1 (Microsoft Windows). Each file contains the paths to the configuration and to the JVM of the instance.
  • Requires Java 7 or 8. The script will first check to see if the Java jstack or jcmd command can be found; if not, the script will fall back to using kill -3 (Linux/Unix) to get stack traces.
  • The Support Extract tool uses the JVM that DS is configured on. This is set in the java.properties file (located in the /path/to/ds/config directory).
  • Disk usage:
    • Calculates how much disk space is needed to generate the zip archive and aborts if there is insufficient space.
    • Zips the collected data into a zip archive on the fly to optimize its use of disk capacity. However, it is preferable to have it generate the data in a separate partition to the one DS is installed on.
    • Can be configured to restrict the number of logs collected based on a timestamp (--logsAfterDate option) or a maximum number (--maxLogFiles option).
  • Microsoft Windows: If you see the following UnauthorizedAccess error on setup or runtime, you must temporarily bypass the Windows Execution Policy for the current user (Set-ExecutionPolicy Bypass -Scope CurrentUser): PS C:\path\to\opendj-support-extract-tool> .\setup.ps1 .\setup.ps1 : File C:\path\to\opendj-support-extract-tool\setup.ps1 cannot be loaded. The file C:\path\to\opendj-support-extract-tool\setup.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at . At line:1 char:1 + .\setup.ps1 + ~~~~~~~~~~~ + CategoryInfo : SecurityError: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess

See the following sections for further information:

Support Extract script (Linux, Unix and Solaris)

  • The system must have zip or tar/gz tools installed.
  • Your system must have top (Linux/Unix) or prstat (Solaris) installed that can use the following parameters to gather diagnostic data for performance or high CPU issues:
    • top:$ top -H -b -n 1 -p ${pid}
    • prstat: $ prstat -L -n 100 -p ${pid}

See Running the Support Extract script (Linux, Unix and Solaris) for further information.

Support Extract PowerShell script (Microsoft Windows)

See Running the PowerShell script (Microsoft Windows) for further information.

Manual commands

  • Linux
    • The system must have zip or tar/gz tools installed.
    • The manual commands can only be used with self-contained instances that do not use a separate instance.loc path.
    • Your system must have top installed that can use the following parameters: $ top -H -b -n 1 -p ${pid}

See Running the manual Linux commands for further information.

  • Microsoft Windows
    • The manual commands can only be used with self-contained instances that do not use a separate instance.loc path.

See Running the manual PowerShell commands for further information.

Using the External Support Extract tool (Linux, Unix and Solaris)

  1. Download the opendj-support-extract-tool.zip file and unzip.
  2. Change to the /path/to/opendj-support-extract-tool directory: $ cd /path/to/opendj-support-extract-tool
  3. Run the setup command to install the tool and provide the location of the DS server configuration: $ ./setupEnsure the path to JAVA_HOME for the JDK is correct; if you need to correct the path, just specify it without /jre, for example: Enter the path to the configuration directory  [/opt/opendj/config]: /opt/DJ1/config  In order fot the tool to work properly, it needs to run the same Java Virtual Machine Release as the Server.   The tool detected this path: "/usr/lib/jvm/jdk1.8.0_112/jre"  Please confirm this is the correct path [n/Y]: n  Please enter the path to Java Home Directory: /usr/lib/jvm/jdk1.8.0_112                          The tool configuration has been succesfully installed, you can now run "supportextract"
  4. Change to the /path/to/opendj-support-extract-tool/bin directory: $ cd /path/to/opendj-support-extract-tool/bin
  5. Run the Support Extract tool as follows depending on whether you are using external or embedded DS (see Support Extract Tool options for information on the available options):
    • External DS: $ ./supportextract --bindDN "cn=Directory Manager" --bindPassword password --outputDirectory /path/to/output/directory
    • Embedded DS: you must specify the server PID of the AM server using the --serverPID option: $ ./supportextract --bindDN "cn=Directory Manager" --bindPassword password --serverPID 2806 --outputDirectory /path/to/output/directory

Runtime example: (External DS) with GC logging not enabled (if you have not set the JVM flags to enable GC logging in the java.properties file, you will see an informational message before the script completes):$ ./supportextract --bindDN "cn=Directory Manager" --bindPassword `cat passfile` --outputDirectory /opt/data/ --maxLogFiles 5 2021-10-25 09:00:53 INFO VERSION: 4.0.4-external 2021-10-25 09:00:53 INFO BUILD: 2e8480e 2021-10-25 09:00:53 INFO The external Support Extract is supported with this Directory Server version. 2021-10-25 09:00:53 INFO The instance is running 2021-10-25 09:00:54 INFO Collecting the monitoring info from cn=monitor 2021-10-25 09:00:55 INFO Collecting process statistics 2021-10-25 09:00:55 INFO  * Generating stack dump, sample number : 1 using jcmd for pid 16677 2021-10-25 09:00:56 INFO    * Generating stack dump, sample number : 2 using jcmd for pid 16677 2021-10-25 09:00:57 INFO    * Generating stack dump, sample number : 3 using jcmd for pid 16677 2021-10-25 09:00:58 INFO    * Generating stack dump, sample number : 4 using jcmd for pid 16677 2021-10-25 09:01:00 INFO    * Generating stack dump, sample number : 5 using jcmd for pid 16677 2021-10-25 09:01:01 INFO    * Generating stack dump, sample number : 6 using jcmd for pid 16677 2021-10-25 09:01:02 INFO    * Generating stack dump, sample number : 7 using jcmd for pid 16677 2021-10-25 09:01:03 INFO    * Generating stack dump, sample number : 8 using jcmd for pid 16677 2021-10-25 09:01:04 INFO    * Generating stack dump, sample number : 9 using jcmd for pid 16677 2021-10-25 09:01:06 INFO    * Generating stack dump, sample number : 10 using jcmd for pid 16677 2021-10-25 09:01:07 INFO   Collecting the configuration files 2021-10-25 09:01:07 INFO   - Adding config.ldif 2021-10-25 09:01:07 INFO   - Adding admin-backend.ldif 2021-10-25 09:01:07 INFO   - Adding rootUser.ldif 2021-10-25 09:01:07 INFO   - Adding java.properties 2021-10-25 09:01:07 INFO   - Adding tasks.ldif 2021-10-25 09:01:07 INFO   - Adding build info 2021-10-25 09:01:07 INFO   - Adding schema files 2021-10-25 09:01:07 INFO   - Adding archived configs 2021-10-25 09:01:07 INFO   - Adding HTTP configuration file(s) 2021-10-25 09:01:07 INFO   - Listing the security stores 2021-10-25 09:01:07 INFO     * config/keystore 2021-10-25 09:01:07 INFO     * db/ads-truststore/ads-truststore 2021-10-25 09:01:07 INFO   Collecting system node information 2021-10-25 09:01:07 INFO   - OS information 2021-10-25 09:01:07 INFO   - Network information 2021-10-25 09:01:07 INFO   - Disk information 2021-10-25 09:01:07 INFO   - Processor information 2021-10-25 09:01:07 INFO   - Linux Release 2021-10-25 09:01:07 INFO   - Linux /proc info files 2021-10-25 09:01:07 INFO     * Adding cpuinfo 2021-10-25 09:01:07 INFO     * Adding meminfo 2021-10-25 09:01:07 INFO     * Adding slabinfo 2021-10-25 09:01:07 INFO     * Adding buddyinfo 2021-10-25 09:01:07 INFO   Collecting ChangelogDb information 2021-10-25 09:01:07 INFO    - Adding files list 2021-10-25 09:01:07 INFO   Collecting backend statistics 2021-10-25 09:01:07 INFO    - userRoot: total jdb files 1 2021-10-25 09:01:07 INFO    - Adding je.info.0, je.config.csv and je.stat.csv 2021-10-25 09:01:07 INFO   Collecting the log files 2021-10-25 09:01:07 INFO    * /opt/600/logs/ldap-access.audit.json * 2021-10-25 09:01:07 INFO    * /opt/600/logs/http-access.audit.json * 2021-10-25 09:01:07 INFO    * /opt/600/logs/errors * 2021-10-25 09:01:07 INFO    * /opt/600/logs/replication * 2021-10-25 09:01:07 INFO    * /opt/600/logs/server.out * 2021-10-25 09:01:07 INFO   Skipping GC Logging. "not enabled" The following archive has been created : /opt/data/opendj-support-data-20211025-090053.zip

  1. Attach the generated zip archive to your ticket.

Using the External Support Extract tool (Microsoft Windows)

  1. Download the opendj-support-extract-tool.zip file and unzip.
  2. Change to the C:\path\to\opendj-support-extract-tool directory: $ cd C:\path\to\opendj-support-extract-tool
  3. Run the setup.ps1 command to install the tool and provide the location of the DS server configuration: $ .\setup.ps1Ensure the path to JAVA_HOME for the JDK is correct; if you need to correct the path, just specify it without \jre. When setting up the Extract on Microsoft Windows for the first time, set the OPENDJ_HOME environment variable using quotes, for example: Enter the path to the configuration directory  [C:\opendj\config]: C:\DJ1\config  In order for the tool to work properly, it needs to run the same Java Virtual Machine Release as the Server.   The tool detected this path: "C:\Program files\Java\jdk1.8.0_112\jre"  Please confirm this is the correct path [n/Y]: n  Please enter the path to Java Home Directory: "C:\Program files\Java\jdk1.8.0_112"                          The tool configuration has been succesfully installed, you can now run "supportextract"
  4. Change to the C:\path\to\opendj-support-extract-tool\bin directory: $ cd C:\path\to\opendj-support-extract-tool\bin
  5. Create a file named passwordFile that contains the cn=Directory Manager password (password must be ASCII encoded): $ echo "password" | Out-File -Encoding ASCII passwordFile
  6. Run the Support Extract tool as follows depending on whether you are using external or embedded DS (see Support Extract Tool options for information on the available options):
    • External DS: $ .\supportextract.ps1 --bindDN "cn=Directory Manager" --bindPassword .\passwordFile --outputDirectory \path\to\output\directory
    • Embedded DS: you must specify the server PID of the AM server using the --serverPID option: $ .\supportextract.ps1 --bindDN "cn=Directory Manager" --bindPassword .\passwordFile --serverPID 2806 --outputDirectory \path\to\output\directory

Runtime example: (External DS) with GC logging not enabled (if you have not set the JVM flags to enable GC logging in the java.properties file, you will see an informational message before the script completes):$ .\supportextract.ps1 --bindDN "cn=Directory Manager" --bindPassword .\passwordFile --outputDirectory C:\data --maxLogFiles 5 2021-10-25 09:00:53 INFO VERSION: 4.0.4-external 2021-10-25 09:00:53 INFO   BUILD: 2e8480e 2021-10-25 09:00:53 INFO   The external Support Extract is supported with this Directory Server version. 2021-10-25 09:00:53 INFO   The instance is running 2021-10-25 09:00:54 INFO   Collecting the monitoring info from cn=monitor 2021-10-25 09:00:55 INFO   Collecting process statistics 2021-10-25 09:00:55 INFO    * Generating stack dump, sample number : 1 using jcmd for pid 16677 2021-10-25 09:00:56 INFO    * Generating stack dump, sample number : 2 using jcmd for pid 16677 2021-10-25 09:00:57 INFO    * Generating stack dump, sample number : 3 using jcmd for pid 16677 2021-10-25 09:00:58 INFO    * Generating stack dump, sample number : 4 using jcmd for pid 16677 2021-10-25 09:01:00 INFO    * Generating stack dump, sample number : 5 using jcmd for pid 16677 2021-10-25 09:01:01 INFO    * Generating stack dump, sample number : 6 using jcmd for pid 16677 2021-10-25 09:01:02 INFO    * Generating stack dump, sample number : 7 using jcmd for pid 16677 2021-10-25 09:01:03 INFO    * Generating stack dump, sample number : 8 using jcmd for pid 16677 2021-10-25 09:01:04 INFO    * Generating stack dump, sample number : 9 using jcmd for pid 16677 2021-10-25 09:01:06 INFO    * Generating stack dump, sample number : 10 using jcmd for pid 16677 2021-10-25 09:01:07 INFO   Collecting the configuration files 2021-10-25 09:01:07 INFO   - Adding config.ldif 2021-10-25 09:01:07 INFO   - Adding admin-backend.ldif 2021-10-25 09:01:07 INFO   - Adding rootUser.ldif 2021-10-25 09:01:07 INFO   - Adding java.properties 2021-10-25 09:01:07 INFO   - Adding tasks.ldif 2021-10-25 09:01:07 INFO   - Adding build info 2021-10-25 09:01:07 INFO   - Adding schema files 2021-10-25 09:01:07 INFO   - Adding archived configs 2021-10-25 09:01:07 INFO   - Adding HTTP configuration file(s) 2021-10-25 09:01:07 INFO   - Listing the security stores 2021-10-25 09:01:07 INFO     * config\keystore 2021-10-25 09:01:07 INFO     * db\ads-truststore\ads-truststore 2021-10-25 09:01:07 INFO   Collecting system node information 2021-10-25 09:01:07 INFO   - OS information 2021-10-25 09:01:07 INFO   - Network information 2021-10-25 09:01:07 INFO   - Disk information 2021-10-25 09:01:07 INFO   - Processor information 2021-10-25 09:01:07 INFO   Collecting ChangelogDb information 2021-10-25 09:01:07 INFO    - Adding files list 2021-10-25 09:01:07 INFO   Collecting backend statistics 2021-10-25 09:01:07 INFO    - userRoot: total jdb files 1 2021-10-25 09:01:07 INFO    - Adding je.info.0, je.config.csv and je.stat.csv 2021-10-25 09:01:07 INFO   Collecting the log files 2021-10-25 09:01:07 INFO    * C:\opendj\logs\ldap-access.audit.json * 2021-10-25 09:01:07 INFO    * C:\opendj\logs\http-access.audit.json * 2021-10-25 09:01:07 INFO    * C:\opendj\logs\errors * 2021-10-25 09:01:07 INFO    * C:\opendj\logs\replication * 2021-10-25 09:01:07 INFO    * C:\opendj\logs\server.out * 2021-10-25 09:01:07 INFO   Skipping GC Logging. "not enabled" The following archive has been created : C:\data\opendj-support-data-20211025-090053.zip

  1. Attach the generated zip archive to your ticket.

Support Extract Tool options

The following options are available when running the Support Extract tool and can be viewed by running the --help option:

Option Usage
--bindDN

Specify the DN to use for binding to the server.

Mandatory.

--bindPassword

Specify the password to use for binding to the server.

Mandatory unless --bindPasswordFile has been specified instead.

--bindPasswordFile

Specify the file that contains the bind password.

Mandatory unless --bindPassword has been specified instead.

--serverPID

Specify the server PID of the AM server.

Mandatory for embedded DS since there is no PID file when DS is embedded.

--outputDirectory

Specify the directory in which the zip archive should be generated.

Mandatory.

--jdkToolsDirectory

Specify the path to the JAVA_HOME's bin directory where the JStack and other JVM command line utilities reside. This must be the same version as the running server's JVM.

Optional.

--logsAfterDate

Specify the date after which log files should be collected. This option overrides the --maxLogFiles option.

Format: "YYYYMMDDhhmmss", for example: "20220308143612" = 08 March 2022, 14:36 12s.

Optional.

--maxLogFiles

Specify the maximum number of log files to collect. This defaults to 100 and is ignored if the  --logsAfterDate is used.

Optional.

--needJavaHeapDump

Include to produce a Java Heap Dump. If this option is included, the binary file will be generated in the same location as the zip archive before it is added to the archive. Please ensure the selected output directory has sufficient space.

Requesting a JAVA heap dump interacts with the server, and often can have a high impact to the running server, therefore --needJavaHeapDump should only be used when requested by ForgeRock Support.

Optional.

--noAuditFiles

Include to prevent audit files being collected. Audit logs are typically not needed for problem analysis. Unless you need to share audit logs with Support for a specific reason, use this option to omit the files from being collected.

Optional.

--noKeystoreFiles

Include to prevent keystore files being collected.

Optional.

--noServerInteraction

Include to prevent the support extract tool from interacting with the server, which means there will be no LDAP operation or jstack collection. 

If collecting jcmd/jstack samples, and interacting with the server on the Admin port is not acceptable, use the --noServerInteraction option; note that this option is superseded when providing --needJavaHeapDump.

Optional.

--version

Include to display DS version details.

Optional.

Running the Support Extract script (Linux, Unix and Solaris)

  1. Download opendj-support-script.sh and copy it to the /path/to/ds directory: $ cp opendj-support-script.sh /path/to/ds
  2. Change to the /path/to/ds directory: $ cd /path/to/ds
  3. Create a file named passwordFile that contains the cn=Directory Manager password. $ echo "password" > passwordFile
  4. Run the script as follows depending on whether you are using an external or embedded instance (see Options for information on the available options):
    • External DS: $ ./opendj-support-script.sh -D "cn=Directory Manager" -j passwordFile -o /path/to/output/directory
    • Embedded DS: you must specify the server PID of the AM server using the -p option: $ ./opendj-support-script.sh -D "cn=Directory Manager" -j passwordFile -p 2806 -o /path/to/output/directory

Runtime example: (External DS) with GC logging enabled: $ ./opendj-support-script.sh -D "cn=Directory Manager" -j bin/passwordFile -o /opt/instances/frsupport -l 5 -------------------------------------------------------------------------------- ForgeRock Extract Script                       2.8 -------------------------------------------------------------------------------- 2021-03-03 13:54:29 INFO VERSION: 2.8-script 2021-03-03 13:54:29 INFO Using storage bin /opt/instances/frsupport 2021-03-03 13:54:29 INFO The instance is running 2021-03-03 13:54:29 INFO Password File found (bin/pass) 2021-03-03 13:54:29 INFO Collecting the monitoring info from cn=monitor 2021-03-03 13:54:29 INFO Collecting process statistics 2021-03-03 13:54:33 INFO  - Generating stack dump, sample number : 1 using jcmd for pid 7444 2021-03-03 13:54:34 INFO  - Generating stack dump, sample number : 2 using jcmd for pid 7444 2021-03-03 13:54:36 INFO  - Generating stack dump, sample number : 3 using jcmd for pid 7444 2021-03-03 13:54:37 INFO  - Generating stack dump, sample number : 4 using jcmd for pid 7444 2021-03-03 13:54:39 INFO  - Generating stack dump, sample number : 5 using jcmd for pid 7444 2021-03-03 13:54:40 INFO  - Generating stack dump, sample number : 6 using jcmd for pid 7444 2021-03-03 13:54:42 INFO  - Generating stack dump, sample number : 7 using jcmd for pid 7444 2021-03-03 13:54:43 INFO  - Generating stack dump, sample number : 8 using jcmd for pid 7444 2021-03-03 13:54:45 INFO  - Generating stack dump, sample number : 9 using jcmd for pid 7444 2021-03-03 13:54:46 INFO  - Generating stack dump, sample number : 10 using jcmd for pid 7444 2021-03-03 13:54:46 INFO Collecting the monitoring info from cn=monitor 2021-03-03 13:54:52 INFO Collecting the configuration files 2021-03-03 13:54:52 INFO  - Adding config.ldif 2021-03-03 13:54:52 INFO  - Adding admin-backend.ldif 2021-03-03 13:54:52 INFO  - Adding admin-backend.ldif.old 2021-03-03 13:54:52 INFO  - Adding monitorUser.ldif 2021-03-03 13:54:52 INFO  - Adding rootUser.ldif 2021-03-03 13:54:52 INFO  - Adding java.properties 2021-03-03 13:54:52 INFO  - Adding buildinfo 2021-03-03 13:54:52 INFO  - Adding tasks.ldif 2021-03-03 13:54:52 INFO  - Adding schema files 2021-03-03 13:54:52 INFO  - Adding HTTP configuration file(s) 2021-03-03 13:54:52 INFO  - Adding archived config files 2021-03-03 13:54:52 INFO    * total files 1 2021-03-03 13:54:52 INFO  - Listing the security stores 2021-03-03 13:54:52 INFO    * db/ads-truststore/ads-truststore 2021-03-03 13:54:52 INFO    * config/keystore 2021-03-03 13:54:53 INFO Collecting system node information 2021-03-03 13:54:53 INFO  - OS information 2021-03-03 13:54:53 INFO  - Network information 2021-03-03 13:54:53 INFO  - Disk information 2021-03-03 13:54:53 INFO  - Linux /proc info files 2021-03-03 13:54:53 INFO    * Adding cpuinfo 2021-03-03 13:54:53 INFO    * Adding meminfo 2021-03-03 13:54:53 INFO    * Adding slabinfo 2021-03-03 13:54:53 INFO    * Adding buddyinfo 2021-03-03 13:54:53 INFO  - Linux Release 2021-03-03 13:54:53 INFO Collecting backend statistics 2021-03-03 13:54:53 INFO  - userRoot: total jdb files 1 2021-03-03 13:54:53 INFO Collecting ChangelogDb information 2021-03-03 13:54:53 INFO  - No changelogDb data found 2021-03-03 13:54:53 INFO Collecting the log files 2021-03-03 13:54:53 INFO  - errors 2021-03-03 13:54:53 INFO  - replication 2021-03-03 13:54:53 INFO  - ldap-access.audit.json 2021-03-03 13:54:53 INFO  - server.out 2021-03-03 13:54:53 INFO  - server.out.orig 2021-03-03 13:54:53 INFO Capturing GC logging information 2021-03-03 13:54:53 INFO  - /opt/600/logs/gc-pid7423-2021-03-03_13-53-39.log 2021-03-03 13:54:53 INFO  - /opt/600/logs/gc-pid7444-2021-03-03_13-53-40.log 2021-03-03 13:54:53 INFO Capturing status output 2021-03-03 13:55:08 INFO Creating a zip archive 2021-03-03 13:55:08 INFO  - using /usr/bin/zip 2021-03-03 13:55:08 INFO Creating a zip manifest 2021-03-03 13:55:08 INFO Adding the zip manifest 2021-03-03 13:55:08 INFO Removing temp files - /opt/instances/frsupport/support-data/ The following archive has been created : opendj-support-data-20210303-135508.zip (attach this to the ticket)If you do not set the JVM flags to enable GC logging in the java.properties file, you will see the following informational message after the script completes:Note: GC logs were not found. If you have GC logs, update this zip as follows /usr/bin/zip -qu opendj-support-data-20210303-135241.zip <pathto/gclog>

  1. Attach the generated zip archive to your ticket.

Options

The following options are mandatory with this script unless noted and can be viewed by running the -H help option:

Option Usage
-D {bindDN}

Specifies the DN to use for binding to the server. 

Default value: cn=Directory Manager. Defaults to using rootDN (cn=Directory Manager) if -D bindDN is not provided.  If more than one rootDN exists, you must specify one using -D bindDN.

Mandatory.

-w {bindPassword}

Password to use to bind to the server.

Mandatory, unless -j, bindPasswordFile has been specified instead.

-j {bindPasswordFile}

Specify the file that contains the bind password.

Mandatory, unless -w bindPassword has been specified instead.

-p {serverPID}

Specify the server PID of the AM server.

Required for embedded DS indicates the server PID of the OpenAM application server.

-o {outputDirectory}

Specify the directory in which the zip archive should be generated.

Mandatory.

-k 

Keep the temporary support-data files. Use this option if you do not want the temporary files automatically deleted after the Support Extract script runs.

Optional.

-l {maxLogFiles}

Maximum number of log files to collect. Can collect 0 to N log files of each type. 

maxLogFiles of 0 collects no log files except server.out. When omitted, collects all logs.

Optional.

-i {stackInterval}

Interval between stack dump loops in seconds. See SLEEP(1)

Default: 1 second - one per second.  Acceptible values: .25, .33, .5, 1+ 

  • ".25" (1/2 a second) - two per second.
  • ".33" (1/2 a second) - two per second .
  • ".5" (1/2 a second) - two per second.
  • "1" (1 second) - one per second.
  • "5" (5 seconds) - one every five seconds.
  • "10" (10 seconds) - one every ten seconds)

Optional.

-m 

{monitorAfterStacks}

Controls when the monitor data is collected.

Used to trap time-sensitive CPU issues when gathering stacks first, is needed.

If -m is omitted, monitor data is gathered before the stack loop. If -m is used, monitor data is gathered after the stack loop.

Optional.

Running the PowerShell script (Microsoft Windows)

  1. Download opendj-support-powershell.ps1 and copy it to C:\path\to\ds directory: $ copy opendj-support-powershell.ps1 C:\path\to\ds
  2. Change to the C:\path\to\ds directory: $ cd C:\path\to\ds
  3. Create a file named passwordFile that contains the cn=Directory Manager password (password must be ASCII encoded):$ echo "password" | Out-File -Encoding ASCII passwordFile
  4. Run the script as follows depending on whether you are using an external or embedded instance (see Options for information on the available options):
    • External DS: PS C:\path\to\opendj-support-powershell.ps1 -D "cn=Directory Manager" -j passwordFile -o C:\data
    • Embedded DS: you must specify the server PID of the AM server using the -p option: PS C:\path\to\opendj-support-powershell.ps1 -D "cn=Directory Manager" -j passwordFile -p 2806 -o C:\data

Runtime example: (External DS):PS C:\opendj> .\opendj-support-powershell.ps1 -D "cn=Directory Manager" -j .\passwordFile -o C:\data -l 5 -------------------------------------------------------------------------------- ForgeRock Extract Powershell - 1.5 -------------------------------------------------------------------------------- 2021-03-03 13:54:29 INFO  VERSION: 1.5-powershell 2021-03-03 13:54:29 INFO    * Using storage bin C:\data\support-data 2021-03-03 13:54:29 INFO    * The instance is running (PID 2360) 2021-03-03 13:54:29 INFO    * Password File found (C:\opendj\passwordFile) 2021-03-03 13:54:29 INFO    * Using rootDN (cn=Directory Manager) 2021-03-03 13:54:29 INFO    * Collecting the monitoring info from cn=monitor (4444) 2021-03-03 13:54:29 INFO    * Collecting process statistics 2021-03-03 13:54:29 INFO      - Skipping, Windows system 2021-03-03 13:54:52 INFO    * Collecting the configuration files 2021-03-03 13:54:52 INFO      - Adding config.ldif 2021-03-03 13:54:52 INFO      - Adding admin-backend.ldif 2021-03-03 13:54:52 INFO      - Adding rootUser.ldif 2021-03-03 13:54:52 INFO      - Adding java.properties 2021-03-03 13:54:52 INFO      - Adding buildinfo 2021-03-03 13:54:52 INFO      - Adding tasks.ldif 2021-03-03 13:54:52 INFO      - Adding schema files 2021-03-03 13:54:52 INFO      - Adding HTTP configuration file(s) 2021-03-03 13:54:52 INFO      - Adding archived config files 2021-03-03 13:54:52 INFO        * total files 1 2021-03-03 13:54:52 INFO      - Listing the security stores 2021-03-03 13:54:52 INFO        * config/keystore 2021-03-03 13:54:52 INFO        * config/truststore not available 2021-03-03 13:54:52 INFO        * config/admin-keystore not available 2021-03-03 13:54:52 INFO        * config/admin-truststore not available 2021-03-03 13:54:52 INFO        * db\ads-truststore\ads-truststore 2021-03-03 13:54:53 INFO    * Collecting backend statistics 2021-03-03 13:54:53 INFO      - userRoot: total jdb files 1 2021-03-03 13:54:53 INFO    * Collecting system node information 2021-03-03 13:54:53 INFO      - Adding OS information 2021-03-03 13:54:53 INFO      - Adding Network information 2021-03-03 13:54:53 INFO      - Adding Disk information 2021-03-03 13:54:53 INFO      - Adding Processor information 2021-03-03 13:54:53 INFO    * Collecting ChangelogDb information 2021-03-03 13:54:53 INFO      - No changelogDb data found 2021-03-03 13:54:53 INFO    * Collecting the log files 2021-03-03 13:54:53 INFO      - access [5 files] 2021-03-03 13:54:53 INFO      - errors [5 files] 2021-03-03 13:54:53 INFO      - replication [5 files] 2021-03-03 13:54:53 INFO      - server.out [1 file] 2021-03-03 13:54:53 INFO      - ldap-access.audit.json [5 files] 2021-03-03 13:54:53 INFO    * Capturing GC logging information 2021-03-03 13:54:53 INFO    * Capturing status output 2021-03-03 13:55:08 INFO    * Creating a zip archive 2021-03-03 13:55:08 INFO    * Removing temp files - C:\data\support-data The following archive has been created : opendj-support-data-20210303-135508.zip (attach this to the ticket)

  1. Attach the generated zip archive to your ticket.

Options

The following options are mandatory with this script and can be viewed by running the -H help option:

Option Usage
-D {bindDN}

Specifies the DN to use for binding to the server. 

Default value: cn=Directory Manager. Defaults to using rootDN (cn=Directory Manager) if -D bindDN is not provided. If more than one rootDN exists, you must specify one using -D bindDN.

Mandatory.

-w {bindPassword}

Password to use to bind to the server.

Mandatory, unless -j, bindPasswordFile has been specified instead.

-j {bindPasswordFile}

Specify the file that contains the bind password.

Mandatory, unless -w bindPassword has been specified instead.

-p {serverPID}

Specify the server PID of the AM server.

Required for embedded DS indicates the server PID of the OpenAM application server.

-o {outputDirectory}

Specify the directory in which the zip archive should be generated.

Mandatory.

-l {maxLogFiles}

Maximum number of log files to collect. Can collect 0 to N log files of each type. 

maxLogFiles of 0 collects no log files with the exception of server.out  When omitted, collects all logs.

Optional.

Running the manual Linux commands

You can manually run the Linux commands either directly from the command line or from within an executable file. The executable file option is recommended if you prefer to display the data in a simple output when running manual commands; it displays the data from all printf directives in formatted text, to standard output.

The manual commands do the following:

  • Capture a cn=monitor ldapsearch.
  • Issue a kill -3 to generate a stack dump in the logs/server.out log file. This will not kill or otherwise harm the running process.
  • Gather CPU usage per thread of the process, for example: -H -b -n 1 -p ${pid}
  • Zip the above data including all needed logs and config files.

Run from command line

Follow this process on each requested server and ensure to run the commands locally from within the instance:

  1. Change to the /path/to/ds directory: $ cd /path/to/ds
  2. Create a file named passwordFile that contains the cn=Directory Manager password: $ echo "password" > passwordFile
  3. Copy and paste the following into the terminal: export jstackdate=`date "+%Y%m%d-%H%M%S"` export date=`date "+%Y-%m-%d %H:%M:%S"` export pid=`cat ./logs/server.pid | awk '{print $1}'` export instancepath=$PWD export outputDirectory="support-data" export log="${outputDirectory}/supportextract.log" mkdir -p ${outputDirectory}/processStats ${outputDirectory}/monitor ${outputDirectory}/changelogDbInfo ${outputDirectory}/config/schema ${outputDirectory}/logs printf "%s\t%s\n" "${date} INFO" "VERSION: 2.1-manualcommands" | tee -ai $log printf "%s\t%s\n" "${date} INFO" "Collecting the monitoring info from cn=monitor" | tee -ai $log bin/ldapsearch --port 4444 --useSsl --trustAll --bindDN "cn=Directory Manager" --bindPasswordFile passwordFile --baseDN "cn=monitor" --searchScope sub "(objectClass=*)" > $outputDirectory/monitor/monitor.ldif for index in {1..10}; do printf "%s\t%s\n" "${date} INFO" " - Generating stack dump, sample number : ${index}" | tee -ai $log; kill -3 ${pid} && top -H -b -n 1 -p ${pid} > $outputDirectory/processStats/top-${index}.txt; sleep 5; done touch $outputDirectory/processStats/jstackdump${jstackdate}-1.txt printf "%s\t%s\n" "${date} INFO" "Collecting ChangelogDb information" | tee -ai $log if [ -r ${instancepath}/changelogDb/domains.state ]; then ls -laR ./changelogDb/* > ./changelogDbInfo/changelogDb.listing cp ./changelogDb/domains.state ${outputDirectory}/changelogDbInfo/ fi printf "%s\t%s\n" "${date} INFO" "Collecting the configuration files" | tee -ai $log ln -s ${instancepath}/config/config.ldif ${outputDirectory}/config/config.ldif if [ -r ${instancepath}/db/admin/admin-backend.ldif ]; then ln -s ${instancepath}/db/admin/admin-backend.ldif ${outputDirectory}/config/admin-backend.ldif ln -s ${instancepath}/db/admin/admin-backend.ldif.old ${outputDirectory}/config/admin-backend.ldif.old ln -s ${instancepath}/db/tasks/tasks.ldif ${outputDirectory}/config/tasks.ldif else ln -s ${instancepath}/config/admin-backend.ldif ${outputDirectory}/config/admin-backend.ldif ln -s ${instancepath}/config/tasks.ldif ${outputDirectory}/config/tasks.ldif fi ln -s ${instancepath}/config/buildinfo ${outputDirectory}/config/buildinfo ln -s ${instancepath}/config/java.properties ${outputDirectory}/config/java.properties ln -s ${instancepath}/config/schema/* ${outputDirectory}/config/schema/ ln -s ${instancepath}/db/rootUser/rootUser.ldif ${outputDirectory}/config/rootUser.ldif ln -s ${instancepath}/db/rootUser/rootUser1.ldif ${outputDirectory}/config/rootUser1.ldif ln -s ${instancepath}/db/monitorUser/monitorUser.ldif ${outputDirectory}/config/monitorUser.ldif ln -s ${instancepath}/db/monitorUser/monitorUser1.ldif ${outputDirectory}/config/monitorUser1.ldif ln -s ${instancepath}/db/schema/* ${outputDirectory}/config/schema/ printf "%s\t%s\n" "${date} INFO" "Collecting the log files" | tee -ai $log ln -s ${instancepath}/logs/*access* ${outputDirectory}/logs/ ln -s ${instancepath}/logs/*errors* ${outputDirectory}/logs/ ln -s ${instancepath}/logs/*replication* ${outputDirectory}/logs/ ln -s ${instancepath}/logs/server.out ${outputDirectory}/logs/server.out ln -s ${instancepath}/logs/*gc* ${outputDirectory}/logs/ printf "%s\t%s\n" "${date} INFO" "Collecting backend statistics" | tee -ai $log for backend in `ls db`; do dbFileCount=`ls db/$backend/*.jdb 2>&1 | wc -l | awk '{print $1}'`; printf "%s\t%s\n" "${date} INFO" " - ${backend}: total jdb files ${dbFileCount}" | tee -ai $log; done export zipdate=`date "+%Y%m%d-%H%M%S"` printf "%s\t%s\n" "${date} INFO" "Creating a zip archive" | tee -ai $log zip -rpq ./opendj-support-data-${zipdate}.zip $outputDirectory/ printf "%s\t%s\n" "${date} INFO" "Creating a zip manifest" unzip -l ./opendj-support-data-${zipdate}.zip >> ./supportextract.manifest zip -qu ./opendj-support-data-${zipdate}.zip ./supportextract.manifest rm -rf ${outputDirectory} printf "\n%s %s\n" "The following archive has been created :" "opendj-support-data-${zipdate}.zip (attach this to the ticket)"
  4. Attach the generated zip archive to your ticket.

Run from within an executable file

You can run the manual commands from within an executable file as follows:  

  1. Change to the /path/to/ds directory: $ cd /path/to/ds
  2. Create a file named passwordFile that contains the cn=Directory Manager password: $ echo "password" > passwordFile
  3. Create a file called opendj-support-manualcommands.sh
  4. Copy and paste the Unix shell commands (above) between blank newlines into the opendj-support-manualcommands.sh file.
  5. Change permissions to make the file executable: $ ./chmod +x opendj-support-manualcommands.sh
  6. Execute the file to run the commands: $ ./opendj-support-manualcommands.sh
  7. Attach the generated zip archive to your ticket.

Running the manual PowerShell commands

Follow this process on each requested server and ensure to run the commands locally from within the instance:

  1. Change to the C:\path\to\ds directory: $ cd C:\path\to\ds
  2. Create a file named passwordFile that contains the cn=Directory Manager password (password must be ASCII encoded): $ echo "password" | Out-File -Encoding ASCII passwordFile
  3. Copy and paste the following into the terminal: cls; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "VERSION: 2.1-manualcommands"; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Using storage bin C:$env:outputDirectory\support-data"; New-Item -ItemType directory -Path $env:outputDirectory\support-data | Out-Null; New-Item -ItemType directory -Path $env:outputDirectory\support-data\logs | Out-Null; New-Item -ItemType directory -Path $env:outputDirectory\support-data\config | Out-Null; New-Item -ItemType directory -Path $env:outputDirectory\support-data\monitor | Out-Null; New-Item -ItemType directory -Path $env:outputDirectory\support-data\changelogDbInfo | Out-Null; New-Item -ItemType directory -Path $env:outputDirectory\support-data\processStats | Out-Null; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Collecting the monitoring info from cn=monitor"; .\bat\ldapsearch --port 4444 --useSsl --trustAll --bindDN "cn=Directory Manager" --bindPasswordFile passwordFile --baseDN "cn=monitor" --searchScope sub "(objectClass=*)" > $env:outputDirectory\support-data\monitor\monitor.ldif; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Collecting ChangelogDb information"; Get-ChildItem -Path changelogDb -Recurse | Out-File -Encoding ASCII $env:outputDirectory\support-data\changelogDbInfo\changelogDb.listing; If(Test-path changelogDb\domains.state) { Get-Content -Path .\changelogDb\domains.state | Out-File -Encoding ASCII $env:outputDirectory\support-data\changelogDbInfo\domains.state }; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Collecting the configuration and schema files"; If(Test-path config\config.ldif) {copy config\config.ldif $env:outputDirectory\support-data\config}; If(Test-path config\admin-backend.ldif) {copy config\admin-backend.ldif $env:outputDirectory\support-data\config}; If(Test-path db\adminRoot\admin-backend.ldif) {copy db\adminRoot\admin-backend.ldif $env:outputDirectory\support-data\config}; If(Test-path config\buildinfo) {copy config\buildinfo $env:outputDirectory\support-data\config}; If(Test-path config\java.properties) {copy config\buildinfo $env:outputDirectory\support-data\config}; If(Test-path config\tasks.ldif) {copy config\tasks.ldif $env:outputDirectory\support-data\config}; If(Test-path db\tasks\tasks.ldif) {copy config\db\tasks.ldif $env:outputDirectory\support-data\config}; If(Test-path config\schema) {copy -Recurse config\schema $env:outputDirectory\support-data\config}; If(Test-path db\schema) {copy -Recurse db\schema $env:outputDirectory\support-data\config}; If(Test-path config\rest2ldap) {copy -Recurse config\rest2ldap $env:outputDirectory\support-data\config}; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Collecting the log files"; If(Test-path logs) {Get-ChildItem -path logs access* | Copy-Item -destination $env:outputDirectory\support-data\logs}; If(Test-path logs) {Get-ChildItem -path logs errors* | Copy-Item -destination $env:outputDirectory\support-data\logs}; If(Test-path logs) {Get-ChildItem -path logs replication* | Copy-Item -destination $env:outputDirectory\support-data\logs}; If(Test-path logs) {Get-ChildItem -path logs ldap-access.audit.json* | Copy-Item -destination $env:outputDirectory\support-data\logs}; If(Test-path logs) {Get-ChildItem -path logs server.out | Copy-Item -destination $env:outputDirectory\support-data\logs}; If(Test-path logs) {Get-ChildItem -path logs *gc* | Copy-Item -destination $env:outputDirectory\support-data\logs}; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Collecting backend statistics"; Get-ChildItem db | ForEach-Object -Process { $dbFileCount = (Get-ChildItem -path db/$_ *.jdb | Measure-Object).Count; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host " - $_ : total jdb files $dbFileCount"; }; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Capturing status output"; .\bat\status.bat --bindDN "cn=Directory Manager" --bindPasswordFile passwordFile --trustAll | Out-File -Encoding ASCII $env:outputDirectory\support-data\status.out; $Source = "$env:outputDirectory\support-data"; $destination = "$env:outputDirectory\opendj-support-data-$(get-date -f yyyyMMdd-HHmmssffff).zip"; If(Test-path $destination) {Remove-item $destination}; Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Creating a zip archive"; Add-Type -assembly "system.io.compression.filesystem"; [io.compression.zipfile]::CreateFromDirectory($Source, $destination); Write-Host -NoNewLine (Get-Date -Format "yyyy-MM-dd HH:mm:ss")" INFO "; Write-Host "Removing temp files - $env:outputDirectory\support-data"; Remove-Item $env:outputDirectory\support-data -Recurse; Write-Host ""; Write-Host "The following archive has been created : C:$env:outputDirectory\opendj-support-data-$(get-date -f yyyyMMdd-HHmmssffff).zip (attach this to the ticket)"

Runtime example: (External DS):2021-03-03 13:54:29 INFO VERSION: 2.1-manualcommands 2021-03-03 13:54:29   INFO Using storage bin C:\support-data 2021-03-03 13:54:29   INFO Collecting the monitoring info from cn=monitor 2021-03-03 13:54:35   INFO Collecting ChangelogDb information 2021-03-03 13:54:35   INFO Collecting the configuration and schema files 2021-03-03 13:54:35   INFO Collecting the log files 2021-03-03 13:54:35   INFO Collecting backend statistics 2021-03-03 13:54:35   INFO   - userRoot: total jdb files 1 2021-03-03 13:54:35   INFO Capturing status output 2021-03-03 13:54:52   INFO Creating a zip archive 2021-03-03 13:54:53   INFO Removing temp files - \support-data The following archive has been created : C:\opendj-support-data-20210303-135508.zip (attach this to the ticket)

  1. Attach the generated zip archive to your ticket.

See Also

What versions of DS are compatible with AM?

Troubleshooting DS

How do I enable Garbage Collector (GC) Logging for DS?

How do I collect JVM data for troubleshooting DS (All versions)?

How do I use cn=monitor entry in DS 5.x and 6.x for monitoring?

How do I collect data for troubleshooting high CPU utilization on DS (All versions) servers?

How do I find which thread is consuming CPU in a Java process in DS (All versions)?

How do I ensure DS (All versions) uses the Java settings from java.properties file when starting?

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.