PingDS release notes

Incompatible changes

DS 8.0

  • DS replicas using change number indexing to provide Internet-Draft change numbers now order change numbers locally on each server. The local change numbers follow the order in which replicated updates arrive.

    DS servers no longer order change numbers globally. The order likely differs from replica to replica.

    This reduces the number of potential problems the change number indexer faces, and so simplifies monitoring.

    Applications that need global consistency in the change log to fail over across replicas can continue to use or switch to changelog cookies.

  • New DS servers now publish Prometheus metrics at /metrics/prometheus/0.0.4 by default.

    The 0.0.4 path element reflects the content type version for the Prometheus text-based format.

  • The global property max-psearches sets a default limit of 100 total concurrent persistent searches.

    By default, the global property max-psearches-policy is set to warn. When it reaches the limit, DS accepts the incoming persistent search request and logs a warning message to the error log.

    If you set max-psearches-policy: reject, when it reaches the limit set by max-psearches, DS rejects incoming persistent search requests.

  • HDAP now returns normalized field names by default.

    To return field names as specified with the _fields query parameter or as stored in the LDAP entry, set the HDAP endpoint configuration property normalize-attribute-names:false or the HDAP gateway configuration setting "normalizeAttributeNames": false.

  • The rebuild-index --rebuildDegraded option is now rebuild-index --rebuildUntrusted.

    The rebuild-index --clearDegradedState option now does nothing. Since DS 7.5.0, DS servers no longer require rebuilding indexes for attributes that have never been used before.

    In addition, DS log messages now mention "trusted" and "untrusted" indexes rather than "degraded" indexes. If you scan log files for messages about degraded indexes, you must update them.

  • The setup-profile --instancePath option is no longer supported.

    Set the instance path when using the setup command instead.

  • The DS plugin API continues to evolve. This release brings many significant changes.

    Make sure you can build plugins built with earlier releases. Review the Javadoc to understand how the API has changed.

  • Setup profiles like the user data profile have changed how they interpret relative paths to LDIF files.

    Previously, the path was either absolute or relative to the current directory. Now, the path is either absolute or relative to the directory where the profile is defined.

DS 7.5.2

  • DS 7.5.x no longer logs debugsearchindex information by default.

    If needed, use the boolean system property org.forgerock.opendj.logDebugSearchIndex to enable it:

    $ OPENDJ_JAVA_ARGS="-Dorg.forgerock.opendj.logDebugSearchIndex=true" start-ds

DS 7.5

The following changes affect the evolving DS plugin API:

Class or interface Changes

PluginOperation

Added:

  • getRequest()

    You can also now use getRequest().getRequestType().

  • hasPrivilege()

Removed:

  • getOperationType()

  • removeAttachment(String name)

PreParseOperation
PreOperationOperation

Added:

  • sendResponses(ResponseStream responses) for sending intermediate responses.

    The APIs were removed from the ClientConnection class.

ClientConnection

This class has a volatile API and will very likely be subject to significant changes in future releases.

Many methods were added and removed.

InProgressSearchOperation
PostOperationSearchOperation
PostResponseSearchOperation
PreOperationSearchOperation
PreParseSearchOperation

To access resource limits, change your code from:

int sizelimit = getSizeLimit();
int timelimit = getTimeLimit();

To:

int sizelimit = getResourceLimits().getSizeLimit();
int timelimit = getResourceLimits().getTimeLimit();

DS 7.4

  • You can upgrade DS 6.0 and later servers directly to DS 7.4.

    When starting from 5.5.x and earlier, first upgrade all servers to DS 6.5 before upgrading further. Direct upgrade from versions earlier than 6.0 is no longer supported.

  • For new DS servers, the setup command no longer enables support for changelog change numbers or change number indexing by default.

    For new servers, the replication server configuration property is changelog-enabled: enabled-cookie-mode-only by default, meaning client applications must use cookies instead of change numbers when searching the changelog. For examples, refer to Use the external change log.

    When you upgrade an existing server in place, the upgrade command keeps the existing server behavior.

  • The documentation describes the new HDAP APIs for HTTP access.

    For documentation covering REST to LDAP, refer to Use REST/HTTP for 7.3.

  • The log publisher properties default-severity and override-severity now take single values.

    Set them to the lowest severity level to log.

  • The create-rc-script option -f|--outputFile has been removed.

    Use -r|--rcScript /etc/init.d/opendj or -s|--systemdService /etc/systemd/system/opendj.service instead.

  • The configuration property big-index-matching-rule has changed to big-index-extensible-matching-rule.

    When creating a big-extensible index, you must set at least one big-index-extensible-matching-rule.

  • The configuration property log-control-oids has changed to log-controls and is true by default for new servers.

  • DS servers no longer return replication conflict entries by default.

    Use the manage DSAIT LDAP control to access them.

