Upgrade Considerations

Important considerations for upgrading to this version of PingDataSync Server are as follows:

Note: Product names have been updated to reflect the UnboundID acquisition by Ping Identity. This change affects naming and branding only. The code base is the same as in prior releases.
  • If you are upgrading a server that was running an earlier version of the JDK, run the dsjavaproperties --initialize command after the software upgrade to compare the settings of the earlier JDK with the requirements for the new server software. Apply necessary changes to the upgraded server, based on the previous performance settings.

  • The 6.0 release makes the following changes to supported platforms:

    • CentOS 7.2 and RedHat 7.2 are now supported operating system versions.
    • SUSE 11 SP4 is now supported, and support for SUSE 11 SP2 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.
    • WildFly 9.x, which is 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 change affects only 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, and servers now default to use HTTPS for console and API connections, including the SCIM API. This change might affect automation scripts and development environments in which HTTPS has not previously been in use.
    • Generated user passwords, like those created by the server during a password reset sequence, are now created as passphrases instead of as random character strings. This change makes such passwords easier to type and remember but does not affect upgrades.
    • The /config directory file permissions have been changed so that only the server user can access them.
    • Customers who use the optional encryption algorithms that the BouncyCastle library provides are encouraged to upgrade to BouncyCastle 1.54.

What's New

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

  • PingDataSync Server now recognizes and handles changes from Active Directory sources, including the non-standard range=n-m suffixes for multi-valued attributes.
  • Added the ability to apply attribute maps programmatically in Server Extensions so that specific maps can be applied to a cascading set of changes that the extension generates.
  • For Java developers whose tools and workflows make use of Maven, the Server SDK .jar file has been deployed to Maven Central. To add the Server SDK as a project dependency, developers need only to add 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 that requires no special configuration. This benefit extends 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 the 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, which is available through GitHub, can now be used with the Configuration API.

  • All servers have an updated web Administrative Console, which includes the following changes:

    • New layouts for operational statistics, processing time, queues, monitors, and installed extensions.
    • Alert and alarm displays that summarize the data in cn=alerts and cn=alarms, based on the configured gauges, as well as filtering and searching for them.
    • A new LDAP Schema Editor for importing schema files, validitating, and creating and editing object classes and attribute types. The editor also supports the 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 be deployed to independent application servers instead of being co-hosted by the servers. This approach simplifies deployment models and increases the separation between the data and application layers.
  • To assist with situations in which a large number of changes might decrease the amount of available disk space, or might increase memory usage or the time required to start the server, alerting and gauge features have been added to the Recent Changes Database.
  • Servers can now trigger events whenever log files are rotated. This change includes copy on rotate and summarize on rotate listeners, as well as Server SDK support for creating custom log file rotation listeners.
  • Root user accounts can now be created, changed, and removed across the topology by using the dsconfig tool or the Administrative Console.

Known Issues and Workarounds

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

  • When deploying the Administrative Console in Tomcat 8 and accessing the Administrative Console application by using Tomcat's Web Application Manager, some browsers, including Safari and Firefox, generate a path URL that encodes the dash in ubid-console. This issue results in a path such as http://localhost:8888/ubid%2Dconsole/, which causes session-management errors.

    Workaround: 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 can be ignored.

    Workaround: To remove these properties, modify the config/java.properties file and run bin/dsjavaproperties while the server is offline.

  • The dsconfig tool and the Administrative Console enable the creation and management of new Root DN users in this release. However, the ability to change the password of a currently logged-on administrator is limited.

    Workaround: To change the administrator's password, use the ldappasswordmodify command, and provide the current and new password.

Resolved Issues

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

Ticket ID Description
DS-979 Added the ability to search for configuration objects and their properties by name with the dsconfig tool.
DS-4235

Added support for the following log file rotation listeners, which allow for custom processing whenever a log file is rotated out of service so that a server can no longer write to it:

  • A copy listener copies the rotated log file to an alternate location, optionally compressing it in the process.
  • A summarize listener invokes the summarize-access-log tool on the rotated log file.

