replication.sdf 47.3 KB
Newer Older
1
# $OpenLDAP$
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
2
# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
3
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4

5
H1: Replication
6

7
8
9
Replicated directories are a fundamental requirement for delivering a 
resilient enterprise deployment.

10
{{PRD:OpenLDAP}} has various configuration options for creating a replicated 
11
12
13
14
15
directory. In previous releases, replication was discussed in terms of
a {{master}} server and some number of {{slave}} servers. A master
accepted directory updates from other clients, and a slave only
accepted updates from a (single) master. The replication structure
was rigidly defined and any particular database could only fulfill
16
17
a single role, either master or slave. Another historic term introduced
with OpenLDAP 2.4 was multimaster.
18
19

As OpenLDAP now supports a wide variety of replication topologies, these
20
21
22
23
24
25
26
terms have been deprecated in favor of {{provider}}/{{multi-provider}} and
{{consumer}}: A provider can accept external write operations and make them
available for retrieval by consumers; consumers request replication updates from
providers. Unlike the rigidly defined master/slave relationships,
provider/consumer roles are quite fluid: replication updates received in a
consumer can be further propagated by that consumer to other servers, so a
consumer can also act simultaneously as a provider. Also, a consumer need not
27
28
29
be an actual LDAP server; it may be just an LDAP client.

The following sections will describe the replication technology and
30
discuss the various replication options that are available.
31

32
H2: Replication Technology
33

34
H3: LDAP Sync Replication
35

36
37
38
The {{TERM:LDAP Sync}} Replication engine, {{TERM:syncrepl}} for
short, is a consumer-side replication engine that enables the
consumer {{TERM:LDAP}} server to maintain a shadow copy of a
39
{{TERM:DIT}} fragment. A syncrepl engine resides at the consumer
40
and executes as one of the {{slapd}}(8) threads. It creates and maintains a
41
replica by connecting to the replication provider to perform
42
43
the initial DIT content load followed either by periodic content
polling or by timely updates upon content changes.
44

45
Syncrepl uses the LDAP Content Synchronization protocol (or LDAP Sync for
46
short) as the consumer synchronization protocol.  LDAP Sync provides
47
48
a stateful replication which supports both pull-based and push-based
synchronization and does not mandate the use of a history store.
49
50
51
52
In pull-based replication the consumer periodically
polls the provider for updates. In push-based replication the consumer
listens for updates that are sent by the provider in realtime. Since the
protocol does not require a history store, the provider does not need to
Gavin Henry's avatar
Gavin Henry committed
53
maintain any log of updates it has received (Note
54
that the syncrepl engine is extensible and additional replication
Gavin Henry's avatar
Gavin Henry committed
55
protocols may be supported in the future.).
56

57
58
59
60
61
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
62
63
64
consumer up-to-date with the provider content. Syncrepl
also enables convenient management of consumers by maintaining replication
status.  The consumer database can be constructed from a consumer-side
65
or a provider-side backup at any synchronization status. Syncrepl
66
can automatically resynchronize the consumer database to be up-to-date
67
with the current provider content.
68

69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
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.
84

85
With syncrepl, a consumer can create a replication agreement without
86
87
88
89
90
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.
Gavin Henry's avatar
Gavin Henry committed
91

92
Syncrepl supports partial, sparse, and fractional replications.  The shadow
93
DIT fragment is defined by a general search criteria consisting of
94
base, scope, filter, and attribute list.  The consumer content is
95
96
also subject to the access privileges of the bind identity of the
syncrepl replication connection.
97

Gavin Henry's avatar
Gavin Henry committed
98

99
H4: The LDAP Content Synchronization Protocol
Gavin Henry's avatar
Gavin Henry committed
100

101
102
103
104
105
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 {{REF:RFC4533}}.
Gavin Henry's avatar
Gavin Henry committed
106

107
108
The LDAP Sync protocol supports both polling and listening for changes
by defining two respective synchronization operations:
109
{{refreshOnly}} and {{refreshAndPersist}}.  Polling is implemented
110
111
112
113
114
by the {{refreshOnly}} operation. The consumer
polls the provider using an LDAP Search request with an LDAP Sync
control attached. The consumer copy is synchronized
to the provider copy at the time of polling using the information
returned in the search.  The provider finishes the
115
search operation by returning {{SearchResultDone}} at the end of
116
117
118
the search operation as in the normal search.  Listening is
implemented by the {{refreshAndPersist}} operation. As the name
implies, it begins with a search, like refreshOnly. Instead of
119
120
finishing the search after returning all entries currently matching
the search criteria, the synchronization search remains persistent
121
122
123
in the provider. Subsequent updates to the synchronization content
in the provider cause additional entry updates to be sent to the
consumer.
Gavin Henry's avatar
Gavin Henry committed
124

