Documentation updates

In addition to the changes described elsewhere in these notes, the published documentation for each DS version includes the following important changes.

DS 7.3

Date Description

Date	Description
2023-04-04	Initial release of Directory Services 7.3 software. The Log message reference now documents all messages including those related to backup. DS documentation now depicts simpler but sufficient deployments with fewer servers for the following benefits: Less complexity for maintainers. Simpler troubleshooting when problems arise. Cheaper deployments. Less replication traffic. Try a simple deployment first and test the results. Use advanced capabilities, such as standalone servers and specialized replication topologies, only when a deployment requires them. For details, refer to the AM and DS deployment documentation. Added Efficiently store backup files. Updated Cache internal nodes to fix the advice about DB cache metrics. Updated Use your own cryptographic keys to list required settings for X.509 key usage extensions. Updated Track last login time and Active accounts to explain last login time format alternatives. Updated the supportextract reference to clarify why the command requires the `top -H` option. Added Different data under different base DNs to clarify why reusing base DNs for multiple setup profiles can lead to errors. Fixed the JSON File Based Access Log Publisher reference to indicate you can change the `log-directory` setting without restarting the component.

2023-04-04

Initial release of Directory Services 7.3 software.

The Log message reference now documents all messages including those related to backup.
DS documentation now depicts simpler but sufficient deployments with fewer servers for the following benefits:
- Less complexity for maintainers.
- Simpler troubleshooting when problems arise.
- Cheaper deployments.
- Less replication traffic.
Try a simple deployment first and test the results. Use advanced capabilities, such as standalone servers and specialized replication topologies, only when a deployment requires them. For details, refer to the AM and DS deployment documentation.
Added Efficiently store backup files.
Updated Cache internal nodes to fix the advice about DB cache metrics.
Updated Use your own cryptographic keys to list required settings for X.509 key usage extensions.
Updated Track last login time and Active accounts to explain last login time format alternatives.
Updated the supportextract reference to clarify why the command requires the top -H option.
Added Different data under different base DNs to clarify why reusing base DNs for multiple setup profiles can lead to errors.
Fixed the JSON File Based Access Log Publisher reference to indicate you can change the log-directory setting without restarting the component.

DS 7.2

Date	Description
2023-04-27	Release of Directory Services 7.2.2 software.
2023-01-26	Release of Directory Services 7.2.1 software. Updated the pages on upgrade to clarify which steps apply only to upgrades from DS 6.5 and earlier. Updated After you upgrade to clarify which steps are required. Corrected an example in Audit configuration changes. Updated Indexes to improve the explanation of big indexes. Updated HTTP-based monitoring to clarify that the `/metrics/api` endpoint represents a collection you query, and requires a `_queryFilter` query string parameter. Fixed the LDAP metrics reference and Prometheus metrics reference to remove obsolete metrics that were previously identified as removed in the release notes. Updated the Java prerequisites section to recommend Java 11.0.12 or later for deployments on Java 11.
2022-06-30	Initial release of Directory Services 7.2 software. Added Replication status (LDAP) to explain the `ds-mon-status` attribute values, and actions to take when the status is not `Normal`. Added Debug a missing index, and updated the page to clarify answers to common questions about indexing. Added Cloud storage samples to show realistic commands for backing up and restoring data at cloud providers. Updated JSON query filters and added Complex JSON queries to demonstrate support for complex JSON query filters. Added Check account usability to demonstrate use of the LDAP account usability control. Added Test password policies to suggest using the DS password quality advice features to evaluate the effectiveness of a new password policy. Updated the steps in Bootstrap replication servers to clarify that you only need to restart the server after changing its configuration if the server loads the list of bootstrap replication servers from the environment.

DS 7.1

