--- title: After you add new servers description: Post-upgrade checklist for PingDS deployments upgraded by adding new servers, covering backups, stale configs, and bootstrap updates. component: pingds version: 7.5 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: 2025-12-21T15:00:00Z keywords: ["Compatibility", "LDAP", "Migration", "Replication", "Setup & Configuration", "Troubleshooting", "Upgrade"] superseded_by: https://docs.pingidentity.com/pingds/8.1/upgrade-guide/after-you-upgrade.html section_ids: overview: Checklist 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 set-cloud-storage-endpoint: Set the cloud storage endpoint for backup upgrade_complete: Upgrade complete --- # 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: * [icon: square-o, set=fa]Back up your directory data.1 * [icon: square-o, set=fa]Update your scripts to account for [incompatible changes](https://docs.pingidentity.com/pingds/release-notes/changes.html). * [icon: square-o, set=fa]Plan your move away from [deprecated](https://docs.pingidentity.com/pingds/release-notes/deprecation.html) features. * [icon: square-o, set=fa]Move to dedicated service accounts for your directory applications.2 * [icon: square-o, set=fa]Manually review and purge the DS server configurations for stale references to old servers.3 * [icon: square-o, set=fa]Update bootstrap replication servers.4 * [icon: square-o, set=fa]Review [what's new and changed](https://docs.pingidentity.com/pingds/release-notes/preface.html) and adopt useful improvements. * [icon: square-o, set=fa][Eliminate outdated password storage](#eliminate-deprecated-passwords). * [icon: square-o, set=fa][Clean up admin data](#post-upgrade-cleanup) (for upgrades from DS 6.x).5 * [icon: square-o, set=fa][Add a monitor user account](#add-monitor-user). * [icon: square-o, set=fa][Update LDAP schema](#update-schema). * [icon: square-o, set=fa][Tune settings](#upgrade-tuning). * [icon: square-o, set=fa][Set the cloud storage endpoint for backup](#set-cloud-storage-endpoint) if you back up to cloud storage. 1 Backup files are *not* compatible between versions. Before starting this task, complete the work to [Use the new security model](after-you-upgrade-in-place.html#upgrade-deployment-ids). 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](../tools-reference/dsconfig.html) 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](../config-guide/repl-bootstrap.html#remove-bootstrap-replication-server), and [add the new, DS 7 servers](../config-guide/repl-bootstrap.html#add-bootstrap-replication-server). 5 Before starting this task, complete the work to [Eliminate outdated password storage](#eliminate-deprecated-passwords). ## 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`: ```bash 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](../install-guide/setup-ds.html), 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: ```bash 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](../security-guide/pwp-samples.html#example-deprecate-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](../ldap-guide/search-ldap.html#extensible-match-search). 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. Find additional examples in [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.x 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.x servers, retire them before continuing. As explained in [Checklist](#overview) 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: ```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. 3. Remove unused configuration settings: > **Collapse: Show details** > > ```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 > ``` 4. 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.** 5. 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 ``` ## 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` | 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](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 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](../config-guide/idx-config.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. 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](https://docs.pingidentity.com/pingds/release-notes/preface.html) and [Performance tuning](../maintenance-guide/tuning.html). ## 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](../maintenance-guide/backup-restore.html#cloud-storage-endpoint). ## Upgrade complete * [icon: check-square-o, set=fa]Perform [these steps](before-you-upgrade.html) before you add servers * [icon: check-square-o, set=fa]Add new servers: * [icon: check-square-o, set=fa]Follow [these instructions](add-new-servers.html) when upgrading from DS 6.x * [icon: check-square-o, set=fa]Follow [these instructions](from-740.html) when upgrading from DS 7.4.0 * [icon: check-square-o, set=fa]Perform [these steps](after-you-upgrade.html) after you finish adding servers