PingDS 7.5.1

Upgrade

This guide shows you how to upgrade PingDS software.

About upgrades

Read this first.
Upgrade strategies

Choose between upgrading in place and upgrading by adding servers.
Upgrade in place

Overwrite old software to upgrade on the same server.
Upgrade by adding servers

Add new servers then retire old ones.

Read the Release notes before you upgrade DS software.

Product names changed when ForgeRock became part of Ping Identity. PingDS was formerly known as ForgeRock Directory Services, for example. Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.

About upgrades

DS 7 is a major release, much more cloud-friendly than ever before, and different in significant ways from earlier releases.

To upgrade successfully from DS 6.5 and earlier, make sure you understand the key differences beforehand. With these in mind, plan the upgrade, how you will test the upgraded version, and how you will recover if the upgrade process does not go as expected:

Fully compatible replication

Some things never change. The replication protocol remains fully compatible with earlier versions.

This means you can still upgrade servers while the directory service is online, but the process has changed.

Key configuration differences
DS 6.5 and earlier DS 7.0 and later

You configure replication after installation.

You configure replication during installation, before starting the server.

You configure which servers replicate.

You configure bootstrap replication servers. Replicas discover other servers through them.

You configure trust and TLS when configuring replication.

By default, you install servers with a shared deployment ID and password that enables trust and TLS.

Before retiring a server, you unconfigure replication for the server.

After retiring a bootstrap replication server, you remove it from other servers' configurations. Otherwise, no unconfiguration is necessary.

Use the dsreplication command.

Use the dsrepl command.

Replicas share secret keys through cn=admin data.

Replicas protect secret keys with the shared deployment ID and password.

In 6.5 and earlier, you set up DS servers that did not yet replicate. Then, when enough of them were online, you configured replication.

In 7, you configure replication at setup time before you start the server. For servers that will have a changelog, you use the setup --replicationPort option for the replication server port. For all servers, you use the setup --bootstrapReplicationServer option to specify the replication servers that the server will contact when it starts up.

The bootstrap replication servers maintain information about the servers in the deployment. The servers learn about the other servers in the deployment by reading the information that the bootstrap replication server maintains. Replicas initiate replication when they contact the first bootstrap replication server.

As directory administrator, you no longer have to configure and initiate replication for a pure DS 7 deployment. DS 7 servers can start in any order as long as they initiate replication before taking updates from client applications.

Furthermore, you no longer have to actively purge replicas you removed from other servers' configurations. The other servers "forget" a replica that disappears for longer than the replication purge delay, meaning they eventually purge its state from memory and from their changelogs. (DS servers do not "forget" bootstrap replication servers, because each server’s configuration explicitly references its bootstrap replication servers.) With earlier DS versions, you had to purge replicas from other servers' configurations after they were removed. DS servers do this automatically now. No administrative action is required.

These new capabilities bring you more deployment flexibility than ever before. As a trade off, you must now think about configuring replication at setup time, and you must migrate scripts and procedures that used older commands to the new dsrepl command.

Unique string-based server IDs

By default, DS 7 servers use unique string-based server IDs.

In prior releases, servers had multiple numeric server IDs. Before you add a new DS 7 server to a deployment of older servers, you must assign it a "numeric" server ID.

Secure by default

The setup --production-mode option is gone. All setup options and profiles are secure by default.

DS 7 servers require:

  • Secure connections.

  • Authentication for nearly all operations, denying most anonymous access by default.

  • Additional access policies when you choose to grant access beyond what setup profiles define.

  • Stronger passwords.

    New passwords must not match known compromised passwords from the default password dictionary. Also in 7, only secure password storage schemes are enabled by default, and reversible password storage schemes are deprecated.

  • Permission to read log files.

Furthermore, DS 7 encrypts backup data by default. As a result of these changes, all deployments now require cryptographic keys.

Deployment ID required

DS 7 deployments require cryptographic keys. Secure connections require asymmetric keys (public key certificates and associated private keys). Encryption requires symmetric (secret) keys that each replica shares.

To simplify key management and distribution, and especially to simplify disaster recovery, DS 7 uses a shared master key to protect secret keys. DS 7 stores the encrypted secret keys with the replicated and backed up data. This is new in DS 7, and replaces cn=admin data and the keys for that backend.

A deployment ID is a random string generated using the dskeymgr command. A deployment ID password is a secret string at least 8 characters long that you choose. The two are a pair. You must have a deployment ID’s password to use the ID.

You generate a shared master key to protect encryption secrets, and optionally, asymmetric key pairs to protect communications, with the dskeymgr command using your deployment ID and password. Even if you provide your own asymmetric keys for securing connections, you must use the deployment ID and password to generate the shared master key.

DS derives other keys from the deployment ID and password.

When you upgrade, or add a DS 7 server to a deployment of pre-7 servers, you must intervene to move from the old model to the new, and unlock all the capabilities of DS 7.

New backup

As before, backups are not guaranteed to be compatible across major and minor server releases. If you must roll back from an unsuccessful upgrade, roll back the data as well as the software.

When you back up DS 7 data, the backup format is different. The new format always encrypts backup data. The new format allows you to back up and restore data directly in cloud storage if you choose.

Backup operations are now incremental by design. The initial backup operation copies all the data, incrementing from nothing to the current state. All subsequent operations back up data that has changed.

Restoring a backup no longer involves restoring files from the full backup archive, and then restoring files from each incremental backup archive. You restore any backup as a single operation.

The previous backup and restore tools are gone. In their place is a single dsbackup command for managing backup and restore operations, for verifying backup archives, and for purging outdated backup files.

For additional details, refer to the rest of the DS 7 documentation.

To the extent possible, separate the upgrade process from the process of adopting new features. The DS upgrade command encourages this by maintaining compatibility where possible.

Once you have validated that the upgrade has completed successfully, take advantage of the new features available.

Activate new features after upgrade

When you upgrade DS, the upgrade process preserves the existing configuration as much as possible. This maintains compatibility, but it means that you do not have access to all new features immediately after upgrade.

You must take additional steps to complete the process, including activating new features. For details, refer to After you add new servers.

Supported upgrades

From…​ To…​ Important Notes

Official DS release, version 6.0 or later

Official DS release, same edition of directory server or replication server

Supported.

Official ForgeRock release, 2.6.x to 5.5.x

Official DS release, directory server or replication server

Not supported.

Workaround: First, upgrade all servers in the deployment to 6.5 before upgrading further. For details on upgrading to 6.5, refer to the DS 6.5 Installation Guide.

Official ForgeRock release, version 2.4 or 2.5

Official DS release, directory server or replication server

Not supported.

Workaround: Upgrade all servers in the deployment to use at least 2.6.0 before upgrading further. For details on upgrading to that version, refer to Upgrading to OpenDJ 2.6.0.

Evaluation release

Official DS release

Not supported.

The evaluation version includes an additional server plugin and configuration. Official releases do not have an upgrade task to remove the plugin and its configuration.

Unofficial build

Official DS release

Not supported.

Upgrade strategies

When you upgrade to a new DS version, you choose between:

For some scenarios, like upgrading Docker images in a Kubernetes deployment, you must upgrade in place.

Upgrade in place

The most straightforward option when upgrading DS servers is to upgrade in place. DS software provides an upgrade command to simplify the process.

