Upgrade Considerations

Important considerations for upgrading to this version of the PingDirectory Server:

  • The summarize-config tool is deprecated, and will be removed in future versions of the product. Use the config-diff tool with the "sourceBaseline" argument to list a summary of changes to the local server configuration.

What's New

These are new features for this release of the PingDirectory Server:

  • Password Validators now have added properties for user-friendly descriptions and errors, which can be used by client applications to improve user interfaces.

  • The self-service password reset function that uses a one-time password (OTP) is now more streamlined. An OTP token can be sent to an end user through email or SMS, and used for authentication when setting a new password.

  • Added initial support for a JSON object attribute syntax, which can be used for attribute types whose values are JSON objects. Indexing options are currently limited. Please see the full release note below for DS-12138.

Resolved Issues

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

Ticket ID Description

Added the 'listKeysExceedingIndexEntryLimit' argument to the verify-index tool, which enables listing the keys for indexes that have exceeded their index entry limits.


Added the ability to reset user passwords with a single-use, time-limited token that is delivered to the end user through some out-of-band mechanism like SMS or email. After determining the identity of the user for whom the password reset token should be generated, an application can use the new "deliver password reset token" extended operation to cause the server to create and deliver the token to the user. This token can then be provided to the "password modify" extended operation in lieu of the user's current password in order to allow that user to select a new password. Password reset tokens can optionally permit users to reset their passwords even if their account is not usable (for example, because their account is locked or their password is expired).


Added the ability to configure the Globally-Unique Attribute and Unique Attribute plugins with a filter to limit attribute uniqueness checking to a subset of matching entries.


Reduced the memory overhead of debug logging in high throughput environments by sharing logging buffers across multiple threads.


Added features to allow clients to better determine the set of requirements that the server will impose for user passwords. The get password quality requirements extended operation can be used to retrieve information about the requirements before an attempted password change. Those requirements can be conveyed to the end user, and can potentially be used to enable some types of client-side validation to identify problems with a password before it is sent to the server. The password validation details request control can be included in an add request, a modify request, or a password modify extended request to identify which specific validation requirements may not have been met by the password provided in the request.

Password validators can be configured with user-friendly messages that better describe the constraints that the validator will impose for passwords, and that the validator should return if a proposed password does not satisfy those constraints. The server will generate these messages if they are not provided in the configuration.


Updated the Configuration API output where properties and their values are listed to include those that are undefined.


Added support for a JSON object attribute syntax, which can be used for attribute types whose values are JSON objects. The syntax requires that each value of this type is a valid JSON object. Two matching rules have also been added for use in conjunction with the JSON object syntax: jsonObjectExactMatch and jsonObjectFilterExtensibleMatch.

The jsonObjectExactMatch equality matching rule is used in evaluating equality filters in search operations, as well as for matching performed against JSON object attributes for add, compare, and modify operations. It determines whether two values are logically-equivalent JSON objects. The field names used in both objects must match exactly (although fields may appear in different orders). The values of each field must have the same data types. String values will be compared in a case-insensitive manner. The order of elements in arrays will be considered significant.

The jsonObjectFilterExtensibleMatch matching rule can perform more powerful matching against JSON objects. The assertion values for these extensible matching filters should be JSON objects that express the constraints for the matching. These JSON object filters are described in detail in the Javadoc documentation (available in the Commercial Edition of the UnboundID LDAP SDK for Java) for the com.unboundid.ldap.sdk.unboundidds.json.JSONObjectFilter class and its subclasses. Although the LDAP SDK can facilitate searches with this matching rule, these searches can be issued through any LDAP client API that supports extensible matching.

Indexing is supported only for the jsonObjectExactMatch matching rule. If possible, non-baseObject searches that use the jsonObjectFilterExtensibleMatch matching rule should be wrapped in an LDAP AND filter that also contains one or more indexed components so that the search can be processed more efficiently.


The setup tool has been updated to use HTTPS for initial configuration. Unsecure HTTP can be enabled post-setup, or by using non-interactive setup.


Updated the server to automatically monitor and report the length of time each operation spends waiting in the work queue before a worker thread can begin to process it.


The Configuration API has been updated to support filtering, sorting, and paging for object list operations. See the Administration guide for usage.