Date	Description
2023-05-25	Release of Directory Services 7.1.5 software.
2022-10-11	Release of Directory Services 7.1.4 software.
2022-09-09	Release of Directory Services 7.1.3 software. Corrected an example in Audit Configuration Changes. Fixed the LDAP Metrics Reference and Prometheus Metrics Reference to remove obsolete metrics that were previously identified as removed in the release notes. Fixed the text to align with the example in When Adding New Servers.
2022-05-18	Updated Configure a NIST-Inspired Subentry Policy to clarify the default PBKDF2 iteration settings for the enabled password storage schemes. Updated Java to clarify that to use TLS 1.3 with PKCS#11, DS requires Java 11.0.8 or later. Updated Deployment Keys to clarify that the need for a single, unique deployment key and password per deployment.
2022-04-25	Mentioned support for Java 17. DS 7.1.1 and later support Java 17.0.3 and later. Updated Encrypt changelog data to clarify that changelog encryption affects only data on disk. Updated JMX-based monitoring to show how to connect with a user using a simple bind and an insecure connection.
2022-02-28	Release of Directory Services 7.1.2 software. Updated Fractional replication to clarify which attributes are replicated everywhere in the fractional replication deployment pattern. Updated Deployment IDs to clarify that a deployment ID is required for all deployments. Updated Antivirus interference to limit the scope of what you allow antivirus and intrusion detection software to scan. Updated When adding new servers and Clean up admin data to be more explicit about when to start new DS 7 servers, and when to retire older servers.
2022-02-08	Added Cloud storage samples to show realistic commands for backing up and restoring data at cloud providers. Added Stop replicating permanently to clarify how to remove a server from a replication topology. Added Filtering results (Prometheus) demonstrating how to filter Prometheus output by changing configuration settings.
2022-01-12	Clearly indicate in Java that DS requires Java 11.0.6 or later. Updated Clean up admin data to clarify that before removing admin data, you must replace or remove references to admin data from your configuration.
2021-12-15	Corrected the command in Read-only replicas that configures a server to accept replication updates, and refuse updates from client applications. Updated the list of actions at the beginning of After you upgrade to clarify when and how to change bootstrap replication server settings in an upgrade that involves adding new servers and retiring old servers.
2021-11-17	Updated Troubleshooting to clarify that proxied authorization as an anonymous user is supported, but not recommended. Added Add a bootstrap replication server to demonstrate the command to configure a new bootstrap replication server. Updated Enable StartTLS and Set the HTTPS Port to clarify when you might need to use the `ssl-cert-nickname` setting.
2021-10-26	Updated Install DS as an IDM repository and Install DS for user data to clarify why to use the `am-identity-store` setup profile when storing AM identities. Added Check profiles to indicate how to list the profiles selected at setup time.
2021-09-28	Release of Directory Services 7.1.1 software. Fixed the procedures in After you upgrade to retain access to required secret keys when upgrading a production-mode server in place.
2021-08-05	Updated Manual initialization to clarify the limitations of alternative methods for manually initializing replicas. Added Replication Status (LDAP) to explain the `ds-mon-status` attribute values, and actions to take when the status is not `Normal`. Updated Install DS for custom cases to clarify the steps to follow when you set up DS replicas without a setup profile, and then create backends that you want to replicate.
2021-06-29	Corrected Replication and data sovereignty to indicate that the top entries in the example domain should not be replicated. Added a note to Initialize from LDIF that clarifies when to follow the steps in Restore to a known state instead.
2021-06-08	Described how to Add a monitor user account after upgrading a service without a replicated account for monitoring. Added Install with existing cryptographic keys, and procedures for using your own keystores and truststores for transport layer security in Key management. Updated Delete entries and Delete (REST) to clarify that deleting a subtree can be a resource-intensive operation. The resources required to remove a branch depend on the number of LDAP entries to delete.
2021-06-02	Updated Incompatible changes to clarify that the `dskeymgr` command no longer supports using the `--alias` and `--outputFile` options together. Updated About the evaluation setup profile and Proxied authorization to clarify that if you are not using the DS evaluation setup profile, you must correctly configure access for successful proxied authorization.
2021-05-12	Initial release of Directory Services 7.1 software. Adapted the Upgrade pages to make them easier to use: When adding new servers reiterates that replication configuration now happens at setup time, and clarifies that the new replica cannot initially connect to an existing standalone replication server. The existing server must be a directory server, not a standalone replication server. After you upgrade describes how to manually update LDAP schema after upgrade. Added Back sp using snapshots and Restore from a snapshot to explain the constraints when using file system snapshots for backing up and restoring directory data. Updated Rebuild indexes to reflect best practices. Updated Cache internal nodes to clarify what to monitor when determining whether to add memory for DB cache. Restored Estimate minimum DB cache size. Updated Add a base DN to a backend to show how to create a replication domain for the new base DN. Updated Cloud storage to mention the need for access to delete files, and the need to restart DS after setting environment variables. Updated Read schema to explain key features of attribute type definitions. Added an example password policy that configures account lockout in Lock accounts after repeated bind failures. Updated ACI subjects to clarify how the security strength factor (`ssf`) setting in ACIs can help neutralize STRIPTLS attacks. Added a table of default global access control policies in Proxy global policies. Updated REST API documentation as the setup process disables API descriptors by default.