The Server SDK also includes an API for creating custom log file rotation listeners.
DS-7505, DS-13571, DS-13860 Updated the default file permissions for new installations on UNIX-based systems. By default, the files and directories that are included in the .zip file are accessible only to the user who extracted the file's contents. Newly created files and directories are also assigned permissions that can be accessed only by the account that is used to run the server. Existing configuration options for setting file permissions, such as the log-file-permissions and db-directory-permissions properties, continue to behave as before. The new config/server.umask file controls the default permissions for all other newly created files and directories.
DS-9407, DS-15183, DS-15220

Updated the initial server configuration to improve security and usability. These changes apply only to new installations and are not applied when an existing installation is updated. The following changes are included:

  • 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 attempts to use the default password policy when selecting a password storage schemes to use for entries that do not explicitly specify a password policy. The plugin also falls back to a salted 256-bit SHA-2 scheme instead of a salted SHA-1 scheme.

  • Many of the weaker password-storage schemes have been disabled by default, including the following schemes:

    • Base64
    • Clear
    • Unsalted MD5
    • Salted MD5
    • 3DES
    • RC4
    • Unsalted SHA-1
  • The default password policy has been updated to use a password generator that generates strong yet memorable passphrases rather than shorter and less-memorable strings of randomly selected characters.
  • Many server loggers have been updated to include the following log elements by default:
    • Instance name
    • Requester DN
    • Requester IP address
    • Request controls
  • The exact match identity mapper has been updated to inspect 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, an email address can now be specified 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 enable the identification of requests that target the root DSE or the subschema subentry. The global configuration has been updated so that requests targeting these entries are added to 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 a user previously requested N entries, setup numbered the entries 0 through N-1. (For example, if a user requested 1,000 entries, they would be numbered 0 through 999). Although a user might logically expect the entries to be numbered 1 through 1000, this format could break things that expect to find an entry numbered with 0. To address this issue, if a user requests the server to be populated with sample data, setup creates one more entry than actually requested so that numbering proceeds from 00 to N.
DS-10312 Added the server's process ID to the output of the status tool.
DS-10464 Added a new rotate-log tool to request the rotation of one or more log files.
DS-10466, DS-10765, DS-14479, DS-15318, DS-16154 Addressed issues associated with config-diff. In some situations, for example, config-diff could not generate commands in an order that respected all dependencies. This issue is now fixed. Most expected warnings are excluded by default, but can be included in the output by using the --includeAllWarnings option. Additionally, the --sourceBindPasswordFile and --targetBindPassword options are now applied in conjunction with the --targetConfigGroup and --sourceConfigGroup options.
DS-10946 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.
DS-12191 Added support for setting the request header size in the Jetty HTTP configuration server properties.
DS-13401 Improved the collect-support-data tool to include information that systemd provides on platforms that support it.
DS-13700

Updated command-line tools based on the LDAP SDK tool APIs to add the following features:

  • Tools can use a properties file to obtain default values for arguments that are not available on the command line. If it exists, the server's config/tools.properties file is used by default. Command-line arguments can be used to specify an alternate properties file or to indicate that no properties file is used.
  • Tools can be launched in an interactive mode, in which the user is prompted for arguments that establish and authenticate a connection, and for any other required arguments. The user can then use an interactive menu to specify values for any remaining arguments.