125
126
127
The {{refreshOnly}} operation and the refresh stage of the
{{refreshAndPersist}} operation can be performed with a present
phase or a delete phase.
Gavin Henry's avatar
Gavin Henry committed
128

129
130
131
In the present phase, the provider sends the consumer the entries updated
within the search scope since the last synchronization. The provider
sends all requested attributes, be they changed or not, of the updated
132
entries.  For each unchanged entry which remains in the scope, the
133
provider sends a present message consisting only of the name of the
134
135
entry and the synchronization control representing state present.
The present message does not contain any attributes of the entry.
136
137
138
139
140
After the consumer receives all update and present entries, it can
reliably determine the new consumer copy by adding the entries added
to the provider, by replacing the entries modified at the provider, and
by deleting entries in the consumer copy which have not been updated
nor specified as being present at the provider.
Gavin Henry's avatar
Gavin Henry committed
141

142
The transmission of the updated entries in the delete phase is the
143
same as in the present phase. The provider sends all the requested
144
attributes of the entries updated within the search scope since the
145
146
last synchronization to the consumer. In the delete phase, however,
the provider sends a delete message for each entry deleted from the
147
148
search scope, instead of sending present messages.  The delete
message consists only of the name of the entry and the synchronization
149
control representing state delete.  The new consumer copy can be
150
151
152
determined by adding, modifying, and removing entries according to
the synchronization control attached to the {{SearchResultEntry}}
message.
Gavin Henry's avatar
Gavin Henry committed
153

154
155
156
157
In the case that the LDAP Sync provider maintains a history store and
can determine which entries are scoped out of the consumer copy since
the last synchronization time, the provider can use the delete phase.
If the provider does not maintain any history store, cannot determine
158
the scoped-out entries from the history store, or the history store
159
160
does not cover the outdated synchronization state of the consumer,
the provider should use the present phase.  The use of the present
161
162
163
164
165
166
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.
Gavin Henry's avatar
Gavin Henry committed
167

168
169
170
At the end of the {{refreshOnly}} synchronization, the provider sends
a synchronization cookie to the consumer as a state indicator of the
consumer copy after the synchronization is completed.  The consumer
171
will present the received cookie when it requests the next incremental
172
synchronization to the provider.
173

174
When {{refreshAndPersist}} synchronization is used, the provider sends
175
a synchronization cookie at the end of the refresh stage by sending
176
a Sync Info message with refreshDone=TRUE.  It also sends a
177
synchronization cookie by attaching it to {{SearchResultEntry}}
178
179
180
181
messages generated in the persist stage of the synchronization search. During
the persist stage, the provider can also send a Sync Info message
containing the synchronization cookie at any time the provider wants
to update the consumer-side state indicator.
182
183
184
185
186
187
188
189
190

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.

191
H4: Syncrepl Details
192
193
194
195
196
197
198
199
200
201
202
203
204
205

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
206
a session log in the provider which stores the
207
{{EX:entryUUID}}s of a finite number of entries deleted from a
208
209
210
database. Multiple consumers share the same 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
211
212
truncated after the last synchronization of the client.  The syncrepl
engine uses the present phase if no session log is configured for
213
the replication content or if the consumer is too outdated
214
215
216
217
218
219
220
221
222
223
224
225
226
227
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
228
229
as an overlay on any backend, but works best with the {{back-mdb}}
backend.
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247

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
Gavin Henry's avatar
Gavin Henry committed
248
shut down. A checkpoint facility exists to cause the {{EX:contextCSN}} to
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
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.

268
The consumer also stores its replication state, which is the provider's
269
{{EX:contextCSN}} received as a synchronization cookie, in the
270
{{EX:contextCSN}} attribute of the suffix entry.  The replication state
271
272
273
274
275
276
277
278
279
280
281
282
283
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
284
285
to fill in the holes in the consumer context if any part of the
consumer content is subordinate to the holes. The glue entries will
286
287
288
289
290
291
292
293
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
Gavin Henry's avatar
Gavin Henry committed
294
this change without the use of the session log on the provider.
295

