Upgrade Considerations

Important considerations for upgrading to this version of PingDataSync Server:

  • This release introduces significant changes to the manner in which servers in a topology are configured with information about each other. After a server has been upgraded from a pre-7.0 version to 7.0 or later, reverting to the previous version is not supported. Before beginning the upgrade process, read "Upgrading the Server" in the PingDataSync Server Administration Guide.
  • SCIM 2 error responses, including Config API error responses, now represent the status field as a JSON string rather than as a number. Clients that are written to expect the earlier version format must be updated. In particular, clients written by using the SCIM 2 SDK for Java need to upgrade to version 2.2.0 or later.
  • The Administrative Console now uses server information from the topology registry to populate its server selection control. If the Console is used to manage a legacy server that does not use the topology registry, the server selection control is not populated. To manage a different server, an administrator must log off from the Console and provide the other server's connection details from the logon page.

What's New

The following features are new with this release of PingDataSync Server:

  • Simplified management tasks that are related to configuring servers in a large cluster topology or in an automated deployment. Most notably, servers can now be added to a cluster while other servers are offline.
  • Added management features for SSL and TLS certificates. The default certificates that are used in inter-server replication can be replaced, validation of client certificates for HTTPS-based services (like the SCIM REST API) can be configured, and you can reload from the trust store for HTTPS client certificates without restarting the server or the HTTP-based services.
  • Added support for the following operating system versions:

    • Ubuntu LTS 16.04
    • CentOS 7.4
    • RedHat Linux 7.4
    • SUSE Enterprise 12 SP3

Known Issues and Workarounds

The simultaneous cloning of multiple PingDirectoryProxy, PingDataSync, and PingDataGovernance Servers from another server of the same type is not currently possible.

Workaround: To create multiple server instances that are identical to a master server, clone the instances one at a time.

Resolved Issues

The following issues have been resolved with this release of PingDataSync Server:

Ticket ID Description

Added the ability to generate administrative alert notifications whenever a task satisfies the following conditions:

  • Starts running
  • Completes successfully
  • Fails to complete successfully

Also added the ability to send an email message to a specified set of users when a task starts running or completes successfully. This functionality complements the existing ability to send an email message when a task fails to complete successfully or when it completes with any state, regardless of success or failure.


Added support for recurring tasks, which can be used to invoke certain kinds of administrative tasks automatically, based on a specified schedule.

At present, only certain kinds of tasks can be scheduled as recurring tasks, including backups and LDIF exports, each of which provides retention support to limit the amount of disk space that the backups and LDIF files consume. It also includes support for any kind of task in which each instance of the task uses exactly the same values for all of the task-specific attributes. Additionally, the Server SDK provides an API for creating custom third-party recurring task implementations.


Implemented invocation logging for several server tools, which write to logs/tools/tool-invocation.log by default upon startup and shutdown. Log entries record the following information:

  • The tool's start and completion times
  • Command-line arguments used to initialize them
  • Name of the system account used to launch the tool

To modify this behavior, edit the config/tool-invocation-logging.properties file.

DS-4570, DS-14281, DS-14282, DS-14283, DS-14284, DS-17197, DS-17366 The admin backend and the tool used to manage it, dsframework, have been replaced by the topology registry and dsconfig, respectively. The topology registry is mirrored automatically across all servers in a topology, so administrative information is synchronized on all servers at all times.
DS-6970 Added support for encrypted logging by using a key that is generated from an encryption settings definition. Encrypted log files can be decrypted by using the encrypt-file tool.
DS-12157, DS-35896