One by one, you stop, upgrade, and restart each server individually, leaving the service running during upgrade:

Advantages Disadvantages

No additional systems to manage.

During the upgrade, the host system must meet the requirements for both the older version and the new release.

For example, you may need to have more than one Java environment installed. The operating system must also be supported for both releases.

Simpler to understand.

Slower to roll back.

Rollback involves restoring each server to its pre-upgrade state.

Once a replica’s databases have been upgraded, they cannot be rolled back.

Easier to maintain compatibility.

To the extent possible, the upgrade command leaves the configuration as is.

You must manually enable new features after the upgrade.

On upgrading replicas

The in-place upgrade process is designed to support a rolling (sequential) upgrade of replicated servers.

Do not upgrade all replicated servers at once in parallel, as this removes all replication changelog data simultaneously, breaking replication.

If the deployment includes DS 7.4.0 servers with data encryption using default settings, you must add new servers instead. For details, read Upgrade from DS 7.4.0.

When upgrading in place, follow these steps for each replica:

  1. Direct client application traffic away from the server to upgrade.

  2. Upgrade the replica.

  3. Direct client application traffic back to the upgraded server.

Add new servers

Adding new servers and then retiring old ones is an alternative to upgrading in place. You replicate data between old and new systems, leaving the service running during the upgrade:

Advantages Disadvantages

Smoothly phase out old host systems.

After successfully completing the upgrade, you gradually retire the old systems.

New host systems to manage.

Faster to roll back.

Old servers remain in operation until the upgrade completes successfully.

Harder to maintain compatibility.

You must manually configure new servers to be fully compatible with existing servers, rather than relying on the upgrade command. This requires an in-depth understanding of both your existing configuration and the new configuration. Some new default settings may be incompatible with the old default settings, for example.

Requires initializing the new replicas.

Depending on the volume of data to synchronize, you can initialize at least the first new replica online. For deployments with medium to large data sets, initialize from exported LDIF or from backup files created using an upgraded DS server. In either case, you must plan the operation.

While the upgrade is in progress, replication monitoring is split between the older servers that use dsreplication status and the newer servers that use dsrepl status.

Run both commands to get a more complete picture of replication status.

You must manually enable new features after the upgrade.

Strategy: in-place upgrade

These pages cover in-place upgrades. For servers, you unpack the new software over old and run the upgrade command, reusing the same host systems. For details about alternative upgrade strategies, refer to Upgrade strategies.

If you use encryption and the default cipher-transformation settings, you cannot upgrade in place from DS 7.4.0. Upgrade by adding new servers instead and refer to Upgrade from DS 7.4.0 for details.

Next steps

Before you upgrade in place

Fulfill these requirements before upgrading PingDS software, especially before upgrading the software in a production environment. Also refer to the requirements listed in release notes.

Global server IDs

Before upgrading, make sure you use unique global server IDs. Prior to DS 7.0, each server could have multiple server IDs. Global server IDs were supported but optional in DS 6.5.

To update each DS 6.5 to use a unique global server ID, set the server-id global configuration property. The following example sets the global server ID to 1:

$ dsconfig \
 set-global-configuration-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --set server-id:1 \
 --trustAll \
 --no-prompt

Server IDs were originally numeric for compatibility with DS 6.5 and earlier servers. In DS 7.0 and later, use strings as server IDs.

Supported Java

  • Always use a JVM with the latest security fixes.

  • Make sure you have a required Java environment installed on the system.

    If your default Java environment is not appropriate, use one of the following solutions:

    • Edit the default.java-home setting in the opendj/config/java.properties file.

    • Set OPENDJ_JAVA_HOME to the path to the correct Java environment.

    • Set OPENDJ_JAVA_BIN to the absolute path of the java command.

  • When running the dskeymgr and setup commands, use the same Java environment everywhere in the deployment and refer to CAs from deployment IDs.

DS software supports the following Java environments:

Vendor Versions

OpenJDK, including OpenJDK-based distributions:

  • AdoptOpenJDK/Eclipse Temurin Java Development Kit (Adoptium)

  • Amazon Corretto

  • Azul Zulu

  • Red Hat OpenJDK

Ping Identity tests most extensively with AdoptOpenJDK/Eclipse Temurin.

Use the HotSpot JVM if possible.

17(1), 21

Oracle Java

17(1), 21

(1) DS requires Java 17.0.8 or later.

TLS cipher support depends solely on the JVM. For details, refer to TLS settings.

CAs from deployment IDs

Due to a change to the Java platform between versions 11 and 17, the keys you generate with the dskeymgr and setup commands using Java 11 are incompatible with keys generated using Java 17 and later.

Using different Java versions is a problem if you use deployment ID-based CA certificates. Replication breaks, for example, when you use the setup command for a new server with a more recent version of Java than was used to set up existing servers.

For details on resolving the issue, refer to Incompatible Java versions.

Required credentials

Perform the upgrade procedure as the user who owns the server files.

Make sure you have the credentials to run commands as this user.

Back up first

Before upgrading, perform a full file system backup of the current server so that you can revert on failure. Make sure you stop the directory server and back up the file system directory where the current server is installed.

Backup archives are not guaranteed to be compatible across major and minor server releases. Restore backups only on directory servers of the same major or minor version.

Disable Windows service

If you are upgrading a server registered as a Windows service, disable the Windows service before upgrade:

C:\path\to\opendj\bat> windows-service.bat --disableService

After upgrade, enable the server as a Windows service again.

Next steps

Directory server

This page shows how to upgrade a directory server in place.

Before upgrading, make sure you stop the server. Once you have unpacked the new server files, do not modify the server configuration until after you have completed the upgrade process.

Failure to follow the upgrade instructions can result in the loss of all user data.

  1. Make sure you’ve completed the tasks in Before you upgrade in place.

  2. Stop the server.

  3. Proceed to upgrade the server:

    1. When upgrading a server installed from the cross-platform ZIP distribution:

      • Unpack the new files over the old files as described in Unpack files.

      • If the existing server uses a Java version that is no longer supported, follow the steps in Java updates, but do not restart the server yet.

      • Run the upgrade command to bring the server up to date with the new software delivery.

        By default, the upgrade command runs interactively, requesting confirmation before making important configuration changes. For some potentially long-duration tasks, such as rebuilding indexes, the default choice is to defer the tasks until after upgrade.

        You can use the --no-prompt option to run the command non-interactively. In this case, the --acceptLicense option lets you accept the license terms non-interactively.

        When using the --no-prompt option, if the upgrade command cannot complete because it requires confirmation for a potentially long or critical task, then it exits with an error, and a message about how to finish making the changes. You can add the --force option to force a non-interactive upgrade to continue in this case, also performing long-running and critical tasks.

    2. When upgrading a server installed from native packages, use the system package management tools.

    Although unlikely, when the server configuration has changed in an incompatible way with the previous release, the upgrade command can fail when performing property value substitution for a configuration expression. If this happens, change the configuration to a static value during upgrade. Use the configuration expression again after you successfully run the upgrade command.

  4. When the mutable data mounted at runtime differs from that of the instance where you first run the upgrade command, upgrade only mutable data by running the command again with the --dataOnly option at runtime.

    The --dataOnly option can be useful when running the server in a Docker container, for example.

  5. Start the upgraded server.

    At this point, the upgrade process is complete. Refer to the resulting upgrade.log file for a full list of operations performed.

    Replication updates the upgraded server with changes that occurred during the upgrade process.

  6. If you disabled the Windows service to upgrade, enable it again:

    C:\path\to\opendj\bat> windows-service.bat --enableService

