PingAuthorize

Working with the collect-support-data tool

If a problem occurs with PingAuthorize Server, you should first run the collect-support-data tool in the server’s bin directory.

The server provides detailed insights into its current state, including any processing issues. The collect-support-data tool compiles relevant support files and diagnostic data, such as outputs from the jps, jstack, and jstat utilities, into a .zip archive for administrators to share with their authorized support provider.

Although the collect-support-data tool tries to collect the same data across all systems for the target PingAuthorize Server, the resulting data might vary between operating systems. The collected data includes the configuration directory, summaries and snippets from the logs directory, monitor entry status, and a list of all files in the server root.

By default, the collect-support-data tool excludes log files that might contain sensitive customer information, including the debug logs described in Enable detailed logging. If you are using test data that doesn’t include sensitive information, send the following log files along with collect-support-data's compressed output file:

  • PingAuthorize/logs/policy-decision.log

  • PingAuthorize/logs/debug-trace.log

  • PingAuthorize/logs/debug.log

  • PingAuthorize/logs/policy-query.log

To prevent the support .zip archive from exceeding e-mail attachment size limits, the collect-support-data tool might only archive portions of certain log files.

Running the collect-support-data tool

Steps

  1. Run the collect-support-data tool.

    Make sure to include the host, port number, bind DN, and bind password.

    Example:

    <PingAuthorize>/bin/collect-support-data \
  --hostname <host> \
  --port <port> \
  --bindDN "cn=<dn>" --bindPassword <password>

  2. Email the generated .zip archive to your authorized support provider.

Invoking the collect-support-data tool as a recurring task

To automatically invoke collect-support-data on a regular basis, create and configure a recurring task.

  • Admin console

  • dsconfig

Use the administrative console

Steps

  1. Go to System > Recurring Tasks.

  2. In the New Recurring Task list, select Collect Support Data Recurring Task.

  3. In the Name field, enter a name for the recurring task.

  4. In the Output Directory field, enter the path of the directory in which support data archive files will be placed.

  5. Do at least one of the following:

    • In the Retain Previous Support Data Archive Count field, enter the number of previous support data archives that PingAuthorize Server should preserve after generating a new archive.

    • In the Retain Previous Support Data Archive Age field, enter the minimum age of previous support data archives that PingAuthorize Server should preserve after generating a new archive. Values for this property should consist of an integer followed by a time unit. For example, a value of 1w specifies that PingAuthorize Server should preserve support data archives for one week.

  6. Configure the rest of the recurring task to meet your business needs.

  7. Click Save.

Use dsconfig

Steps

  • Run dsconfig with the create-recurring-task subcommand and the following options and parameters:

    <PingAuthorize>/bin/dsconfig create-recurring-task \
  --task-name <your-task-name> \
  --type collect-support-data \
  --set output-directory:<your-directory-path> \
  --set retain-previous-support-data-archive-count:<count>

    You must include at least one of the following parameters in your command:

    • retain-previous-support-data-archive-count: Specifies the number of previous support data archives that PingAuthorize Server should preserve after generating a new archive.

    • retain-previous-support-data-archive-age: Specifies the minimum age of previous support data archives that PingAuthorize Server should preserve after generating a new archive. Values for this property should consist of an integer followed by a time unit. For example, a value of 1w specifies that PingAuthorize Server should preserve support data archives for one week.

Server commands used in the collect-support-data tool

The following presents a summary of the data collectors that the collect-support-data tool archives in .zip format. If an error occurs during processing, you can re-run the specific data collector command and send the results to your authorized support provider.

Data Collector Description

status

Run status -F to show the full version information of PingAuthorize Server (Unix, Windows).

server-state

Run server-state to show the current state of the PingAuthorize Server process (Unix, Windows).

JDK commands used in the collect-support-data tool

Data Collector Description

jps

Java Virtual Machine Process status tool. Reports information on the JVM (Linux, Windows, Mac OS).

jstack

