Upgrade Considerations

Important considerations for upgrading to this version of the PingDataMetrics Server:
Note: The product names have been updated to reflect the UnboundID acquisition by Ping Identity. This is a naming and branding change only; the code base is the same as in prior releases and will continue to be maintained into the future.
  • If upgrading the server that was running an older version of the JDK, run the dsjavaproperties --initialize command after the software upgrade to compare the settings of the older JDK with requirements for the new server software. Apply any necessary changes to the upgraded server based on previous performance settings.

  • Due to licensing considerations, the Metrics API no longer supports output of the bitmap charts formats .jpg and .png; data is still available as CSV, XML, and JSON. This does not affect the PingDataMetrics Server dashboards and does not affect the Query Builder.

  • The 6.0 release makes these changes to supported platforms:
    • CentOS 7.2 and RedHat 7.2 are now supported operating system versions.
    • SUSE 11 SP4 is now supported; SUSE 11 SP2 support has been retired.
    • Linux KVM and VMWare ESXi 6.x have been added as supported virtual machine environments.
    • Deprecation of JDKs 7.x. Customers are strongly advised to use JDK 8 with this release. A later release of the platform will remove support for JDK versions 7.x. At that time customers will be required to upgrade to JDK 8.x when upgrading servers. This will apply to all of our JDK flavors (OpenJDK, OracleJDK, IBM JDK) on all platforms.
    • WildFly 9.x (renamed from JBoss) is now a supported application server for all web applications, including the Administrative Console and sample applications. Support for JBoss 7.x has been retired. Tomcat support remains unchanged in this release
  • PBKDF2 is now the default encoding for root passwords. This only affects new installations.

  • In addition to changing the default password storage scheme for root users to PBKDF2, the default password storage scheme for regular users has been changed to salted 256-bit SHA-2.

  • HTTPS defaults to ON: servers now default to use HTTPS for console and API connections including the SCIM API. This may affect automation scripts and development environments where HTTPS has not been in use before.

  • Generated user passwords, for example those created by the server during a password reset sequence, are now created as pass-phrases instead of random character strings. This makes them them easier to type and remember. This change will not affect upgrades.

  • The /config directory file permissions have been changed so that they are only accessible by the server user.

  • Customers who choose to use the optional encryption algorithms provided by the third-party BouncyCastle library are encouraged to upgrade to BouncyCastle 1.54.

What's New

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

  • For Java developers whose tools and workflows make use of Maven, the Server SDK jar has been deployed to Maven Central so that a developer can now add the Server SDK as a project dependency by adding a few lines to a project's pom.xml. Also, developers can now generate a Server SDK project that Maven-aware IDEs such as IntelliJ IDEA can package into an extension bundle with no special configuration needed. This benefit extends similarly to continuous integration systems such as Jenkins.

  • The dsconfig tool provides the ability to search for and quickly navigate to configuration objects and properties in which the name, synopsis, or description matches a provided pattern.

  • A new rotate-log tool and task have been added, which can be used to trigger rotation of one or more log files.

  • The Configuration API is now fully supported for all servers. In this release, the API was changed to match SCIM conventions for attribute naming, resource modeling, and the standard HTTP verbs. The UnboundID SCIM 2 SDK (available through GitHub) can now be used with the Configuration API.

  • All servers have an updated web Administrative Console. This includes the following:
    • New layouts for operational statistics, processing time, queues, all monitors, and the list of installed extensions.
    • Alert and alarm displays, summarizing the data in cn=alerts and cn=alarms and based on the configured gauges. Plus, filtering and searching for these.
    • A new LDAP Schema Editor for importing schema files, validity checking, creation and editing of object classes and attribute types. The editor also supports viewing of the attribute syntaxes, inheritance, and indexes that exist for each attribute and the dependencies between object classes and attributes
  • The new Administrative Console can also be deployed to independent application servers instead of being co-hosted by the servers. This simplifies deployment models and increases separation between data and application layers.

  • To assist with situations where a very large number of changes may cause disk, memory, and server start time to increase unexpectedly, alerting and gauge features have been added to the Recent Changes Database.

  • Servers can now trigger events whenever log file rotation occurs. This includes copy on rotate and summarize on rotate listeners, as well as Server SDK support for creating custom log file rotation listeners.

  • It is now possible to create, change, and remove root user accounts across the topology using the dsconfig tool and Administrative Console.

Known Issues/Workarounds

