upstream/openldap
1
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2026-06-14 19:20:03 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Sync with HEAD

Browse source
This commit is contained in:
Kurt Zeilenga 2005-05-10 18:13:02 +00:00
parent 77a925d7f6
commit 0d183bd75a
10 changed files with 1624 additions and 411 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
doc/guide/admin/Makefile Normal file
View file

@ -0,0 +1,66 @@
## Makefile for OpenLDAP Administrator's Guide
# $OpenLDAP$
## This work is part of OpenLDAP Software <http://www.openldap.org/>.
##
## Copyright 2005 The OpenLDAP Foundation.
## All rights reserved.
##
## Redistribution and use in source and binary forms, with or without
## modification, are permitted only as authorized by the OpenLDAP
## Public License.
##
## A copy of this license is available in the file LICENSE in the
## top-level directory of the distribution or, alternatively, at
## <http://www.OpenLDAP.org/license.html>.
all: guide.html index.html
sdf-src: \
../plain.sdf \
../preamble.sdf \
abstract.sdf \
config.sdf \
dbtools.sdf \
guide.sdf \
install.sdf \
intro.sdf \
master.sdf \
monitoringslapd.sdf \
preface.sdf \
proxycache.sdf \
quickstart.sdf \
referrals.sdf \
replication.sdf \
runningslapd.sdf \
sasl.sdf \
schema.sdf \
security.sdf \
slapdconfig.sdf \
syncrepl.sdf \
title.sdf \
tls.sdf \
tuning.sdf
sdf-img: \
../images/LDAPlogo.gif \
config_local.gif \
config_ref.gif \
config_repl.gif \
config_x500fe.gif \
config_x500ref.gif \
intro_dctree.gif \
intro_tree.gif \
replication.gif
guide.html: guide.sdf sdf-src sdf-img
sdf -2html guide.sdf
index.html: index.sdf sdf-src sdf-img
sdf -2topics index.sdf
admin.html: admin.sdf sdf-src sdf-img
sdf -DPDF -2html admin.sdf
guide.pdf: admin.html
htmldoc --book --duplex --bottom 36 --top 36 \
--toclevels 2 \
-f guide.pdf admin.html

13
doc/guide/admin/admin.sdf Normal file
View file

@ -0,0 +1,13 @@
# $OpenLDAP$
# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# guide.sdf
#
!define DOC_TOC 0
!macro build_html_cover
!endmacro
!include "master.sdf"

BIN
doc/guide/admin/config_dit.gif Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 4.5 KiB

59
doc/guide/admin/intro.sdf
View file