296
297
298
For configuration, please see the {{SECT:Syncrepl}} section.


299
300
301
302
303
304
305
H2: Deployment Alternatives

While the LDAP Sync specification only defines a narrow scope for replication,
the OpenLDAP implementation is extremely flexible and supports a variety of
operating modes to handle other scenarios not explicitly addressed in the spec.


306
307
H3: Delta-syncrepl replication

308
* Disadvantages of LDAP Sync replication:
309

310
LDAP Sync replication is an object-based replication mechanism. 
311
When any attribute value in a replicated object is changed on the provider, 
Gavin Henry's avatar
Gavin Henry committed
312
313
each consumer fetches and processes the complete changed object, including
{{B:both the changed and unchanged attribute values}} during replication.
314
315
316
317
318
One advantage of this approach is that when multiple changes occur to
a single object, the precise sequence of those changes need not be preserved;
only the final state of the entry is significant. But this approach
may have drawbacks when the usage pattern involves single changes to
multiple objects.
319

Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
320
For example, suppose you have a database consisting of 102,400 objects of 1 KB 
321
each. Further, suppose you routinely run a batch job to change the value of 
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
322
a single two-byte attribute value that appears in each of the 102,400 objects 
323
on the provider. Not counting LDAP and TCP/IP protocol overhead, each time you 
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
324
run this job each consumer will transfer and process {{B:100 MB}} of data to
325
process {{B:200KB of changes!}}
326
327
328
329
330
331
332
333
334
335
336
337

99.98% of the data that is transmitted and processed in a case like this will 
be redundant, since it represents values that did not change. This is a waste 
of valuable transmission and processing bandwidth and can cause an unacceptable 
replication backlog to develop. While this situation is extreme, it serves to 
demonstrate a very real problem that is encountered in some LDAP deployments.


* Where Delta-syncrepl comes in:

Delta-syncrepl, a changelog-based variant of syncrepl, is designed to address 
situations like the one described above. Delta-syncrepl works by maintaining a 
338
changelog of a selectable depth in a separate database on the provider. The replication consumer 
339
340
checks the changelog for the changes it needs and, as long as 
the changelog contains the needed changes, the consumer fetches the changes
341
from the changelog and applies them to its database. If, however, a consumer
342
is too far out of sync (or completely empty), conventional syncrepl is used to 
343
344
bring it up to date and replication then switches back to the delta-syncrepl
mode.
345

346
347
348
349
350
Note: since the database state is stored in both the changelog DB and the
main DB on the provider, it is important to backup/restore both the changelog
DB and the main DB using slapcat/slapadd when restoring a DB or copying
it to another machine.

351
352
353
For configuration, please see the {{SECT:Delta-syncrepl}} section.


354
H3: N-Way Multi-Provider Replication
355

356
357
Multi-Provider replication is a replication technique using Syncrepl to replicate 
data to multiple provider ("Provider") Directory servers. 
358

359
H4: Valid Arguments for Multi-Provider replication
360

361
362
363
364
365
* If any provider fails, other providers will continue to accept updates
* Avoids a single point of failure
* Providers can be located in several physical sites i.e. distributed across
the network/globe.
* Good for Automatic failover/High Availability
366

367
H4: Invalid Arguments for Multi-Provider replication
368

369
(These are often claimed to be advantages of Multi-Provider replication but
370
those claims are false):
371

372
373
374
* It has {{B:NOTHING}} to do with load balancing
* Providers {{B:must}} propagate writes to {{B:all}} the other servers, which 
means the network traffic and write load spreads across all 
375
of the servers the same as for single-provider.
376
* Server utilization and performance are at best identical for
377
Multi-Provider and Single-Provider replication; at worst Single-Provider is
378
379
superior because indexing can be tuned differently to optimize for the
different usage patterns between the provider and the consumers.
380

381
H4: Arguments against Multi-Provider replication
382