Updated the local DB backend so that changes to the db-checkpointer-wakeup-interval property no longer require a restart to take effect, and to expose new monitor attributes with useful information about the processing performed by the database cleaner.


Fixed an issue where changes to SMTP External Server configurations did not take effect until after a server restart.


Addressed cases where some messages may be suppressed in logs and alerts.


Changed the default password policy behavior to prevent users from changing their passwords to their current password value. This logic will apply regardless of password history settings.


Added a configuration option to enable a wait period before removing a 'server unavailable' alert after a garbage collection task is performed. This allows sub-systems like replication to restart before the server becomes available again. For the Periodic GC Plugin, this option is 'delay-post-gc.' For a Forced GC Task entry, the attribute is named 'ds-task-delay-post-gc.' Both options take a value in milliseconds, and have a default value equivalent to 20 seconds.


Updated UnboundID work queue processing to log expensive work queue operations and diagnostic thread stack traces when a queue backlog alarm is raised.


Fixed an issue that generated the following error message, but did not impact the current operation: "An unexpected error occurred while notifying a change notification listener of a modify operation: RuntimeException: The specified condition must be true. The error occurred at com.unboundid.directory.server.types.AuthenticationInfo.replaceUserEntries."


Added support for running on Oracle Java 8 and OpenJDK 8 platforms.


Added logging of all HTTP requests disallowed due to CORS. This should make it easier to debug HTTP 403/Forbidden errors.


Updated the server to avoid the use of the server-side sort and virtual list view request controls in search requests that span multiple subtree views or multiple entry-balanced backend sets. If the server cannot honor a non-critical server-side sort or virtual list view control, then it will process the search operation as if the control had not been included in the request. If the server cannot honor a critical server-side sort or virtual list view control, then it will return an error result to the client.


Update the Detailed HTTP Operation Log Publisher to log the correct return code (404 NOT FOUND) when a request is not handled by defined endpoints.


The server can now detect an "out of file handles" situation on the operating system, and shut down to prevent running in an unreliable state.


Added support for three new extended operations for interacting with single-use tokens:

- The "get supported OTP delivery mechanisms" operation provides information about which one-time password delivery mechanisms are configured in the server, and which of those are available for a specified user.

- The "deliver single-use token" operation can generate a token value and provide it to a specified user through an out-of-band communication mechanism like email, SMS, or voice call.

- The "consume single-use token" operation indicates that the user has received a single-use token from the "deliver single-use token" operation, and to consume that token so that it cannot be reused.


Fixed an issue where configuring numeric IPv4 address filtering by connection criteria in a log publisher performed unnecessary reverse host name lookups.


Updated the notification destination cn=monitor entry (objectclass of ds-notification-destination-monitor-entry) to include an attribute, ds-notification-age-of-next-pending-change-seconds, which tracks how out-of-date the destination is in seconds. Values are only maintained on the master server for that domain (ds-notification-master=true). A value of 0 on the master server for that domain indicates that the destination is up-to-date. This attribute can be used in a gauge to generate alarms if a destination gets too far behind.


JDBC external servers now give precedence to settings in the jdbc-driver-url property, over other dsconfig JDBC Managed Object settings for host-name, port, and database-name. The jdbc-driver-url property setting can be used instead of the other JDBC Managed Object settings.


MakeLDIF templates now have the ability to escape special characters curly braces, angle brackets, and square brackets using a backslash. See config/MakeLDIF/examples-of-all-tags.template for further examples.


Fixed a rare condition that might cause the logger rotation and retention thread to exit under heavy file system load or a network file system outage.


Fixed the Local DB Backend configuration help text for deadlock-retry-limit, which incorrectly stated that a value of zero would result in unlimited retry attempts. That value actually results in no retry attempts.


Fixed an issue where the Datastore parsed the last login time value using the wrong time zone. The incorrect time affected password policy decisions and was delivered in the response to a password policy state extended request.


Improved server locking used by dsconfig in offline batch mode, so that the server lock is held for the entire batch duration, instead of for each invocation. Also, reduced the probability of contention for file locks used by server tools to determine the server status.


Fixed an issue in the Server SDK where the ServerContext sendAlert method incorrectly generated a Java RuntimeException when attempting to send a third-party extension alert.