@ -1,5 +1,5 @@
# $OpenLDAP$
# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Introduction to OpenLDAP Directory Services
@ -132,10 +132,10 @@ be useful to you.
{{How is the information protected from unauthorized access?}} Some
directory services provide no protection, allowing anyone to see
the information. LDAP provides a mechanism for a client to
authenticate, or prove its identity to a directory server, paving
the way for rich access control to protect the information the
server contains. LDAP also supports privacy and integrity security
the information. LDAP provides a mechanism for a client to authenticate,
or prove its identity to a directory server, paving the way for
rich access control to protect the information the server contains.
LDAP also supports data security (integrity and confidentiality)
services.
@ -172,8 +172,8 @@ servers.
The stand-alone LDAP daemon, or {{slapd}}(8), can be viewed as a
{{lightweight}} X.500 directory server. That is, it does not
implement the X.500's DAP. As a {{lightweight directory}} server,
{{slapd}}(8) implements only a subset of the X.500 models.
implement the X.500's DAP nor does it support the complete X.500
models.
If you are already running a X.500 DAP service and you want to
continue to do so, you can probably stop reading this guide. This
@ -194,19 +194,19 @@ H2: What is the difference between LDAPv2 and LDAPv3?
LDAPv3 was developed in the late 1990's to replace LDAPv2.
LDAPv3 adds the following features to LDAP:
- Strong Authentication via {{TERM:SASL}}
- Integrity and Confidentiality Protection via {{TERM:TLS}} (SSL)
- Strong authentication and data security services via {{TERM:SASL}}
- Certificate authentication and data security services via {{TERM:TLS}} (SSL)
- Internationalization through the use of Unicode
- Referrals and Continuations
- Schema Discovery
- Extensibility (controls, extended operations, and more)
LDAPv2 is historic ({{REF:RFC3494}}). As most implementations
(including {{slapd}}(8)) of LDAPv2 do not conform to the LDAPv2
technical specification, interoperatibility amongst implementations
claiming LDAPv2 support will be limited. As LDAPv2 differs
significantly from LDAPv3, deploying both LDAPv2 and LDAPv3
simultaneously can be quite problematic. LDAPv2 should be avoided.
LDAPv2 is historic ({{REF:RFC3494}}). As most {{so-called}} LDAPv2
implementations (including {{slapd}}(8)) do not conform to the
LDAPv2 technical specification, interoperatibility amongst
implementations claiming LDAPv2 support is limited. As LDAPv2
differs significantly from LDAPv3, deploying both LDAPv2 and LDAPv3
simultaneously is quite problematic. LDAPv2 should be avoided.
LDAPv2 is disabled by default.
@ -223,12 +223,14 @@ interesting features and capabilities include:
{{slapd}} supports LDAP over both IPv4 and IPv6 and Unix IPC.
{{B:{{TERM[expand]SASL}}}}: {{slapd}} supports strong authentication
services through the use of SASL. {{slapd}}'s SASL implementation
utilizes {{PRD:Cyrus}} {{PRD:SASL}} software which supports a number
of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI.
and data security (integrity and confidentiality) services through
the use of SASL. {{slapd}}'s SASL implementation utilizes {{PRD:Cyrus}}
{{PRD:SASL}} software which supports a number of mechanisms including
DIGEST-MD5, EXTERNAL, and GSSAPI.
{{B:{{TERM[expand]TLS}}}}: {{slapd}} provides privacy and integrity
protections through the use of TLS (or SSL). {{slapd}}'s TLS
{{B:{{TERM[expand]TLS}}}}: {{slapd}} supports certificate-based
authentication and data security (integrity and confidentiality)
services through the use of TLS (or SSL). {{slapd}}'s TLS
implementation utilizes {{PRD:OpenSSL}} software.
{{B:Topology control}}: {{slapd}} can be configured to restrict
@ -239,8 +241,8 @@ This feature utilizes {{TCP wrappers}}.
control facility, allowing you to control access to the information
in your database(s). You can control access to entries based on
LDAP authorization information, {{TERM:IP}} address, domain name
and other criteria. {{slapd}} supports both {{static}} and
{{dynamic}} access control information.
and other criteria. {{slapd}} supports both {{static}} and {{dynamic}}
access control information.
{{B:Internationalization}}: {{slapd}} supports Unicode and language
tags.
@ -248,11 +250,12 @@ tags.
{{B:Choice of database backends}}: {{slapd}} comes with a variety
of different database backends you can choose from. They include
{{TERM:BDB}}, a high-performance transactional database backend;
{{TERM:HDB}}, a hierarchical high-performance transactional backend;
{{TERM:LDBM}}, a lightweight DBM based backend; {{SHELL}}, a backend
interface to arbitrary shell scripts; and PASSWD, a simple backend
interface to the {{passwd}}(5) file. The BDB backend utilizes
{{ORG:Sleepycat}} {{PRD:Berkeley DB}}. The LDBM utilizes either
{{PRD:Berkeley DB}} or {{PRD:GDBM}}.
interface to the {{passwd}}(5) file. The BDB and HDB backends
utilize {{ORG:Sleepycat}} {{PRD:Berkeley DB}}. The LDBM utilizes
either {{PRD:Berkeley DB}} or {{PRD:GDBM}}.
{{B:Multiple database instances}}: {{slapd}} can be configured to
serve multiple databases at the same time. This means that a single
@ -264,7 +267,7 @@ backends.
{{slapd}} lets you write your own modules easily. {{slapd}} consists
of two distinct parts: a front end that handles protocol communication
with LDAP clients; and modules which handle specific tasks such as
database operations. Because these two pieces communicate via a
database operations. Because these two pieces communicate via a
well-defined {{TERM:C}} {{TERM:API}}, you can write your own
customized modules which extend {{slapd}} in numerous ways. Also,
a number of {{programmable database}} modules are provided. These
@ -273,8 +276,8 @@ programming languages ({{PRD:Perl}}, {{shell}}, {{PRD:SQL}}, and
{{PRD:TCL}}).
{{B:Threads}}: {{slapd}} is threaded for high performance. A single
multi-threaded {{slapd}} process handles all incoming requests
using a pool of threads. This reduces the amount of system overhead
multi-threaded {{slapd}} process handles all incoming requests using
a pool of threads. This reduces the amount of system overhead
required while providing high performance.
{{B:Replication}}: {{slapd}} can be configured to maintain shadow

