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
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|
Upgrade in Place
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
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.
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.
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.
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.
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.
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.