Next steps

Directory proxy

This page shows how to upgrade a directory proxy server in place. A directory proxy server has no local user data.

Before upgrading, make sure you stop the server. Once you have unpacked the new server files, do not modify the server configuration until after you have completed the upgrade process.

Failure to follow the upgrade instructions can result in the loss of all user data.

  1. Make sure you’ve completed the tasks in Before you upgrade in place.

  2. Stop the server.

  3. Proceed to upgrade the server:

    1. When upgrading a server installed from the cross-platform ZIP distribution:

      • Unpack the new files over the old files as described in Unpack files.

      • If the existing server uses a Java version that is no longer supported, follow the steps in Java updates, but do not restart the server yet.

      • Run the upgrade command to bring the server up to date with the new software delivery.

        By default, the upgrade command runs interactively, requesting confirmation before making important configuration changes. For some potentially long-duration tasks, such as rebuilding indexes, the default choice is to defer the tasks until after upgrade.

        You can use the --no-prompt option to run the command non-interactively. In this case, the --acceptLicense option lets you accept the license terms non-interactively.

        When using the --no-prompt option, if the upgrade command cannot complete because it requires confirmation for a potentially long or critical task, then it exits with an error, and a message about how to finish making the changes. You can add the --force option to force a non-interactive upgrade to continue in this case, also performing long-running and critical tasks.

    2. When upgrading a server installed from native packages, use the system package management tools.

    Although unlikely, when the server configuration has changed in an incompatible way with the previous release, the upgrade command can fail when performing property value substitution for a configuration expression. If this happens, change the configuration to a static value during upgrade. Use the configuration expression again after you successfully run the upgrade command.

  4. When the mutable data mounted at runtime differs from that of the instance where you first run the upgrade command, upgrade only mutable data by running the command again with the --dataOnly option at runtime.

    The --dataOnly option can be useful when running the server in a Docker container, for example.

  5. Start the upgraded server.

    At this point, the upgrade process is complete. Refer to the resulting upgrade.log file for a full list of operations performed.

    Replication updates the upgraded server with changes that occurred during the upgrade process.

  6. If you disabled the Windows service to upgrade, enable it again:

    C:\path\to\opendj\bat> windows-service.bat --enableService

Next steps

Replication server

This page shows how to upgrade a standalone replication server in place. A standalone replication server has no local user data. If the server holds user data, refer to Directory server instead.

Before upgrading, make sure you stop the server. Once you have unpacked the new server files, do not modify the server configuration until after you have completed the upgrade process.

Failure to follow the upgrade instructions can result in the loss of all user data.

  1. Make sure you’ve completed the tasks in Before you upgrade in place.

  2. Stop the server.

  3. Proceed to upgrade the server:

    1. When upgrading a server installed from the cross-platform ZIP distribution:

      • Unpack the new files over the old files as described in Unpack files.

      • If the existing server uses a Java version that is no longer supported, follow the steps in Java updates, but do not restart the server yet.

      • Run the upgrade command to bring the server up to date with the new software delivery.

        By default, the upgrade command runs interactively, requesting confirmation before making important configuration changes. For some potentially long-duration tasks, such as rebuilding indexes, the default choice is to defer the tasks until after upgrade.

        You can use the --no-prompt option to run the command non-interactively. In this case, the --acceptLicense option lets you accept the license terms non-interactively.

        When using the --no-prompt option, if the upgrade command cannot complete because it requires confirmation for a potentially long or critical task, then it exits with an error, and a message about how to finish making the changes. You can add the --force option to force a non-interactive upgrade to continue in this case, also performing long-running and critical tasks.

    2. When upgrading a server installed from native packages, use the system package management tools.

    Although unlikely, when the server configuration has changed in an incompatible way with the previous release, the upgrade command can fail when performing property value substitution for a configuration expression. If this happens, change the configuration to a static value during upgrade. Use the configuration expression again after you successfully run the upgrade command.

  4. When the mutable data mounted at runtime differs from that of the instance where you first run the upgrade command, upgrade only mutable data by running the command again with the --dataOnly option at runtime.

    The --dataOnly option can be useful when running the server in a Docker container, for example.

  5. Start the upgraded server.

    At this point, the upgrade process is complete. Refer to the resulting upgrade.log file for a full list of operations performed.

    Replication updates the upgraded server with changes that occurred during the upgrade process.

  6. If you disabled the Windows service to upgrade, enable it again:

    C:\path\to\opendj\bat> windows-service.bat --enableService

Next steps

HDAP gateway

Replace the HDAP gateway with the newer version, as for a fresh installation, and rewrite the configuration to work with the new version.

Next steps

DSML gateway

Replace the DSML gateway with the newer version, as for a fresh installation.

Next steps

After you upgrade in place

The DS server upgrade process preserves the existing configuration as much as possible. This maintains compatibility, but there are more steps you must take.

Many example commands on this page use cn=Directory Manager as the name of the directory superuser account. This was the default before DS 7.

Here, cn=Directory Manager stands for the name of the directory superuser account in DS 6.5 and earlier.

Checklist

Use this checklist to make sure you don’t miss these important post-upgrade tasks:

1 Backup files are not compatible between versions. Before starting this task, complete the work to Use the new security model.

2 You would not run all your applications as the Linux root user or the Windows Administrator. Stop using superuser accounts like cn=Directory Manager as service accounts. Many DS setup profiles create service accounts for applications to use when authenticating to DS. For examples of AM service accounts, refer to the base-entries.ldif files in setup profiles under the opendj/template/setup-profiles/AM directory.

3 You can read the opendj/config/config.ldif file to find stale references, but always use the dsconfig command to make changes to the configuration.

4 Before starting this task, complete the work to Use the new security model and to Eliminate outdated password storage.

Use the new security model

If you have upgraded DS 6.5 or earlier servers in place, enable upgraded servers to use the new security model. You can’t add new servers using normal procedures until you have completed these steps. Some new features depend on the new model.

DS release 7 changes the security model to configure replication at setup time, make disaster recovery more straightforward, and simplify symmetric key distribution:

  • In prior releases, trust and symmetric key distribution in a replication topology depend on the replicated cn=admin data base DN. DS servers prior to release 7 reference each others' instance keys and use them to protect symmetric keys in cn=admin data entries.

  • DS servers now rely on a deployment ID and password to derive a shared master key and offer a default PKI to trust each others' certificates. DS servers protect symmetric keys using the shared master key to encrypt and decrypt them. For details, refer to Deployment IDs.

The following examples demonstrate the process of creating keys and updating the configuration for replicas installed with the DS 6.5 evaluation profile:

  1. Make sure you have upgraded all DS servers to version 7 or later.

  2. Generate a deployment ID for the deployment:

    ###
# Generate a deployment ID for the topology.
# Do this once and SAVE THE DEPLOYMENT ID:
$ dskeymgr create-deployment-id --deploymentIdPassword password
<deployment-id>

    For more command options, refer to dskeymgr. The default validity for the deployment ID is 10 years.

  3. For each upgraded server, add at least the shared master key generated using the deployment ID:

    Show details 
    ###
