git.sur5r.net Git - openldap/blob - doc/guide/admin/syncrepl.sdf

   1 # $OpenLDAP$
   2 # Copyright 2003, The OpenLDAP Foundation, All Rights Reserved.
   3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   4
   5 H1: LDAP Sync Replication
   6
   7 The LDAP Sync replication engine is designed to function as an
   8 improved alternative to {{slurpd}}(8).  While the replication with
   9 {{slurpd}}(8) provides the replication capability for improved capacity,
  10 availability, and reliability, it has some drawbacks:
  11
  12 ^ It is {{not stateful}}, hence lacks the resynchronization capability.
  13 Because there is no representation of replica state in the replication
  14 with {{slurpd}}(8), it is not possible to provide an efficient
  15 mechanism to make the slave replica consistent to the master replica
  16 once they become out of sync. For instance, if the slave database
  17 content is damaged, the slave replica should be re-primed from the
  18 master replica again. with a state-based replication, it would be
  19 possible to recover the slave replica from a local backup. The slave
  20 replica, then, will be synchronized by calculating and transmitting
  21 the diffs between the slave replica and the master replica based
  22 on their states. The LDAP Sync replication is {{stateful}}.
  23
  24 + It is {{history-based}}, not {{state-based}}. The replication with
  25 {{slurpd}}(8) relies on the history information in the replication
  26 log file generated by {{slapd}}(8). If a portion of the log file
  27 that contains updates yet to be synchronized to the slave is truncated
  28 or damaged, a full reload is required. The state-based replication,
  29 on the other hand, would not rely on the separate history store.
  30 In the LDAP Sync replication, every directory entry has its state
  31 information in the {{EX:entryCSN}} operational attribute. The replica
  32 contents are calculated based on the consumer cookie and the
  33 {{EX:entryCSN}} of the directory entries.
  34
  35 + It is {{push-based}}, not {{pull-based}}. In the replication with
  36 {{slurpd}}(8), it is the master who decides when to synchronize the
  37 replica. The pull-based polling replication is not possible with
  38 {{slurpd}}(8). For example, in order to make a daily directory backup
  39 which is an exact image at a time, it is required to make the slave
  40 replica read-only by stopping {{slurpd}}(8) during backup. After backup,
  41 {{slurpd}}(8) can be run in an one-shot mode to resynchronize the slave
  42 replica with the updates during the backup. In a pull-based, polling
  43 replication, it is guaranteed to be read-only between the two polling
  44 points. The LDAP Sync replication supports both {{push-based}}
  45 and {{pull-based}} replication.
  46
  47 + It only supports the fractional replication and does not support
  48 the sparse replication. The LDAP Sync replication supports both the
  49 fractional and sparse replication. It is possible to use general
  50 search specification to initiate a synchronization session only for
  51 the interesting subset of the context.
  52
  53
  54 H2: LDAP Content Sync Protocol Description
  55
  56 The LDAP Sync replication uses the LDAP Content Sync protocol (refer
  57 to the Internet Draft entitled "The LDAP Content Synchronization
  58 Operation") for replica synchronization. The LDAP Content Sync
  59 protocol operation is based on the replica state which is transmitted
  60 between replicas as the synchronization cookies. There are two
  61 operating modes: {{refreshOnly}} and {{refreshAndPersist}}. In both
  62 modes, a consumer {{slapd}}(8) connects to a provider {{slapd}}(8)
  63 with a cookie value representing the state of the consumer replica.
  64 The non-persistent part of the synchronization consists of two
  65 phases.
  66
  67 The first is the {{state-based}} phase. The entries updated after
  68 the point in time the consumer cookie represents will be transmitted
  69 to the consumer. Because the unit of synchronization is entry, all
  70 the requested attributes will be transmitted even though only some
  71 of them are changed. For the rest of the entries, the present
  72 messages consisting only of the name and the synchronization control
  73 will be sent to the consumer. After the consumer receives all the
  74 updated and present entries, it can reliably make its replica
  75 consistent to the provider replica. The consumer will add all the
  76 newly added entries, replace the entries if updated entries are
  77 existent, and delete entries in the local replica if they are neither
  78 updated nor specified as present.
  79
  80 The second is the {{log-based}} phase. This phase is incorporated
  81 to optimize the protocol with respect to the volume of the present
  82 traffic. If the provider maintains a history store from which the
  83 content to be synchronized can be reliably calculated, this log-base
  84 phase follows the state-base phase. In this mode, the actual directory
  85 update operations such as delete, modify, and add are transmitted.
  86 There is no need to send present messages in this log-based phase.
  87
  88 If the protocol operates in the refreshOnly mode, the synchronization
  89 will terminate. The provider will send a synchronization cookie
  90 which reflects the new state to the consumer. The consumer will
  91 present the new cookie at the next time it requests a synchronization.
  92 If the protocol operates in the refreshAndPersist mode, the
  93 synchronization operation remains persistent in the provider. Every
  94 updates made to the provider replica will be transmitted to the
  95 consumer. Cookies can be sent to the consumer at any time by using
  96 the SyncInfo intermediate response and at the end of the synchronization
  97 by using the SyncDone control attached to the SearchResultDone
  98 message.
  99
 100 Entries are uniquely identified by the {{EX:entryUUID}} attribute
 101 value in the LDAP Content Sync protocol. It can role as a reliable
 102 entry identifier while DN of an entry can change by modrdn operations.
 103 The {{EX:entryUUID}} is attached to each SearchResultEntry or
 104 SearchResultReference as a part of the Sync State control.
 105
 106
 107 H2: LDAP Sync Replication Details
 108
 109 The LDAP Sync replication uses both the refreshOnly and the
 110 refreshAndPersist modes of synchronization. If an LDAP Sync replication
 111 is specified in a database definition, the {{slapd}}(8) schedules an
 112 execution of the LDAP Sync replication engine. In the refreshOnly
 113 mode, the engine will be rescheduled at the interval time after a
 114 replication session ends. In the refreshAndPersist mode, the engine
 115 will remain active to process the SearchResultEntry messages from
 116 the provider.
 117
 118 The LDAP Sync replication uses only the state-base synchronization
 119 phase.  Because {{slapd}}(8) does not currently implement history store
 120 like changelog or tombstone, it depends only on the state-base
 121 phase. A Null log-base phase follows the state-base phase.
 122
 123 As an optimization, no entries will be transmitted to a consumer
 124 if there has been no update in the master replica after the last
 125 synchronization with the consumer. Even present messages for the
 126 unchanged entries are not transmitted. The consumer retains its
 127 replica contents.
 128
 129 H3: entryCSN
 130
 131 The LDAP Sync replication implemented in OpenLDAP stores state
 132 information to ever entry in the entryCSN attribute. entryCSN of
 133 an entry is the CSN or {{change sequence number}}, which is the
 134 refined timestamp, at which the entry was updated most lately. The
 135 CSN consists of three parts: the time, a replica ID, and a change
 136 count within a single second.
 137
 138 H3: contextCSN
 139
 140 contextCSN represents the current state of the provider replica.
 141 It is the largest entryCSN of all entries in the context such that
 142 no transaction having smaller entryCSN value remains outstanding.
 143 Because the entryCSN value is obtained before transaction start and
 144 transactions are not committed in the entryCSN order, special care
 145 needed to be taken to manage the proper contextCSN value in the
 146 transactional environment. Also, the state of the search result set
 147 is required to correspond to the contextCSN value returned to the
 148 consumer as a sync cookie.
 149
 150 contextCSN, the provider replica state, is stored in the
 151 syncProviderSubentry. The value of the contextCSN is transmitted
 152 to the consumer replica as a Sync Cookie. The cookie is stored in
 153 the syncreplCookie attribute of syncConsumerSubentry subentry. The
 154 consumer will use the stored cookie value to represent its replica
 155 state when it connects to the provider in the future.
 156
 157 H3: Glue Entry
 158
 159 Because general search filter can be used in the LDAP Sync replication,
 160 an entry might be created without a parent, if the parent entry was
 161 filtered out. The LDAP Sync replication engine creates the glue
 162 entries for such holes in the replica. The glue entries will not
 163 be returned in response to a search to the consumer {{slapd}}(8) if
 164 manageDSAit is not set. It will be returned if it is set.
 165
 166 H2: Configuring slapd for LDAP Sync Replication
 167
 168 It is relatively simple to start servicing with a replicated OpenLDAP
 169 environment with the LDAP Sync replication, compared to the replication
 170 with {{slurpd}}(8). First, we should configure both the provider and
 171 the consumer {{slapd}}(8) servers appropriately. Then, start the provider
 172 slapd instance first, and the consumer slapd instance next.
 173 Administrative tasks such as database copy and temporal shutdown
 174 (or read-only demotion) of the provider are not required.
 175
 176 H3: Set up the provider slapd
 177
 178 There is no special slapd.conf(5) directive for the provider {{slapd}}(8).
 179 Because the LDAP Sync searches are subject to access control, proper
 180 access control privileges should be set up for the replicated
 181 content.
 182
 183 When creating a provider database from an ldif file using {{slapadd}}(8),
 184 you must create and update a state indicator of the database context
 185 up to date. slapadd(8) will store the contextCSN in the
 186 syncProviderSubentry if it is given the {{EX:-w}} flag. It is also
 187 possible to create the syncProviderSubentry with an appropriate
 188 contextCSN value by directly including it in the ldif file. If
 189 {{slapadd}}(8) runs without the {{EX:-w}} flag, the provided
 190 contextCSN will be stored. With the {{EX:-w}} flag, a new value
 191 based on the current time will be stored as contextCSN. {{slapcat}}(8)
 192 can be used to retrieve the directory with the contextCSN when it
 193 is run with the {{EX:-m}} flag.
 194
 195 Only the BDB (back-bdb) and HDB (back-hdb) backends can perform as
 196 the LDAP Sync replication provider. Back-ldbm currently does not
 197 have the LDAP Content Sync protocol functionality.
 198
 199 H3: Set up the consumer slapd
 200
 201 The consumer slapd is configured by {{slapd.conf}}(5) configuration
 202 file. For the configuration directives, see the {{SECT:syncrepl}}
 203 section of {{SECT:The slapd Configuration File}} chapter. In the
 204 configuration file, make sure the DN given in the {{EX:updatedn=}}
 205 directive of the syncrepl specification has permission to write to
 206 the database. Below is an example syncrepl specification at the
 207 consumer replica :
 208
 209 >       syncrepl id = 1
 210 >               provider=ldap://provider.example.com:389
 211 >               updatedn="cn=replica,dc=example,dc=com"
 212 >               binddn="cn=syncuser,dc=example,dc=com"
 213 >               bindmethod=simple
 214 >               credentials=secret
 215 >               searchbase="dc=example,dc=com"
 216 >               filter="(objectClass=organizationalPerson)"
 217 >               attrs="cn,sn,ou,telephoneNumber,title,l"
 218 >               schemachecking=on
 219 >               scope=sub
 220 >               type=refreshOnly
 221 >               interval=01:00:00
 222
 223 In this example, the consumer will connect to the provider slapd
 224 at port 389 of {{FILE:ldap://provider.example.com}} to perform a
 225 polling (refreshOnly) mode of synchronization once a day.  It will
 226 bind as {{EX:cn=syncuser,dc=example,dc=com}} using simple authentication
 227 with password "secret".  Note that the access control privilege of
 228 the DN specified by the binddn= directive should be set properly
 229 to synchronize the desired replica content.  The consumer will write
 230 to its database with the privilege of the
 231 {EX:cn=replica,dc=example,dc=com}} entry as specified by the
 232 {{EX:updatedn=}} directive.  The updatedn entry should have write
 233 permission to the database.
 234
 235 The synchronization search in the example will search for entries
 236 whose objectClass is organizationalPerson in the entire subtree
 237 under {{EX:dc=example,dc=com}} search base inclusively. The requested
 238 attributes are cn, sn, ou, telephoneNumber, title, and l. The schema
 239 checking is turned on, so that the consumer {{slapd}}(8) will enforce
 240 entry schema checking when it process updates from the provider
 241 {{slapd}}(8).
 242
 243 The LDAP Sync replication engine is backend independent. All three
 244 native backends can perform as the LDAP Sync replication consumer.
 245
 246 H3: Start the provider and the consumer slapd
 247
 248 If the currently running provider {{slapd}}(8) already has the
 249 syncProviderSubentry in its database, it is not required to restart
 250 the provider slapd. You don't need to restart the provider {{slapd}}(8)
 251 when you start a replicated LDAP service. When you run a consumer
 252 {{slapd}}(8), it will immediately perform either the initial full reload
 253 if cookie is NULL or too out of date, or incremental synchronization
 254 if effective cookie is provided. In the refreshOnly mode, the next
 255 synchronization session is scheduled to run interval time after the
 256 completion of the current session. In the refreshAndPersist mode,
 257 the synchronization session is open between the consumer and provider.
 258 The provider will send update message whenever there are updates
 259 in the provider replica.