The following are known issues in the current version of the PingDataMetrics Server:

  • When deploying the Administrative Console in Tomcat 8, and accessing the Administrative Console application using Tomcat's Web Application Manager, some browsers (including Safari and Firefox) will generate a path URL that encodes the dash in ubid-console. This results in a path such as http://localhost:8888/ubid%2Dconsole/, which causes session management errors. To workaround this issue, copy and paste the generated link into a browser, and replace the encoded dash with a dash (-) character.

  • The PermSize and MaxPermSize JVM properties are no longer supported in JDK 8, and will safely be ignored. These properties can be removed by modifying the config/java.properties file and running bin/dsjavaproperties while the server is offline.

  • Security criteria for root passwords with the default configuration will be increased in a future release. This might affect automated installation scripts that currently use less secure passwords. This will not affect existing root accounts.

  • The <tt>dsconfig</tt> tool and the Administrative Console enables creating and managing new Root DN users in this release. However, there is a limitation with changing the password of the currently logged in administrator. The <tt>ldappasswordmodify</tt> command can be used to change the administrator's password by providing the current and new password.

Resolved Issues

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

Ticket ID Description

Added the ability to search for configuration objects and their properties by name with the dsconfig tool.


Added support for log file rotation listeners, which allow for custom processing whenever a log file is rotated out of service so that the server will no longer write to it. A copy listener (which will copy the rotated log file to an alternate location, optionally compressing it in the process), and a summarize listener (which will invoke the summarize-access-log tool on the rotated log file) are included. The Server SDK also includes an API for creating custom log file rotation listeners.


Updated the default file permissions for new installations on UNIX-based systems. Files and directories included in the zip file will be only be accessible to their owner (the user that unzipped the file) by default.

Newly-created files and directories will also be assigned permissions that allow them to be accessed only by the account used to run the server. Existing configuration options for setting file permissions (the log-file-permissions and db-directory-permissions properties) will continue to behave as before. The new config/server.umask file will control the default permissions for all other newly-created files and directories.

Updated the initial server configuration to improve security and usability. These changes apply only to new installations and will not be applied when updating an existing installation. Changes include:
  • Updated the default password policy to use a default password storage scheme that uses a salted 256-bit SHA-2 digest rather than a salted SHA-1 digest.
  • Updated the root password policy to use a default password storage scheme of PBKDF2 rather than salted 512-bit SHA-2.
  • Updated the secure password policy to use a default password storage scheme of PBKDF2 rather than a CRYPT variant that uses multiple rounds of 256-bit SHA-2.
  • Updated the password policy import plugin so that it will attempt to use the default password policy to select the password storage scheme(s) to use for entries that do not explicitly specify a password policy. The plugin will also fall back to using a salted 256-bit SHA-2 scheme instead of a salted SHA-1 scheme.
  • A number of weaker password storage schemes have been disabled by default, including base64, clear, unsalted MD5, salted MD5, 3DES, RC4, and unsalted SHA-1.
  • The default password policy has been updated to use a password generator that generates very strong yet memorable passphrases rather than a shorter and less-memorable string of randomly-selected characters.
  • Many of the server loggers have been updated to include additional log elements by default, including the instance name, requester DN, requester IP address, and request controls.
  • The exact match identity mapper has been updated to look at the mail attribute in addition to the uid attribute. When targeting a user with an authentication ID value (as when using SASL authentication or the proxied authorization v2 request control), it is now possible to specify an email address as an alternative to a user ID.
  • The UNBOUNDID-TOTP SASL mechanism handler has been updated to prevent TOTP password reuse by default.
  • Added new request criteria that make it possible to identify requests that target the root DSE or the subschema subentry. The global configuration has been updated so that requests targeting these entries will be in the default exceptions lists if the server is configured to reject insecure or unauthenticated requests.
  • Updated the template that setup generates for creating sample data to use a more logical and user-friendly numeric range. When the user requests N entries, setup would previously number the entries 0 through N-1 (for example, if the user requested 1000 entries, they would be numbered 0 through 999). It is logical for a user to expect them to be numbered 1 through 1000, but this change could break things that expecting to find an entry numbered with zero. To address this, if the user requests the server be populated with sample data, setup will create one more entry than actually requested so the numbering will go from 0 to N.

The ability to request server-generated charts from the Metrics Engine has been removed in this release.


Added the server's process ID to the output of the status tool.


Added a new rotate-log tool to request the rotation of one or more log files.


Addressed a few issues in config-diff. In some situations, config-diff would not generate commands in an order that respected all dependencies. This has been fixed. Most expected warnings are now excluded by default but can be included in the output with the --includeAllWarnings option. The --sourceBindPasswordFile and --targetBindPassword are now applied in conjunction with the --targetConfigGroup and --sourceConfigGroup options.


