syncrepl.sdf

OpenLdap是LDAP的开源项目

transactions are not committed in the issue order.

The provider stores the {{EX:contextCSN}} of a context in the
{{EX:contextCSN}} attribute of the context suffix entry. The attribute
is not written to the database after every update operation though;
instead it is maintained primarily in memory. At database start
time the provider reads the last saved {{EX:contextCSN}} into memory
and uses the in-memory copy exclusively thereafter. By default,
changes to the {{EX:contextCSN}} as a result of database updates
will not be written to the database until the server is cleanly
shut down. A checkpoint facility exists to cause the contextCSN to
be written out more frequently if desired.

Note that at startup time, if the provider is unable to read a
{{EX:contextCSN}} from the suffix entry, it will scan the entire
database to determine the value, and this scan may take quite a
long time on a large database. When a {{EX:contextCSN}} value is
read, the database will still be scanned for any {{EX:entryCSN}}
values greater than it, to make sure the {{EX:contextCSN}} value
truly reflects the greatest committed {{EX:entryCSN}} in the database.
On databases which support inequality indexing, setting an eq index
on the {{EX:entryCSN}} attribute and configuring {{contextCSN}}
checkpoints will greatly speed up this scanning step.

If no {{EX:contextCSN}} can be determined by reading and scanning
the database, a new value will be generated. Also, if scanning the
database yielded a greater {{EX:entryCSN}} than was previously
recorded in the suffix entry's {{EX:contextCSN}} attribute, a
checkpoint will be immediately written with the new value.

The consumer also stores its replica state, which is the provider's
{{EX:contextCSN}} received as a synchronization cookie, in the
{{EX:contextCSN}} attribute of the suffix entry.  The replica state
maintained by a consumer server is used as the synchronization state
indicator when it performs subsequent incremental synchronization
with the provider server. It is also used as a provider-side
synchronization state indicator when it functions as a secondary
provider server in a cascading replication configuration.  Since
the consumer and provider state information are maintained in the
same location within their respective databases, any consumer can
be promoted to a provider (and vice versa) without any special
actions.

Because a general search filter can be used in the syncrepl
specification, some entries in the context may be omitted from the
synchronization content.  The syncrepl engine creates a glue entry
to fill in the holes in the replica context if any part of the
replica content is subordinate to the holes. The glue entries will
not be returned in the search result unless {{ManageDsaIT}} control
is provided.

Also as a consequence of the search filter used in the syncrepl
specification, it is possible for a modification to remove an entry
from the replication scope even though the entry has not been deleted
on the provider. Logically the entry must be deleted on the consumer
but in {{refreshOnly}} mode the provider cannot detect and propagate
this change without the use of the session log.


H2: Configuring Syncrepl

Because syncrepl is a consumer-side replication engine, the syncrepl
specification is defined in {{slapd.conf}} (5) of the consumer
server, not in the provider server's configuration file.  The initial
loading of the replica content can be performed either by starting
the syncrepl engine with no synchronization cookie or by populating
the consumer replica by adding an {{TERM:LDIF}} file dumped as a
backup at the provider.

When loading from a backup, it is not required to perform the initial
loading from the up-to-date backup of the provider content. The
syncrepl engine will automatically synchronize the initial consumer
replica to the current provider content. As a result, it is not
required to stop the provider server in order to avoid the replica
inconsistency caused by the updates to the provider content during
the content backup and loading process.

When replicating a large scale directory, especially in a bandwidth
constrained environment, it is advised to load the consumer replica
from a backup instead of performing a full initial load using
syncrepl.


H3: Set up the provider slapd

The provider is implemented as an overlay, so the overlay itself
must first be configured in {{slapd.conf}} (5) before it can be
used. The provider has only two configuration directives, for setting
checkpoints on the {{EX:contextCSN}} and for configuring the session
log.  Because the LDAP Sync search is subject to access control,
proper access control privileges should be set up for the replicated
content.

The {{EX:contextCSN}} checkpoint is configured by the

>	syncprov-checkpoint <ops> <minutes>

directive. Checkpoints are only tested after successful write
operations.  If {{<ops>}} operations or more than {{<minutes>}}
time has passed since the last checkpoint, a new checkpoint is
performed.

The session log is configured by the

>	syncprov-sessionlog <size>

directive, where {{<size>}} is the maximum number of session log
entries the session log can record. When a session log is configured,
it is automatically used for all LDAP Sync searches within the
database.

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.

A more complete example of the {{slapd.conf}} content is thus:

>	database bdb
>	suffix dc=Example,dc=com
>	rootdn dc=Example,dc=com
>	directory /var/ldap/db
>	index objectclass,entryCSN,entryUUID eq
>
>	overlay syncprov
>	syncprov-checkpoint 100 10
>	syncprov-sessionlog 100


H3: Set up the consumer slapd

The syncrepl replication is specified in the database section of
{{slapd.conf}} (5) for the replica context.  The syncrepl engine
is backend independent and the directive can be defined with any
database type.

>	database hdb
>	suffix dc=Example,dc=com
>	rootdn dc=Example,dc=com
>	directory /var/ldap/db
>	index objectclass,entryCSN,entryUUID eq
>
>	syncrepl rid=123
>		provider=ldap://provider.example.com:389
>		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
at port 389 of {{FILE:ldap://provider.example.com}} to perform a
polling ({{refreshOnly}}) mode of synchronization once a day.  It
will bind as {{EX:cn=syncuser,dc=example,dc=com}} using simple
authentication with password "secret".  Note that the access control
privilege of {{EX:cn=syncuser,dc=example,dc=com}} should be set
appropriately in the provider to retrieve the desired replication
content. Also the search limits must be high enough on the provider
to allow the syncuser to retrieve a complete copy of the requested
content.  The consumer uses the rootdn to write to its database so
it always has full permissions to write all content.

The synchronization search in the above example will search for the
entries whose objectClass is organizationalPerson in the entire
subtree rooted at {{EX:dc=example,dc=com}}. The requested attributes
are {{EX:cn}}, {{EX:sn}}, {{EX:ou}}, {{EX:telephoneNumber}},
{{EX:title}}, and {{EX:l}}. The schema checking is turned off, so
that the consumer {{slapd}} (8) will not enforce entry schema
checking when it process updates from the provider {{slapd}} (8).

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


H3: Start the provider and the consumer slapd

The provider {{slapd}} (8) is not required to be restarted.
{{contextCSN}} is automatically generated as needed: it might be
originally contained in the {{TERM:LDIF}} file, generated by
{{slapadd}} (8), generated upon changes in the context, or generated
when the first LDAP Sync search arrives at the provider.  If an
LDIF file is being loaded which did not previously contain the
{{contextCSN}}, the {{-w}} option should be used with {{slapadd}}
(8) to cause it to be generated. This will allow the server to
startup a little quicker the first time it runs.

When starting a consumer {{slapd}} (8), it is possible to provide
a synchronization cookie as the {{-c cookie}} command line option
in order to start the synchronization from a specific state.  The
cookie is a comma separated list of name=value pairs. Currently
supported syncrepl cookie fields are {{csn=<csn>}} and {{rid=<rid>}}.
{{<csn>}} represents the current synchronization state of the
consumer replica.  {{<rid>}} identifies a consumer replica locally
within the consumer server. It is used to relate the cookie to the
syncrepl definition in {{slapd.conf}} (5) which has the matching
replica identifier.  The {{<rid>}} must have no more than 3 decimal
digits.  The command line cookie overrides the synchronization
cookie stored in the consumer replica database.