Made the following improvements to backend backup and restore, as well as to LDIF export and import:

  • Added the ability to encrypt backups and LDIF exports with a key generated from one of the following sources:

    • User-supplied passphrase
    • Encryption settings definition

    Previously, encrypted backups and LDIF exports used only a secret key that was known solely to servers within the replication topology. The new options simplify the processes of restoring encrypted backups and importing encrypted LDIF files in servers outside the replication topology. The encrypt-file utility can be used to decrypt encrypted backups and LDIF exports, regardless of the manner in which the encryption key was obtained.

  • Added the ability to limit the rate at which backups and LDIF exports are written to disk, which helps to avoid performance problems that result from these operations saturating the disk subsystem.
  • Added new global configuration properties for automatically encrypting backups and LDIF exports by default. If data encryption is enabled during setup, these properties are set automatically to true.
  • Added new global configuration properties that can specify the encryption settings definitions that are used to obtain encryption keys for backups and LDIF exports that are encrypted automatically. If no encryption settings definitions are specified, the server uses its preferred encryption settings definition or, if no encryption settings definitions are available, an internal topology key.
  • Added a new configuration property for compressing encrypted LDIF exports automatically.
  • Updated the backup tool to add the following arguments, which can be used to specify which key to use for encrypting a backup:

    • --promptForEncryptionPassphrase
    • --encryptionPassphraseFile
    • --encryptionSettingsDefinitionID

    Added a --doNotEncrypt argument that forces a backup to remain unencrypted even if automatic encryption is enabled.

    Added a --maxMegabytesPerSecond argument that imposes a limit on the rate at which a backup can be written to disk.

  • Updated the restore tool to add the following arguments, which can be used to provide a user-supplied passphrase when accessing the contents of an encrypted backup:

    • --promptForEncryptionPassphrase
    • --encryptionPassphraseFile

    For backups that are encrypted with an encryption settings definition or an internal topology key, the server can determine the correct key automatically.

  • Updated the export-ldif tool to add the following arguments, which can be used to specify which key to use for encrypting the export:

    • --promptForEncryptionPassphrase
    • --encryptionPassphraseFile
    • --encryptionSettingsDefinitionID

    Added a --doNotEncrypt argument that forces an LDIF export to remain unencrypted even if automatic encryption is enabled.

    Added a --maxMegabytesPerSecond argument that imposes a limit on the rate at which an LDIF file can be written to disk.

  • Updated the import-ldif tool to add the following arguments, which can be used to provide a user-supplied passphrase when accessing the contents of an encrypted LDIF export:

    • --promptForEncryptionPasshprase
    • --encryptionPassphraseFile

    Although the --isEncrypted and --isCompressed arguments are no longer necessary because the tool detects encryption and compression automatically, they remain available to preserve backward compatibility. Further, the tool can automatically identify the appropriate key for exports that are encrypted with a key obtained from an encryption settings definition or an internal topology key.

DS-15223, DS-35895

Added the ability to configure data encryption during setup by using a key that is obtained by any of the following methods:

  • Random generation
  • Generated from a user-supplied passphrase
  • Obtained from an export of another server's encryption settings database

When setting up multiple instances, if the same encryption passphrase is provided to each instance, then all instances share the same encryption key.

The encryption-settings tool has also been updated, as follows:

  • Encryption settings definitions can be created from passphrases.
  • Descriptions can be provided when encryption settings definitions are created.
  • Create timestamps can be recorded for new definitions.

Additionally, you can create ciphers that use the Galois Counter Mode (GCM) cipher mode (for example, a cipher transformation of AES/GCM/PKCS5Padding) for authenticated encryption. Definitions that are created with a cipher algorithm but without a transformation now use stronger settings.

The default encryption settings export format also provides stronger encryption. Newer server instances can cleanly import encryption settings that other servers have exported. To export encryption settings for import into earlier servers, use the --use-legacy-export-format argument.

DS-16508 Updated the dsconfig list subcommands to list objects of all complexity levels rather than requiring the --advanced flag to list advanced and expert objects.
DS-17347 Fixed a class loader issue where Sync Source extensions that were written using the Server SDK threw a ClassNotFound exception when importing classes not included in the PingDataSync Server base classpath.
DS-17543 Sync Pipe plugins can now be enabled for specific Sync Classes when creating or editing a Sync Class. As before, Sync Pipe plugins that are enabled on the Sync Pipe also run for all associated Sync Classes. If plugins are enabled on the Sync Pipe as well as an associated Sync Class, the plugins on the Sync Pipe run before the plugins on the Sync Class.
DS-17891 Added a manage-certificates tool that performs multiple functions related to TLS certificate management.