383
384
385
* Breaks the data consistency guarantees of the directory model
* {{URL:http://www.openldap.org/faq/data/cache/1240.html}}
* If connectivity with a provider is lost because of a network partition, then 
386
"automatic failover" can just compound the problem
387
* Typically, a particular machine cannot distinguish between losing contact
388
 with a peer because that peer crashed, or because the network link has failed
389
* If a network is partitioned and multiple clients start writing to each of the 
390
"providers" then reconciliation will be a pain; it may be best to simply deny 
391
writes to the clients that are partitioned from the single provider
392
393


394
For configuration, please see the {{SECT:N-Way Multi-Provider}} section below
395

396
H3: Mirror mode replication
397

398
Mirror mode is a hybrid configuration that provides all of the consistency
399
guarantees of single-provider replication, while also providing the high
400
availability of multi-provider. In Mirror mode two providers are set up to
401
replicate from each other (as a multi-provider configuration), but an
402
external frontend is employed to direct all writes to only one of
403
404
405
the two servers. The second provider will only be used for writes if
the first provider crashes, at which point the frontend will switch to
directing all writes to the second provider. When a crashed provider is
406
repaired and restarted it will automatically catch up to any changes
407
on the running provider and resync.
408

409
H4: Arguments for Mirror mode
410
411

* Provides a high-availability (HA) solution for directory writes (replicas handle reads)
412
413
* As long as one provider is operational, writes can safely be accepted
* Provider nodes replicate from each other, so they are always up to date and
414
can be ready to take over (hot standby)
415
* Syncrepl also allows the provider nodes to re-synchronize after any downtime
416

417

418
H4: Arguments against Mirror mode
419

420
* Mirror mode is not what is termed as a Multi-Provider solution. This is because
421
writes have to go to just one of the mirror nodes at a time
422
* Mirror mode can be termed as Active-Active Hot-Standby, therefore an external
423
424
server (slapd in proxy mode) or device (hardware load balancer)
is needed to manage which provider is currently active
425
426
* Backups are managed slightly differently

427
For configuration, please see the {{SECT:Mirror mode}} section below
428
429


430
431
432
433
434
435
H3: Syncrepl Proxy Mode

While the LDAP Sync protocol supports both pull- and push-based replication,
the push mode (refreshAndPersist) must still be initiated from the consumer
before the provider can begin pushing changes. In some network configurations,
particularly where firewalls restrict the direction in which connections
436
can be made, a provider-initiated push mode may be needed.
437
438
439
440

This mode can be configured with the aid of the LDAP Backend
({{SECT: Backends}} and {{slapd-ldap(8)}}). Instead of running the
syncrepl engine on the actual consumer, a slapd-ldap proxy is set up
Gavin Henry's avatar
Gavin Henry committed
441
near (or collocated with) the provider that points to the consumer,
442
443
444
445
and the syncrepl engine runs on the proxy.

For configuration, please see the {{SECT:Syncrepl Proxy}} section.

446
447
448
449
450
H2: Configuring the different replication types

H3: Syncrepl

H4: Syncrepl configuration
451
452
453
454

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
455
loading of the consumer content can be performed either by starting
456
the syncrepl engine with no synchronization cookie or by populating
457
the consumer by loading an {{TERM:LDIF}} file dumped as a
458
459
460
461
462
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
463
464
to the current provider content. As a result, it is not
required to stop the provider server in order to avoid the replication
465
466
467
468
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
469
constrained environment, it is advised to load the consumer
470
471
472
473
474
475
476
477
from a backup instead of performing a full initial load using
syncrepl.


H4: Set up the provider slapd

The provider is implemented as an overlay, so the overlay itself
must first be configured in {{slapd.conf}}(5) before it can be
478
479
used. The provider has two primary configuration directives and
two secondary directives for when delta-syncrepl is being used.
480
481
Because the LDAP Sync search is subject to access control, proper
access control privileges should be set up for the replicated
482
483
content.

484
485
The two primary options to configure are the checkpoint and
sessionlog behaviors.
486

487
488
489
490
491
The {{EX:contextCSN}} checkpoint is configured by the

>	syncprov-checkpoint <ops> <minutes>

directive. Checkpoints are only tested after successful write
492
operations. If {{<ops>}} operations or more than {{<minutes>}}
493
time has passed since the last checkpoint, a new checkpoint is
494
performed. Checkpointing is disabled by default.
495
496
497

The session log is configured by the

498
>	syncprov-sessionlog <ops>
499

500
501
502
directive, where {{<ops>}} is the maximum number of session log
entries the session log can record. All write operations (except Adds)
are recorded in the log.
503
504
505
506
507

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.

508
509
510
511
The reloadhint option is configured by the

>	syncprov-reloadhint <TRUE|FALSE>

512
513
directive. It must be set TRUE when using the accesslog overlay for
delta-based syncrepl replication support. The default is FALSE.
514
515
516
517
518
519
520
521
522
523
524
525
526

The nonpresent option should only be configured if the overlay is
being placed on top of a log database, such as when used with
delta-syncrepl.

The nonpresent option is configured by the

>	syncprov-nopresent <TRUE|FALSE>

directive. This value should only be set TRUE for a syncprov instance
on top of a log database (such as one managed by the accesslog overlay).
The default is FALSE.

527
528
A more complete example of the {{slapd.conf}}(5) content is thus:

529
530
>	database mdb
>	maxsize 1073741824
531
532
533
534
535
536
537
538
539
540
541
542
>	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


H4: Set up the consumer slapd

543
544
The syncrepl directive is specified in the database section of
{{slapd.conf}}(5) for the consumer context. The syncrepl engine
545
546
547
is backend independent and the directive can be defined with any
database type.

548
549
>	database mdb
>	maxsize 1073741824
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
>	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
>		type=refreshOnly
>		interval=01:00:00:00
>		searchbase="dc=example,dc=com"
>		filter="(objectClass=organizationalPerson)"
>		scope=sub
>		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}}(8)
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
586
checking when it processes updates from the provider {{slapd}}(8).
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610

