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.
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
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:
|11389 11636 14444 18443 18989|
|21389 21636 24444 28443 28989|
Add Three DS 7 Servers
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.
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.
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
|31389 31636 34444 38443 38989|
|41389 41636 44444 48443|
|51389 51636 54444 58443 58989|
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.
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.
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.
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.
cn=admin dataand 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.
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.
At this point, the upgrade process is complete, and the service runs DS 7 servers. You can begin to use new DS 7 features.
To stop and remove the servers you installed, you can use the teardown script.