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 should take.

Overview

  • Back up your directory data.

    Backup files are not compatible between versions.

  • Update your scripts to account for incompatible changes.

    For details, refer to Incompatible changes.

  • Perform the steps in "Clean Up Admin Data".

  • Plan your move away from deprecated features.

    For details, refer to Deprecated.

  • 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 command to make changes to the configuration.

    For example, to purge old bootstrap replication servers from the configuration, see "Remove a Bootstrap Replication Server".

  • Review what's new and changed in the intervening releases to identify useful changes.

    For this release, read the Release notes, and plan to take advantage of new features and improvements.

  • Apply the procedures that follow:

Clean Up Admin Data

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

    DS servers need the replicated cn=admin data base DN only for deployments that use (deprecated) reversible password storage schemes (3DES, AES, Blowfish, RC4). If your deployment does not use reversible passwords storage schemes, you can remove cn=admin data after upgrading all DS servers to version 7 or later.

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

  2. Start the servers.

  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: 

    $ dsrepl \
 cleanup-migrated-pre-7-0-topology \
 --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.

Note

After cleanup, the dsrepl status command can show cn=admin data status even if you have removed the backend.

Use the New Security Model

If you have upgraded DS servers in place, enable upgraded servers to use the new security model.

Note

If you started by adding DS 7 or later servers, as described in When Adding New Servers, then the new DS servers already have the keys. In that case, you can skip these steps.

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 key for the deployment: 

    ###
# Generate a deployment key for the topology.
# Do this once and SAVE THE DEPLOYMENT KEY:
$ dskeymgr create-deployment-key --deploymentKeyPassword password
deployment-key

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

    ###
# Use the same deployment key on each server:
export DEPLOYMENT_KEY=deployment-key

# Add a shared master key based on the deployment key:
dskeymgr \
 export-master-key-pair \
 --alias master-key \
 --deploymentKey $DEPLOYMENT_KEY \
 --deploymentKeyPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePasswordFile /path/to/opendj/config/keystore.pin

# Deployment key-based PKI?
# Add a deployment key CA certificate:
dskeymgr \
 export-ca-cert \
 --deploymentKey $DEPLOYMENT_KEY \
 --deploymentKeyPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePasswordFile /path/to/opendj/config/keystore.pin

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

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

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

    ###
# Register the shared master key with the Crypto Manager:
dsconfig \
 set-crypto-manager-prop \
 --set master-key-alias:master-key \
 --set key-manager-provider:"Default Key Manager" \
 --hostname localhost \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
 --no-prompt

# Deployment key-based PKI?
# Switch to the new keys for secure communications:
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

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

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

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
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 FileNotesAction
    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
    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
$  template/db/schema/03-pwpolicyextension.ldif db/schema
$ ./bin/start-ds

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 and Performance Tuning.

Use String-Based Server IDs

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

  1. Make sure all your servers have been successfully upgraded to DS 7.

  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 \
 --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
 --no-prompt

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

Read a different version of :