Java Virtual Machine Stack Trace. Prints the stack traces of threads for the Java process (Linux, Windows, Mac OS).

jstat

Java Virtual Machine Statistics Monitoring Tool. Displays performance statistics for the JVM (Linux, Windows, Mac OS).

jinfo

Displays the Java configuration information for the Java process (Linux, Windows, Mac OS).

Linux commands used in the collect-support-data tool

Data Collector Description

tail

Displays the last few lines of a file. Tails the /var/logs/messages directory.

uname

Prints system, machine, and operating system information.

ps

Prints a snapshot of the current active processes.

df

Prints the amount of available disk space for file systems in 1024-byte units.

cat

Concatenates the following files and prints to standard output:

  • /proc/cpuinfo

  • /proc/meminfo

  • /etc/hosts

  • /etc/nsswitch.conf

  • /etc/resolv.conf

netstat

Prints the state of network interfaces, protocols, and the kernel routing table.

ifconfig

Prints information on all interfaces.

uptime

Prints the time the server has been up and active.

dmesg

Prints the message buffer of the kernel.

vmstat

Prints information about virtual memory statistics.

iostat

Prints disk I/O and CPU utilization information.

mpstat

Prints performance statistics for all logical processors.

pstack

Prints an execution stack trace on an active processed specified by the pid.

top

Prints a list of active processes and how much CPU and memory each process is using.

MacOS commands used in the collect-support-data tool

Data Collector Description

uname

Prints system, machine, and operating system information.

uptime

Prints the time the server has been up and active.

ps

Prints a snapshot of the current active processes.

system_profiler

Prints system hardware and software configuration.

vm_stat

Prints machine virtual memory statistics.

tail

Displays the last few lines of a file. Tails the /var/log/system.log directory.

netstat

Prints the state of network interfaces, protocols, and the kernel routing table.

ifconfig

Prints information on all interfaces.

df

Prints the amount of available disk space for file systems in 1024-byte units.

sample

Profiles a process during an interval.

Available tool options

The following options are available for the collect-support-data tool:

--noLdap

Specifies that no information should be collected over LDAP. Use this option only if the server is completely unresponsive or won’t start, and only as a last resort.

--pid <pid>

Specifies the ID of an additional process from which information should be collected. This is a useful option for troubleshooting external server tools, and you can specify it multiple times for each external server.

--sequential

Use this option to troubleshoot Out of Memory errors. By default, the collect-support-data tool collects data in parallel to minimize the collection time necessary for some analysis utilities. This option specifies that data collection should be run sequentially rather than in parallel. Specifying this option reduces the initial memory footprint of the collect-support-data tool but increases the time required for completion.

--reportCount <count>

Specifies the number of reports generated for commands that support sampling (for example, vmstat, iostat, or mpstat). If you specify a value of 0, no reports are generated for these commands. If you don’t provide this option, the number of reports generated defaults to 10.

--reportInterval <interval>

Specifies the number of seconds between reports for commands that support sampling (for example, mpstat). You must specify a value greater than 0 for this option. If you don’t provide this option, the number of seconds between reports defaults to 1.

--maxJstacks <number>

Specifies the number of jstack samples to collect. If you don’t provide this option, the number of samples collected defaults to 10.

--collectExpensiveData

Specifies that data for expensive or long-running processes should be collected. To prevent negative impact on server performance, data for these processes are not collected by default.

--comment <comment>

Allows provisioning of additional information about the collected data set. The comment you provide will be added to the generated archive as a README file.

--includeBinaryFiles

Specifies that binary files should be included in the archive collection. By default, all binary files are excluded from data collection.

--outputPath

Specifies the path (and optionally, the name) for the support data archive file. If the path specifies a filename, the archive is written to that file. If the path specifies a directory, the file is written to that directory with a server-generated name.

--useRemoteServer

Invokes the collect-support-data tool against a remote server instance and streams the output and resulting support data archive back to the client. This is a useful option when the server instance is running in a container, as it might otherwise be difficult to invoke commands or access files in that container.