For more detailed information on the syncrepl directive, see the
{{SECT:syncrepl}} section of {{SECT:The slapd Configuration File}}
chapter of this admin guide.


H4: Start the provider and the consumer slapd

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
611
consumer. {{<rid>}} identifies a consumer locally
612
613
within the consumer server. It is used to relate the cookie to the
syncrepl definition in {{slapd.conf}}(5) which has the matching
614
{{<rid>}}.  The {{<rid>}} must have no more than 3 decimal
615
digits.  The command line cookie overrides the synchronization
616
cookie stored in the consumer database.
617
618


619
620
H3: Delta-syncrepl

621
H4: Delta-syncrepl Provider configuration
622

623
Setting up delta-syncrepl requires configuration changes on both the provider and 
624
625
replica servers:

626
>     # Give the replicator DN unlimited read access.  This ACL needs to be
Pierangelo Masarati's avatar
Pierangelo Masarati committed
627
628
629
>     # merged with other ACL statements, and/or moved within the scope
>     # of a database.  The "by * break" portion causes evaluation of
>     # subsequent rules.  See slapd.access(5) for details.
630
>     access to *
631
>        by dn.base="cn=replicator,dc=example,dc=com" read
632
633
634
635
636
>        by * break
>     
>     # Set the module path location
>     modulepath /opt/symas/lib/openldap
>     
637
638
>     # Load the mdb backend
>     moduleload back_mdb.la
639
640
641
642
643
644
645
646
>     
>     # Load the accesslog overlay
>     moduleload accesslog.la
>     
>     #Load the syncprov overlay
>     moduleload syncprov.la
>     
>     # Accesslog database definitions
647
>     database mdb
648
649
650
651
>     suffix cn=accesslog
>     directory /db/accesslog
>     rootdn cn=accesslog
>     index default eq
652
>     index entryCSN,objectClass,reqEnd,reqResult,reqStart,reqDN
653
654
655
656
657
>     
>     overlay syncprov
>     syncprov-nopresent TRUE
>     syncprov-reloadhint TRUE
>     
658
659
>     # Let the replicator DN have limitless searches
>     limits dn.exact="cn=replicator,dc=example,dc=com" time.soft=unlimited time.hard=unlimited size.soft=unlimited size.hard=unlimited
660
661
>     
>     # Primary database definitions
662
>     database mdb
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
>     suffix "dc=symas,dc=com"
>     rootdn "cn=manager,dc=symas,dc=com"
>     
>     ## Whatever other configuration options are desired
>     
>     # syncprov specific indexing
>     index entryCSN eq
>     index entryUUID eq
>     
>     # syncrepl Provider for primary db
>     overlay syncprov
>     syncprov-checkpoint 1000 60
>     
>     # accesslog overlay definitions for primary db
>     overlay accesslog
>     logdb cn=accesslog
>     logops writes
>     logsuccess TRUE
>     # scan the accesslog DB every day, and purge entries older than 7 days
>     logpurge 07+00:00 01+00:00
>     
684
685
>     # Let the replicator DN have limitless searches
>     limits dn.exact="cn=replicator,dc=example,dc=com" time.soft=unlimited time.hard=unlimited size.soft=unlimited size.hard=unlimited
686

687
For more information, always consult the relevant man pages ({{slapo-accesslog}}(5) and {{slapd.conf}}(5))
688
689


