Installing the PingDataMetrics server - PingDirectory - 9.3

PingDirectory 9.3

PingDirectory 9.3
PingDirectory 9.3

This section describes how to install the PingDataMetrics server.


PingDataMetrics will be deprecated in the PingDirectory 10.0 release. For more information about support for versions of PingDirectory containing PingDataMetrics, see Ping Identity's End-of-Life Policy (sign on required).

To monitor and provide statistics for your PingDirectory suite of products, see Monitoring PingDirectory metrics with Splunk.

Click the following tabs to see instructions for the task you want to perform.

Configuring a non-root user

The PingDataMetrics server installer cannot be run as the root user, and generally, the server (and PostgreSQL) should not be run as root.

As a non-root user, network port numbers below 1024 cannot be used.

In general, the account must do the following:

  • Listen on privileged network ports.
  • Bypass restrictions on resource limits.

For security, the account should be restricted from the following:

  • The ability to see processes owned by other users on the system.
  • The ability to create hard links to files owned by other users on the system.

Configuring servers to be monitored

Before installing the PingDataMetrics server, configure the servers to be monitored:

  • PingDirectory server
  • PingDirectoryProxy server
  • PingDataSync server
  • PingAuthorize

The monitored servers require sufficient disk space to store the monitoring data and can be configured with Tracked Applications if there are specific application bind distinguished names (DNs) that should be monitored.

Disk space requirements and monitoring intervals

The metrics backend on the monitored servers is responsible for the temporary storage of metric data and is configured to keep a maximum amount of metric history based on log retention policies, which are configured with the dsconfig command.

The default retention policies define a cap on disk space usage, which in turn determines the amount of metric history retained. If the PingDataMetrics server is stopped for a period of time, the monitored servers should be configured to retain enough metrics history to prevent gaps in data when the PingDataMetrics server restarts. The amount of disk space required for metrics history might also depend on the monitored server's Stats Collector Plugin settings. In general, 500MB is enough to retain an eight-hour span of metrics history.

The value of the sample-flush-interval property of the monitored server's metrics backend determines the maximum delay between when a metric is captured and when it can be picked up by the PingDataMetrics server. The flush interval can be set between 15 and 60 seconds, with longer values resulting in less processing load on the PingDataMetrics server. However, this flush interval increases the latency between when the metric was captured and when it becomes visible in a chart or dashboard. Changing the sample-flush-interval attribute to 60 seconds has the PingDataMetrics server keep 2000 minutes of history.

The number of metrics produced per unit of time varies based on the configuration. No formula can compute exact storage required for each hour of history. However, 60MB per hour is a standard estimate.

Tracked applications

If the PingDataMetrics server monitors client applications associated with the monitored servers, configure the Tracked Applications feature for monitored servers as well.

Activity performed by a particular LDAP bind DN can be associated with a PingDataMetrics server application-name, which in turn can be included in PingDataMetrics server service level agreement (SLA) definitions.

The Processing Time Histogram plugin is configured on each PingDirectory server and PingDirectoryProxy server as a set of histogram ranges. These ranges should be defined identically across all monitored servers. For each monitored server, set the separate-monitor-entry-per-tracked-application property of the processing time histogram plugin to true. Per-application monitoring information appears under cn=monitor. The per-application-ldap-stats property must also be set to per-application-only in the Stats Collector Plugin. For Tracked Application configuration details, see the PingDirectory Server Administration Guide.

The following example sets the required property of the Processing Time Histogram plugin:

$ bin/dsconfig set-plugin-prop \
  --plugin-name "Processing Time Histogram" \
  --set separate-monitor-entry-per-tracked-application:true

The following example sets the required property of the Stats Collector plugin:

$ bin/dsconfig set-plugin-prop \
  --plugin-name "Stats Collector" \
  --set per-application-ldap-stats:per-application-only

Installing the server

Use the setup command to install the server.

The server must be started and stopped by the user who installed it.


A Windows installation requires that the Visual Studio 2010 runtime patch be installed before running the setup command.

  1. Sign on as a user other than root.
  2. Obtain the latest .zip release bundle, as described in Downloading the installation packages, and extract it in a directory owned by this user.
    $ unzip PingData<server-version>.zip
  3. Change to the server root directory.
    $ cd PingData<server>
  4. Run the setup command.
    $ ./setup
  5. To accept the End-User License Agreement, enter yes or press Enter to accept the default.
  6. Read the installation process and prerequisites. Press Enter.
  7. Enter the port number of the PostgreSQL database instance to use to store monitoring or press Enter to accept the default port.
  8. Enter the directory to be used for PostgreSQL data files or press Enter to accept the default.

    The default is pgsql_data.


    If the name entered is a relative path name, it is created in the current working directory.

  9. Enter a name for the database administrative account or press Enter to accept the default.

    The setup command creates a user (role) and database to be used by the PingDataMetrics server. These credentials are strictly for use by this command during this session and are not retained.

  10. Enter and save a password.
  11. Choose the name of the PostgreSQL account to be associated with the PingDataMetrics server historical monitoring data, or press Enter to accept the default.

    The default is metrics.


    The setup command creates this user account using the administrative account specified in step 9.

  12. To enter and confirm a new password, type yes and provide a new password or press Enter to accept the default.
  13. Enter the fully-qualified host name for the server or press Enter to accept the default.
  14. Create the initial root user DN for the server or press Enter to accept the default.
  15. Enter and confirm a password for this account.
  16. Enter the port for HTTPS connection to the Platform APIs or press Enter to accept the default.

    The Platform APIs are the System for Cross-domain Identity Management (SCIM) and the Configuration.

  17. Enter the port on which the PingDataMetrics server accepts LDAP client connections or press Enter to accept the default.
  18. To enable LDAPS, enter yes or press Enter to accept the default of no.
  19. If LDAPS is enabled, enter the port on which the server accepts LDAPS client connections or press Enter to accept the default of 2636.
  20. To enable StartTLS, enter yes or press Enter to accept the default of no.
  21. Select a certificate option for the server.
    • Generate self-signed certificate. This is recommended for testing purposes only.
    • Use an existing certificate located on a Java KeyStore (JKS).
    • Use an existing certificate located on a PKCS12 KeyStore.
    • Use an existing certificate on a PKCS11 token.

    Depending on the option you choose, you might need additional information. If you choose the Java or the PKCS#12 KeyStore, you need the KeyStore path and PIN. If you choose the PKCS#11 token, you need the key PIN.

  22. Select the desired encryption for the directory data, backups, and log files.
    • Encrypt data with a key generated from an interactively provided passphrase. Using a passphrase (obtained interactively or read from a file) is the recommended approach for new deployments, and you should use the same encryption passphrase when setting up each server in the topology.
    • Encrypt data with a key generated from a passphrase read from a file.
    • Encrypt data with a randomly generated key. This is intended for testing, or if you intend to import the resulting encryption settings definition into other instances in the topology.
    • Do not encrypt server data.
  23. Choose an option to assign the amount of memory that the server should allocate to the PingDataMetrics server, or press Enter to accept the default.
  24. When the configuration is complete, press Enter (yes) to start the server.
  25. To install the PingDataMetrics server with the defined parameters, press Enter.
After you install the PingDataMetrics server, access the Metrics landing page at https://host:HTTPS-port/view/index for access to the default dashboards, chart builder tool, and online documentation.