DS 7.0

Date	Description
2022-01-12	Clearly indicated that DS requires Java 11.0.6 or later.
2021-11-17	Updated Troubleshooting to clarify that proxied authorization as an anonymous user is supported, but not recommended. Updated Manual Initialization to clarify the limitations of alternative methods for manually initializing replicas.
2021-06-29	Added a note in Initialize from LDIF that clarifies when to follow the steps in Restore to a Known State instead. Corrected Replication and Data Sovereignty to indicate that the top entries in the example domain should not be replicated. Described how to Add a Monitor User Account after upgrading a service without a replicated account for monitoring. Updated Rebuild Indexes to note that, when a server rebuilds an index online, the data in the affected database backend is temporarily unavailable to client applications.
2021-04-28	Added Back Up Using Snapshots and Restore From a Snapshot to explain the constraints when using file system snapshots for backing up and restoring directory data.
2021-04-06	Updated Restore to clarify that even a single directory server replica replays changes after you restore data, and to link to the procedure for restoring data to a known state, should you choose to prevent this. Added Remove a Bootstrap Replication Server to demonstrate how to purge a bootstrap replication server from other servers' configurations. DS servers now purge replica state from memory and from changelogs when a replica disappears for longer than the replication purge delay. This happens without any administrative action. They do not purge bootstrap replication servers from their configurations, however. You must do that manually after retiring a bootstrap replication server. Updated the release notes to mention known issue OPENDJ-7905.
2021-03-29	Release of Directory Services 7.0.2 software.
2021-02-04	Adapted the Upgrade Guide to make it easier to use: When Adding New Servers reiterates that replication configuration now happens at setup time, and clarifies that the new replica cannot initially connect to an existing standalone replication server. The existing server must be a directory server, not a standalone replication server. After You Upgrade describes how to manually update LDAP schema after upgrade.
2020-12-10	Release of Directory Services 7.0.1 software. Updated When Adding New Servers to reiterate that replication configuration now happens at setup time. Updated Install DS for User Data to clarify that the procedure is for installing your own user data. Updated Restrict Protocols and Cipher Suites to correct the examples demonstrating how to configure a server to require TLSv1.3. Updated List Protocols and Cipher Suites to correct the description of the `ECDHE_RSA` algorithm. Updated Use a Non-Default Superuser Account to add the missing `cn` attribute in the sample alternative directory superuser entry. Updated Use the Debian Package to demonstrate installing the `java11-runtime` virtual package, which is a dependency of the DS Debian package.
2020-09-07	Fix Javadoc search box.
2020-08-10	Initial release of Directory Services 7.0 software. Best practices Updated Java Settings to reflect current recommendations for JVM settings. Added Linux Page Caching to explain how to avoid long pauses when the kernel flushes dirty pages to disk. Added Disaster Recovery. Added On Load Balancers with recommendations for your deployment. Added Tune Settings to underline the importance of revisiting tuning settings during major version upgrades. Added Custom Schema to demonstrate how to add a custom attribute with an enumeration syntax. Updated Server Commands to explain that commands that change server files must run as a user who has the same filesystem permissions as the user who installs and runs the server. Updated Groups to more strongly recommend dynamic groups over static groups. Updated Authentication (Binds) to emphasize the role of identity mappers. Better examples Many more examples throughout the documentation now use secure connections to servers. Updated Getting Started to include Windows PowerShell examples alongside the Bash examples. Updated HTTP-Based Monitoring and LDAP-Based Monitoring to add examples showing how to monitor operation and work queue statistics, database size, and active users. Errata Updated Install DS for AM Identities to mention that the default base DN for the profile is `ou=identities`. Updated Metric Types Reference to clarify the definitions of monitoring metrics. Updated Active Accounts to fix an incorrect example, and to clarify that the format string must match the syntax of the attribute. Updated Necessary Indexes to use the appropriate filter use metrics, which were new in DS 6. Updated Support for Languages and Locales to clarify that although DS software supports many locales, DS software is only partially localized. Reorganization The documentation now uses titles that better reflect the content. For details, refer to Having Trouble Finding Something? Reworked Install Directory Proxy to make it easier to get started with DS directory proxy servers. Moved the section on configuration expressions to Property Value Substitution. Updated Enable the External Changelog to clarify which configuration is required, and to cover standalone directory servers. The separate procedure, To Enable the External Change Log (Standalone Server), has been removed. Replication Added Port Use and Operations to describe how replication uses DS server ports that must remain open to remote clients. Updated Disk Space Thresholds to remove the claim that replication updates are applied after the disk full threshold is reached. Updated When Adding New Servers to explain that you must set up replication for the first time between servers of the same version. Updated Install Standalone Servers and Replication to clarify that if you want to restrict TLS protocols or cipher suites, do so before configuring replication. Updated About Replication and the release notes to clarify how replication is resilient to host clock anomalies. Updated Replication Delay (LDAP) and Replication Delay (Prometheus) to provide a better explanation of replication delay metrics. Install Standalone Servers demonstrates simplified setup processes. Redundant procedures for standalone servers were removed from the documentation on configuring replication. Simplified Move a Server. REST Added Map LDAP Entries and Nested Resources to demonstrate additional REST to LDAP mappings. Updated API Configuration to clarify that resource type names can only be reused when referring to identical resource type definitions. Security Added Authenticate With a Third-Party Certificate to clarify how to safely allow authentication with client certificates that are self-signed or not signed by a CA you control. Updated Certificate-Based Authentication to clearly indicate how to trust a certificate that was not signed by a well-known CA. Updated Assign Password Policies to clarify that you must not assign more than one password policy to the same account. Rewrote parts of Cryptographic Keys to clarify when to use a private CA and when to use a public CA. Setup Added a reference to the setup profile API in Create Your Own. Added a table of backends with default settings to Data Storage.