690
H4: Delta-syncrepl Consumer configuration
691

692
>     # Replica database configuration
693
>     database mdb
694
695
696
697
698
699
700
701
702
703
704
>     suffix "dc=symas,dc=com"
>     rootdn "cn=manager,dc=symas,dc=com"
>     
>     ## Whatever other configuration bits for the replica, like indexing
>     ## that you want
>     
>     # syncrepl specific indices
>     index entryUUID eq
>     
>     # syncrepl directives
>     syncrepl  rid=0
705
>               provider=ldap://ldapprovider.example.com:389
706
>               bindmethod=simple
707
>               binddn="cn=replicator,dc=example,dc=com"
708
>               credentials=secret
709
>               searchbase="dc=example,dc=com"
710
711
712
713
714
715
716
>               logbase="cn=accesslog"
>               logfilter="(&(objectClass=auditWriteObject)(reqResult=0))"
>               schemachecking=on
>               type=refreshAndPersist
>               retry="60 +"
>               syncdata=accesslog
>     
717
718
>     # Refer updates to the provider
>     updateref               ldap://ldapprovider.example.com
719
720
721


The above configuration assumes that you have a replicator identity defined 
722
in your database that can be used to bind to the provider.
723

724
Note: An accesslog database is unique to a given provider. It should
725
never be replicated.
726

727
H3: N-Way Multi-Provider
728

729
730
For the following example we will be using 3 Provider nodes. Keeping in line with
{{B:test050-syncrepl-multiprovider}} of the OpenLDAP test suite, we will be configuring
731
732
733
734
735
736
737
738
739
740
741
742
743
744
{{slapd(8)}} via {{B:cn=config}}

This sets up the config database:

>     dn: cn=config
>     objectClass: olcGlobal
>     cn: config
>     olcServerID: 1
>     
>     dn: olcDatabase={0}config,cn=config
>     objectClass: olcDatabaseConfig
>     olcDatabase: {0}config
>     olcRootPW: secret

745
746
Each server must have a unique server ID ({{EX:SID}}), so
second and third servers will have a different {{EX:olcServerID}} obviously:
747
748
749
750
751
752
753
754
755
756
757

>     dn: cn=config
>     objectClass: olcGlobal
>     cn: config
>     olcServerID: 2
>     
>     dn: olcDatabase={0}config,cn=config
>     objectClass: olcDatabaseConfig
>     olcDatabase: {0}config
>     olcRootPW: secret

758
This sets up syncrepl as a provider (since these are all providers):
759
760
761
762
763
764
765

>     dn: cn=module,cn=config
>     objectClass: olcModuleList
>     cn: module
>     olcModulePath: /usr/local/libexec/openldap
>     olcModuleLoad: syncprov.la

766
Now we setup the first Provider Node (replace $URI1, $URI2 and $URI3 etc. with your actual ldap urls):
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793

>     dn: cn=config
>     changetype: modify
>     replace: olcServerID
>     olcServerID: 1 $URI1
>     olcServerID: 2 $URI2
>     olcServerID: 3 $URI3
>     
>     dn: olcOverlay=syncprov,olcDatabase={0}config,cn=config
>     changetype: add
>     objectClass: olcOverlayConfig
>     objectClass: olcSyncProvConfig
>     olcOverlay: syncprov
>     
>     dn: olcDatabase={0}config,cn=config
>     changetype: modify
>     add: olcSyncRepl
>     olcSyncRepl: rid=001 provider=$URI1 binddn="cn=config" bindmethod=simple
>       credentials=secret searchbase="cn=config" type=refreshAndPersist
>       retry="5 5 300 5" timeout=1
>     olcSyncRepl: rid=002 provider=$URI2 binddn="cn=config" bindmethod=simple
>       credentials=secret searchbase="cn=config" type=refreshAndPersist
>       retry="5 5 300 5" timeout=1
>     olcSyncRepl: rid=003 provider=$URI3 binddn="cn=config" bindmethod=simple
>       credentials=secret searchbase="cn=config" type=refreshAndPersist
>       retry="5 5 300 5" timeout=1
>     -
794
795
>     add: olcMultiProvider
>     olcMultiProvider: TRUE
796

797
Now start up the provider and a consumer/s, also add the above LDIF to the first consumer, second consumer etc. It will then replicate {{B:cn=config}}. You now have N-Way Multi-Provider on the config database.
798