# Use the same deployment ID on each server:
export DEPLOYMENT_ID=<deployment-id>

# Add a shared master key based on the deployment ID:
dskeymgr \
 export-master-key-pair \
 --alias master-key \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin

# Deployment ID-based PKI?
# Add a deployment ID CA certificate:
dskeymgr \
 export-ca-cert \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin

# Deployment ID-based PKI?
# Add a deployment ID-based TLS certificate:
dskeymgr \
 create-tls-key-pair \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin \
 --hostname localhost \
 --hostname opendj.example.com \
 --subjectDn CN=DS,O=ForgeRock

    The default validity for the certificate is one year.

  4. For each upgraded server, start the server, if necessary.

  5. For each upgraded server, update the configuration to use the new keys.

    Show details

    The following example uses the private PKI keys based on the deployment ID and password. At minimum, even if you use your own keys for PKI, update the Crypto Manager to use the shared master key:

    # Copy the keys used to protect secret keys and replication traffic
# to the default key manager keystore.
# This makes the keys available for trust and decryption
# after you switch to the default key and trust managers:
keytool \
 -importkeystore \
 -srckeystore /path/to/opendj/db/ads-truststore/ads-truststore \
 -srcstorepass:file /path/to/opendj/db/ads-truststore/ads-truststore.pin \
 -destkeystore /path/to/opendj/config/keystore \
 -deststoretype PKCS12 \
 -deststorepass:file /path/to/opendj/config/keystore.pin

# Configure the server to wrap new secret keys
# using the new shared master key:
dsconfig \
 set-crypto-manager-prop \
 --set key-manager-provider:"Default Key Manager" \
 --set master-key-alias:master-key \
 --reset digest-algorithm \
 --reset mac-algorithm \
 --reset key-wrapping-transformation \
 --hostname localhost \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --no-prompt

# Deployment ID-based PKI?
dsconfig \
 create-trust-manager-provider \
 --set enabled:true \
 --set trust-store-file:config/keystore \
 --set trust-store-pin:\&{file:config/keystore.pin} \
 --set trust-store-type:PKCS12 \
 --type file-based \
 --provider-name PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

# Switch to the new keys to secure
# administrative and replication communications:
dsconfig \
 set-administration-connector-prop \
 --set ssl-cert-nickname:ssl-key-pair \
 --set trust-manager-provider:PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

dsconfig \
 set-synchronization-provider-prop \
 --provider-name "Multimaster Synchronization" \
 --set key-manager-provider:"Default Key Manager" \
 --set ssl-cert-nickname:ssl-key-pair \
 --set trust-manager-provider:PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

# Switch to the new keys for other secure communications:
dsconfig \
 set-connection-handler-prop \
 --handler-name HTTPS \
 --set ssl-cert-nickname:ssl-key-pair \
 --set trust-manager-provider:PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

dsconfig \
 set-connection-handler-prop \
 --handler-name LDAP \
 --set ssl-cert-nickname:ssl-key-pair \
 --set trust-manager-provider:PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

dsconfig \
 set-connection-handler-prop \
 --handler-name LDAPS \
 --set ssl-cert-nickname:ssl-key-pair \
 --set trust-manager-provider:PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

  6. For each upgraded server, restart the server, causing it to generate new secret keys, wrapped using the shared master key:

    stop-ds --restart

Eliminate outdated password storage

Reversible password storage schemes (3DES, AES, Blowfish, RC4) have been deprecated since DS 7.0. Many password storage schemes are no longer enabled by default for new installations.

After upgrading to DS 7 and later, migrate active accounts away from the following deprecated and outdated password storage schemes:

  • 3DES

  • AES

  • Base64

  • Blowfish

  • CRYPT

  • Clear

  • PBKDF2

  • PKCS5S2

  • SHA-1

  • Salted SHA-1

  • Salted SHA-256

  • Salted SHA-384

  • Salted SHA-512

Follow these steps:

  1. On at least one DS replica, add an index for passwords using deprecated or outdated storage schemes.

    The following example creates the index on an upgraded server with data for dc=example,dc=com in a backend called userRoot. The directory superuser account on the upgraded server has DN cn=Directory Manager:

    dsconfig \
 create-backend-index \
 --backend-name userRoot \
 --type generic \
 --index-name userPassword \
 --set index-type:big-extensible \
 --set big-index-included-attribute-value:3DES \
 --set big-index-included-attribute-value:AES \
 --set big-index-included-attribute-value:Base64 \
 --set big-index-included-attribute-value:Blowfish \
 --set big-index-included-attribute-value:CRYPT \
 --set big-index-included-attribute-value:Clear \
 --set big-index-included-attribute-value:PBKDF2 \
 --set big-index-included-attribute-value:PKCS5S2 \
 --set big-index-included-attribute-value:RC4 \
 --set big-index-included-attribute-value:SHA-1 \
 --set big-index-included-attribute-value:Salted\ SHA-1 \
 --set big-index-included-attribute-value:Salted\ SHA-256 \
 --set big-index-included-attribute-value:Salted\ SHA-384 \
 --set big-index-included-attribute-value:Salted\ SHA-512 \
 --set big-index-extensible-matching-rule:1.3.6.1.4.1.36733.2.1.4.14 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --no-prompt

rebuild-index \
 --baseDN dc=example,dc=com \
 --index userPassword \
 --hostname localhost \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll

    The ds-evaluation setup profile, described in Install DS for evaluation, includes a userPassword big index for reversible password storage schemes.

  2. Search for accounts using these password storage schemes on the replica where you added the index:

    ldapsearch \
 --hostname localhost \
 --port 1636 \
 --useSSL \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --simplePageSize 100 \
 --baseDn dc=example,dc=com \
  "(|(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=3DES)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=AES)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=BASE64)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=BLOWFISH)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=CRYPT)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=CLEAR)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=PBKDF2)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=PKCS5S2)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=RC4)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SHA)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA256)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA384)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA512))" \
 1.1

    If the search returns no matches, set enabled: false for the unused storage schemes in each server configuration. You can skip to the rest of the steps in this procedure.

  3. If the search returns any DNs, migrate active accounts to another storage scheme, such as PBKDF2-HMAC-SHA256.

    For details, refer to Deprecate a password storage scheme. When a user binds successfully with their existing password or changes their password, DS stores the password with the new scheme.

  4. Wait for all active accounts to bind or to update their passwords.

    The definition of active depends on the deployment. You decide how long a user can go without binding before you consider their account inactive. For details, refer to Active accounts.

  5. Run the search again, adding a filter to match active accounts.

    After the migration, the search ideally returns no results.

  6. Once you are confident active accounts no longer use deprecated or outdated storage schemes, set enabled: false for the unused storage schemes in each server configuration.

    Inactive accounts—​those with no binds during the migration—​must now reset their passwords before they can bind.

For additional examples, refer to How do I change a password storage scheme and apply a new password policy to users in DS (All versions)?

Clean up admin data

These steps are required after you upgrade from DS 6.5 and earlier to ensure servers share secret keys according to the new security model.

If, after cleanup, your deployment still stores secret keys under the replicated cn=admin data base DN, do not disable cn=admin data or remove the adminRoot database.

