PingDS 7.5.1

About upgrades

DS 7 is a major release, much more cloud-friendly than ever before, and different in significant ways from earlier releases.

To upgrade successfully from DS 6.5 and earlier, make sure you understand the key differences beforehand. With these in mind, plan the upgrade, how you will test the upgraded version, and how you will recover if the upgrade process does not go as expected:

Fully compatible replication

Some things never change. The replication protocol remains fully compatible with earlier versions.

This means you can still upgrade servers while the directory service is online, but the process has changed.

Key configuration differences
DS 6.5 and earlier DS 7.0 and later

You configure replication after installation.

You configure replication during installation, before starting the server.

You configure which servers replicate.

You configure bootstrap replication servers. Replicas discover other servers through them.

You configure trust and TLS when configuring replication.

By default, you install servers with a shared deployment ID and password that enables trust and TLS.

Before retiring a server, you unconfigure replication for the server.

After retiring a bootstrap replication server, you remove it from other servers' configurations. Otherwise, no unconfiguration is necessary.

Use the dsreplication command.

Use the dsrepl command.

Replicas share secret keys through cn=admin data.

Replicas protect secret keys with the shared deployment ID and password.

In 6.5 and earlier, you set up DS servers that did not yet replicate. Then, when enough of them were online, you configured replication.

In 7, you configure replication at setup time before you start the server. For servers that will have a changelog, you use the setup --replicationPort option for the replication server port. For all servers, you use the setup --bootstrapReplicationServer option to specify the replication servers that the server will contact when it starts up.

The bootstrap replication servers maintain information about the servers in the deployment. The servers learn about the other servers in the deployment by reading the information that the bootstrap replication server maintains. Replicas initiate replication when they contact the first bootstrap replication server.

As directory administrator, you no longer have to configure and initiate replication for a pure DS 7 deployment. DS 7 servers can start in any order as long as they initiate replication before taking updates from client applications.

Furthermore, you no longer have to actively purge replicas you removed from other servers' configurations. The other servers "forget" a replica that disappears for longer than the replication purge delay, meaning they eventually purge its state from memory and from their changelogs. (DS servers do not "forget" bootstrap replication servers, because each server’s configuration explicitly references its bootstrap replication servers.) With earlier DS versions, you had to purge replicas from other servers' configurations after they were removed. DS servers do this automatically now. No administrative action is required.

These new capabilities bring you more deployment flexibility than ever before. As a trade off, you must now think about configuring replication at setup time, and you must migrate scripts and procedures that used older commands to the new dsrepl command.

Unique string-based server IDs

By default, DS 7 servers use unique string-based server IDs.

In prior releases, servers had multiple numeric server IDs. Before you add a new DS 7 server to a deployment of older servers, you must assign it a "numeric" server ID.

Secure by default

The setup --production-mode option is gone. All setup options and profiles are secure by default.

DS 7 servers require:

  • Secure connections.

  • Authentication for nearly all operations, denying most anonymous access by default.

  • Additional access policies when you choose to grant access beyond what setup profiles define.

  • Stronger passwords.

    New passwords must not match known compromised passwords from the default password dictionary. Also in 7, only secure password storage schemes are enabled by default, and reversible password storage schemes are deprecated.

  • Permission to read log files.

Furthermore, DS 7 encrypts backup data by default. As a result of these changes, all deployments now require cryptographic keys.

Deployment ID required

DS 7 deployments require cryptographic keys. Secure connections require asymmetric keys (public key certificates and associated private keys). Encryption requires symmetric (secret) keys that each replica shares.

To simplify key management and distribution, and especially to simplify disaster recovery, DS 7 uses a shared master key to protect secret keys. DS 7 stores the encrypted secret keys with the replicated and backed up data. This is new in DS 7, and replaces cn=admin data and the keys for that backend.

A deployment ID is a random string generated using the dskeymgr command. A deployment ID password is a secret string at least 8 characters long that you choose. The two are a pair. You must have a deployment ID’s password to use the ID.

You generate a shared master key to protect encryption secrets, and optionally, asymmetric key pairs to protect communications, with the dskeymgr command using your deployment ID and password. Even if you provide your own asymmetric keys for securing connections, you must use the deployment ID and password to generate the shared master key.

DS derives other keys from the deployment ID and password.

When you upgrade, or add a DS 7 server to a deployment of pre-7 servers, you must intervene to move from the old model to the new, and unlock all the capabilities of DS 7.

New backup

As before, backups are not guaranteed to be compatible across major and minor server releases. If you must roll back from an unsuccessful upgrade, roll back the data as well as the software.

When you back up DS 7 data, the backup format is different. The new format always encrypts backup data. The new format allows you to back up and restore data directly in cloud storage if you choose.

Backup operations are now incremental by design. The initial backup operation copies all the data, incrementing from nothing to the current state. All subsequent operations back up data that has changed.

Restoring a backup no longer involves restoring files from the full backup archive, and then restoring files from each incremental backup archive. You restore any backup as a single operation.

The previous backup and restore tools are gone. In their place is a single dsbackup command for managing backup and restore operations, for verifying backup archives, and for purging outdated backup files.

For additional details, refer to the rest of the DS 7 documentation.

To the extent possible, separate the upgrade process from the process of adopting new features. The DS upgrade command encourages this by maintaining compatibility where possible.

Once you have validated that the upgrade has completed successfully, take advantage of the new features available.

Activate new features after upgrade

When you upgrade DS, the upgrade process preserves the existing configuration as much as possible. This maintains compatibility, but it means that you do not have access to all new features immediately after upgrade.

You must take additional steps to complete the process, including activating new features. For details, refer to After you add new servers.

Supported upgrades

From…​ To…​ Important Notes

Official DS release, version 6.0 or later

Official DS release, same edition of directory server or replication server

Supported.

Official ForgeRock release, 2.6.x to 5.5.x

Official DS release, directory server or replication server

Not supported.

Workaround: First, upgrade all servers in the deployment to 6.5 before upgrading further. For details on upgrading to 6.5, refer to the DS 6.5 Installation Guide.

Official ForgeRock release, version 2.4 or 2.5

Official DS release, directory server or replication server

Not supported.

Workaround: Upgrade all servers in the deployment to use at least 2.6.0 before upgrading further. For details on upgrading to that version, refer to Upgrading to OpenDJ 2.6.0.

Evaluation release

Official DS release

Not supported.

The evaluation version includes an additional server plugin and configuration. Official releases do not have an upgrade task to remove the plugin and its configuration.

Unofficial build

Official DS release

Not supported.