The update tool enforces the specification of a new product license when updating to a new major version. To specify a license, perform either of the following steps:

  • Use the --licenseKeyFile command-line options.
  • Copy the license file to the top-level directory of the server package that is used to perform the update.
Important: To request a license, visit the Ping Identity licensing website or contact sales@pingidentity.com.
DS-35536 Support for the IBM JDK has been retired.
DS-35576 Updated the JMX connection handler's monitor provider so that when a JMX connection is closed, it is removed from the list of established connections. After a JMX client disconnects, the server might require a few minutes to detect the closure and to update the monitor.
DS-35581 Updated the server to include an instance of the Periodic Stats Logger plugin that is enabled by default to aid in diagnosing support issues. The Historical Stats Logger plugin logs performance statistics to logs/monitor-history/historical-dsstats.csv every five minutes. This process works in concert with the Monitor History plugin, which logs the full contents of cn=monitor to logs/monitor-history every five minutes. The output that collect-support-data generates also includes the tail of the .csv file automatically.
DS-35583 Fixed a defect in which configuring PingDirectory Server on a Windows machine with a space in the home directory pathname caused the server setup to fail.
DS-35601 Added a new Monitor Entry for SSL Cipher Suite and Protocol information. The new entry is available under cn=SSL Context,cn=monitor.
DS-35648 Added a missing double-quote to bat/transform-ldif.bat, which prevented the command from being invoked successfully on Windows systems.
DS-35727, DS-35728 Updated setup to include key usage, extended key usage, and subject alternative name extensions in the self-signed certificates that it generates.
DS-35868 The create-systemd-script command now suggests placing the script created in /etc/systemd/system.

Provided the means to request that the server dynamically reload the certificate key and trust stores used by all HTTP connection handler instances that provide support for HTTPS. To make such a request, use one of the following tasks, tools, or methods:

  • A reload HTTP connection handler certificates task
  • The reload-http-connection-handler-certificates tool
  • The ServerContext#reloadHTTPConnectionHandlerCertificates method (to make the request programmatically from a Server SDK extension)
DS-36000 Added the PingOne for Customers Sync Destination for Ping Data Sync. Identities can now be synchronized from on-premises identity stores to PingOne for Customers.
DS-36054 Added an encrypt-file tool that can encrypt and decrypt data with a user-supplied passphrase, an encryption settings definition, or a topology key that is shared among server instances. encrypt-file includes support for decrypting content in encrypted backups, LDIF exports, and log files.
DS-36070 Fixed an issue with compressed logging that could leave data buffered in memory and not actually written out to disk until the logger is closed.
DS-36075 Updated tools that interact with log or LDIF files to support reading from input files that are compressed and encrypted, and to support writing to compressed and encrypted output files.
DS-36088 In addition to specifying an exact set of cipher suites for the LDAP and HTTP Connection Handlers, administrators can now specify inclusions to, or exclusions from, the set of cipher suites that the server selects.
DS-36093 Added support for TLS1.2 with STARTLS to connect to an SMTP server.
DS-36198 Updated the SCIM Sync Destination to always send credentials preemptively when configured to use HTTP basic authentication.
DS-36326 Fixed a compatibility issue when PingFederate was used as a SCIM Sync Destination, and a PingFederate Server's SCIM schema response that contained the schema for the User resource type could not be parsed.
DS-36328 Updated the server to reduce contention when converting between strings and the bytes that comprise them.
DS-36360 Increased the default size of the queue that holds alert notifications so that they can be processed asynchronously by a background thread. When many alerts are generated in a short period of time, this change reduces the probability of the queue becoming full, and prevents the blocking of subsequent alerts while the server catches up. Also updated the server to log a message when the queue becomes full, so that administrators are made aware of the problem and are provided with suggestions for addressing it.
DS-36466 Fixed an issue in which the password attribute could be deleted when PingDataSync Server was used with an Active Directory Sync Source.
DS-36545 Added a sanitize option to the Monitor History plugin that, if enabled, redacts the small amount of potentially personally identifiable information that could appear in search filters and LDAP DNs within the monitor. This fix facilitates the sharing of monitor history files with the support team in secure environments.