DS-13823 The collect-support-data tool now captures Kerberos configuration and logging information.
DS-14213 Added the ability to create local constants in LDIF template files by using the new local keyword.
DS-14298 To apply Sync maps programmatically, a new API, applyMaps(), is available for PingDataSync Server plugins.
DS-14430 Updated the Apache commons collections library to address the security vulnerability that CVE 2015-4852 describes.
DS-14548 Added a monitor entry for each Server SDK extension.
DS-14606 The resync tool now supports sync pipes that use Notification mode.
DS-14694 Added a --prettyPrint option to the config-diff tool to make the output more human-readable.
DS-14704 Updated the restore command so that it can no longer be used to restore a backup of the configuration backend. The command now points the administrator toward safer ways for reverting configuration changes, including using the config-diff command.
DS-14749 Updated the server's support for the Twilio Messaging Service so that it uses the newer Messages API, instead of the earlier SMS API, when sending SMS messages. The earlier API has been deprecated, and Twilio now imposes a 120-character limit for messages sent through that API. The Messages API allows the server to take advantage of the full 160 characters per SMS message.
DS-14765 Updated the Active Directory PingDataSync Source so that it correctly handles the range options on attributes that are returned with the DirSync control.
DS-14807 Tools that prepare a server for access by another server, such as prepare-external-server, now validate base DN entries before modifications are performed on the prepared server.
DS-14857 Fixed an issue with the dsjavaproperties tool, in which java properties for PermSize and MaxPermSize could be added when using JDK 8, which no longer supports these options.
DS-14878 To prevent the possible retention of data in memory, memory utilization has been improved when processing entries with large attributes.
DS-14923 Updated the bcrypt, crypt, PBKDF2, and scrypt password-storage schemes so that they can be used to create new instances.
DS-14979 Fixed a case in which changes to attribute syntax configurations did not apply to undefined attributes, which rely on default attribute types.
DS-15015 Server SDK extensions are now built with a Java source version of 1.7 by default.
DS-15087 Fixed an issue in which destination attributes wth hard-coded values were excluded inappropriately during a resync, when the --excludeSourceAttr option was used.
DS-15088 The former suite of Administrative Console applications, each of which was tied to a particular product (for example the dsconsole.war for PingDirectory Server) are no longer available, and have been superseded by a new version of the Administrative Console that can manage 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 option, enable an HTTP Connection Handler and add the Administrative Console Web Application Extension to the handler. For the latter option, download and extract the management-console-[version].zip file, and install the ubid-console.war file according to your container's instructions.
DS-15108 Replaced the scramble-ldif tool with a more powerful transform-ldif tool with support for several additional transformation types. The new transform-ldif tool is backward-compatible with the former scramble-ldif tool, and the scramble-ldif shell script and batch file are still included with the server to ensure compatibility with scripts that depend on that tool.
DS-15175 The Configuration API now returns unquoted, native Javascript values for integer, real number, and Boolean properties. Duration and size property values, such as 1 w or 100 G, continue to be represented as JavaScript string types.
DS-15178 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.
DS-15187 Literal curly brackets ({}) can now be included in value patterns and conditional value patterns of constructed attribute mappings by doubling them. Literal { and }} are specified by {{{{ and }}, respectively.
DS-15221 Changed interactive setup default value for HTTPS enablement.
DS-15337 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.
DS-15361, DS-15363, DS-15434 Updated interactive setup to display default values. Also improved the overall layout and appearance.
DS-15400 Addressed an issue in which dsconfig incorrectly permitted the deletion of certain configuration objects.
DS-15412 Improved the error messages that the manage-extensions tool generates when attempting to install invalid extensions.
DS-15417 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 is reflected only in new installations, and not when updating an existing deployment.
DS-15422 Root DN User configuration entries can now be managed fully through the configuration management interfaces, such as dsconfig and the Administrative Console.
DS-15437 Provided a graphical tool, watch-entry, that is intended to demonstrate replication or synchronization latency by watching an LDAP entry for changes. If the entry changes, the background of modified attributes temporarily becomes red. Attributes can also be directly modified.
DS-15466 Added logging information when initializing web application and servlet extensions in case an extension causes conflicts or delays.
DS-15513 PingDataSync Server now uses the max-connection-age configuration property to limit the age of LDAP connections to external servers.
DS-15521 Updated setup to encode the root password with the PBKDF2 password-storage scheme instead of SSHA512.
DS-15522 To prevent Java JVM pauses, the updater tool now increases the PermSize and MaxPermSize parameters to the recommended values.
DS-15571 To accommodate the Administrative Console, increased the minimum memory requirements for the server process from 256MB to 384MB.
DS-15592 Fixed an error that could occur during upgrade when a missing custom schema prevented the configuration from loading.
DS-15621 Updated the Groovy Scripting Language version to 2.4.6.
DS-15622 Fixed an issue that prevented the deletion of disabled debug loggers.
DS-15670 The prepare-endpoint-server CLI that is included with PingDataSync Server correctly sets permissions when the Synchronization user already exists.
DS-15753 The Data Services Markup Language (DSML) client and gateway components have been discontinued and are no longer available.
DS-16224 Updated the sanitize-log tool to add support for JSON-formatted access and error log files.
DS-16728 Sensitive attribute values can now be redacted in the sync and sync-failed-ops log files. By default, the values of encoded passwords are redacted. The redaction can be configured with the log-redaction-regex property in the global Sync configuration.