This applies, for example, to deployments that use (deprecated) reversible password storage schemes (3DES, AES, Blowfish, RC4). It also applies to deployments where servers were set up in production mode, and use keys with automatically generated, self-signed certificates to protect replication connections.

If you do choose to disable cn=admin data and remove the adminRoot database, you must first manually ensure that admin data is no longer used, and then remove references to it from your configuration.

  1. Make sure you have upgraded all DS servers to version 7 or later.

    As explained in Checklist at the top of this page, this means purging stale references to retired servers from the new servers' configurations, and updating bootstrap replication server settings to reference only the new, DS 7 servers.

  2. Make sure you have followed the steps in Use the new security model.

  3. Run the cleanup command.

    For example, run the cleanup command on each server with directory superuser credentials. If the credentials are the same on every server, it is enough to run the command once.

    After upgrading from DS 6.5 or earlier, make sure you set the --bootstrapServer option. Target at least two servers for redundancy. The following example uses the servers with IDs 1 and 2 as the bootstrap servers:

    $ dsrepl \
 cleanup-migrated-pre-7-0-topology \
 --bootstrapServer 1 \
 --bootstrapServer 2 \
 --bindDn "cn=Directory Manager" \
 --bindPassword password \
 --hostname localhost \
 --port 4444 \
 --trustAll \
 --no-prompt

    The command is idempotent. You can run it multiple times if the initial run cannot fully complete the cleanup process.

  4. Remove unused configuration settings:

    Show details 
    dsconfig \
 delete-key-manager-provider \
 --provider-name "Crypto Manager Key Manager" \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

dsconfig \
 delete-key-manager-provider \
 --provider-name "Replication Key Manager" \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

dsconfig \
 delete-trust-manager-provider \
 --provider-name "Replication Trust Manager" \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

# Skip this command if the deployment has passwords stored
# with reversible password storage schemes:
dsconfig \
 delete-backend \
 --backend-name adminRoot \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --trustAll \
 --bindPassword password \
 --no-prompt

  5. Replace references to Admin Data in the server configuration.

    Find all references to admin data in your configuration:

    $ grep -i "admin data" /path/to/opendj/config/config.ldif

    How you replace or remove these references depends on your deployment.

  6. Remove unused files:

    # Skip these commands if the deployment has passwords stored
# with reversible password storage schemes:
$ rm -rf /path/to/opendj/db/adminRoot
$ rm -rf /path/to/opendj/db/ads-truststore

Add a monitor user account

The dsrepl status command, and general server monitoring require an account with the monitor-read privilege. Since DS 6, you can create a monitor user account at setup time; however, the setup process does not require that you create such an account, and earlier versions do not offer the option.

If no such account exists, do one of the following:

Use this replicated account when monitoring DS servers and when running the dsrepl status command.

Update LDAP schema

Update LDAP schema definitions to support new features.

When you upgrade servers, the servers inherit existing LDAP schema definitions. This ensures compatibility between the newer and older servers during upgrade; however, upgrade does not apply changes that new features depend on.

Once all servers run the latest software, add LDAP schema definitions required to use additional features:

  1. Make sure you have upgraded all DS servers to version 7 or later.

  2. Compare current schema definitions with the schema templates.

    The following example summarizes the differences for a new server added to a 6.5 deployment:

    $ cd /path/to/opendj
$ diff -q db/schema template/db/schema
Files db/schema/00-core.ldif and template/db/schema/00-core.ldif differ
Files db/schema/03-pwpolicyextension.ldif and template/db/schema/03-pwpolicyextension.ldif differ
Files db/schema/04-rfc2307bis.ldif and template/db/schema/04-rfc2307bis.ldif differ
Only in db/schema: 60-ds-evaluation-schema.ldif
Only in db/schema: 99-user.ldif

    The following table summarizes the changes in detail:

    Schema File Notes Action

    00-core.ldif

    An update of the mail attribute to support UTF-8 characters and cosmetic changes due to schema replication:

    • Each definition in db/schema/00-core.ldif has X-SCHEMA-FILE '00-core.ldif'. No definitions in template/db/schema/00-core.ldif have the X-SCHEMA-FILE extension.

    • Some object classes in db/schema/00-core.ldif are explicitly defined as STRUCTURAL.

    Other minor differences:

    • In 7, some attribute definitions have minimum upper bounds.

    • The schema for collective attributes is extended.

    Replace with template file

    03-pwpolicyextension.ldif

    The new version was rewritten to support fully featured replicated password policies.

    Replace with template file

    04-rfc2307bis.ldif

    In DS 7.2 and later, the new version aligns schema definitions with those of the latest RFC 2703bis Internet-Draft, An Approach for Using LDAP as a Network Information Service.

    Replace with template file

    60-ds-evaluation-schema.ldif

    Added to existing version by the evaluation setup profile.

    Keep existing file

    99-user.ldif

    Contains replication metadata.

    Keep existing file

    Any schema file missing in template/db/schema

    This includes schema from setup profiles and any custom schema definitions for the deployment.

    Keep existing file

  3. For each upgraded server, update the schema to the latest version.

    The following example updates the schema on a single server. Always stop a server before making changes to its files:

    $ cd /path/to/opendj
$ ./bin/stop-ds
$ cp template/db/schema/00-core.ldif db/schema
$ cp template/db/schema/03-pwpolicyextension.ldif db/schema
$ cp template/db/schema/04-rfc2307bis.ldif db/schema
$ ./bin/start-ds

  4. Rebuild indexes for the following attributes, which DS considers degraded:

    • automountInformation

    • automountKey

    • automountMapName

    • gecos

    • ipHostNumber

    • ipNetworkNumber

    • mail

    • memberNisNetGroup

    • memberUid

    • nisMapEntry

    • nisNetgroupTriple

    For details, refer to Automate index rebuilds.

Tune settings

Major software releases include significant changes that can render existing tuning settings obsolete. When upgrading to a new major release of DS or Java software, revisit the system configuration, server configuration, and Java settings. As part of the upgrade process, adjust the settings appropriately to align your deployment with the new software version.

For information and suggestions on tuning, read the Release notes and Performance tuning.

Use string-based server IDs

After upgrading from earlier releases, you can change server IDs to strings:

  1. Make sure you have upgraded all DS servers to version 7 or later.

  2. For each server, change the global server ID to the desired string.

    The following example shows a command that changes a server’s global ID to a string:

    $ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set server-id:ds-us-west-1 \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  3. Restart the server for the change to take effect.

Use the entity tag plugin for ETags

The ETag plugin generates ETag attribute values more efficiently. For compatibility, the plugin is configured by default only on new servers.

After upgrading all servers, you can configure the plugin manually on each server:

  1. Make sure you have upgraded all DS servers.

  2. For each server, configure the plugin:

    $ dsconfig \
 create-plugin \
 --plugin-name "Entity Tag" \
 --type entity-tag \
 --set enabled:true \
 --set invoke-for-internal-operations:true \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

The plugin generates real ETag attributes for new and updated entries.

Activate cloud storage for backup

When upgrading in place from DS 6.5.x and earlier, the upgrade process does not unpack the libraries required to store backup files in the cloud, and does not configure the plugin used for the feature. You must activate cloud storage for backup if you want to use the feature.

  1. Unpack the libraries required to store backup files in the cloud:

    $ cd /path/to/opendj
