--- title: After you upgrade description: The DS server upgrade process preserves the existing configuration as much as possible. This maintains compatibility, but there are additional steps you must take. component: pingds version: 7.2 page_id: pingds:upgrade-guide:after-you-upgrade canonical_url: https://docs.pingidentity.com/pingds/8.1/upgrade-guide/after-you-upgrade.html llms_txt: https://docs.pingidentity.com/pingds/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2024-10-07T17:18:52Z superseded_by: https://docs.pingidentity.com/pingds/8.1/upgrade-guide/after-you-upgrade.html section_ids: checklist: Checklist upgrade-deployment-ids: Use the new security model eliminate-deprecated-passwords: Eliminate outdated password storage post-upgrade-cleanup: Clean up admin data add-monitor-user: Add a monitor user account update-schema: Update LDAP schema upgrade-tuning: Tune settings upgrade-server-ids: Use string-based server IDs upgrade-etag-implementation: Use the entity tag plugin for ETags upgrade-cloud-backup: Activate cloud storage for backup --- # After you upgrade The DS server upgrade process preserves the existing configuration as much as possible. This maintains compatibility, but there are additional steps you must take. ## Checklist Use this checklist to make sure you don't miss these important post-upgrade tasks: | Task | Done? | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | Back up your directory data.Backup files are *not* compatible between versions. | ▢ | | Update your scripts to account for [incompatible changes](https://docs.pingidentity.com/pingds/release-notes/changes.html). | ▢ | | Plan your move away from [deprecated](https://docs.pingidentity.com/pingds/release-notes/deprecation.html) features. | ▢ | | Move to dedicated service accounts for your directory applications.You would not run all your UNIX applications as root, or all your Windows applications as Administrator. Stop using administrator 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, see the `base-entries.ldif` files in setup profiles under the `opendj/template/setup-profiles/AM` directory. | ▢ | | Manually review and purge the DS server configurations for stale references to old servers.You can read the `opendj/config/config.ldif` file to find stale references, but always use the [dsconfig](../tools-reference/dsconfig.html) command to make changes to the configuration. | ▢ | | After you upgrade by adding new servers, but before you retire old servers, update bootstrap replication server settings to [remove the old servers](../config-guide/replication.html#remove-bootstrap-replication-server), and [add the new, DS 7 servers](../config-guide/replication.html#add-bootstrap-replication-server). | ▢ | | Review [what's new and changed](https://docs.pingidentity.com/pingds/release-notes/preface.html) in the intervening releases to identify useful changes, and take advantage of new features and improvements. | ▢ | | [Use the new security model](#upgrade-deployment-ids) (in-place upgrades only, required). | ▢ | | [Eliminate outdated password storage](#eliminate-deprecated-passwords) | ▢ | | [Clean up admin data](#post-upgrade-cleanup) (required for upgrades from DS 6.5 and earlier).Before starting this task, complete the work to [Use the new security model](#upgrade-deployment-ids). | ▢ | | [Add a monitor user account](#add-monitor-user). | ▢ | | [Update LDAP schema](#update-schema). | ▢ | | [Tune settings](#upgrade-tuning). | ▢ | | [Use string-based server IDs](#upgrade-server-ids). | ▢ | | [Use the entity tag plugin for ETags](#upgrade-etag-implementation). | ▢ | | [Activate cloud storage for backup](#upgrade-cloud-backup) (in-place upgrades only, optional). | ▢ | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Many example commands in 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. | ## 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 cannot add new servers using normal procedures until you have completed these steps*. Some new features depend on the new model.If you started by adding DS 7 or later servers, as described in [When adding new servers](add-new-servers.html), then the new DS servers already have the keys. In that case, you can skip these steps. | DS release 7 changes the security model to let you configure replication at setup time, to make disaster recovery more straightforward, and to simplify symmetric key distribution: * In prior releases, trust and symmetric key distribution in a replication topology depends 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 provide 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, see [Deployment IDs](../security-guide/pki.html#about-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: ```bash ### # Generate a deployment ID for the topology. # Do this once and SAVE THE DEPLOYMENT ID: $ dskeymgr create-deployment-id --deploymentIdPassword password ``` For more command options, refer to [dskeymgr](../tools-reference/dskeymgr.html). 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: > **Collapse: Show details** > > ```bash > \### > # Use the same deployment ID on each server: > export 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. > **Collapse: 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: > > ```bash > # 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: ```bash stop-ds --restart ``` ## Eliminate outdated password storage Reversible password storage schemes (3DES, AES, Blowfish, RC4) are 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 For instructions on migrating accounts away from outdated storage schemes, refer to [How do I change a password storage scheme and apply a new password policy to users in PingDS?](https://support.pingidentity.com/s/article/How-do-I-change-a-password-storage-scheme-and-apply-a-new-password-policy-to-users-in-PingDS) ## 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 upgraded by adding new servers, and still have DS 6.5 or earlier servers, retire them before continuing. 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. If you upgraded in place, make sure you have followed the steps in [Use the new security model](#upgrade-deployment-ids). 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 sufficient to run the command once: * After upgrade in place * After adding new servers ```bash $ dsrepl \ cleanup-migrated-pre-7-0-topology \ --bindDn "cn=Directory Manager" \ --bindPassword password \ --hostname localhost \ --port 4444 \ --trustAll \ --no-prompt ``` ```bash $ 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. 4. Remove unused configuration settings: > **Collapse: Show details** > > * After upgrade in place > > * After adding new servers > > ```bash > 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 > ``` > > ```bash > 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 > ``` 5. Replace references to `Admin Data` in the server configuration. Find all references to admin data in your configuration: ```bash $ 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: ```bash # 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 ``` | | | | - | ---------------------------------------------------------------------------------------------------------------- | | | After cleanup, the `dsrepl status` command can show `cn=admin data` status even if you have removed the backend. | ## 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: * Add the `monitor-read` privilege to an existing, replicated user entry, as demonstrated in [Monitor privilege](../monitoring-guide/ldap-monitoring.html#monitoring-read-privilege). * Add a separate, replicated monitor user account, as demonstrated in [How do I create a dedicated user for monitoring in PingDS?](https://support.pingidentity.com/s/article/How-do-I-create-a-dedicated-user-for-monitoring-in-PingDS) 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: ```bash $ 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` | 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](https://datatracker.ietf.org/doc/html/draft-howard-rfc2307bis-02), *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: ```bash $ 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, if they exist, for the following attributes, which DS considers degraded: * `automountInformation` * `automountKey` * `automountMapName` * `gecos` * `ipHostNumber` * `ipNetworkNumber` * `memberNisNetGroup` * `memberUid` * `nisMapEntry` * `nisNetgroupTriple` For details, see [Automate index rebuilds](../config-guide/indexing.html#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. Adjust the settings appropriately for your deployment as part of the upgrade process. For information and suggestions on tuning, read the [Release notes](https://docs.pingidentity.com/pingds/release-notes/preface.html) and [Performance tuning](../maintenance-guide/tuning.html). ## 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: ```bash $ 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: ```bash $ 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. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you started by adding DS 7 or later servers, as described in [When adding new servers](add-new-servers.html), then the new DS servers already have the libraries and plugin configuration. In that case, you can skip these steps. | 1. Unpack the libraries required to store backup files in the cloud: ```bash $ cd /path/to/opendj $ unzip -o -q extensions/backup-cloud-extension.zip ``` 1. Restart DS. 2. Configure the cloud storage plugin to use the libraries: ```bash $ 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 ```