DS 7.3

  • New DS servers now write replication messages to the server error log (default: opendj/logs/errors).

  • Metrics formerly under cn=entry cache,cn=monitor have moved under cn=entry caches,cn=monitor.

DS 7.2

  • The deployment key described in earlier DS 7 releases has been renamed deployment ID:

    • A deployment ID is not a cryptographic key or digital certificate.

    • A deployment ID does uniquely identify a DS deployment.

    The change affects the commands and the documentation:

    Old option New option

    --deploymentKey

    --deploymentId

    --deploymentKeyPassword

    --deploymentIdPassword

    The name change does not affect the deployment IDs (formerly keys) themselves. You can continue to use existing IDs (keys) in your deployments.

  • The setup command now requires a --deploymentId option.

    Before running setup for the first time, generate a deployment ID as shown throughout the documentation:

    $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password
<deployment-id>
$ export DEPLOYMENT_ID=<deployment-id>

  • As a side effect of the change to allow mail addresses to include UTF-8 characters, DS no longer supports zero-length mail addresses.

    If you cannot prevent applications from adding zero-length mail addresses and no addresses use UTF-8, set the advanced core schema property allow-zero-length-values-directory-string to true.

  • The following changes affect proxy backend configurations:

    Old Property New Property

    heartbeat-interval

    keep-alive-interval

    heartbeat-search-request-base-dn

    keep-alive-search-request-base-dn

  • The lookthrough-limit setting has been removed. Use time-limit instead.

    DS servers now enforce time-limit and ds-rlimit-time-limit settings while evaluating the entries to return for a search, rather than enforcing time limits only when sending entries.

    DS servers now ignore the ds-rlim-lookthrough-limit setting.

  • The global advanced setting, cursor-entry-limit, has been replaced by a max-candidate-set-size setting, which corresponds to the maximum number of candidate entries that DS servers maintain in memory when querying attribute indexes.

  • The dsbackup command no longer supports specifying options before the subcommand.

    You must now put all options after the subcommand, as has always been indicated in the documentation.

DS 7.1

  • With the introduction of the global configuration property, group-id-failover-order, which takes a comma-separated list of group IDs, commas are no longer permitted in group IDs.

    The upgrade command replaces each , with a . in group IDs.

  • The following changes affect proxy backend configurations:

    Old Property New Property Notes

    load-balancing-algorithm

    None

    All proxy backends now use affinity load balancing. As a result, they always route requests with the same target DN to the same server.

    bind-connection-pool-idle-timeout

    connection-pool-idle-timeout

    DS proxy backends no longer use shared connection pools.

    bind-connection-pool-max-size

    connection-pool-max-size

    bind-connection-pool-min-size

    connection-pool-min-size

    request-connection-pool-size

    None

  • When using the dskeymgr command to generate a PEM format certificate, you can no longer use the --alias option. The PEM format does not support aliases.

    If you do use the --alias and --outputFile options together, the command now displays an error message:

    You may not provide both the --outputFile and the --alias arguments

DS 7.0

Accounts

  • The default directory superuser (Directory Manager) DN is now uid=admin for new servers.

    The upgrade process does not change the directory superuser DN for existing servers.

    This change makes it easier to manage the server configuration over REST, as the default identity mapper configuration maps the HTTP admin username to the LDAP DN uid=admin.

  • The replication service discovery mechanism now obtains some information by reading the cn=monitor LDAP entry. As a result, the bind-dn account must now have the monitor-read privilege.

    This affects accounts used by DS directory proxy servers to bind to DS replication servers. For an example showing the account with the monitor-read privilege, refer to Try DS directory proxy.

Backup

  • DS backups taken with this release are not compatible with backups from earlier releases.

  • Scheduled backup tasks continue after upgrade.

  • Tasks created with the restore command in earlier releases are removed during upgrade.

Data

The default backend ID for application data depends on the setup profiles.

The upgrade process does not change the backend ID for existing servers.

LDAP

When matching strings in attributes with telephone number syntax, DS servers now behave as follows:

  • As in previous versions, a search for "(telephoneNumber=1555123456)" matches entries with telephone number values +1 555 123 456 and 1 555 123456.

  • All + characters are ignored.

    In other words, + is no longer significant when matching a telephone number syntax attribute.

  • A search for "(telephoneNumber=*Flower*)" returns only entries with telephone numbers containing Flower (case-insensitive match).

  • A search for "(telephoneNumber=15550102)" no longer matches entries with telephone numbers like +15550102 - Home.