$ unzip -o -q extensions/backup-cloud-extension.zip

  2. Restart DS.

  3. Configure the cloud storage plugin to use the libraries:

    $ dsconfig \
create-plugin \
--plugin-name Cloud\ Storage\ Plugin \
--type custom \
--set enabled:true \
--set java-class:com.forgerock.opendj.server.backup.cloud.CloudStoragePlugin \
--set plugin-type:initialization \
--hostname localhost \
--port 4444 \
--bindDn "cn=Directory Manager" \
--trustAll \
--no-prompt

Set the cloud storage endpoint for backup

If you back up to cloud storage, set the storage endpoint to control where your backup files go.

Use one of these dsbackup options:

  • --storage-property endpoint:endpoint-url

  • --storage-property endpoint.env.var:environment-variable-for-endpoint-url

For details, refer to Cloud storage endpoint.

Upgrade complete

Strategy: new servers

These pages cover upgrade by adding new servers on new host systems, then retiring old servers. For details about alternative upgrade strategies, refer to Upgrade strategies.

Next steps

Before you add new servers

Fulfill these requirements before upgrading PingDS software, especially before upgrading the software in a production environment. Also refer to the requirements listed in release notes.

Supported Java

  • Always use a JVM with the latest security fixes.

  • Make sure you have a required Java environment installed on the system.

    If your default Java environment is not appropriate, use one of the following solutions:

    • Edit the default.java-home setting in the opendj/config/java.properties file.

    • Set OPENDJ_JAVA_HOME to the path to the correct Java environment.

    • Set OPENDJ_JAVA_BIN to the absolute path of the java command.

  • When running the dskeymgr and setup commands, use the same Java environment everywhere in the deployment and refer to CAs from deployment IDs.

DS software supports the following Java environments:

Vendor Versions

OpenJDK, including OpenJDK-based distributions:

  • AdoptOpenJDK/Eclipse Temurin Java Development Kit (Adoptium)

  • Amazon Corretto

  • Azul Zulu

  • Red Hat OpenJDK

Ping Identity tests most extensively with AdoptOpenJDK/Eclipse Temurin.

Use the HotSpot JVM if possible.

17(1), 21

Oracle Java

17(1), 21

(1) DS requires Java 17.0.8 or later.

TLS cipher support depends solely on the JVM. For details, refer to TLS settings.

CAs from deployment IDs

Due to a change to the Java platform between versions 11 and 17, the keys you generate with the dskeymgr and setup commands using Java 11 are incompatible with keys generated using Java 17 and later.

Using different Java versions is a problem if you use deployment ID-based CA certificates. Replication breaks, for example, when you use the setup command for a new server with a more recent version of Java than was used to set up existing servers.

For details on resolving the issue, refer to Incompatible Java versions.

Next steps

Add new servers

When upgrading by adding new DS 7 and later servers to a DS 6.5 or earlier deployment, add the new directory servers or replication servers as described on this page.

If all the servers are DS 7 or later and use the new security model based on deployment IDs, not cn=admin data, then skip these instructions. Install the new servers as described in the pages on Installation, and rebuild indexes as necessary.

  • Set up replication before upgrade. Do not set up replication for the first time between servers of different versions.

  • The new server you add must first connect to an existing replica that is a directory server, not a standalone replication server.

  • Newer directory servers update LDAP schema definitions to add support for new features. The newer schema definitions are not all compatible with older servers.

  1. Install and set up a new server, but do not start it, yet.

    Because replication is now configured at setup time, you may need to create the new server with some specific arguments. The following table indicates which arguments are needed for which kind of server:

    New server is a…​ Use this replication setup option

    Combined DS/RS

    --replicationPort port

    Standalone DS

    N/A

    Standalone RS

    --replicationPort port

    • Do not use the setup --bootstrapReplicationServer option. In a later step of this procedure, you will use the dsrepl add-local-server-to-pre-7-0-topology command. That command configures the bootstrap replication server settings for the new server based on the existing deployment.

    • Do not use the setup --start option. In a later step of this procedure, you will start the server.

    For details about setup options, refer to Setup hints, and many of the examples that use the setup command.

  2. Configure the new server settings to be compatible with the settings of the existing servers.

    Examples of incompatible default settings include:

    • Password storage schemes not available in earlier versions.

    • String-based server IDs. Server IDs were limited to numbers between 1 and 65535.

      Remove leading 0 (zero) characters when setting a numeric server ID. DS servers classify a server ID with a leading 0 as a string, not a number.

    • String-based group IDs. Group IDs were also limited to numbers.

    • TLS protocols and cipher suites.

    For changes in the release, refer to Incompatible changes. If the existing servers run a release older than 6.5, refer to similar pages in the previous release notes.

  3. Configure the new server as a replica of an existing server that is a directory server, and not a standalone replication server:

    $ dsrepl \
 add-local-server-to-pre-7-0-topology \
 --hostname pre-7-ds.example.com \
 --port 4444 \
 --bindDn "cn=admin,cn=Administrators,cn=admin data" \
 --bindPassword password \
 --baseDn dc=example,dc=com \
 --trustAll \
 --no-prompt

    The existing server in this example is a directory server, as suggested by the ds in the hostname. The dsrepl add-local-server-to-pre-7-0-topology command does not support connecting to a standalone replication server.

    The command configures the new server, discovering the replication servers in the deployment, and setting the bootstrap replication servers.

    The command also generates one or more dsrepl initialize commands. Copy those commands, and add required credentials for use when initializing the new server.

    In the example command shown here:

    • The --bindDn and --bindPassword options reflect either the UID and password of the existing servers' global replication administrator, or the DN and password of any user with sufficient access to act as global administrator on all servers.

    • The insecure --trustAll option is used to simplify this procedure.

      To avoid using this option, add the remote server’s CA or signing certificate to the new server’s keystore, and use the appropriate keystore options.

  4. Start the new server.

  5. Initialize the new server:

    New server is a…​ Initialize these base DNs

    Combined DS/RS

    cn=admin data, cn=schema, all directory data DNs

    Standalone DS

    cn=admin data, cn=schema, all directory data DNs

    Standalone RS

    cn=admin data

    • For cn=admin data and cn=schema, use the dsrepl initialize command(s) from the previous step.

    • For other base DNs, if initializing over the network is appropriate—​for example, because there is little directory data under the base DN compared to available network bandwidth—​use the dsrepl initialize command.

      Otherwise, initialize from LDIF or from backup taken on another new server of the same version. For details, refer to Manual initialization.

      Test the initialization process to make sure you understand the duration and ramifications of the chosen initialization method.

      Use the results to make an evidence-based decision on whether to use backup/restore or export/import instead of online initialization.

  6. Align the change number indexing settings on the new servers to match the same settings on the existing servers.

  7. Rebuild "degraded" mail indexes for the change to the mail attribute schema definition to allow UTF-8 characters.

    The definitions for DS 7.3 and later allow UTF-8, whereas earlier versions allow only ASCII. The change does not affect the data, but does affect mail indexes.

    For details, refer to Automate index rebuilds.

  8. Rebuild indexes as necessary for changes to schema definitions for the RFC 2703bis Internet-Draft, An Approach for Using LDAP as a Network Information Service.

    The definitions for DS 7.2 and later align with those of the latest Internet-Draft. The change does not affect the data, but does affect indexes for the following attributes:

    • automountInformation

    • automountKey

    • automountMapName

    • gecos

    • ipHostNumber

    • ipNetworkNumber

    • memberNisNetGroup

    • memberUid

    • nisMapEntry

    • nisNetgroupTriple

    Use the new schema Use the old schema

    When you add a new server, it replicates the new schema.

    Rebuild "degraded" indexes on existing, older servers.

    For details, on rebuilding degraded indexes, refer to Automate index rebuilds.

    Before upgrading, save a copy of the schema file, db/schema/04-rfc2307bis.ldif, from an existing server.

    After upgrading:

    • Replace the newer schema file with your saved copy.

    • Rebuild "degraded" indexes on the newer servers.

  9. If necessary, add the deprecated /admin and /api (REST to LDAP) endpoints to the server configuration:

    # /admin
