Upgrade to DS 7: #3 In-Place Upgrade

ForgeRock logo This is post 3 of a series of 3 on upgrading servers to ForgeRock Directory Services 7.

If you’ve read the first post in this series, you understand the key differences that you need to know before upgrading.

The most straightforward option when upgrading DS servers is to upgrade in place. One by one, you stop, upgrade, and restart each server individually, leaving the service running during upgrade.

The in-place upgrade process is simpler to understand, and maintains compatibility with earlier settings. It is slower to roll back if you find a problem late in the upgrade process. You must manually enable new features after upgrade.

This demonstration installs two DS 6.5 replicas, upgrades them in place, and deploys keys required to use the new security model.

The demonstration is self-contained, and expected to run in a Bash terminal on your computer. It was written on Ubuntu 20.04 with OpenJDK 8 and 11, installing servers in /path/to. Edit the scripts, if necessary, to try the demo on your computer.

Install Two DS 6.5 Servers

Download the setup script so you can try this yourself. Before you run the setup as is, download DS 6.5 in .zip format.

The setup script installs two DS 6.5 servers that are both directory servers and replication servers. The script configures the servers with the DS evaluation profile (base DN: dc=example,dc=com), and uses Java 8. (DS 6.5 also supports Java 11, but DS 7 supports only Java 11 as of this writing).

After installation, the servers are running, and replicating with each other:

/path/to/ds-rs-111389 11636 14444 18443 18989cn=Directory Manager:password cn=monitor:password
/path/to/ds-rs-221389 21636 24444 28443 28989cn=Directory Manager:password cn=monitor:password

Upgrade in Place

Before you run the upgrade and cleanup script as is, download DS 7 in .zip format.

In a rolling upgrade, the script stops each server, unpacks the new software over the old, and updates the configuration to use Java 11 before running the upgrade command.

To the extent possible, the upgrade command does not change the server configuration, or the LDAP schema. It aims to preserve compatibility, letting you make configuration changes later at your convenience.

On Cleanup

After you finish rolling out new servers, and are satisfied with the results, you retire older servers, and then clean up the configuration of your new servers. The cleanup process is optional, but recommended. It aims to bring the deployment in line with current best practices, and unlocks new features.

Schema Files

The cleanup process replaces older configuration schema with DS 7 templates. In this case, one of the newer schema files lets you use fully featured and replicated password policies. Before you do this in production, review the differences in your schema files.

New Security Model

When you install a new DS 7 server, you use a deployment key and password to derive at least a shared master key. The shared master key protects secret keys, which are then distributed in the replicated data they encrypt. When you upgrade, however, the servers carry on using the ADS instance key to protect secret keys, and replication of cn=admin data to distribute the keys.

The script adds keys based on a deployment key and password, and changes the server configurations to use them. You generate your deployment key with the dskeymgr command and the deployment key password of your choice. Keep the deployment key password secret. The scripts use a demonstration deployment key that was generated with password as the password, and should only be used for this demonstration.

Cleanup Command

When only DS 7 servers using the new security model remain, the script starts the servers, and runs a dsrepl cleanup-migrated-pre-7-0-topology command. This is only part of the cleanup process, limiting the dependency on the old security model based on cn=admin data and ADS keys.

The command is conservative about cleanup. It does not remove cn=admin data, because the deployment depends on the secret keys in the backend to decrypt any data in the deployment that has been encrypted. This includes passwords stored with reversible password storage schemes, encrypted backends, and encrypted backup archives.

Admin Data

If you are sure that your deployment does not use encrypted data, then you can remove cn=admin data and the ADS keys as well, as shown in the script. Otherwise, reencrypt the data before removing the old keys:

  • Deprecate password policies that use reversible storage schemes, and wait until passwords for all active users are hashed.
  • Export encrypted backends to cleartext LDIF, import with encryption based on DS 7 keys:
    • Make sure you have enough time to export and import in less than the replication purge delay.
    • Export the encrypted backend to LDIF.
    • Stop the server.
    • Remove cn=admin data and related configuration entries from the server configuration.
    • Import the backend from LDIF, overwriting existing data, and encrypting with a symmetric key protected by the shared master key.
    • Start the server.Replication online brings the server up to date for changes that happened while it was down.

Replication Status

After making the changes, the script checks replication status and displays the result.

cn=admin data can still appear in the output, even if you removed the data.

Go Further

At this point, the upgrade process is complete, and the service runs DS 7 servers. You can begin to use new DS 7 features.

You can now make additional changes to your DS 7 deployment, such as switching to string-based server IDs, or deprecating old password storage in favor of more secure options.

To stop and remove the servers you installed, you can use the teardown script.


2 thoughts on “Upgrade to DS 7: #3 In-Place Upgrade

  1. Pingback: Upgrade to DS 7: #1 What’s Changed – Margin Notes 2.0

  2. Pingback: ForgeRock Directory Services 7 – Ludo Sketches

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.