PingDS release notes

Incompatible changes

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".

DS 6.0

  • Root DN users no longer belong to a special group or have alternate names, nor are their accounts stored in the configuration file, config.ldif. Instead, directory superusers are now stored in their own, separate backends whose base DN is the user DN.

    When you upgrade a server, the upgrade process moves existing root DN users to their own LDIF backends. The LDIF files for these backends are found in the /path/to/opendj/db directory.

    You can choose to store directory superuser entries in database backends instead of LDIF backends. This allows you to encrypt the data on disk, for example. (Recreate the backend as a JE backend, and then import from the LDIF file.)

  • Previously, root DN user profiles had an alternate-bind-dn property. This was used to allow you to specify bind DNs such as cn=Directory Manager instead of cn=Directory Manager,cn=Root DNs,cn=config. As the root user DNs are now top-level DNs, this mechanism is no longer supported.

  • Directory superuser privileges are now specified as ds-privilege-name values on their entries.

    As a result of this change, the dsconfig get-root-dn-prop and dsconfig set-root-dn-prop subcommands are no longer supported.

  • For new installations, defaults have changed for the following JE backend properties:

    • The default for db-log-file-max has increased from 100 MB to 1 GB.

    • The default for db-log-filecache-size has increased from 100 to 200.

    • The default for disk-low-threshold is now 5% of the filesystem size, plus 5 GB.

    • The default for disk-full-threshold is now 5% of the filesystem size, plus 1 GB.

    The new defaults for disk-low-threshold and disk-full-threshold apply for replication servers as well.

  • Default connection handler names have been shortened. The "Connection Handler" suffixes have been dropped from the names.

    For example, the default "LDAP Connection Handler" is now named "LDAP".

  • Server configuration expressions have been reimplemented to align with other Ping Identity Platform software.

  • The setup command option --useJceks has been renamed to --useJceKeyStore.

    The setup command option --useJceksTrustStore has been renamed to --useJceTrustStore.

  • When creating a schema provider for a customized JSON query matching rule, the type to create is now json-query-equality-matching-rule, rather than json-schema.

  • For new DS server installations, the file layout has changed to mutable data, which is changed by the server at runtime, from potentially immutable configuration data.

    When you upgrade an existing server, the following files remain where they were in the old layout:

    • LDAP schema files located in the config/schema/ directory

    • The config/ads-truststore.pin and config/ads-truststore.pin files

    When you set up a new server, the new file layout is used for all files. The file names in the following table indicate where files have moved.

    Old Layout New Layout

    config/admin-backend.ldif

    config/admin-backend.ldif.old

    db/admin/admin-backend.ldif

    db/admin/admin-backend.ldif.old

    config/ads-truststore

    config/ads-truststore.pin

    db/ads-truststore/ads-truststore

    db/ads-truststore/ads-truststore.pin

    config/archived-configs

    var/archived-configs

    config/config.ldif.startok

    var/config.ldif.startok

    All LDAP schema files that were in the config/schema/ directory…​

    …​are now in the db/schema/ directory.

    config/tasks.ldif

    db/tasks/tasks.ldif

    All files that were in the config/upgrade/ directory…​

    …​are now in the var/upgrade/directory.

  • The command-line performance tools no longer accept printf-style format strings in templates. Instead, they use a {1}, {2}, {n} token syntax, where the {1} represents the first data source, {2} the second, and so on.

    As an example, the following command measures search throughput and response time. For each search, the command substitutes a random value for {1} from the specified range of rand(0,2000):

    $ searchrate -p 1389 -b "dc=example,dc=com" -g "rand(0,2000)" "(uid=user.{1})"

    The tools also support relative indexing, using {} tokens without numbers. In the example above, "(uid=user.{})" would reference the -g "rand(0,2000)" data source.

    This change affects the following tools:

    • addrate

    • authrate

    • modrate

    • searchrate

DS 5.5

  • Port-related options, and their short versions (such as -p for --port), no longer have default values when used in non-interactive mode:

    Commands affected Options affected

    addrate
    authrate
    backup
    control-panel
    dsconfig
    export-ldif
    import-ldif
    ldapcompare
    ldapdelete
    ldapmodify
    ldappasswordmodify
    ldapsearch
    manage-account
    manage-tasks
    modrate
    rebuild-index
    restore
    searchrate
    stop-ds

    --port

    dsreplication

    --port
    --port1
    --port2
    --portDestination
    --portSource
    --replicationPort1
    --replicationPort2

  • The -t | --numThreads option for the following tools has changed to -t | --numConcurrentRequests:

    • addrate

    • authrate

    • modrate

    • searchrate

  • The dsreplication command’s --baseDn option is now only available where it is applicable.

    The reset-change-number, resume, status, and suspend subcommands no longer accept a --baseDn option.

  • The product name has been aligned with the official name of the software release. The full product name starting with this release is ForgeRock Directory Services.

    This change impacts clients that depend on the product name.

    It also impacts the name used in product subcomponents. For example, in earlier releases the syslog handler sent messages with the process name OpenDJ. The syslog handler now sends messages with the process name ForgeRock.

  • Manually changing the enabled property of an external change log domain returns incoherent results across the topology and is not supported.