$ dsconfig \
 create-http-endpoint \
 --endpoint-name /admin \
 --type admin-endpoint \
 --set authorization-mechanism:"HTTP Basic" \
 --set enabled:true \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

# /api (REST to LDAP)
$ dsconfig \
 create-http-endpoint \
 --endpoint-name /api \
 --type rest2ldap-endpoint \
 --set authorization-mechanism:"HTTP Basic" \
 --set config-directory:config/rest2ldap/endpoints/api \
 --set enabled:true \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Next steps

Upgrade from DS 7.4.0

If the deployment includes a DS 7.4.0 server with data encryption using default settings, follow the procedures in this page.

If the deployment has no DS 7.4.0 servers or does not use data encryption, skip this page.

The problem

Due to an issue (OPENDJ-10211) in the way DS 7.4.0 encrypts data on disk when using the default cipher-transformation: AES/GCM/NoPadding setting, the backend or changelog data on disk and encrypted with 7.4.0 is incompatible with all other DS versions.

If the deployment is configured with non-default cipher-transformation settings that do not use the AES algorithm and GCM mode, the problem doesn’t affect the deployment. In this case, skip this page.

Otherwise, the directory data on disk uses incompatible encryption. Any binary backups of the backend data are also affected. You can’t use the upgrade command to upgrade a DS server to 7.4.0 from earlier versions or from 7.4.0 to later versions.

The solution

You can upgrade by adding new DS servers; follow these steps:

  1. Upgrade by adding new servers, leaving existing 7.4.0 servers in operation during the upgrade.

    When initializing new servers, do not use backup files, as they use incompatible encryption. Instead, either initialize data over the network or initialize from plaintext LDIF.

  2. Change the bootstrap replication servers for each server to stop using the DS 7.4.0 servers.

  3. If you use backup files, create them from the new servers with compatible encryption.

  4. Stop directing client application traffic to the DS 7.4.0 servers.

  5. Wait until the replication purge delay has elapsed (default: 3 days) and retire the DS 7.4.0 servers.

Next steps

After you add new servers

The DS server upgrade process preserves the existing configuration as much as possible. This maintains compatibility, but there are more steps you must take.

Checklist

Use this checklist to make sure you don’t miss these important post-upgrade tasks:

1 Backup files are not compatible between versions. Before starting this task, complete the work to Use the new security model.

2 You would not run all your applications as the Linux root user or the Windows Administrator. Stop using superuser accounts like cn=Directory Manager as service accounts. Many DS setup profiles create service accounts for applications to use when authenticating to DS. For examples of AM service accounts, refer to the base-entries.ldif files in setup profiles under the opendj/template/setup-profiles/AM directory.

3 You can read the opendj/config/config.ldif file to find stale references, but always use the dsconfig command to make changes to the configuration.

4 After you upgrade by adding new servers, but before you retire old servers, update bootstrap replication server settings to remove the old servers, and add the new, DS 7 servers.

5 Before starting this task, complete the work to Eliminate outdated password storage.

Eliminate outdated password storage

Reversible password storage schemes (3DES, AES, Blowfish, RC4) have been deprecated since DS 7.0. Many password storage schemes are no longer enabled by default for new installations.

After upgrading to DS 7 and later, migrate active accounts away from the following deprecated and outdated password storage schemes:

  • 3DES

  • AES

  • Base64

  • Blowfish

  • CRYPT

  • Clear

  • PBKDF2

  • PKCS5S2

  • SHA-1

  • Salted SHA-1

  • Salted SHA-256

  • Salted SHA-384

  • Salted SHA-512

Follow these steps:

  1. On at least one DS replica, add an index for passwords using deprecated or outdated storage schemes.

    The following example creates the index on an upgraded server with data for dc=example,dc=com in a backend called userRoot. The directory superuser account on the upgraded server has DN cn=Directory Manager:

    dsconfig \
 create-backend-index \
 --backend-name userRoot \
 --type generic \
 --index-name userPassword \
 --set index-type:big-extensible \
 --set big-index-included-attribute-value:3DES \
 --set big-index-included-attribute-value:AES \
 --set big-index-included-attribute-value:Base64 \
 --set big-index-included-attribute-value:Blowfish \
 --set big-index-included-attribute-value:CRYPT \
 --set big-index-included-attribute-value:Clear \
 --set big-index-included-attribute-value:PBKDF2 \
 --set big-index-included-attribute-value:PKCS5S2 \
 --set big-index-included-attribute-value:RC4 \
 --set big-index-included-attribute-value:SHA-1 \
 --set big-index-included-attribute-value:Salted\ SHA-1 \
 --set big-index-included-attribute-value:Salted\ SHA-256 \
 --set big-index-included-attribute-value:Salted\ SHA-384 \
 --set big-index-included-attribute-value:Salted\ SHA-512 \
 --set big-index-extensible-matching-rule:1.3.6.1.4.1.36733.2.1.4.14 \
 --hostname localhost \
 --port 4444 \
 --bindDn "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --no-prompt

rebuild-index \
 --baseDN dc=example,dc=com \
 --index userPassword \
 --hostname localhost \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll

    The ds-evaluation setup profile, described in Install DS for evaluation, includes a userPassword big index for reversible password storage schemes.

  2. Search for accounts using these password storage schemes on the replica where you added the index:

    ldapsearch \
 --hostname localhost \
 --port 1636 \
 --useSSL \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --simplePageSize 100 \
 --baseDn dc=example,dc=com \
  "(|(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=3DES)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=AES)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=BASE64)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=BLOWFISH)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=CRYPT)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=CLEAR)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=PBKDF2)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=PKCS5S2)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=RC4)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SHA)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA256)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA384)\
(userPassword:1.3.6.1.4.1.36733.2.1.4.14:=SSHA512))" \
 1.1

    If the search returns no matches, set enabled: false for the unused storage schemes in each server configuration. You can skip to the rest of the steps in this procedure.

  3. If the search returns any DNs, migrate active accounts to another storage scheme, such as PBKDF2-HMAC-SHA256.

    For details, refer to Deprecate a password storage scheme. When a user binds successfully with their existing password or changes their password, DS stores the password with the new scheme.

  4. Wait for all active accounts to bind or to update their passwords.

    The definition of active depends on the deployment. You decide how long a user can go without binding before you consider their account inactive. For details, refer to Active accounts.

  5. Run the search again, adding a filter to match active accounts.

    After the migration, the search ideally returns no results.

  6. Once you are confident active accounts no longer use deprecated or outdated storage schemes, set enabled: false for the unused storage schemes in each server configuration.

    Inactive accounts—​those with no binds during the migration—​must now reset their passwords before they can bind.

