--- title: Incompatible changes description: Lists incompatible changes in PingDS releases that require action when upgrading, including command syntax, protocol, and behavior differences. component: pingds version: release-notes page_id: pingds::changes canonical_url: https://docs.pingidentity.com/pingds/release-notes/changes.html revdate: 2026-04-20T12:00:00Z keywords: ["Compatibility", "LDAP"] section_ids: changes-81: DS 8.1 changes-80: DS 8.0 changes-75: DS 7.5.2 ds_7_5: DS 7.5 changes-74: DS 7.4 changes-73: DS 7.3 changes-72: DS 7.2 changes-71: DS 7.1 changes-70: DS 7.0 accounts: Accounts backup: Backup data: Data ldap: LDAP logging: Logging mail: Mail replication: Replication rest: REST security: Security setup: Setup tools: Tools upgrade: Upgrade security-defaults: Default security settings ds_6_5: DS 6.5 --- # Incompatible changes ## DS 8.1 * When rotating access log files, DS continues to add a timestamp as the rotation filename suffix. Previously, the timestamps reflected local time. The timestamps now reflect Coordinated Universal Time (UTC) instead and have a trailing `Z` as a timezone indicator. This change can cause an offset of several hours in the timestamps depending on your time zone. Newly rotated audit files can temporarily have timestamps earlier than existing files. * Simplification of the `backendstat` command resulted in these changes: | Subcommand | Change | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `dump-index` | Specify the base DN.The *-n \| --backendId* option was removed.Specify the index name as a trailing argument. The *-i \| --indexName* option was removed. | | `dump-raw-db` | Specify either the base DN or the backend ID.Use the backend ID to dump indexes not linked to base DN.Specify the database name as a trailing argument. The *-d \| --dbName* option was removed. | | `list-backends` | Subcommand removed. | | `list-base-dns` | The output table now lists the base DNs and backends where they're defined. | | `list-indexes` | Specify the base DN.The option to specify a backend ID was removed. | | `list-raw-dbs` | No changes. | * The `OPENDJ_JFR_ENABLED` environment variable to enable or disable the Java Flight Recorder for DS is now named `DS_JFR_ENABLED`. ## DS 8.0 * DS replicas using [change number indexing](https://docs.pingidentity.com/pingds/8/config-guide/changelog.html#ecl-configure-changenumber-indexer) to provide [Internet-Draft change numbers](https://docs.pingidentity.com/pingds/8/config-guide/changelog.html#ecl-legacy-format) 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](https://docs.pingidentity.com/pingds/8/ldap-guide/change-notification.html#use-ecl). * 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](https://prometheus.io/docs/instrumenting/exposition_formats/#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](https://docs.pingidentity.com/pingds/8/_attachments/javadoc/index.html) to understand how the API has changed. * Setup profiles like the [user data profile](https://docs.pingidentity.com/pingds/8/install-guide/profile-user-data.html) 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: ```console $ 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:```java int sizelimit = getSizeLimit(); int timelimit = getTimeLimit(); ```To:```java 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](https://docs.pingidentity.com/pingds/7.4/ldap-guide/change-notification.html#use-ecl). 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](https://docs.pingidentity.com/pingds/7.3/rest-guide/preface.html) 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: ```bash $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password $ export 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 can't 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](#security-defaults). * 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](#security-defaults). 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 don't 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 don't 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` before 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 before 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"`.