Starting and Stopping Your Server Instance
Configuring the Server Instance
Configuring the Proxy Components
Configuring Security Between Clients and Servers
Configuring Security Between the Proxy and the Data Source
Configuring Servers With the Control Panel
Configuring Data Replication With dsreplication
To Enable Replication Between Two Servers
To Initialize a Replicated Server
To Initialize an Entire Topology
To Obtain the Status of a Replicated Topology
Configuring Large Replication Topologies
Modifying the Replication Configuration With dsconfig
Retrieving the Replication Domain Name
Changing the Replication Purge Delay
To Change the Replication Purge Delay
Changing the Heartbeat Interval
To Change the Heartbeat Interval
To Change the Isolation Policy
Configuring Encrypted Replication
To Configure Encrypted Replication
Configuring Replication Groups
To Configure A Replication Group
Configuring Assured Replication
To Configure Assured Replication in Safe Data Mode
To Configure Assured Replication in Safe Read Mode
Configuring Fractional Replication
Configuring Replication Status
To Configure the Degraded Status Threshold
Initializing a Replicated Server With Data
Initializing a Single Replicated Server
Initializing a New Replicated Topology
Adding a Directory Server to an Existing Replicated Topology
Changing the Data Set in an Existing Replicated Topology
To Change the Data Set With import-ldif or Binary Copy
Appending Data in an Existing Replicated Topology
Configuring Schema Replication
Replicating to a Read-Only Server
To Configure a Replica as Read-Only
Detecting and Resolving Replication Inconsistencies
Types of Replication Inconsistencies
The External Change Log (ECL) publicizes all changes that have occurred in a directory server database and is particularly useful for synchronizing the LDAP directory with other subsystems. The ECL logs the changes made in replicated suffixes only — changes made in non-replicated suffixes are not logged.
This topic describes how to enable the ECL in your directory service and how to configure client applications so that they can access the ECL.
For information about the architecture of the ECL, see External Change Log in Sun OpenDS Standard Edition 2.2 Architectural Reference. For a description of the ECL internals that will enable you to port applications relying on other change logs, see Porting Applications that Rely on Other Change Logs in Sun OpenDS Standard Edition 2.2 Architectural Reference.
The ECL is available by default when replication is configured in one of the following ways:
By configuring a directory server as part of a replicated topology during installation. For more information, see Setting Up Replication During Installation in Sun OpenDS Standard Edition 2.2 Installation Guide.
By using this method, you can conceivably set up replication on a standalone server, which will enable you to have access to an ECL on a standalone server.
By configuring replication after installation, by using the dsreplication command. For more information, see Configuring Data Replication With dsreplication.
Note - The ECL is not available if you configured replication with the --onlyReplicationServer or --noReplicationServer options.
To verify that the ECL is configured on a directory server instance, run the following search command:
$ ldapsearch -h localhost -p 1389 -D "cn=directory manager" -w password \ -s base -b "" "objectclass=*" namingContexts dn: namingContexts: cn=changelog namingContexts: dc=Europe,dc=com namingContexts: dc=us,dc=com
The ECL can function supports two APIs, which enable two distinct modes of operation:
Cookie mode. This is the recommended API that you should use to access the ECL.
In cookie mode, the client application provides an ECL exchange control in its request to the server. In this mode, the DIT and schema provided in the entries that are returned by the server are not compatible with the LDAP change log draft (http://tools.ietf.org/html/draft-good-ldap-changelog-04).
Draft-compatible mode. This mode should be used only by existing applications that rely on the LDAP change log draft.
In this mode, the DIT and schema provided in the entries that are returned by the server are compatible with the LDAP change log draft.
For improved performance and for simplicity, you should port client applications to use the cookie mode. For more information, see Porting Applications that Rely on Other Change Logs in Sun OpenDS Standard Edition 2.2 Architectural Reference.
Each entry in the ECL has an associated cookie. When a client application sends a SEARCH request, the application provides either the cookie of the last message that was read from the ECL (in a previous SEARCH), or an empty value. The server returns the ECL entries associated with that cookie.
Each entry is returned with its associated cookie. When the application disconnects, it stores the last cookie that it received, and provides this cookie to the server with its next SEARCH request.
This transmission of ECL cookies is illustrated in the following diagram.
The content of the cookie is not a public interface for the client application. The client application sends the cookie as a request control and the server sends the cookie as a response control.
The cookie exchange control has an OID of 1.3.6.1.4.1.26027.1.5.4. If the server identifies that the cookie provided by the application is corrupted, the request is rejected. The request is also rejected if the server identifies that the configuration of the ECL has changed since the server sent this cookie to the application, or that the ECL has been purged and the oldest change stored is newer than the cookie value. In this case, additional information is returned, indicating that a full resynchronization of the external application is recommended.
Note - If a server is disconnected from the replication topology and processes changes from clients connected to it, convergence cannot be guaranteed.
The following request and response examples indicate how the client application searches using the external change log and how the ECL responds.
To start reading the ECL, the client sends the first SEARCH request on cn=changelog, specifying an empty value in the cookie exchange control.
$ ldapsearch -h localhost -p 1389 -D "cn=directory manager" -w password \ --control "1.3.6.1.4.1.26027.1.5.4:false:;" -b "cn=changelog" "(objectclass=*)" "*" +
The server sends each change to the client in a SearchResultEntry. The cookie attribute specifies the new cookie value. This value is also sent in a cookie exchange control, along with the entry.
# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4): dc=europe,dc=com:0000012187eae081456200000001;o=example:; dn: cn=0000012187eae081456200000001,dc=europe,dc=com,cn=changelog objectClass: top objectClass: changeLogEntry replicationCSN: 0000012187eae081456200000001 replicaIdentifier: 17762 targetDN: cn=chek-piao chea,ou=unit1,o=people,dc=europe,dc=com changeTime: 20090528155105Z changes:: cmVwbGFjZTogc2VlQWxzbwpzZWVBbHNvOiBjbj1tY29uZmlnCi0KcmVwbGFjZTogbW9kaW ZpZXJzTmFtZQptb2RpZmllcnNOYW1lOiBjbj1EaXJlY3RvcnkgTWFuYWdlcixjbj1Sb290IEROcyxjb j1jb25maWcKLQpyZXBsYWNlOiBtb2RpZnlUaW1lc3RhbXAKbW9kaWZ5VGltZXN0YW1wOiAyMDA5MDUy ODE1NTEwNVoKLQo= changeType: modify changeLogCookie: dc=europe,dc=com:0000012187eae081456200000001; targetEntryUUID: 08d1830c-02f1-34a6-9cf4-8d1270ec1db0 changeNumber: 0
To read the ECL from the last returned entry, the client sends the SEARCH request on cn=changelog, specifying the last cookie value that it received in the cookie exchange control.
$ ldapsearch -h localhost -p 1389 -D "cn=directory manager" -w password --control "1.3.6.1.4.1.26027.1.5.4:false:dc=europe,dc=com:0000012187eae081456200000001;" -b "cn=changelog" "(objectclass=*)"
The DN for entries that are returned in the ECL is of the form:
cn=replicationCSN,replication-domain-DN,cn=changelog
For example:
dn: cn=0000012187eae081456200000001,dc=europe,dc=com,cn=changelog
The following attributes are returned for ECL entries:
targetDN / MUST changeType / MUST changeTime / MUST changeNumber / MUST // used only for compatibility mode changes / MAY, MUST for add, mod newRDN / MAY, MUST for modrdn deleteOldRDN / MAY, MUST for modrdn newSuperior / MAY, MUST for modrdn replicaIdentifier / MAY, OPERATIONAL / specific OpenDS value replicationCSN / MAY, OPERATIONAL / specific OpenDS value targetEntryuuid / MAY, OPERATIONAL / specific OpenDS value changelogcookie / MAY, OPERATIONAL
No specific server configuration is required for clients to use the ECL, although any client application that needs to use the ECL must be initialized as follows:
This is the value of the lastExternalChangelogCookie attribute of the root DSE. For example:
$ ldapsearch -h localhost -p 1389 -D "cn=directory manager" -w password \ -s base -b "" "objectclass=*" lastExternalChangelogCookie dn: objectClass: top objectClass: ds-root-dse lastExternalChangelogCookie: dc=europe:00000121cea5221c04b100000005 \ 00000121cea5319e04b400000009;
The application can now start reading the ECL by providing the last cookie value as the value of the search control. For example:
$ ldapsearch -h localhost -p 1389 -D "cn=directory manager" -w password --control "1.3.6.1.4.1.26027.1.5.4:false:dc=europe:00000121cea5221c04b100000005 \ 00000121cea5319e04b400000009" -b "cn=changelog" "(objectclass=*)"
Access to the ECL is ruled by global ACIs that can be configured on the server. By default, only the root user can access the ECL.
For information about configuring global ACIs, see Managing Global ACIs With dsconfig.
The ECL is purged simultaneously with the replication change log. For information about changing the interval at which the replication change log is purged, see Changing the Replication Purge Delay.
Sometimes, an application might submit a search request on the ECL, providing a cookie value that is older than the oldest change stored on the server (because a purge has occurred since the last request from that application). In this case, the server rejects the requests and indicates that the cookie is too old and that a full resync is required.