5
doc/guide/admin/master.sdf
View file

@ -1,5 +1,5 @@
# $OpenLDAP$
# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# master file for the OpenLDAP Administrator's Guide
@ -36,6 +36,9 @@ PB:
!include "install.sdf"; chapter
PB:
!include "slapdconf2.sdf"; chapter
PB:
!include "slapdconfig.sdf"; chapter
PB:

21
doc/guide/admin/schema.sdf
View file

@ -1,5 +1,5 @@
# $OpenLDAP$
# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Schema Specification
@ -81,15 +81,13 @@ There are five steps to defining new schema:
H3: Object Identifiers
Each schema element is identified by a globally unique
{{TERM[expand]OID}} (OID). OIDs are also used to identify
other objects.
They are commonly found in protocols described by {{TERM:ASN.1}}. In
Each schema element is identified by a globally unique {{TERM[expand]OID}}
(OID). OIDs are also used to identify other objects. They are
commonly found in protocols described by {{TERM:ASN.1}}. In
particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
As OIDs are hierarchical, your organization
can obtain one OID and branch it as needed. For example,
if your organization were assigned OID {{EX:1.1}}, you could branch
the tree as follows:
As OIDs are hierarchical, your organization can obtain one OID and
branch it as needed. For example, if your organization were assigned
OID {{EX:1.1}}, you could branch the tree as follows:
!block table; colaligns="LR"; coltags="EX,N"; align=Center; \
title="Table 8.2: Example OID hierarchy"
@ -129,10 +127,7 @@ you. OIDs obtained using this form may be used for any purpose
including identifying LDAP schema elements.
Alternatively, OID name space may be available from a national
authority (e.g., ANSI, BSI).
For private experiments, OIDs under {{EX:1.1}} may be used. The
OID {{EX:1.1}} arc is regarded as dead name space.
authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
H3: Name Prefix

77
doc/guide/admin/security.sdf
View file