For additional examples, refer to How do I change a password storage scheme and apply a new password policy to users in DS (All versions)?

Clean up admin data

These steps are required after you upgrade from DS 6.5 and earlier to ensure servers share secret keys according to the new security model. You must follow the upgrade procedures to add new DS 7 servers until you have completed these steps.

If, after cleanup, your deployment still stores secret keys under the replicated cn=admin data base DN, do not disable cn=admin data or remove the adminRoot database.

This applies, for example, to deployments that use (deprecated) reversible password storage schemes (3DES, AES, Blowfish, RC4). It also applies to deployments where servers were set up in production mode, and use keys with automatically generated, self-signed certificates to protect replication connections.

If you do choose to disable cn=admin data and remove the adminRoot database, you must first manually ensure that admin data is no longer used, and then remove references to it from your configuration.

  1. Make sure you have upgraded all DS servers to version 7 or later.

    If you still have DS 6.5 or earlier servers, retire them before continuing.

    As explained in Checklist at the top of this page, this means purging stale references to retired servers from the new servers' configurations, and updating bootstrap replication server settings to reference only the new, DS 7 servers.

  2. Run the cleanup command.

    For example, run the cleanup command on each server with directory superuser credentials. If the credentials are the same on every server, it is sufficient to run the command once:

    $ dsrepl \
 cleanup-migrated-pre-7-0-topology \
 --bindDn uid=admin \
 --bindPassword password \
 --hostname localhost \
 --port 4444 \
 --trustAll \
 --no-prompt

    The command is idempotent. You can run it multiple times if the initial run cannot fully complete the cleanup process.

  3. Remove unused configuration settings:

    Show details 
    dsconfig \
 delete-key-manager-provider \
 --provider-name "Crypto Manager Key Manager" \
 --hostname localhost \
 --port 4444 \
 --bindDn uid=admin \
 --trustAll \
 --bindPassword password \
 --no-prompt

dsconfig \
 delete-key-manager-provider \
 --provider-name "Replication Key Manager" \
 --hostname localhost \
 --port 4444 \
 --bindDn uid=admin \
 --trustAll \
 --bindPassword password \
 --no-prompt

dsconfig \
 delete-trust-manager-provider \
 --provider-name "Replication Trust Manager" \
 --hostname localhost \
 --port 4444 \
 --bindDn uid=admin \
 --trustAll \
 --bindPassword password \
 --no-prompt

# Skip this command if the deployment has passwords stored
# with reversible password storage schemes:
dsconfig \
 delete-backend \
 --backend-name adminRoot \
 --hostname localhost \
 --port 4444 \
 --bindDn uid=admin \
 --trustAll \
 --bindPassword password \
 --no-prompt

  4. Replace references to Admin Data in the server configuration.

    Find all references to admin data in your configuration:

    $ grep -i "admin data" /path/to/opendj/config/config.ldif

    How you replace or remove these references depends on your deployment.

  5. Remove unused files:

    # Skip these commands if the deployment has passwords stored
# with reversible password storage schemes:
$ rm -rf /path/to/opendj/db/adminRoot
$ rm -rf /path/to/opendj/db/ads-truststore

Add a monitor user account

The dsrepl status command, and general server monitoring require an account with the monitor-read privilege. Since DS 6, you can create a monitor user account at setup time; however, the setup process does not require that you create such an account, and earlier versions do not offer the option.

If no such account exists, do one of the following:

Use this replicated account when monitoring DS servers and when running the dsrepl status command.

Update LDAP schema

Update LDAP schema definitions to support new features.

When you upgrade servers, the servers inherit existing LDAP schema definitions. This ensures compatibility between the newer and older servers during upgrade; however, upgrade does not apply changes that new features depend on.

Once all servers run the latest software, add LDAP schema definitions required to use additional features:

  1. Make sure you have upgraded all DS servers to version 7 or later.

  2. Compare current schema definitions with the schema templates.

    The following example summarizes the differences for a new server added to a 6.5 deployment:

    $ cd /path/to/opendj
$ diff -q db/schema template/db/schema
Files db/schema/00-core.ldif and template/db/schema/00-core.ldif differ
Files db/schema/03-pwpolicyextension.ldif and template/db/schema/03-pwpolicyextension.ldif differ
Files db/schema/04-rfc2307bis.ldif and template/db/schema/04-rfc2307bis.ldif differ
Only in db/schema: 60-ds-evaluation-schema.ldif
Only in db/schema: 99-user.ldif

    The following table summarizes the changes in detail:

    Schema File Notes Action

    00-core.ldif

    An update of the mail attribute to support UTF-8 characters and cosmetic changes due to schema replication:

    • Each definition in db/schema/00-core.ldif has X-SCHEMA-FILE '00-core.ldif'. No definitions in template/db/schema/00-core.ldif have the X-SCHEMA-FILE extension.

    • Some object classes in db/schema/00-core.ldif are explicitly defined as STRUCTURAL.

    Other minor differences:

    • In 7, some attribute definitions have minimum upper bounds.

    • The schema for collective attributes is extended.

    Replace with template file

    03-pwpolicyextension.ldif

    The new version was rewritten to support fully featured replicated password policies.

    Replace with template file

    04-rfc2307bis.ldif

    In DS 7.2 and later, the new version aligns schema definitions with those of the latest RFC 2703bis Internet-Draft, An Approach for Using LDAP as a Network Information Service.

    Replace with template file

    60-ds-evaluation-schema.ldif

    Added to existing version by the evaluation setup profile.

    Keep existing file

    99-user.ldif

    Contains replication metadata.

    Keep existing file

    Any schema file missing in template/db/schema

    This includes schema from setup profiles and any custom schema definitions for the deployment.

    Keep existing file

  3. For each upgraded server, update the schema to the latest version.

    The following example updates the schema on a single server. Always stop a server before making changes to its files:

    $ cd /path/to/opendj
$ ./bin/stop-ds
$ cp template/db/schema/00-core.ldif db/schema
$ cp template/db/schema/03-pwpolicyextension.ldif db/schema
$ cp template/db/schema/04-rfc2307bis.ldif db/schema
$ ./bin/start-ds

  4. Rebuild indexes for the following attributes, which DS considers degraded:

    • automountInformation

    • automountKey

    • automountMapName

    • gecos

    • ipHostNumber

    • ipNetworkNumber

    • mail

    • memberNisNetGroup

    • memberUid

    • nisMapEntry

    • nisNetgroupTriple

    For details, refer to Automate index rebuilds.

Tune settings

Major software releases include significant changes that can render existing tuning settings obsolete. When upgrading to a new major release of DS or Java software, revisit the system configuration, server configuration, and Java settings. As part of the upgrade process, adjust the settings appropriately to align your deployment with the new software version.

For information and suggestions on tuning, read the Release notes and Performance tuning.

Set the cloud storage endpoint for backup

If you back up to cloud storage, set the storage endpoint to control where your backup files go.

Use one of these dsbackup options:

  • --storage-property endpoint:endpoint-url

  • --storage-property endpoint.env.var:environment-variable-for-endpoint-url

For details, refer to Cloud storage endpoint.

Upgrade complete