From: Kurt Zeilenga Date: Tue, 2 Dec 2003 21:03:21 +0000 (+0000) Subject: Mostly formating... X-Git-Tag: OPENLDAP_REL_ENG_2_1_MP~295 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=f1411d693f494dada001893f99aee4a9d12b3d9a;p=openldap Mostly formating... --- diff --git a/doc/guide/admin/replication.sdf b/doc/guide/admin/replication.sdf index e61450b67a..ab67b57c18 100644 --- a/doc/guide/admin/replication.sdf +++ b/doc/guide/admin/replication.sdf @@ -266,7 +266,8 @@ DN given by the {{EX:binddn=}} directive must exist in the slave slapd's database (or be the rootdn specified in the slapd config file) in order for the bind operation to succeed. The DN should also be listed as the {{EX:updatedn}} for the database in the slave's -slapd.conf(5). +slapd.conf(5). It is generally recommended that this DN be +different than the {{EX:rootdn}}. Note: The use of strong authentication and transport security is highly recommended. diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index 53cd3477e9..0af5298b8e 100644 --- a/doc/guide/admin/slapdconfig.sdf +++ b/doc/guide/admin/slapdconfig.sdf @@ -307,11 +307,11 @@ given, the standard LDAP port number (389 or 636) is used. URI such as {{EX:ldap://slave.example.com:389}} or {{EX:ldaps://slave.example.com:636}}. -The {{EX:binddn=}} parameter gives the DN to bind as for updates to -the slave slapd. It should be a DN which has read/write -access to the slave slapd's database, typically given as a -{{EX:rootdn}} in the slave's config file. It must also match the -{{EX:updatedn}} directive in the slave slapd's config file. Since DNs are +The {{EX:binddn=}} parameter gives the DN to bind as for updates +to the slave slapd. It should be a DN which has read/write access +to the slave slapd's database. It must also match the {{EX:updatedn}} +directive in the slave slapd's config file. Generally, this DN +{{should not}} be the same as the {{EX:rootdn}}. Since DNs are likely to contain embedded spaces, the entire {{EX:"binddn="}} string should be enclosed in double quotes. @@ -500,13 +500,12 @@ schema conformance. The default is off. The {{EX:updatedn}} parameter specifies the DN in the consumer site which is allowed to make changes to the replica. This DN is used -locally by the syncrepl engine when updating the replica with -the entries received from the provider site by using the -internal operation mechanism. The update of the replica content -is subject to the access control privileges of the DN. -The DN should have read/write access to the replica database. -It is typically given as a {{EX:rootdn}} in the consumer site's -config file. +locally by the syncrepl engine when updating the replica with the +entries received from the provider site by using the internal +operation mechanism. The update of the replica content is subject +to the access control privileges of the DN. The DN should have +read/write access to the replica database. Generally, this DN +{{should not}} be the same as {{EX:rootdn}}. The {{EX:binddn}} parameter gives the DN to bind as for the syncrepl searches to the provider slapd. It should be a DN diff --git a/doc/guide/admin/syncrepl.sdf b/doc/guide/admin/syncrepl.sdf index 81785f1bad..13a9ec297e 100644 --- a/doc/guide/admin/syncrepl.sdf +++ b/doc/guide/admin/syncrepl.sdf @@ -9,30 +9,30 @@ 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. +^ 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 +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. +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 ++ 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 @@ -41,8 +41,8 @@ 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. +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 @@ -50,6 +50,7 @@ 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 @@ -57,13 +58,14 @@ 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 +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 @@ -75,13 +77,13 @@ 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 +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-base phase. +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 @@ -95,12 +97,13 @@ 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 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 +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 @@ -127,10 +130,10 @@ 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. +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 @@ -177,29 +180,31 @@ 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 ldif file using slapadd(8), +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. +syncProviderSubentry if it is given the {{EX:-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 {{EX:-w}} flag, the provided +contextCSN will be stored. With the {{EX:-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 {{EX:-m}} flag. + +Only the BDB (back-bdb) and HDB (back-hdb) backends can perform as +the LDAP Sync replication provider. Back-ldbm currently does not +have the LDAP Content Sync protocol functionality. H3: Set up the consumer slapd -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 : +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 syncrepl specification has permission to write to +the database. Below is an example syncrepl specification at the +consumer replica : > syncrepl id = 1 > provider=ldap://provider.example.com:389 @@ -216,19 +221,20 @@ example syncrepl specification at the consumer replica : > interval=01:00:00 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. +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 +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 +{EX:cn=replica,dc=example,dc=com}} entry as specified by the +{{EX: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 +under {{EX: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