# $OpenLDAP$
-# Copyright 2003, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 2003-2007 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: LDAP Sync Replication
-The LDAP Sync replication engine is designed to function as an
-improved alternative to {{slurpd}}(8). While the replication with
-{{slurpd}}(8) provides the replication capability for improved capacity,
-availability, and reliability, it has some drawbacks :
-
-^ It is not stateful, hence lacks the resynchronization capability.
-Because there is no representation of replica state in the replication
-with {{slurpd}}(8), it is not possible to provide an efficient mechanism
-to make the slave replica consistent to the master replica once
-they become out of sync. For instance, if the slave database content
-is damaged, the slave replica should be re-primed from the master
-replica again. with a state-based replication, it would be possible
-to recover the slave replica from a local backup. The slave replica,
-then, will be synchronized by calculating and transmitting the diffs
-between the slave replica and the master replica based on their
-states. The LDAP Sync replication is stateful.
-
-+ It is history-based, not state-based. The replication with
-{{slurpd}}(8) relies on the history information in the replication log
-file generated by {{slapd}}(8). If a portion of the log file that
-contains updates yet to be synchronized to the slave is truncated
-or damaged, a full reload is required. The state-based replication,
-on the other hand, would not rely on the separate history store.
-In the LDAP Sync replication, every directory entry has its state
-information in the entryCSN operational attribute. The replica
-contents are calculated based on the consumer cookie and the entryCSN
-of the directory entries.
-
-+ It is push-based, not pull-based. In the replication with
-{{slurpd}}(8), it is the master who decides when to synchronize the
-replica. The pull-based polling replication is not possible with
-{{slurpd}}(8). For example, in order to make a daily directory backup
-which is an exact image at a time, it is required to make the slave
-replica read-only by stopping {{slurpd}}(8) during backup. After backup,
-{{slurpd}}(8) can be run in an one-shot mode to resynchronize the slave
-replica with the updates during the backup. In a pull-based, polling
-replication, it is guaranteed to be read-only between the two polling
-points. The LDAP Sync replication supports both the push-based
-replication and the pull-based replication.
-
-+ It only supports the fractional replication and does not support
-the sparse replication. The LDAP Sync replication supports both the
-fractional and sparse replication. It is possible to use general
-search specification to initiate a synchronization session only for
-the interesting subset of the context.
-
-H2: LDAP Content Sync Protocol Description
-
-The LDAP Sync replication uses the LDAP Content Sync protocol (refer
-to the Internet Draft entitled "The LDAP Content Synchronization
-Operation") for replica synchronization. The LDAP Content Sync
-protocol operation is based on the replica state which is transmitted
-between replicas as the synchronization cookies. There are two
-operating modes : refreshOnly and refreshAndPersist. In both modes,
-a consumer {{slapd}}(8) connects to a provider {{slapd}}(8) with a cookie
-value representing the state of the consumer replica. The non-persistent
-part of the synchronization consists of two phases.
-
-The first is the state-base phase. The entries updated after the
-point in time the consumer cookie represents will be transmitted
-to the consumer. Because the unit of synchronization is entry, all
-the requested attributes will be transmitted even though only some
-of them are changed. For the rest of the entries, the present
-messages consisting only of the name and the synchronization control
-will be sent to the consumer. After the consumer receives all the
-updated and present entries, it can reliably make its replica
-consistent to the provider replica. The consumer will add all the
-newly added entries, replace the entries if updated entries are
-existent, and delete entries in the local replica if they are neither
-updated nor specified as present.
-
-The second is the log-base phase. This phase is incorporated to
-optimize the protocol with respect to the volume of the present
-traffic. If the provider maintains a history store from which the
-content to be synchronized can be reliably calculated, this log-base
-phase follows the state-base phase. In this mode, the actual directory
-update operations such as delete, modify, and add are transmitted.
-There is no need to send present messages in this log-base phase.
-
-If the protocol operates in the refreshOnly mode, the synchronization
-will terminate. The provider will send a synchronization cookie
-which reflects the new state to the consumer. The consumer will
-present the new cookie at the next time it requests a synchronization.
-If the protocol operates in the refreshAndPersist mode, the
-synchronization operation remains persistent in the provider. Every
-updates made to the provider replica will be transmitted to the
-consumer. Cookies can be sent to the consumer at any time by using
-the SyncInfo intermediate response and at the end of the synchronization
-by using the SyncDone control attached to the SearchResultDone
+The LDAP Sync replication engine, syncrepl for short, is a consumer-side
+replication engine that enables the consumer LDAP server to maintain
+a shadow copy of a DIT fragment. A syncrepl engine resides at the
+consumer-side as one of the {{slapd}} (8) threads. It creates and
+maintains a consumer replica by connecting to the replication
+provider to perform the initial DIT content load followed either
+by periodic content polling or by timely updates upon content
+changes.
+
+Syncrepl uses the LDAP Content Synchronization (or LDAP Sync for
+short) protocol as the replica synchronization protocol. It provides
+a stateful replication which supports both pull-based and push-based
+synchronization and does not mandate the use of a history store.
+
+Syncrepl keeps track of the status of the replication content by
+maintaining and exchanging synchronization cookies. Because the
+syncrepl consumer and provider maintain their content status, the
+consumer can poll the provider content to perform incremental
+synchronization by asking for the entries required to make the
+consumer replica up-to-date with the provider content. Syncrepl
+also enables convenient management of replicas by maintaining replica
+status. The consumer replica can be constructed from a consumer-side
+or a provider-side backup at any synchronization status. Syncrepl
+can automatically resynchronize the consumer replica up-to-date
+with the current provider content.
+
+Syncrepl supports both pull-based and push-based synchronization.
+In its basic refreshOnly synchronization mode, the provider uses
+pull-based synchronization where the consumer servers need not be
+tracked and no history information is maintained. The information
+required for the provider to process periodic polling requests is
+contained in the synchronization cookie of the request itself. To
+optimize the pull-based synchronization, syncrepl utilizes the
+present phase of the LDAP Sync protocol as well as its delete phase,
+instead of falling back on frequent full reloads. To further optimize
+the pull-based synchronization, the provider can maintain a per-scope
+session log as a history store. In its refreshAndPersist mode of
+synchronization, the provider uses a push-based synchronization.
+The provider keeps track of the consumer servers that have requested
+a persistent search and sends them necessary updates as the provider
+replication content gets modified.
+
+With syncrepl, a consumer server can create a replica without
+changing the provider's configurations and without restarting the
+provider server, if the consumer server has appropriate access
+privileges for the DIT fragment to be replicated. The consumer
+server can stop the replication also without the need for provider-side
+changes and restart.
+
+Syncrepl supports both partial and sparse replications. The shadow
+DIT fragment is defined by a general search criteria consisting of
+base, scope, filter, and attribute list. The replica content is
+also subject to the access privileges of the bind identity of the
+syncrepl replication connection.
+
+
+H2: The LDAP Content Synchronization Protocol
+
+The LDAP Sync protocol allows a client to maintain a synchronized
+copy of a DIT fragment. The LDAP Sync operation is defined as a set
+of controls and other protocol elements which extend the LDAP search
+operation. This section introduces the LDAP Content Sync protocol
+only briefly. For more information, refer to the Internet Draft
+{{The LDAP Content Synchronization Operation
+<draft-zeilenga-ldup-sync-05.txt>}}.
+
+The LDAP Sync protocol supports both polling and listening for
+changes by defining two respective synchronization operations:
+{{refreshOnly}} and {{refreshAndPersist}}. Polling is implemented
+by the {{refreshOnly}} operation. The client copy is synchronized
+to the server copy at the time of polling. The server finishes the
+search operation by returning {{SearchResultDone}} at the end of
+the search operation as in the normal search. The listening is
+implemented by the {{refreshAndPersist}} operation. Instead of
+finishing the search after returning all entries currently matching
+the search criteria, the synchronization search remains persistent
+in the server. Subsequent updates to the synchronization content
+in the server cause additional entry updates to be sent to the
+client.
+
+The {{refreshOnly}} operation and the refresh stage of the
+{{refreshAndPersist}} operation can be performed with a present
+phase or a delete phase.
+
+In the present phase, the server sends the client the entries updated
+within the search scope since the last synchronization. The server
+sends all requested attributes, be it changed or not, of the updated
+entries. For each unchanged entry which remains in the scope, the
+server sends a present message consisting only of the name of the
+entry and the synchronization control representing state present.
+The present message does not contain any attributes of the entry.
+After the client receives all update and present entries, it can
+reliably determine the new client copy by adding the entries added
+to the server, by replacing the entries modified at the server, and
+by deleting entries in the client copy which have not been updated
+nor specified as being present at the server.
+
+The transmission of the updated entries in the delete phase is the
+same as in the present phase. The server sends all the requested
+attributes of the entries updated within the search scope since the
+last synchronization to the client. In the delete phase, however,
+the server sends a delete message for each entry deleted from the
+search scope, instead of sending present messages. The delete
+message consists only of the name of the entry and the synchronization
+control representing state delete. The new client copy can be
+determined by adding, modifying, and removing entries according to
+the synchronization control attached to the {{SearchResultEntry}}
message.
-Entries are uniquely identified by the entryUUID attribute value
-in the LDAP Content Sync protocol. It can role as a reliable entry
-identifier while DN of an entry can change by modrdn operations.
-The entryUUID is attached to each SearchResultEntry or
-SearchResultReference as a part of the Sync State control.
-
-H2: LDAP Sync Replication Details
-
-The LDAP Sync replication uses both the refreshOnly and the
-refreshAndPersist modes of synchronization. If an LDAP Sync replication
-is specified in a database definition, the {{slapd}}(8) schedules an
-execution of the LDAP Sync replication engine. In the refreshOnly
-mode, the engine will be rescheduled at the interval time after a
-replication session ends. In the refreshAndPersist mode, the engine
-will remain active to process the SearchResultEntry messages from
-the provider.
-
-The LDAP Sync replication uses only the state-base synchronization
-phase. Because {{slapd}}(8) does not currently implement history store
-like changelog or tombstone, it depends only on the state-base
-phase. A Null log-base phase follows the state-base phase.
-
-As an optimization, no entries will be transmitted to a consumer
-if there has been no update in the master replica after the last
-synchronization with the consumer. Even present messages for the
-unchanged entries are not transmitted. The consumer retains its
-replica contents.
-
-H3: entryCSN
-
-The LDAP Sync replication implemented in OpenLDAP stores state
-information to ever entry in the entryCSN attribute. entryCSN of
-an entry is the CSN (change sequence number), which is the refined
-timestamp, at which the entry was updated most lately. The CSN
-consists of three parts : the time, a replica ID, and a change count
-within a single second.
-
-H3: contextCSN
-
-contextCSN represents the current state of the provider replica.
-It is the largest entryCSN of all entries in the context such that
-no transaction having smaller entryCSN value remains outstanding.
-Because the entryCSN value is obtained before transaction start and
-transactions are not committed in the entryCSN order, special care
-needed to be taken to manage the proper contextCSN value in the
-transactional environment. Also, the state of the search result set
-is required to correspond to the contextCSN value returned to the
-consumer as a sync cookie.
-
-contextCSN, the provider replica state, is stored in the
-syncProviderSubentry. The value of the contextCSN is transmitted
-to the consumer replica as a Sync Cookie. The cookie is stored in
-the syncreplCookie attribute of syncConsumerSubentry subentry. The
-consumer will use the stored cookie value to represent its replica
-state when it connects to the provider in the future.
-
-H3: Glue Entry
-
-Because general search filter can be used in the LDAP Sync replication,
-an entry might be created without a parent, if the parent entry was
-filtered out. The LDAP Sync replication engine creates the glue
-entries for such holes in the replica. The glue entries will not
-be returned in response to a search to the consumer {{slapd}}(8) if
-manageDSAit is not set. It will be returned if it is set.
-
-H2: Configuring slapd for LDAP Sync Replication
-
-It is relatively simple to start servicing with a replicated OpenLDAP
-environment with the LDAP Sync replication, compared to the replication
-with {{slurpd}}(8). First, we should configure both the provider and
-the consumer {{slapd}}(8) servers appropriately. Then, start the provider
-slapd instance first, and the consumer slapd instance next.
-Administrative tasks such as database copy and temporal shutdown
-(or read-only demotion) of the provider are not required.
+In the case that the LDAP Sync server maintains a history store and
+can determine which entries are scoped out of the client copy since
+the last synchronization time, the server can use the delete phase.
+If the server does not maintain any history store, cannot determine
+the scoped-out entries from the history store, or the history store
+does not cover the outdated synchronization state of the client,
+the server should use the present phase. The use of the present
+phase is much more efficient than a full content reload in terms
+of the synchronization traffic. To reduce the synchronization
+traffic further, the LDAP Sync protocol also provides several
+optimizations such as the transmission of the normalized {{EX:entryUUID}}s
+and the transmission of multiple {{EX:entryUUIDs}} in a single
+{{syncIdSet}} message.
+
+At the end of the {{refreshOnly}} synchronization, the server sends
+a synchronization cookie to the client as a state indicator of the
+client copy after the synchronization is completed. The client
+will present the received cookie when it requests the next incremental
+synchronization to the server.
+
+When {{refreshAndPersist}} synchronization is used, the server sends
+a synchronization cookie at the end of the refresh stage by sending
+a Sync Info message with TRUE refreshDone. It also sends a
+synchronization cookie by attaching it to {{SearchResultEntry}}
+generated in the persist stage of the synchronization search. During
+the persist stage, the server can also send a Sync Info message
+containing the synchronization cookie at any time the server wants
+to update the client-side state indicator. The server also updates
+a synchronization indicator of the client at the end of the persist
+stage.
+
+In the LDAP Sync protocol, entries are uniquely identified by the
+{{EX:entryUUID}} attribute value. It can function as a reliable
+identifier of the entry. The DN of the entry, on the other hand,
+can be changed over time and hence cannot be considered as the
+reliable identifier. The {{EX:entryUUID}} is attached to each
+{{SearchResultEntry}} or {{SearchResultReference}} as a part of the
+synchronization control.
+
+
+H2: Syncrepl Details
+
+The syncrepl engine utilizes both the {{refreshOnly}} and the
+{{refreshAndPersist}} operations of the LDAP Sync protocol. If a
+syncrepl specification is included in a database definition, {{slapd}}
+(8) launches a syncrepl engine as a {{slapd}} (8) thread and schedules
+its execution. If the {{refreshOnly}} operation is specified, the
+syncrepl engine will be rescheduled at the interval time after a
+synchronization operation is completed. If the {{refreshAndPersist}}
+operation is specified, the engine will remain active and process
+the persistent synchronization messages from the provider.
+
+The syncrepl engine utilizes both the present phase and the delete
+phase of the refresh synchronization. It is possible to configure
+a per-scope session log in the provider server which stores the
+{{EX:entryUUID}}s of a finite number of entries deleted from a
+replication content. Multiple replicas of single provider content
+share the same per-scope session log. The syncrepl engine uses the
+delete phase if the session log is present and the state of the
+consumer server is recent enough that no session log entries are
+truncated after the last synchronization of the client. The syncrepl
+engine uses the present phase if no session log is configured for
+the replication content or if the consumer replica is too outdated
+to be covered by the session log. The current design of the session
+log store is memory based, so the information contained in the
+session log is not persistent over multiple provider invocations.
+It is not currently supported to access the session log store by
+using LDAP operations. It is also not currently supported to impose
+access control to the session log.
+
+As a further optimization, even in the case the synchronization
+search is not associated with any session log, no entries will be
+transmitted to the consumer server when there has been no update
+in the replication context.
+
+The syncrepl engine, which is a consumer-side replication engine,
+can work with any backends. The LDAP Sync provider can be configured
+as an overlay on any backend, but works best with the {{back-bdb}}
+or {{back-hdb}} backend. The provider can not support refreshAndPersist
+mode on {{back-ldbm}} due to limits in that backend's locking
+architecture.
+
+The LDAP Sync provider maintains a {{EX:contextCSN}} for each
+database as the current synchronization state indicator of the
+provider content. It is the largest {{EX:entryCSN}} in the provider
+context such that no transactions for an entry having smaller
+{{EX:entryCSN}} value remains outstanding. The {{EX:contextCSN}}
+could not just be set to the largest issued {{EX:entryCSN}} because
+{{EX:entryCSN}} is obtained before a transaction starts and
+transactions are not committed in the issue order.
+
+The provider stores the {{EX:contextCSN}} of a context in the
+{{EX:contextCSN}} attribute of the context suffix entry. The attribute
+is not written to the database after every update operation though;
+instead it is maintained primarily in memory. At database start
+time the provider reads the last saved {{EX:contextCSN}} into memory
+and uses the in-memory copy exclusively thereafter. By default,
+changes to the {{EX:contextCSN}} as a result of database updates
+will not be written to the database until the server is cleanly
+shut down. A checkpoint facility exists to cause the contextCSN to
+be written out more frequently if desired.
+
+Note that at startup time, if the provider is unable to read a
+{{EX:contextCSN}} from the suffix entry, it will scan the entire
+database to determine the value, and this scan may take quite a
+long time on a large database. When a {{EX:contextCSN}} value is
+read, the database will still be scanned for any {{EX:entryCSN}}
+values greater than it, to make sure the {{EX:contextCSN}} value
+truly reflects the greatest committed {{EX:entryCSN}} in the database.
+On databases which support inequality indexing, setting an eq index
+on the {{EX:entryCSN}} attribute and configuring {{contextCSN}}
+checkpoints will greatly speed up this scanning step.
+
+If no {{EX:contextCSN}} can be determined by reading and scanning
+the database, a new value will be generated. Also, if scanning the
+database yielded a greater {{EX:entryCSN}} than was previously
+recorded in the suffix entry's {{EX:contextCSN}} attribute, a
+checkpoint will be immediately written with the new value.
+
+The consumer also stores its replica state, which is the provider's
+{{EX:contextCSN}} received as a synchronization cookie, in the
+{{EX:contextCSN}} attribute of the suffix entry. The replica state
+maintained by a consumer server is used as the synchronization state
+indicator when it performs subsequent incremental synchronization
+with the provider server. It is also used as a provider-side
+synchronization state indicator when it functions as a secondary
+provider server in a cascading replication configuration. Since
+the consumer and provider state information are maintained in the
+same location within their respective databases, any consumer can
+be promoted to a provider (and vice versa) without any special
+actions.
+
+Because a general search filter can be used in the syncrepl
+specification, some entries in the context may be omitted from the
+synchronization content. The syncrepl engine creates a glue entry
+to fill in the holes in the replica context if any part of the
+replica content is subordinate to the holes. The glue entries will
+not be returned in the search result unless {{ManageDsaIT}} control
+is provided.
+
+Also as a consequence of the search filter used in the syncrepl
+specification, it is possible for a modification to remove an entry
+from the replication scope even though the entry has not been deleted
+on the provider. Logically the entry must be deleted on the consumer
+but in {{refreshOnly}} mode the provider cannot detect and propagate
+this change without the use of the session log.
+
+
+H2: Configuring Syncrepl
+
+Because syncrepl is a consumer-side replication engine, the syncrepl
+specification is defined in {{slapd.conf}} (5) of the consumer
+server, not in the provider server's configuration file. The initial
+loading of the replica content can be performed either by starting
+the syncrepl engine with no synchronization cookie or by populating
+the consumer replica by adding an {{TERM:LDIF}} file dumped as a
+backup at the provider.
+
+When loading from a backup, it is not required to perform the initial
+loading from the up-to-date backup of the provider content. The
+syncrepl engine will automatically synchronize the initial consumer
+replica to the current provider content. As a result, it is not
+required to stop the provider server in order to avoid the replica
+inconsistency caused by the updates to the provider content during
+the content backup and loading process.
+
+When replicating a large scale directory, especially in a bandwidth
+constrained environment, it is advised to load the consumer replica
+from a backup instead of performing a full initial load using
+syncrepl.
+
H3: Set up the provider slapd
-There is no special slapd.conf(5) directive for the provider {{slapd}}(8).
-Because the LDAP Sync searches are subject to access control, proper
-access control privileges should be set up for the replicated
+The provider is implemented as an overlay, so the overlay itself
+must first be configured in {{slapd.conf}} (5) before it can be
+used. The provider has only two configuration directives, for setting
+checkpoints on the {{EX:contextCSN}} and for configuring the session
+log. Because the LDAP Sync search is subject to access control,
+proper access control privileges should be set up for the replicated
content.
-When creating a provider database from an ldif file using slapadd(8),
-you must create and update a state indicator of the database context
-up to date. slapadd(8) will store the contextCSN in the
-syncProviderSubentry if it is given the -w flag. It is also possible
-to create the syncProviderSubentry with an appropriate contextCSN
-value by directly including it in the ldif file. If slapadd(8) runs
-without the -w flag, the provided contextCSN will be stored. With
-the -w flag, a new value based on the current time will be stored
-as contextCSN. slapcat(8) can be used to retrieve the directory
-with the contextCSN when it is run with the -m flag.
-
-Only the back-bdb and the back-hdb backends can perform as the LDAP
-Sync replication provider. Back-ldbm currently does not have the
-LDAP Content Sync protocol functionality.
+The {{EX:contextCSN}} checkpoint is configured by the
-H3: Set up the consumer slapd
+> syncprov-checkpoint <ops> <minutes>
+
+directive. Checkpoints are only tested after successful write
+operations. If {{<ops>}} operations or more than {{<minutes>}}
+time has passed since the last checkpoint, a new checkpoint is
+performed.
+
+The session log is configured by the
+
+> syncprov-sessionlog <size>
+
+directive, where {{<size>}} is the maximum number of session log
+entries the session log can record. When a session log is configured,
+it is automatically used for all LDAP Sync searches within the
+database.
-The consumer slapd is configured by slapd.conf(5) configuration
-file. For the configuration directives, see syncrepl section of the
-slapd Configuration File chapter. In the configuration file, make
-sure the DN given in the updatedn= directive of the syncrepl
-specification has permission to write to the database. Below is an
-example syncrepl specification at the consumer replica :
+Note that using the session log requires searching on the {{entryUUID}}
+attribute. Setting an eq index on this attribute will greatly benefit
+the performance of the session log on the provider.
-> syncrepl id = 1
+A more complete example of the {{slapd.conf}} content is thus:
+
+> database bdb
+> suffix dc=Example,dc=com
+> rootdn dc=Example,dc=com
+> directory /var/ldap/db
+> index objectclass,entryCSN,entryUUID eq
+>
+> overlay syncprov
+> syncprov-checkpoint 100 10
+> syncprov-sessionlog 100
+
+
+H3: Set up the consumer slapd
+
+The syncrepl replication is specified in the database section of
+{{slapd.conf}} (5) for the replica context. The syncrepl engine
+is backend independent and the directive can be defined with any
+database type.
+
+> database hdb
+> suffix dc=Example,dc=com
+> rootdn dc=Example,dc=com
+> directory /var/ldap/db
+> index objectclass,entryCSN,entryUUID eq
+>
+> syncrepl rid=123
> provider=ldap://provider.example.com:389
-> updatedn="cn=replica,dc=example,dc=com"
-> binddn="cn=syncuser,dc=example,dc=com"
-> bindmethod=simple
-> credentials=secret
+> type=refreshOnly
+> interval=01:00:00:00
> searchbase="dc=example,dc=com"
> filter="(objectClass=organizationalPerson)"
-> attrs="cn,sn,ou,telephoneNumber,title,l"
-> schemachecking=on
> scope=sub
-> type=refreshOnly
-> interval=01:00:00
+> attrs="cn,sn,ou,telephoneNumber,title,l"
+> schemachecking=off
+> bindmethod=simple
+> binddn="cn=syncuser,dc=example,dc=com"
+> credentials=secret
In this example, the consumer will connect to the provider slapd
-at port 389 of ldap://provider.example.com to perform a polling
-(refreshOnly) mode of synchronization once a day. It will bind as
-"cn=syncuser,dc=example,dc=com" using simple authentication with
-password "secret". Note that the access control privilege of the DN
-specified by the binddn= directive should be set properly to
-synchronize the desired replica content. The consumer will write to
-its database with the privilege of the "cn=replica,dc=example,dc=com"
-entry as specified by the updatedn= directive. The updatedn entry
-should have write permission to the database.
-
-The synchronization search in the example will search for entries
-whose objectClass is organizationalPerson in the entire subtree
-under "dc=example,dc=com" search base inclusively. The requested
-attributes are cn, sn, ou, telephoneNumber, title, and l. The schema
-checking is turned on, so that the consumer {{slapd}}(8) will enforce
-entry schema checking when it process updates from the provider
-{{slapd}}(8).
-
-The LDAP Sync replication engine is backend independent. All three
-native backends can perform as the LDAP Sync replication consumer.
-
+at port 389 of {{FILE:ldap://provider.example.com}} to perform a
+polling ({{refreshOnly}}) mode of synchronization once a day. It
+will bind as {{EX:cn=syncuser,dc=example,dc=com}} using simple
+authentication with password "secret". Note that the access control
+privilege of {{EX:cn=syncuser,dc=example,dc=com}} should be set
+appropriately in the provider to retrieve the desired replication
+content. Also the search limits must be high enough on the provider
+to allow the syncuser to retrieve a complete copy of the requested
+content. The consumer uses the rootdn to write to its database so
+it always has full permissions to write all content.
+
+The synchronization search in the above example will search for the
+entries whose objectClass is organizationalPerson in the entire
+subtree rooted at {{EX:dc=example,dc=com}}. The requested attributes
+are {{EX:cn}}, {{EX:sn}}, {{EX:ou}}, {{EX:telephoneNumber}},
+{{EX:title}}, and {{EX:l}}. The schema checking is turned off, so
+that the consumer {{slapd}} (8) will not enforce entry schema
+checking when it process updates from the provider {{slapd}} (8).
+
+For more detailed information on the syncrepl directive, see the
+{{SECT:syncrepl}} section of {{SECT:The slapd Configuration File}}
+chapter of this admin guide.
+
+
H3: Start the provider and the consumer slapd
-If the currently running provider {{slapd}}(8) already has the
-syncProviderSubentry in its database, it is not required to restart
-the provider slapd. You don't need to restart the provider {{slapd}}(8)
-when you start a replicated LDAP service. When you run a consumer
-{{slapd}}(8), it will immediately perform either the initial full reload
-if cookie is NULL or too out of date, or incremental synchronization
-if effective cookie is provided. In the refreshOnly mode, the next
-synchronization session is scheduled to run interval time after the
-completion of the current session. In the refreshAndPersist mode,
-the synchronization session is open between the consumer and provider.
-The provider will send update message whenever there are updates
-in the provider replica.
+The provider {{slapd}} (8) is not required to be restarted.
+{{contextCSN}} is automatically generated as needed: it might be
+originally contained in the {{TERM:LDIF}} file, generated by
+{{slapadd}} (8), generated upon changes in the context, or generated
+when the first LDAP Sync search arrives at the provider. If an
+LDIF file is being loaded which did not previously contain the
+{{contextCSN}}, the {{-w}} option should be used with {{slapadd}}
+(8) to cause it to be generated. This will allow the server to
+startup a little quicker the first time it runs.
+
+When starting a consumer {{slapd}} (8), it is possible to provide
+a synchronization cookie as the {{-c cookie}} command line option
+in order to start the synchronization from a specific state. The
+cookie is a comma separated list of name=value pairs. Currently
+supported syncrepl cookie fields are {{csn=<csn>}} and {{rid=<rid>}}.
+{{<csn>}} represents the current synchronization state of the
+consumer replica. {{<rid>}} identifies a consumer replica locally
+within the consumer server. It is used to relate the cookie to the
+syncrepl definition in {{slapd.conf}} (5) which has the matching
+replica identifier. The {{<rid>}} must have no more than 3 decimal
+digits. The command line cookie overrides the synchronization
+cookie stored in the consumer replica database.
projects / openldap / blobdiff