DS 6.5

Date	Description
2022-08-03	Release of DS 6.5.6.
2021-11-10	Corrected a link in Product Improvements.
2021-08-16	Release of DS 6.5.5. Added Linux Page Caching to explain how to avoid long pauses when the kernel flushes dirty pages to disk.
2021-06-29	Added a note in To Initialize All Servers From the Same LDIF that clarifies when to follow the steps in To Restore All Replicas to a Known State instead. Corrected Data Replication and Data Sovereignty to indicate that the top entries in the example domain should not be replicated. Updated HTTP-Based Monitoring and LDAP-Based Monitoring to clarify that the current replication delay metric is only meaningful once the server has received replication updates. Updated Rebuilding Indexes to note that, when a server rebuilds an index online, the data in the affected database backend is temporarily unavailable to client applications.
2020-11-24	Updated Troubleshooting TLS/SSL Connections and How Certificates are Used to add an example command that demonstrates how to list trusted certificates with the Java 8 `keytool` command.
2020-11-06	Fixed the list of known issues for 6.5.0.
2020-09-23	Release of DS 6.5.4. Updated Monitoring Metrics to add notes that some JVM metrics, particularly GC-related metrics, depend on the JVM version and configuration. Updated Fulfilling Storage Requirements to highlight that DS servers do not support NFS for directory data. Fixed the port number for the first server in Trying Replication.
2020-02-27	Release of DS 6.5.3. Updated To Enable the External Change Log to clarify which configuration is required, and to cover standalone directory servers. The separate procedure, To Enable the External Change Log (Standalone Server), has been removed. Added an explanation for Crypto Manager support for PKCS#11 modules. Changed `dsreplication enable` to `dsreplication configure` in examples. Removed obsolete options in `ldifdiff` examples.
2020-01-22	Added OPENDJ-5423 to the list of fixes for DS 6.5.1.
2019-12-20	Updated Changing Server Certificates to clarify that, when using a keystore to hold DS server keys, the password for the keystore and any private keys it contains must be the same. Updated To Allow a User to Read the Change Log to include access to changelog attributes on the root DSE entry. The IDM liveSync feature requires access to these attributes. Updated LDAP Metrics by Name to fix the types of the `ds-mon-updates-inbound-queue` and `ds-mon-updates-outbound-queue` metrics, which are integers.
2019-12-20	Added Replication Network Use and Operations to describe how replication uses DS server ports that must remain open to remote clients. Updated Troubleshooting LDIF Import to reference the correct configuration property for relaxing syntax checking.
2019-11-12	Updated Running in a Container as the section is no longer relevant to Java 8 update 191 and later releases. Updated Preventing Interference With Antivirus Software to clarify how to prevent interference. Added To Disable Change Number Indexing to explain how to disable change number indexing when not needed. For example, disable change number indexing when using DS as a CTS store for AM. Updated Metric Types to clarify the definitions of monitoring metrics.
2019-09-17	Updated the release notes to indicate deprecated JVM monitoring metrics. Added Upgrading System and Server Tuning to underline the importance of revisiting tuning settings during major version upgrades. Updated To Set Up a Directory Proxy Server to clarify the requirements when setting up a directory proxy server in production mode. Added On Using a Load Balancer with recommendations for your deployment. Updated Resetting the Directory Manager’s Password to indicate the default file that holds the directory superuser entry. Added To Transform a Directory Server/Replication Server Into a Standalone Directory Server. Updated Choosing the Listen Address for Replication to fix a broken link.
2019-06-20	Release of DS 6.5.2. Updated Java Settings to remove mention of the `-XX:+UseAES -XX:+UseAESIntrinsics` options. Recent JVM versions enable these options automatically. If you enable them manually, you may also need the `-XX:+UnlockDiagnosticVMOptions` option. Updated Managing Data Replication to clarify that you should not run `dsreplication configure` and `dsreplication initialize` commands at the same time, nor should you run multiple `dsreplication configure` commands at the same time.
2019-04-10	Release of DS 6.5.1. Updated documentation for all `setup` command profiles that now let you set the domain or the base DN.
2018-11-28	Initial release of DS 6.5. Added a new guide, Getting Started , that provides a quick, hands-on looks at what Directory Services software can do. Added a new chapter, Configuring REST APIs, focused on administrative work to build REST APIs. The chapter includes a new section, Mapping JSON Profiles to LDAP, as an example for administrators creating new REST APIs starting from JSON resources rather than LDAP entries. Added a new chapter, Deploying for DevOps and SaaS, that focuses on use of DS software in DevOps and SaaS deployments. Added a section, Setting Disk Space Thresholds For Replication Changelog Databases, showing how to set low and full disk thresholds for replication server changelog databases. Updated To Add a New Replica to an Existing Topology to reflect the need to use the `dsreplication` command installed with a 2.6 server when adding a new server to a replication topology with 2.6.x servers. Rewrote the section, Choosing Load Balancing Settings, to clarify how to choose among the alternatives offered by directory proxy servers. Attribute Types now includes a Used By list in each table of attribute properties. The list consists of links to sections describing the object classes that require or allow the the attribute. A new section shows how to back up and restore configuration files. Refer to Backing Up and Restoring Configuration Files. Added a step in To Upgrade Replicated Servers showing how to add missing privileges to the global administrator account. These privileges are required when using the `dsreplication status` command. Added an example of the proxy user and ACI required on DS directory servers. Refer to To Set Up a Directory Proxy Server. Corrected the synopsis for `targattrfilters` in ACI Targets. The documentation incorrectly suggested `(targattrfilters != "expression")` as a legal ACI target. In an ACI target, `targattrfilters` must be set equal to an expression, as in `(targattrfilters = "expression"). The documentation also incorrectly indicated that you separate `targattrfilters` expressions with semicolons. Instead, use commas to separate multiple `targattrfilters` expressions. Clarified in Updating Resources that an update operation requires a JSON payload including all the writable fields of the resource that you want to retain. The update replaces the writable fields of the resource with the values in your JSON payload. If you want to change only part of a JSON resource, refer to Patching Resources instead. Updated To Set Up JMX Access to explain how to avoid periodic full garbage collection events when using JMX.

DS 6.0

Date	Description
2021-12-14	Added To Disable Change Number Indexing to explain how to disable change number indexing when not needed. For example, disable change number indexing when using DS as a CTS store for AM. Updated the list of fixed issues to include OPENDJ-4729.
2019-09-26	Updated Preventing Interference With Antivirus Software to clarify how to prevent interference.
2018-11-26	Fixed paths to point to the correct `ads-truststore` file location, which is now `/path/to/opendj/db/ads-truststore` by default.
2018-06-27	Clarified that Solaris is no longer supported.
2018-06-18	Corrected the synopsis for `targattrfilters` in ACI Targets. The documentation incorrectly suggested `(targattrfilters != "expression")` as a legal ACI target. In an ACI target, `targattrfilters` must be set equal to an expression, as in `(targattrfilters = "expression").
2018-05-13	Added a step in To Upgrade Replicated Servers showing how to add missing privileges to the global administrator account. These privileges are required when using the `dsreplication status` command.
2018-05-04	Initial release of Directory Services 6.0. Added a Deployment Guide. Updated Initializing Replicas to clarify the tradeoffs to consider when deciding how to initialize replication. The section has also been updated to demonstrate the `dsreplication initialize` command, which is the subcommand to use when initializing a single replica. Updated Enforcing Strong Passwords and Strong Password Storage to improve the recommendations regarding password storage. Added Adding a REST to LDAP Mapping for a Custom Object to demonstrate how to configure your REST to LDAP APIs. Added Adding Subentry Password Policies to demonstrate how to use this feature with REST to LDAP. The Javadoc now describes all ForgeRock classes and interfaces required to write server plugins and LDAP client applications.