799
We still have to replicate the actual data, not just the config, so add to the provider (all active and configured consumers/providers will pull down this config, as they are all syncing). Also, replace all {{${}}} variables with whatever is applicable to your setup:
800
801
802
803
804
805
806
807
808

>     dn: olcDatabase={1}$BACKEND,cn=config
>     objectClass: olcDatabaseConfig
>     objectClass: olc${BACKEND}Config
>     olcDatabase: {1}$BACKEND
>     olcSuffix: $BASEDN
>     olcDbDirectory: ./db
>     olcRootDN: $MANAGERDN
>     olcRootPW: $PASSWD
809
>     olcLimits: dn.exact="$MANAGERDN" time.soft=unlimited time.hard=unlimited size.soft=unlimited size.hard=unlimited
810
>     olcSyncRepl: rid=004 provider=$URI1 binddn="$MANAGERDN" bindmethod=simple
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
811
>       credentials=$PASSWD searchbase="$BASEDN" type=refreshOnly
812
813
>       interval=00:00:00:10 retry="5 5 300 5" timeout=1
>     olcSyncRepl: rid=005 provider=$URI2 binddn="$MANAGERDN" bindmethod=simple
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
814
>       credentials=$PASSWD searchbase="$BASEDN" type=refreshOnly
815
816
>       interval=00:00:00:10 retry="5 5 300 5" timeout=1
>     olcSyncRepl: rid=006 provider=$URI3 binddn="$MANAGERDN" bindmethod=simple
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
817
>       credentials=$PASSWD searchbase="$BASEDN" type=refreshOnly
818
>       interval=00:00:00:10 retry="5 5 300 5" timeout=1
819
>     olcMultiProvider: TRUE
820
821
822
823
824
825
826
>     
>     dn: olcOverlay=syncprov,olcDatabase={1}${BACKEND},cn=config
>     changetype: add
>     objectClass: olcOverlayConfig
>     objectClass: olcSyncProvConfig
>     olcOverlay: syncprov