Logging

  • The batch configuration for the JMS common audit handler for access logs has changed to support reconnection if the broker becomes unavailable.

    This change adds a batch.writeInterval setting. It removes the following settings:

    • batch.batchEnabled

    • batch.insertTimeoutSec

    • batch.pollTimeoutSec

    • batch.shutdownTimeoutSec

    • batch.threadCount

  • The example JDBC audit handler configuration for logging to MySQL has changed.

    The old configuration is not compatible with MySQL 8, supported in DS 7.

Mail

The global property smtp-server has been replaced with a configuration object, mail server.

Replication

  • The group-id and server-id identifiers are now global settings, and only take a single value per server.

    Replication domain and replication server configurations no longer have mutable server-id and group-id properties.

  • The external changelog domain configuration has moved to the replication domain and replication server configurations.

    This affects the following properties:

    • ecl-include

    • ecl-include-for-deletes

    • changelog-enabled-excluded-domains

  • The following replication domain configuration properties have moved to the replication synchronization provider:

    • changetime-heartbeat-interval

    • isolation-policy

    • heartbeat-interval

    • initialization-window-size

    • log-changenumber

    • referrals-url

    • solve-conflicts

    • source-address

  • The following replication server properties have moved to the replication synchronization provider:

    • replication-purge-delay

    • source-address

  • In addition to the property changes, the replication synchronization provider has changed:

    • A new property, bootstrap-replication-server, takes the addresses of one or more replication servers this server should contact to discover the rest of the topology.

    • The replication-purge-delay property has replaced the replication domain property, conflicts-historical-purge-delay.

      In this release, the replication-purge-delay setting alone governs how long the replica retains data in the changelog and historical metadata necessary to solve conflicts in directory entries.

REST

  • The resourceTypeProperty field is no longer used in REST to LDAP configurations. The resource type is now inferred from the property with "type": "resourceType".

Security

  • Default security settings have been hardened.

    For details, refer to Default Security Settings.

  • The following configuration changes impact TLS-related settings:

    The Crypto Manager no longer has the following properties:

    • ssl-cert-nickname

    • ssl-cipher-suite

    • ssl-encryption

    • ssl-protocol

    The replication synchronization provider configuration object now has the following properties:

    • key-manager-provider

    • ssl-cert-nickname

    • ssl-cipher-suite

    • ssl-encryption

    • ssl-protocol

    • trust-manager-provider

    The following configuration objects now have ssl-cipher-suite and ssl-protocol properties:

    • HTTP OAuth2 OpenAM authorization mechanism

    • HTTP OAuth2 token introspection (RFC 7662) authorization mechanism

    • Replication service discovery mechanism

    • Static service discovery mechanism

  • The default fingerprint algorithm for the fingerprint certificate mapper is now SHA-256.

Setup

The setup command has changed:

  • The --productionMode option has been removed.

    Default settings are now secure. For details, refer to Default Security Settings.

    The evaluation setup profile is compatible with other setup profiles. However, if you apply the evaluation setup profile last, it sets unauthenticated-requests-policy:allow, granting global permission to perform operations over insecure connections.

  • Subcommands have been replaced by setup profiles.

  • The setup command no longer starts the server by default.

    Before starting your new DS server, finish configuration.

    If no further configuration is required, use the setup --start option.

  • For new servers, key pairs with self-signed certificates are no longer used. Instead, the setup process generates keys used for secure connections, and derives a shared master key to protect secret keys for data encryption. These keys depend on a deployment ID and deployment ID password.

    The deployment ID and deployment ID password are required as part of the setup process:

    • If you do not provide your own keys, the generated keys and the signing CA certificate are stored in a PKCS#12 keystore file, config/keystore.

      The password is stored in a PIN file, config/keystore.pin.

      You can use the CA certificate as the root of trust for an entire deployment.

    • By default, replication now relies on the same key pairs as all other connection handlers to secure network communications.

      The Replication Key Manager and Replication Trust Manager providers now point to the providers chosen during the setup process.

    • The Default Key Manager is now named after its keystore format, such as PKCS12.

  • The following setup command options have been removed:

    • -a, --addBaseEntry

    • -b, --baseDn

    • --useJvmTrustStore

    • -l, --ldifFile

    • -O, --doNotStart

    • --productionMode

    • -R, --rejectFile

    • --skipFile

    Add your initial data before starting the server by creating a backend database, configuring indexes, and importing from LDIF.

  • The -d, --sampleData option has moved. It is now provided as the generatedUsers parameter of the ds-evaluation setup profile.