DS 5.5

Date	Description
2020-11-06	Corrected the lists of key fixes for 5.5.0 and 5.5.1.
2020-04-03	Release of Directory Services 5.5.3. Added To Disable Change Number Indexing to explain how to disable change number indexing when not needed. For example, disable change number indexing when using DS as a CTS store for AM.
2018-11-26	Added On Using a Load Balancer with recommendations for your deployment. Updated Preventing Interference With Antivirus Software to clarify how to prevent interference.
2018-10-01	Release of Directory Services 5.5.2. Removed the `-A` option from the `modrate` and `searchrate` tools reference. This option was never supported.
2018-07-19	Release of Directory Services 5.5.1. Clarified when you must use `-XX:+UseCompressedOops`. Documented the impact of the name change from `OpenDJ` to `ForgeRock Directory Services`. Documented that each backend needs its own backup directory in Backing Up Directory Data. Clarified that Solaris is no longer supported. Fixed contradictory tuning advice for JVM new generation in Java Settings. Corrected the synopsis for `targattrfilters` in ACI Targets. The documentation incorrectly suggested `(targattrfilters != "expression")` as a legal ACI target. In an ACI target, `targattrfilters` must be set equal to an expression, as in `(targattrfilters = "expression"). Updated Using Built-In Functions to reflect that the `read()` and `readProperties()` functions require absolute paths, not relative paths. Fixed the example for setting `group-id` on a replication server in To Set Up Replication Groups. Fixed the explanation of how the REST to LDAP gateway maps an HTTP Basic user name to an LDAP bind DN in Gateway Configuration File. Fixed broken links to the Configuration Reference. Sorted properties correctly in the Configuration Reference. Fixed an error in the online LDIF export example shown in To Export LDIF Data. The Javadoc now describes all ForgeRock classes and interfaces required to write server plugins and LDAP client applications.
2017-10-18	Initial release of Directory Services 5.5. A new LDAP Schema Reference is available. This reference covers the LDAP schema elements defined by default. Database Cache Settings now better describes caching for larger directories, such as those with 10 million entries or more. Initializing Replicas has been updated to suggest how to initialize replication depending on your circumstances. The documentation on Breaking a Multi-Role Server Into Standalone Components has been removed. Instead of creating a multi-role (DS/RS) server and then splitting it apart, use the `setup` command to create standalone servers at installation time.

DS release notes