827
828
829
830
831
832
833
834
Note: All of your servers' clocks must be tightly synchronized using
e.g. NTP {{http://www.ntp.org/}}, atomic clock, or some other reliable
time reference.

Note: As stated in {{slapd-config}}(5), URLs specified in {{olcSyncRepl}}
directives are the URLs of the servers from which to replicate. These
must exactly match the URLs {{slapd}} listens on ({{-h}} in {{SECT:Command-Line Options}}).
Otherwise slapd may attempt to replicate from itself, causing a loop.
835

836
837
838
839
840
841
842
843
844
845
846
Note: The {{entryCSN}} and {{contextCSN}} attributes are used
to track changes to an entry and naming context, respectively. The
{{EX:SID}} which must be unique for each replication provider is a
component of these CSNs. If you're using {{slapadd}} to load a
database and there are no entryCSNs already present in the input
LDIF, {{slapadd}} will generate them with a {{SID}} of {{EX:000}}. This
is not a valid {{SID}} for multi-provider replication, and you
should use the {{EX:-S}} option of {{slapadd}} (8) to specify
a valid {{SID}} for these generated CSNs. If there are existing
entryCSNs in the input LDIF, {{slapadd}} will not change them.

847
H3: Mirror mode
848

849
Mirror mode configuration is actually very easy. If you have ever setup a normal
850
slapd syncrepl provider, then the only change is the following two directives:
851

852
>       multiprovider  on
853
>       serverID    1
854

855
Note: You need to make sure that the {{serverID}} of each provider node is 
856
different and add it as a global configuration option.
857
858
859

H4: Mirror Node Configuration

Gavin Henry's avatar
Gavin Henry committed
860
861
The first step is to configure the syncrepl provider the same as in the 
{{SECT:Set up the provider slapd}} section.
862

863
Here's a specific cut down example using {{SECT:LDAP Sync Replication}} in
864
{{refreshAndPersist}} mode:
865

866
Mirror mode node 1:
867

868
869
870
871
>       # Global section
>       serverID    1
>       # database section
>       
872
873
874
875
876
877
878
879
880
881
>       # syncrepl directive
>       syncrepl      rid=001
>                     provider=ldap://ldap-sid2.example.com
>                     bindmethod=simple
>                     binddn="cn=mirrormode,dc=example,dc=com"
>                     credentials=mirrormode
>                     searchbase="dc=example,dc=com"
>                     schemachecking=on
>                     type=refreshAndPersist
>                     retry="60 +"
Gavin Henry's avatar
Gavin Henry committed
882
>
883
>       multiprovider on
884

885
Mirror mode node 2:
886

887
888
889
890
>       # Global section
>       serverID    2
>       # database section
>       
891
892
893
894
895
896
897
898
899
900
901
902
903
904
>       # syncrepl directive
>       syncrepl      rid=001
>                     provider=ldap://ldap-sid1.example.com
>                     bindmethod=simple
>                     binddn="cn=mirrormode,dc=example,dc=com"
>                     credentials=mirrormode
>                     searchbase="dc=example,dc=com"
>                     schemachecking=on
>                     type=refreshAndPersist
>                     retry="60 +"
>
>       multiprovider on

It's simple really; each Mirror mode node is setup {{B:exactly}} the same, except
Howard Chu's avatar
Howard Chu committed
905
that the {{serverID}} is unique, and each consumer is pointed to 
Gavin Henry's avatar
Gavin Henry committed
906
the other server.
907

908
H5: Failover Configuration
909
910
911
912

There are generally 2 choices for this; 1.  Hardware proxies/load-balancing or 
dedicated proxy software, 2. using a Back-LDAP proxy as a syncrepl provider

913
A typical enterprise example might be:
914

915
916
!import "dual_dc.png"; align="center"; title="Mirror mode Enterprise Configuration"
FT[align="Center"] Figure X.Y: Mirror mode in a Dual Data Center Configuration
917

918
H5: Normal Consumer Configuration
919
920
921
922
923

This is exactly the same as the {{SECT:Set up the consumer slapd}} section. It
can either setup in normal {{SECT:syncrepl replication}} mode, or in 
{{SECT:delta-syncrepl replication}} mode.

924
H4: Mirror mode Summary
925

926
You will now have a directory architecture that provides all of the 
927
928
consistency guarantees of single-provider replication, while also providing the 
high availability of multi-provider replication.
929

930

931
932
933
934
935
936
937
938
H3: Syncrepl Proxy

!import "push-based-complete.png"; align="center"; title="Syncrepl Proxy Mode"
FT[align="Center"] Figure X.Y: Replacing slurpd

The following example is for a self-contained push-based replication solution:

>	#######################################################################
939
>	# Standard OpenLDAP Provider
940
941
942
943
944
945
946
947
948
949
>	#######################################################################
>	
>	include     /usr/local/etc/openldap/schema/core.schema
>	include     /usr/local/etc/openldap/schema/cosine.schema
>	include     /usr/local/etc/openldap/schema/nis.schema
>	include     /usr/local/etc/openldap/schema/inetorgperson.schema
>	
>	include     /usr/local/etc/openldap/slapd.acl
>	
>	modulepath  /usr/local/libexec/openldap
950
>	moduleload  back_mdb.la
951
952
953
954
955
956
957
958
>	moduleload  syncprov.la
>	moduleload  back_ldap.la
>	
>	pidfile     /usr/local/var/slapd.pid
>	argsfile    /usr/local/var/slapd.args
>	
>	loglevel    sync stats
>	
959
>	database    mdb
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
>	suffix      "dc=suretecsystems,dc=com"
>	directory   /usr/local/var/openldap-data
>	
>	checkpoint      1024 5
>	
>	index       objectClass eq
>	# rest of indexes
>	index       default     sub
>	
>	rootdn		"cn=admin,dc=suretecsystems,dc=com"
>	rootpw	  	testing	
>	
>	# syncprov specific indexing
>	index entryCSN eq
>	index entryUUID eq
>	
>	# syncrepl Provider for primary db
>	overlay syncprov
>	syncprov-checkpoint 1000 60
>	
980
>	# Let the replicator DN have limitless searches
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
>	limits dn.exact="cn=replicator,dc=suretecsystems,dc=com" time.soft=unlimited time.hard=unlimited size.soft=unlimited size.hard=unlimited
>	
>	database    monitor
>	
>	database    config
>	rootpw	  	testing
>	
>	##############################################################################
>	# Consumer Proxy that pulls in data via Syncrepl and pushes out via slapd-ldap
>	##############################################################################
>	
>	database        ldap
>	# ignore conflicts with other databases, as we need to push out to same suffix
>	hidden		    on
>	suffix          "dc=suretecsystems,dc=com"
>	rootdn          "cn=slapd-ldap"
>	uri             ldap://localhost:9012/
>	
>	lastmod         on
>	        
For faster browsing, not all history is shown. View entire blame