Upgrade Considerations

Important considerations for upgrading to this version of the Directory Server

  • To ensure correct search results with Delegated Admin, disable client caching by updating the Delegated Admin HTTP Servlet Extension to return response headers, and then stop and restart the server, as follows:

    dsconfig set-http-servlet-extension-prop --extension-name "Delegated Admin" --set "response-header:Cache-Control: no-cache, no-store, must-revalidate" --set "response-header:Expires: 0" --set "response-header:Pragma: no-cache"

Known Issues/Workarounds

The following are known issues in the current version of the Directory Server

  • When dsreplication is run to add a server to the topology using another node that is not the topology master, it may fail with the following error:

    "Error updating replication configuration on base DN dc=example,dc=com of server 'ds3' (ldaps://localhost:3636). See /Users/<name>/installs/7.2/s3/logs/tools/dsreplication.log for a detailed log of this operation. Details: A communication problem occurred while contacting the server: The connection to server localhost:3389 was closed while waiting for a response to an add request AddRequest(dn='cn=dc_example_dc_com,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config', attrs={Attribute(name=objectclass, values={'top', 'ds-cfg-replication-domain'}), Attribute(name=cn, values={'dc_example_dc_com'}), Attribute(name=ds-cfg-server-id, values={'11443'}), Attribute(name=ds-cfg-base-dn, values={'dc=example,dc=com'})}): A request sent on this client connection caused an internal error in the server. This connection will be terminated."

    The workaround for this issue is to use the topology master for the --host1 parameter of dsreplication to add the new server into the topology.

Resolved Issues

The following issues have been resolved with this release of the Directory Server:

Ticket ID Description

Updated the pass-through authentication plugin to add a bind-dn-pattern configuration property that allows constructing the DN of the remote user from information in the local user entry. Alternately, if the remote server supports simple authentication with a bind DN value that is not actually a valid LDAP distinguished name, this property can be used to supply that identifier. For example, when passing through authentication to Microsoft Active Directory, this property can be used to construct a bind DN that is actually the user principal name (UPN) for the remote account.

Also, updated the pass-through authentication plugin to add an included-local-entry-base-dn configuration property that can be used to indicate which local entries are eligible for pass-through authentication. By default, pass-through authentication is automatically enabled for all users contained in any public backend, but this property can be used to restrict that set of users without the need to define a request criteria. This change also ensures that the server no longer attempts to pass through authentication attempts for root users or topology administrators by default (although if that ability is desired, it can be re-enabled by adding "cn=config" as an included-local-entry-base-dn value).


Updated the server to make the replication missing changes state persist across restarts. If a server is offline for longer than the configured purge delay, then replication cannot automatically bring the server back in-sync with the rest of the topology. To avoid serving stale data, the server enters lockdown mode when it has missed changes. Prior to this change, restarting the server would incorrectly clear this missing changes state, and it would not enter lockdown mode, which could lead to it serving stale data. Now the server must be reinitialized either from a recent backup or by using "dsreplication initialize" to clear the missing changes state.


Added logging for DNS lookups that take longer than a warning threshold. The default warning threshold is 10 seconds. Added the DNS Resolution monitor to track DNS lookup speed.


Fixed an issue that could cause entryUUID mismatches on replicas configured to automatically use entryUUID as the naming attribute for add requests matching a given set of connection or request criteria.


The Delegated Admin configuration has changed significantly. Delegated Admin Resource Types were removed and replaced by REST Resource Types. Delegated Administrators and Delegated Group Administrators were removed and replaced by Delegated Admin Rights and Delegated Admin Resource Rights. Previous configurations are converted to the new configuration definitions by the update tool when the server is updated.


Fixed an issue that could cause an error during an LDIF export of a data set with a large number of non-leaf entries. In such cases, the data is written to multiple files that are merged at the end of the export process. If the LDIF export was encrypted with a passphrase or an encryption settings definition, the merge process could fail, leaving the export spread across multiple files instead of aggregated into a single file.

This issue did not affect the usability or integrity of the export data. It could still be imported, although the administrator would need to list each of the export files in the correct order when performing the import.


The following enhancements were made to the topology manager to make it easier to diagnose the connection errors:

- Added monitoring information for all the failed outbound connections (including the time since it's been failing and the last error message seen when the failure occurred) from a server to one of its configured peers and the number of failed outbound connections.

- Added alarms/alerts for when a server fails to connect to a peer server within a configured grace period.


The dsreplication tool has been fixed to work when the node being used to enable replication is currently out-of-sync with the topology master.


The topology manager will now raise a mirrored-subtree-manager-connection-asymmetry alarm when a server is able to establish outbound connections to its peer servers, but those peer servers are unable to establish connections back to the server within the configured grace period. The alarm is cleared as soon as there is connection symmetry.


Addressed several issues with the pass-through authentication plugin.


If the plugin is configured with a search filter pattern, then it may perform a search to find the entry in the external server that corresponds to the entry for the local user that is trying to bind. In such cases, search requests may have been issued over the same connections that were also been used to process bind operations. The change in authorization identity resulting from those bind attempts may interfere with the ability to perform the searches. The plugin has been updated to ensure that search and bind requests are now issued over separate connections.


If the plugin is configured with multiple external servers, then it can use some or all of those servers in a pass-through authentication attempt. If a search or bind attempt fails against the first server, and if that failure indicates that there may have been a problem with the server or the connection to it, then the plugin would have re-tried the operation in other servers until the attempt succeeds, the attempt fails in a way that does not indicate a problem with the server or the connection, or all servers have been tried. However, if only a single external server had been configured, then no retry attempt would have been made. The plugin has been updated so that if it is only configured with a single external server, and if a failure is encountered while communicating with that server that may benefit from retrying that operation, then the plugin will attempt to establish a new connection to that server and retry the operation.


If the Directory Server is configured with a location, then the pass-through authentication plugin will use that information to determine the order in which the external servers should be accessed. It will first attempt external servers in the same location as the Directory Server, followed by servers in the most preferred failover location, the second-most preferred failover location, and so on. However, the plugin might have used external servers that did not have a location assigned, or that were assigned to a location that is not one of the Directory Server's preferred failover locations. The plugin has been updated to ensure that these servers may be used, albeit with a lower priority than the other servers.


The plugin offered very little information that could help an administrator troubleshoot problems with pass-through authentication processing. Some types of operations could be investigated by enabling debug logging with an appropriate scope, but no information about the pass-through authentication processing would appear in the Directory Server access log. The plugin has been updated to add information about its processing to the bind operation's access log message, including the ultimate success or failure of the pass-through authentication attempt, the result of user mapping, and whether the local user's password was updated. Further, the plugin now makes more information about its internal processing available through the server's debug logging facility.