From: Jong Hyuk Choi Date: Sun, 21 Dec 2003 19:54:29 +0000 (+0000) Subject: rewrite of the syncrepl section X-Git-Tag: OPENLDAP_REL_ENG_2_1_MP~117 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=8fa4ca58932c70283b6120e9577c0d4924839525;p=openldap rewrite of the syncrepl section --- diff --git a/doc/guide/admin/syncrepl.sdf b/doc/guide/admin/syncrepl.sdf index 9f34f9bfe6..5314befa09 100644 --- a/doc/guide/admin/syncrepl.sdf +++ b/doc/guide/admin/syncrepl.sdf @@ -4,261 +4,357 @@ 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 {{EX:entryCSN}} operational attribute. The replica -contents are calculated based on the consumer cookie and the -{{EX: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 {{push-based}} -and {{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: The LDAP Content Sychronization Operation - -The LDAP Sync replication uses the LDAP Content Synchronization (or -LDAP Sync) protocol (refer to the Internet Draft titled {{The LDAP -Content Synchronization Operation}}) for replica synchronization. - -The LDAP Sync 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-based}} 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-based}} 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-based 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 -message. - -Entries are uniquely identified by the {{EX: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 {{EX: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-based 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 {{slapd}}(8) stores state -information to ever entry in the {{EX:entryCSN}} attribute. -{{EX:entryCSN}} of an entry is the CSN or {{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 - -{{EX:contextCSN}} represents the current state of the provider -replica. It is the largest {{EX:entryCSN}} of all entries in the -context such that no transaction having smaller {{EX:entryCSN}} -value remains outstanding. Because the {{EX:entryCSN}} value is -obtained before transaction start and transactions are not committed -in the {{EX:entryCSN}} order, special care needed to be taken to -manage the proper {EX:contextCSN}} value in the transactional -environment. Also, the state of the search result set is required -to correspond to the {{EX:contextCSN}} value returned to the consumer -as a sync cookie. - -{{EX:contextCSN}}, the provider replica state, is stored in the -{{EX:syncProviderSubentry}}. The value of the {{EX:contextCSN}} is -transmitted to the consumer replica as a Sync Cookie. The cookie -is stored in the {{EX:syncreplCookie}} attribute of -{{EX: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 providing a replicated directory -service with 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. +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. + +Syncrepl provides a stateful replication which supports both the +pull-based and the push-based synchronizations and does not mandate +the use of the 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 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 the pull-based and the +push-based synchronization. In its basic refreshOnly mode synchronization, +the provider uses a 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 the 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 the 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 +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 +}}. + +The LDAP Sync protocol supports both polling and listening for +changes by defining two respective synchronization operations: +{{refreshOnly}} and {{refreshAndPersist}}. +The 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 have additional entry updates be sent to the client. + +The {{refreshOnly}} operation and the refresh stage of the +{{refreshAndPersist}} operation can be performed by +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. + +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 the 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 and the names 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. + +While {{slapd}} (8) can function as the LDAP Sync provider only +when it is configured with either {{back-bdb}} or {{back-hdb}} backend, +the syncrepl engine, which is a consumer-side replication engine, +can work with any backends. + +The LDAP Sync provider maintains {{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. +{{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:syncreplCookie}} attribute of the immediate child entry of +the context suffix whose DN is {{cn=ldapsync,}} and +object class is {{EX:syncProviderSubentry}}. + +The consumer stores its replica state, which is the provider's +{{EX:contextCSN}} received as a synchronization cookie, +in the {{EX:syncreplCookie}} attribute of the immediate child +of the context suffix whose DN is {{cn=syncrepl,}} +and object class is {{EX:syncConsumerSubentry}}. +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. + is the replica ID uniquely identifying the replica locally in the +syncrepl consumer server. is an integer which has no more than +three decimal digits. + +Because a general search filter can be used in the syncrepl specification, +not all entries in the context will be returned as 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 +as the search result unless {{ManageDsaIT}} control is provided. + +It is possible to retrieve {{EX:syncProviderSubentry}} and +{{EX:syncConsumerSubentry}} by performing an LDAP search with +the respective entries as the base object and with the base scope. + + +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 and demoting an +{{TERM:LDIF}} file dumped as a backup at the provider. +{{slapadd}} (8) supports the replica promotion and demotion. + +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 content. - -When creating a provider database from an {{TERM: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 -{{EX:contextCSN}} in the {{EX:syncProviderSubentry}} if it is given -the {{EX:-w}} flag. It is also possible to create the -{{EX:syncProviderSubentry}} with an appropriate {{EX:contextCSN}} -value by directly including it in the ldif file. If {{slapadd}}(8) -runs without the {{EX:-w}} flag, the provided {{EX:contextCSN}} -will be stored. With the {{EX:-w}} flag, a new value based on the -current time will be stored as {{EX:contextCSN}}. {{slapcat}}(8) -can be used to retrieve the directory with the {{EX:contextCSN}} -when it is run with the {{EX:-m}} flag. - -Only the BDB (back-bdb) and HDB (back-hdb) backends can perform as -the LDAP Sync replication provider. LDBM (back-ldbm) currently -does not have the LDAP Sync protocol functionality. +There is no special {{slapd.conf}} (5) directive for the provider +syncrepl server except for the session log directive. 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 the {{TERM:LDIF}} file using +{{slapadd}} (8), {{EX:contextCSN}} and the {{EX:syncProviderSubentry}} +entry must be created. {{slapadd -p -w}} will create +a new {{EX:contextCSN}} from the {{EX:entryCSN}}s of the added entries. +It is also possible to create the {{EX:syncProviderSubentry}} with +an appropriate {{EX:contextCSN}} value by directly including it +in the ldif file. {{slapadd -p}} will preserve the provider's +contextCSN or will change it to the consumer's contextCSN +if it is to promote a replica to the provider's content. +The {{EX:syncProviderSubentry}} can be included in the ldif output +when {{slapcat}} (8) is given the {{-m}} flag; +the {{EX:syncConsumerSubentry}} can be retrieved by the {{-k}} +flag of {{slapcat}} (8). + +The session log is configured by + +> sessionlog + +directive, where {{}} is the ID of the per-scope session log +in the provider server and {{}} is the maximum number of +session log entries the session log store can record. {{}} +is an integer no longer than 3 decimal digits. If the consumer +server sends a synchronization cookie containing {{sid=}} +where {{}} matches the session log ID specified in the directive, +the LDAP Sync search is to utilize the session log store. H3: Set up the consumer slapd -The consumer slapd is configured by {{slapd.conf}}(5) configuration -file. For the configuration directives, see the {{SECT:syncrepl}} -section of {{SECT:The slapd Configuration File}} chapter. In the -configuration file, make sure the DN given in the {{EX:updatedn=}} -directive of the {{EX:syncrepl}} specification has permission to -write to the database. Below is an example {{EX:syncrepl}} specification -at the consumer replica: +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. -> syncrepl id = 1 +> 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 +> updatedn="cn=replica,dc=example,dc=com" +> 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 {{FILE:ldap://provider.example.com}} to perform a -polling (refreshOnly) mode of synchronization once a day. It will +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 -the DN specified by the {{EX:binddn=}} directive should be set -properly to synchronize the desired replica content. The consumer -will write to its database with the privilege of the -{EX:cn=replica,dc=example,dc=com}} entry as specified by the -{{EX:updatedn=}} directive. The {{EX: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 {{EX:dc=example,dc=com}} search base inclusively. The requested -attributes are {{EX:cn}}, {{EX:sn}}, {{EX:ou}}, {{EX:telephoneNumber}}, -{{EX:title}}, and {{EX: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. +{{EX:cn=syncuser,dc=example,dc=com}} should be set appropriately +in the provider to retrieve the desired replication content. +The consumer will write to its database with the privilege of the +{EX:cn=replica,dc=example,dc=com}} entry as specified in the +{{EX:updatedn=}} directive. The {{EX:updatedn}} entry should have +write permission to the replica 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 -{{EX: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 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 arrived at the provider. + +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=}}, {{sid=}}, and +{{rid=}}. {{}} represents the current synchronization state +of the consumer replica. {{}} is the identity of the per-scope +session log to which this consumer will be associated. {{}} 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. +Both {{}} and {{}} have no more than 3 decimal digits. +The command line cookie overrides the synchronization cookie +stored in the consumer replica database.