@ -1,11 +1,11 @@
# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Security Considerations
OpenLDAP Software is designed to run in a wide variety of computing
environments from tightly-controlled closed networks to the global
Internet. Hence, OpenLDAP Software provides many different security
Internet. Hence, OpenLDAP Software supports many different security
mechanisms. This chapter describes these mechanisms and discusses
security considerations for using OpenLDAP Software.
@ -37,12 +37,9 @@ H3: IP Firewall
to restrict access based upon the client's IP address and/or network
interface used to communicate with the client.
Generally, {{slapd}}(8) listens on port 389/tcp for LDAP over
{{TERM:TCP}} (e.g. {{F:ldap://}}) and port 636/tcp for LDAP over
{{TERM:SSL}} (e.g. {{F:ldaps://}}). Note that LDAP over TCP
sessions can be protected by {{TERM:TLS}} through the use of
{{StartTLS}}. StartTLS is the Standard Track mechanism for protecting
LDAP sessions with TLS.
Generally, {{slapd}}(8) listens on port 389/tcp for {{F:ldap://}}
sessions and port 636/tcp for {{F:ldaps://}}) sessions. {{slapd}}(8)
may be configured to listen on other ports.
As specifics of how to configure IP firewall are dependent on the
particular kind of IP firewall used, no examples are provided here.
@ -51,9 +48,9 @@ See the document associated with your IP firewall.
H3: TCP Wrappers
OpenLDAP supports {{TERM:TCP}} Wrappers. TCP Wrappers provide a rule-based
access control system for controlling TCP/IP access to the server.
For example, the {{host_options}}(5) rule:
{{slapd}}(8) supports {{TERM:TCP}} Wrappers. TCP Wrappers provide
a rule-based access control system for controlling TCP/IP access
to the server. For example, the {{host_options}}(5) rule:
> slapd: 10.0.0.0/255.0.0.0 127.0.0.1 : ALLOW
> slapd: ALL : DENY
@ -71,15 +68,16 @@ of TCP wrappers.
See {{hosts_access}}(5) for more information on TCP wrapper rules.
H2: Integrity and Confidentiality Protection
H2: Data Integrity and Confidentiality Protection
{{TERM[expand]TLS}} (TLS) can be used to provide integrity and
confidentiality protection. OpenLDAP supports both StartTLS and
{{F:ldaps://}}. See the {{SECT:Using TLS}} chapter for more
information.
{{TERM[expand]TLS}} (TLS) can be used to provide data integrity and
confidentiality protection. OpenLDAP supports negotiation of
{{TERM:TLS}} ({{TERM:SSL}}) via both StartTLS and {{F:ldaps://}}.
See the {{SECT:Using TLS}} chapter for more information. StartTLS
is the standard track mechanism.
A number of {{TERM[expand]SASL}} (SASL) mechanisms, such as DIGEST-MD5
and {{TERM:GSSAPI}}, also provide integrity and confidentiality
and {{TERM:GSSAPI}}, also provide data integrity and confidentiality
protection. See the {{SECT:Using SASL}} chapter for more information.
@ -124,41 +122,42 @@ to the "simple" bind operation. Unauthenticated access is obtained
by providing a name but no password. Authenticated access is obtain
by providing a valid name and password.
An anonymous bind results in an {{anonymous}} authorization.
Anonymous bind mechanism is enabled by default, but can be disabled
by specifying "{{EX:disallow bind_anon}}" in {{slapd.conf}}(5).
An anonymous bind results in an {{anonymous}} authorization
association. Anonymous bind mechanism is enabled by default, but
can be disabled by specifying "{{EX:disallow bind_anon}}" in
{{slapd.conf}}(5).
An unauthenticated bind results in an {{anonymous}} authorization.
Unauthenticated bind mechanism is disabled by default, but can be
enabled by specifying "{{EX:allow bind_anon_cred}}" in {{slapd.conf}}(5).
As a number of LDAP applications mistakenly generate unauthenticated
bind request when authenticated access was intended (that is, they
do not ensure a password was provided), this mechanism should
generally not be enabled.
An unauthenticated bind also results in an {{anonymous}} authorization
association. Unauthenticated bind mechanism is disabled by default,
but can be enabled by specifying "{{EX:allow bind_anon_cred}}" in
{{slapd.conf}}(5). As a number of LDAP applications mistakenly
generate unauthenticated bind request when authenticated access was
intended (that is, they do not ensure a password was provided),
this mechanism should generally remain disabled.
A successful user/password authenticated bind results in a user
authorization identity, the provided name, being associated with
the session. User/password authenticated bind is enabled by default.
However, as this mechanism offers no evesdropping protection (e.g.,
the password is set in the clear), it is recommended that it be
used only in tightly controlled systems or when the LDAP session
is protected by other means (e.g., TLS, {{TERM:IPSEC}}). Where the
administrator relies on TLS to protect the password, it is recommended
that unprotected authentication be disabled. This is done by setting
"{{EX:disallow bind_simple_unprotected}}" in {{slapd.conf}}(5).
The {{EX:security}} directive's {{EX:simple_bind}} option provides
fine grain control over the level of confidential protection to
require for {{simple}} user/password authentication.
However, as this mechanism itself offers no evesdropping protection
(e.g., the password is set in the clear), it is recommended that
it be used only in tightly controlled systems or when the LDAP
session is protected by other means (e.g., TLS, {{TERM:IPSEC}}).
Where the administrator relies on TLS to protect the password, it
is recommended that unprotected authentication be disabled. This
is done by setting "{{EX:disallow bind_simple_unprotected}}" in
{{slapd.conf}}(5). The {{EX:security}} directive's {{EX:simple_bind}}
option provides fine grain control over the level of confidential
protection to require for {{simple}} user/password authentication.
The user/password authenticated bind mechanism can be completely
disabled by setting "{{EX:disallow bind_simple}}".
Note: An unsuccessful bind always results in the session having
an {{anonymous}} authorization state.
an {{anonymous}} authorization association.
H3: SASL method
The LDAP SASL method allows use of any SASL authentication
The LDAP {{TERM:SASL}} method allows use of any SASL authentication
mechanism. The {{SECT:Using SASL}} discusses use of SASL.

1173
doc/guide/admin/slapdconf2.sdf Normal file
View file

File diff suppressed because it is too large Load diff

70
doc/guide/admin/slapdconfig.sdf
View file

@ -1,5 +1,5 @@
# $OpenLDAP$
# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# Copyright 1999-2005, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: The slapd Configuration File
@ -287,13 +287,12 @@ perform" error.
H4: replica
> replica uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
> [bindmethod={simple|kerberos|sasl}]
> [bindmethod={simple|sasl}]
> ["binddn=<DN>"]
> [saslmech=<mech>]
> [authcid=<identity>]
> [authzid=<identity>]
> [credentials=<password>]
> [srvtab=<filename>]
This directive specifies a replication site for this database. The
{{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
@ -316,20 +315,14 @@ database. Since DNs are likely to contain embedded spaces, the
entire {{EX:"binddn=<DN>"}} string should be enclosed in double
quotes.
The {{EX:bindmethod}} is {{EX:simple}} or {{EX:kerberos}} or {{EX:sasl}},
depending on whether simple password-based authentication or Kerberos
authentication or {{TERM:SASL}} authentication is to be used when connecting
to the slave slapd.
The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}}, depending
on whether simple password-based authentication or {{TERM:SASL}}
authentication is to be used when connecting to the slave slapd.
Simple authentication should not be used unless adequate integrity
and privacy protections are in place (e.g. TLS or IPSEC). Simple
authentication requires specification of {{EX:binddn}} and
{{EX:credentials}} parameters.
Kerberos authentication is deprecated in favor of SASL authentication
mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}
mechanisms. Kerberos authentication requires {{EX:binddn}} and
{{EX:srvtab}} parameters.
Simple authentication should not be used unless adequate data
integrity and confidentiality protections are in place (e.g. TLS
or IPSEC). Simple authentication requires specification of
{{EX:binddn}} and {{EX:credentials}} parameters.
SASL authentication is generally recommended. SASL authentication
requires specification of a mechanism using the {{EX:saslmech}} parameter.
@ -430,7 +423,6 @@ H4: syncrepl
> [sizelimit=<limit>]
> [timelimit=<limit>]
> [schemachecking=on|off]
> [updatedn=<DN>]
> [bindmethod=simple|sasl]
> [binddn=<DN>]
> [saslmech=<mech>]
@ -507,15 +499,6 @@ required by the schema definition.
If it is turned off, entries will be stored without checking
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. 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
which has read access to the replication content in the
@ -526,10 +509,10 @@ depending on whether simple password-based authentication or
{{TERM:SASL}} authentication is to be used when connecting
to the provider slapd.
Simple authentication should not be used unless adequate integrity
and privacy protections are in place (e.g. TLS or IPSEC). Simple
authentication requires specification of {{EX:binddn}} and
{{EX:credentials}} parameters.
Simple authentication should not be used unless adequate data
integrity and confidentiality protections are in place (e.g. TLS
or IPSEC). Simple authentication requires specification of {{EX:binddn}}
and {{EX:credentials}} parameters.
SASL authentication is generally recommended. SASL authentication
requires specification of a mechanism using the {{EX:saslmech}} parameter.
@ -597,33 +580,6 @@ containing the database and associated indices live.
> directory /usr/local/var/openldap-data
H4: sessionlog <sid> <limit>
This directive specifies a session log store in the syncrepl
replication provider server which contains information on
the entries that have been scoped out of the replication
content identified by {{EX:<sid>}}.
The first syncrepl search request having the same {{EX:<sid>}} value
in the cookie establishes the session log store in the provider server.
The number of the entries in the session log store is limited
by {{EX:<limit>}}. Excessive entries are removed from the store
in the FIFO order. Both {{EX:<sid>}} and {{EX:<limit>}} are
non-negative integers. {{EX:<sid>}} has no more than three decimal digits.
The LDAP Content Synchronization operation that falls into a pre-existing
session can use the session log store in order to reduce the amount
of synchronization traffic. If the replica is not so outdated that
it can be made up-to-date by the information in the session store,
the provider slapd will send the consumer slapd the identities of the
scoped-out entries together with the in-scope entries added to or
modified within the replication content. If the replica status is
outdated too much and beyond the coverage of the history store,
then the provider slapd will send the identities of the unchanged
in-scope entries along with the changed in-scope entries.
The consumer slapd will then remove those entries in the replica
which are not identified as present in the provider content.
H3: LDBM Database Directives
Directives in this category only apply to a {{TERM:LDBM}} database.

551
doc/guide/admin/syncrepl.sdf
View file

@ -1,5 +1,5 @@
# $OpenLDAP$
# Copyright 2003, The OpenLDAP Foundation, All Rights Reserved.
# Copyright 2003-2005, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: LDAP Sync Replication
@ -8,62 +8,63 @@ 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.
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. It provides a stateful
replication which supports both
pull-based and push-based synchronization and does not mandate
the use of a history store.
Syncrepl uses the LDAP Content Synchronization (or LDAP Sync for
short) protocol as the replica synchronization protocol. It provides
a stateful replication which supports both pull-based and push-based
synchronization and does not mandate the use of a 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 for 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 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
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 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.
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.
With syncrepl, a consumer server can create a replica without 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.
With syncrepl, a consumer server can create a replica without
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.
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.
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
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
@ -71,275 +72,277 @@ only briefly. For more information, refer to the Internet Draft
The LDAP Sync protocol supports both polling and listening for
changes by defining two respective synchronization operations:
{{refreshOnly}} and {{refreshAndPersist}}.
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 cause additional entry updates to be sent to the client.
{{refreshOnly}} and {{refreshAndPersist}}. 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 cause additional entry updates to be sent to the
client.
The {{refreshOnly}} operation and the refresh stage of the
{{refreshAndPersist}} operation can be performed with
a present phase or a delete phase.
{{refreshAndPersist}} operation can be performed with 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
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.
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
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.
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 multiple {{EX:entryUUIDs}} in a single
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 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.
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.
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
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.
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.
{{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 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.
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 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.
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
as an overlay on any backend, but works best with the {{back-bdb}} or
{{back-hdb}} backend. The provider can not support refreshAndPersist
mode on {{back-ldbm}} due to limits in that backend's locking architecture.
as an overlay on any backend, but works best with the {{back-bdb}}
or {{back-hdb}} backend. The provider can not support refreshAndPersist
mode on {{back-ldbm}} due to limits in that backend's locking
architecture.
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.
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 shut down. A
checkpoint facility exists to cause the contextCSN to be written
out more frequently if desired.
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.
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.
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 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<rid>,<suffix>}}
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.
<rid> is the replica ID uniquely identifying the replica locally in the
syncrepl consumer server. <rid> is an integer which has no more than
three decimal digits.
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.
It is possible to retrieve the
{{EX:syncConsumerSubentry}} by performing an LDAP search with
the respective entry as the base object and with the base scope.
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
as the search result unless {{ManageDsaIT}} control is provided.
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.
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 and demoting an
{{TERM:LDIF}} file dumped as a backup at the provider.
{{slapadd}} (8) supports the replica promotion and demotion.
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.
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.
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 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.
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 <sid> <size>
> syncprov-sessionlog <size>
directive, where {{<sid>}} is the ID of the per-scope session log
in the provider server and {{<size>}} is the maximum number of
session log entries the session log can record. {{<sid>}}
is an integer no longer than 3 decimal digits. If the consumer
server sends a synchronization cookie containing {{sid=<sid>}}
where {{<sid>}} matches the session log ID specified in the directive,
the LDAP Sync search is to utilize the session log.
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.
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 0 100
> 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.
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
@ -349,54 +352,56 @@ can be defined with any database type.
> scope=sub
> 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
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.
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.
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}},
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).
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}}
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 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.
{{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>}}, {{sid=<sid>}}, and
{{rid=<rid>}}. {{<csn>}} represents the current synchronization state
of the consumer replica. {{<sid>}} is the identity of the per-scope
session log to which this consumer will be associated. {{<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.
Both {{<sid>}} and {{<rid>}} have no more than 3 decimal digits.
The command line cookie overrides the synchronization cookie
stored in the consumer replica database.
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.