Added a --dry-run option to dsconfig, which can be used in batch mode to validate the configuration changes in a batch file without applying them.


Added support for setting the request header size in the Jetty http configuration server properties.


The setup tool now creates the Postgres database directory under the server root, instead of the user's current directory. The data directory location can be changed by specifying the --databaseDataDir option when invoking setup.


Improved the collect-support-data tool to include information provided by systemd on platforms that support it.

Updated command-line tools based on the LDAP SDK tool APIs to add the following features:
  • Tools can obtain default values for any arguments not provided on the command line from a properties file. If it exists, the server's config/tools.properties file will be used by default. Command-line arguments can be used to specify an alternate properties file or to indicate that no properties file should be used.
  • Tools can be launched in an interactive mode, in which the user is prompted for arguments used to establish and authenticate the connection, and for any other required arguments. The user can then use an interactive menu to specify values for any remaining arguments.

Collect-support-data tool now captures Kerberos config and log information.


The PingDataMetrics Server REST API servlet has a new authentication timeout property to allow a configurable session timeout. Previously, the authentication session timeout was 15 minutes.


Added the ability to create local constants in LDIF template files using the new 'local' keyword.


Updated the Apache commons collections library to address the security vulnerability described by CVE 2015-4852.


Added a monitor entry for each Server SDK extension.


Added a --prettyPrint option to the config-diff tool to make the output more human-readable.


Updated the restore command so that it can no longer be used to restore a backup of the config backend. The command now points the administrator for safer ways to revert configuration changes, including using config-diff.


Updated the server's support for the Twilio Messaging Service so that it uses the newer "Messages" API when sending SMS messages instead of the older "SMS" API. The older API has been deprecated, and Twilio now imposes a 120-character limit for messages sent via that API. The messages API allows the server to take advantage of the full 160 characters per SMS message.


Fixed an issue with the dsjavaproperties tool where java properties for PermSize and MaxPermSize could be added when using JDK 8, which no longer supports these options.


Updated the bcrypt, crypt, PBKDF2 and scrypt password storage schemes so they can be used to create new instances.


Fixed a case where attribute syntax configuration changes would not apply to undefined attributes, which rely on default attribute types.


Server SDK extensions are now built with a Java source version of 1.7 by default.


The former suite of Administrative Console applications, each of which were tied to a particular product (for example the dsconsole.war for the PingDirectory Server) are no longer available, and have been superceded by a new version of the Administrative Console capable of managing any server product. You can choose to access the Administrative Console by hosting it within a server, or by deploying it in an external servlet container. For the former, enable an HTTP Connection Handler and add the Administrative Console Web Application Extension to the handler. For the latter, download and unzip the management-console-[version].zip file, and install the ubid-console.war file according to your container's instructions.


The Configuration API now returns unquoted, native Javascript values for integer, real number, and boolean properties. Duration and size property values, for example '1 w' or '100 G', continue to be represented as Javascript string types.


Improved the error messages and examples for create-rc-script and create-systemd-script by explicitly suggesting the use of sudo so that the scripts can modify protected files.


Changed interactive setup default value for HTTPS enablement.


The monitored-servers tool now enables specifying a monitoring user bind DN when adding servers.


Improved the error messages for create-rc-script and create-systemd-script when the directory in which the script will be created does not exist.


Updated interactive setup to display default values, and improved the overall layout and appearance.


Addressed an issue where dsconfig incorrectly allowed certain configuration objects to be deleted.


Improved the error messages produced by the manage-extensions tool when attempting to install invalid extensions.


Updated the global ACIs that ship with the server to use a separate ACI for each control or extended request to allow by default, rather than grouping all desired controls together in one ACI and all desired extended requests together in a second ACI. This change will only be reflected in new installations, and not when updating an existing deployment.


Root DN User configuration entries can now be fully managed through the configuration management interfaces such as dsconfig and the Administrative Console.


Added more logging information when initializing web application and servlet extensions in case an extension causes conflicts or delays.


Updated setup to encode the root password with the PBKDF2 password storage scheme instead of SSHA512.


Updater tool will increase PermSize and MaxPermSize parameters to recommended value to prevent Java JVM pauses.


Fixed an error that could occur during upgrade when the configuration can not be loaded due to missing custom schema.


Updated the Groovy Scripting Language version to 2.4.6.


Fixed an issue that prevented the deletion of disabled debug loggers.


Updated the version of the XML serialization library XStream from 1.3.1 to 1.4.9 to address a security vulnerability in the prior version.


Updated the sanitize-log tool to add support for JSON-formatted access and error log files.