Upgrade to DS 7: #2 Add New Servers

This is post 2 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.

One option when upgrading DS servers is to upgrade by adding new servers, leaving the service running during upgrade. Once you finishing adding new servers, and are satisfied with the result, you retire old servers and clean up the new servers to access the newest features.

This process makes it easier to phase out old systems, and might speed up rollback, if necessary. It involves more systems during the upgrade, requires initializing new replicas, and calls on you to reconfigure new servers to align with the older servers. You must manually enable new features after upgrade.

This demonstration installs two DS 6.5 replicas, adds three new DS 7 servers to the deployment, and then cleans up after upgrade, removing the DS 6.5 servers.

IMPORANT: This demonstration is intended as an example.
You must test your own version in a non-production environment before deploying to production.

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	Ports	Credentials
/path/to/ds-rs-1	11389 11636 14444 18443 18989	cn=Directory Manager:password cn=monitor:password
/path/to/ds-rs-2	21389 21636 24444 28443 28989	cn=Directory Manager:password cn=monitor:password
–	–	uid=Admin:password

Add Three DS 7 Servers

Before you run the script to add servers as is, download DS 7 in .zip format.

The script installs these servers that use Java 11:

• /path/to/ds-rs-7: A DS 7 server with the evaluation profile that is a directory server and a replication server.
• /path/to/ds-7: A standalone DS 7 directory server with the evaluation profile.
• /path/to/rs-7: A standalone DS 7 replication server.

Server IDs

Notice that the server IDs are numbers. The existing deployment uses numeric server IDs.

New Security Model

The new servers’ keys rely on a deployment key. 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.

Configuration Compatibility

Before starting the new servers, the script adapts their configurations for compatibility with DS 6.5. In this case, with servers installed with the evaluation profile and no other changes, the only adaptations required are to enable the PBKDF2 and Slated SHA-512 password storage schemes. In DS 7, these password storage schemes are disabled in favor of strong default schemes.

Real-world deployments may well require additional configuration adaptations. DS 7 configures servers to be secure by default. To determine what you must do, compare your DS 6.5 configuration with a fresh DS 7 configuration. It may help to read the DS 6.5 config.ldif alongside the DS 7 config.ldif, entry by entry. This is perhaps the most difficult part of upgrading by adding servers.

Add to Deployment

The script adds the servers to the existing deployment, starts them, and initializes replication from ds-rs-1:

Path	Ports	Credentials
/path/to/ds-rs-7	31389 31636 34444 38443 38989	uid=admin:password cn=monitor:password
/path/to/ds-7	41389 41636 44444 48443	uid=admin:password cn=monitor:password
/path/to/rs-7	51389 51636 54444 58443 58989	uid=admin:password cn=monitor:password

When initializing replication, the script overwrites DS 7 schema with 6.5 schema for compatibility.

While the upgrade is in progress, replication monitoring is split between the older servers, which use dsreplication status, and the newer servers, which use dsrepl status. Run both commands to get a more complete picture of replication status.

Remove 6.5 Servers and Clean Up

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.

Removal of 6.5 Servers

The cleanup script stops and removes the two DS 6.5 servers.

Cleanup Command

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

Removing administrators from admin backend ..... Done
Cleaning and updating configuration of server localhost:34444 ..... Done
Cleaning and updating configuration of server localhost:54444 ..... Done
Cleaning and updating configuration of server localhost:44444 ..... Done
Removing servers from admin backend ..... Done
Removing instance keys from admin backend ..... Done

All servers have been cleaned

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.

Schema Files

As described above, the previous script overwrites DS 7 schema with 6.5 schema for compatibility. The cleanup script reverses that process, replacing older configuration schema with DS 7 templates. Before you do this in production, review the differences in your schema files.

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, re-encrypt 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.