Tools

  • DS command line tools no longer support the -w - and --bindPassword - options to prompt interactively for a password.

    Instead, provide the bind DN and omit the -w - or --bindPassword - option. The tools then prompt for a password unless you specify the --no-prompt option.

Upgrade

You can upgrade DS 3.0 and later servers directly to DS 7.

When starting from 2.6, first upgrade all servers to DS 6.5 before upgrading further. Direct upgrade from 2.6 is no longer supported.

Default Security Settings

When you set up new DS servers, they are now configured with tighter security settings by default. These changes do not affect DS servers that you upgrade from earlier versions. If you require more lenient settings for compatibility, you must configure them after setting up the server:

  • All operations except bind requests and StartTLS requests, and base object searches on the root DSE, require secure connections.

    This behavior is governed by the global configuration property, unauthenticated-requests-policy, which is now set to allow-discovery, instead of allow, unless the last setup profile applied is the ds-evaluation profile.

  • The password storage scheme for the Default Password Policy and Root Password Policy is now PBKDF2-HMAC-SHA256 with 10 iterations. For stronger security, raise the number of iterations, and require users to change their passwords.

    PBKDF2-HMAC-SHA256 is a computationally intensive one-way hashing scheme. When used with a high number of iterations, it is intentionally orders of magnitude slower than the previous default for user passwords, which was Salted SHA-512.

    PBKDF2-HMAC-SHA256 and similar computationally intensive password storage schemes lower throughput and raise response times for some operations, including the following:

    • Importing plaintext passwords from LDIF; for example, during evaluation and testing with generated data.

    • Updating passwords.

    • Authenticating with passwords.

    To migrate user passwords to a new storage scheme, refer to Password storage.

  • SASL mechanism handler configurations for CRAM-MD5 and DIGEST-MD5 are no longer present in the default configuration.

  • Password storage scheme configurations for MD5, RC4, and Salted MD5 are no longer present in the default configuration.

    Less secure and reversible password storage schemes have been disabled in the default configuration. You must therefore enable these password storage schemes if you intend to use them.

    Setting New Default

    Crypto Manager

    SHA-256

    Crypto Manager

    RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING

    Crypto Manager

    HmacSHA256

    Global setting

    allow-discovery

    Password storage scheme: 3DES

    false

    Password storage scheme: AES

    false

    Password storage scheme: Base64

    false

    Password storage scheme: Blowfish

    false

    Password storage scheme: Clear

    false

    Password storage scheme: CRYPT

    false

    Password storage scheme: PBKDF2

    false

    Password storage scheme: PKCS5S2

    false

    Password storage scheme: Salted SHA-1

    false

    Password storage scheme: Salted SHA-256

    false

    Password storage scheme: Salted SHA-384

    false

    Password storage scheme: Salted SHA-512

    false

    Password storage scheme: SHA-1

    false

    Pluggable (JE) backend

    AES/GCM/NoPadding

    Replication server

    AES/GCM/NoPadding

DS 6.5

  • There is an issue when running an upgrade from DS 6.5.0 to 6.5.1. If you did not set the je-backend-shared-cache-enabled property and accepted the default value of true prior to the upgrade, the value changes AFTER upgrade to false. You may have to reset this value to true for your deployments.

    If you set the je-backend-shared-cache-enabled property prior to upgrade to either true or false, the value does not change after upgrade.

  • The status command has been rewritten, with the following notable changes:

    • The command is no longer interactive.

    • You must supply the required options when invoking the status command.

    • The command now has an --offline option.

    • When you run status --offline on a running server, the command only displays a portion of the available information.

    • You can now run the command against a remote DS server version 6 or later.

    • The output shows more information than before.

  • The dsreplication status command no longer shows metrics for M.C. (missing changes) and A.O.M.C. (age of oldest missing change). Instead, it shows the replication delay.

    For DS 6 and later servers that expose a replication delay metric, the command shows the delay value. For DS 5.5 and earlier servers, the command shows N/A.

  • The db/admin backend has been renamed db/adminRoot.

  • The global server configuration property, reject-unauthenticated-requests, a boolean, has been removed and replaced with the property, unauthenticated-requests-policy. The new property can be set to the following values:

    reject

    Same behavior as reject-unauthenticated-requests:true

    allow

    Same behavior as reject-unauthenticated-requests:false

    allow-discovery

    Like reject, but allows unauthenticated base object searches of the root DSE

  • The proxy backend configuration property service-discovery-mechanism has been renamed shard.

  • The encode-password command now displays the encoded password without additional characters.

    In other words, the output is now {scheme}encoded-password rather than Encoded Password: "{scheme}encoded-password".