LDAPviewer

olcSyncrepl (syncrepl)

Available from version 2.2+. Defines the current database (DIT) as a replica which is kept up-to-date with another DIT content by establishing the current server as a replication consumer running a syncrepl replication engine. The corresponding master (a.k.a provider) is configured with a overlay syncprov entry/directive. The replicated content is kept synchronized to the master content using the LDAP Content Synchronization protocol (RFC 4533, interestingly, still with EXPERIMENTAL status though widely implemented). From 2.4 OpenLDAP now supports both classic Master-Slave and Multi-Master configurations. More information and configuration examples.

Any consumer (slave) can have multiple simultaneous olcSyncrepl/syncrepl connections each described by a separate attribute/directive.

Notes:

  1. While the majority of implementations may use replication for classic operational backup or simple load balancing which generally require complete copies to be maintained, the feature can be used for a variety of functions. For example, it is possible to extract data of a certain type only, say, jpegPhoto (though to create a viable DIT as a minimum objectClass, + and all mandatory attributes for all possible objectClasses would also have to included). Alternatively, in a multi-master environment it is possible to sync only those attributes to selected masters that the user wishes to be updated at those masters (information hiding). Creative readers will undoubtedly find more applications.

  2. When connecting to the provider (the operation defined by olcSynrepl/syncrepl) slapd is acting as a client (not a server) and therefore sources its default parameters from ldap.conf not cn=config (or slapd.conf).

# OLC (cn=config) form
olcSynrepl:

# slapd.conf form
syncrepl 
 [attrs=attr-list]
 [attrsonly]
 [authcid=identity]
 [authzid=identity]
 [binddn=dn]
 [bindmethod=simple|sasl]
 [credentials=passwd]
 [filter=filter-str]
 [interval=dd:hh:mm:ss]
 [keepalive=idle-seconds:probe-number:interval-seconds]
 [logbase=base DN]
 [logfilter=filter str]
 [network-timeout=seconds]
 provider=ldap[s]://hostname[:port]
 [realm=realm]
 [retry=retry-interval num-retries | + ]
 rid=replica-ID 
 [saslmech=mech]
 [schemachecking=on|off]
 [scope=sub|one|base] 
 searchbase=base DN
 [secprops=properties]
 [sizelimit=number-of-entries | 0 (unlimited)]
 [starttls=yes|critical]
 [suffixmassage=rename-dn]
 [syncdata=default|accesslog|changelog]
 [timelimit=seconds | 0 (unlimited)]
 [timeout=seconds]
 [tls_cacert=/path/to/file.ext]
 [tls_certdir=/path/to/directory]
 [tls_cert=/path/to/file.ext]
 [tls_cipher-suite=cipher-list]
 [tls_crlcheck=none|peer|all]
 [tls_key=/path/to/file.ext]
 [tls_protocol_min=major[.minor]]
 [tls_reqcert=allow|demand|try]
 [type=refreshOnly|refreshAndPersist]

Mandatory parameters are rid, provider and searchbase all others are optional.

attrs=attr-list Defines a double-quote enclosed, comma separated list of those attributes that should be replicated. If omitted it defaults to "*,+" (all user and operational attributes) which will yield a useable and exact replica. If the attrs list leaves out any attributes this will result in a, perhaps useable, but incomplete copy of the provider (master). In general, leaving out operational attributes is a bad idea but especially createTimestamp, modifyTimestamp, creatorsName and modifiersName should always be included or simply use +. Note Operational attributes are generally modest in size. Omtting this parameter or defensively defining it with its default value as shown will ensure a fully operational and complete copy of the master:
# starts with comment symbol - indicates explantory text only
# copy all attributes (user and operational) for every objectClass
# if omitted defaults to this value
attrs="*,+"

# @objectClass format
# following will include all user attributes for objectClass
# inetOrgPerson (but not operational attributes)
attrs="@inetOrgPerson"

# create an minimal DIT extract based on inetOrgPerson jpegPhoto
attrs="+,objectclass,sn,cn,jpegPhoto"
In general, only use the attrs, exattrs and attrsoly parameters if you have a very specific or unusual requirement (see Note.
attrsonly If present only the attribute name is syncrohonized not the value. If not present both the attribute name and its value are synchronized.
authcid=identity Only relevant if bindmethod=sasl - defines the authenication identity.
authzid=identity Only relevant if bindmethod=sasl - defines the authorization identity.
binddn=dn The binddn is optional. When present it defines a DN (and typically requires credentials authentication information depending on the bindmethod selected) that will allow access to the searchbase. While it is tempting to use the rootdn of the target DIT this should be avoided whenever possible. The binddn user only requires read (search) permission for the required DIT or DIT fragment being replicated. In general the lowest possible security level DN should be used or a unique ACL created to provide minimal (read) access. If the parameter is omitted an anonymous bind is performed - which is pretty scary.
bindmethod=simple|sasl May take the values simple or sasl. A bindmethod=simple requires the options binddn (quoted string) and credentials. If simple is used then all data, possibly including passwords, are sent in the clear and thus liable to network snooping unless either IPSec or TLS is used. TLS may be invoked either directly by specifying LDAPS in the provider URL, for example, provider=ldaps://ldap.example.com or using startttls=yes or starttls=critical. IPSec would be configured externally and thus be invisible to OpenLDAP configuration. bindmethod=sasl requires the parameter saslmech. Depending on the mechanism, an authentication identity and/or credentials can be specified using authcid and credentials. The authzid parameter may be used to specify an proxy authorization identity. Specific security properties (as the sasl-secprops keyword above) for a SASL bind can be set with the secprops parameter. A non default SASL realm can be set with the realm option.
credentials=secret The credentials parameter is always required with bindmethod=simple if bindmethod=dn is present and, depending on the SASL method, may be required with bindmethod=sasl and defines the password to be used to authenticate when binding to the binddn. The default is CLEARTEXT which will cause the password to be sent in the clear and thus be liable to network snooping unless TLS or IPSec are in use (see bindmethod description for TLS options). Examples:
# send the authentication password in CLEARTEXT
# OLC (cn=config) form
olcSynrepl:
 ...
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...
# slapd.conf form
syncrepl
 ...
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...
 
# send the authentication password over TLS
# OLC (cn=config) form
olcSynrepl:
 ...
 provider=ldaps://ldap.example.com
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...
# slapd.conf form
syncrepl
 ...
 provider=ldaps://ldap.example.com
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...
exattrs=attr-list If the list of attributes that will not be replicated is smaller than that to be replicated the exattrs may offer a quicker way of defining them. The attributes to be replicated are the set defined by attrs minus those defined by exattrs as shown:
# exclude one attribute only
# OLC (cn=config) form
olcSynrepl:
 ...
 attrs="*,+"
 exattrs="jpegPhoto"
 ...
# slapd.conf form
syncrepl
 ...
 attrs="*,+"
 exattrs="jpegPhoto"
 ...
filter=filter-str All synchronization operation are based on a search to the provider. This defines the search filter to be used. If omitted it defaults to (objectClass=*) (a presence filter for the objectClass attribute present in every objectclass therefore every entry) which means sync every entry thus ensuring a complete replica. It can, however, be any valid Filter String if DIT subsets are being replicated thus (objectClass=inetOrgPerson) will only sync entries with the inetOrgPerson objectClass or (mail=*n) will only sync entries that have a mail attribute ending in n or N.
interval=seconds Only relevant with RefreshOnly and defines the time between synchronization processes. May be defined either using dd:hh:mm:ss format or the number of seconds. Thus interval=00:01:00:00 (or interval=3600 using seconds format) will attempt to synchronize every hour. The default is 1 day = 86400 seconds or 1:00:00:00.
keepalive=idle-seconds:probe-number:interval-seconds Synchronization uses a TCP connection. Many TCP implementations provide some form of keepalive mechanism and some allow this behavior to be controlled by applications. The keepalive paramater is only relevant in the later case and allows the user to define the idle-seconds (period in seconds) after which a connection is assumed to be idle and in which probes may be send every interval-seconds. probe-number defines the number of consecutive non-response probes before the connection is closed.
logbase Required only when syncdata=accesslog is used to invoke delta synchronization (explanation and configuration examples) and defines the suffix of the accesslog DIT (it must match the logdb value defined for the overlay accesslog in the provider of the DIT being replicated.
logfilter Required only when syncdata=accesslog is used to invoke delta synchronization (explanation and configuration examples) and defines the search filter used when reading the accesslog. Typical logfilter value when used in delta synchronization operations is:
# OLC (cn=config) form
olcSynrepl:
 ...
 syncdata=accesslog
 logfilter=(&(objectclass=auditWriteObject)(reqResult=0))

# slapd.conf form
syncrepl
 ...
 syncdata=accesslog
 logfilter=(&(objectclass=auditWriteObject)(reqResult=0))

The objectClass auditWriteObject is used to write log entries in the accesslog. The attribute reqResult=0 references the saved operation result code for the operation and the value 0 indicates that only successful operations should be returned in the search.

network-timeout=seconds Defines how long the consumer (slave) will wait to establish a network connection to the provider (master). Once established, the parameter determines how long the consumer will then wait for the initial Bind request to complete. If not defined the value of NETWORK_TIMEOUT in the ldap.conf file is used (its default is 0 or unlimited).
provider=uri Specifies the replication provider site containing the master content as an LDAP URI which has the generic format ldap[s]::/domain-name[:port]. If port is not defined, the standard LDAP (389) or LDAPS (636) port is used.
# non-TLS connection using port 386
# OLC (cn=config) form
olcSynrepl:
 ...
 provider=ldap://ldap.example.com
# optionally use starttls
 starttls=yes
 ...
# slapd.conf form
syncrepl
 ...
 provider=ldap://ldap.example.com
# optionally use starttls
 starttls=yes
 ...
 
# TLS connection using port 636
# OLC (cn=config) form
olcSynrepl:
 ...
 provider=ldaps://ldap.example.com
 # starttls must not be present
 ...
# slapd.conf form
syncrepl
 ...
 provider=ldaps://ldap.example.com
# starttls must not be present
 ...
 
retry=retry-interval num-retries | + If an error occurs during replication (either refreshOnly or refreshAndPersist), the consumer will attempt to reconnect according to the retry parameter which is a list of retry-interval and num-retries pairs. For example, retry="60 10 300 3" directs the consumer to retry every 60 seconds for the first 10 times and then retry every 300 seconds for the next 3 times before it stops retrying. num-retries may be set to '+' in which the consumer will retry indefinitely, thus retry="300 +" will retry every 300 seconds indefinitely.
realm=realm Only relevant if bindmethod=sasl - defines the realm when using Kerberos within SASL.
rid Identifies the current syncrepl directive within the replication consumer server. It is an arbitrary, unique, non-negative integer having no more than three digits. Thus if there is a single olcSyncrepl/syncrepl attribute/directive you could use rid=000 (or rid=001 or any 1 - 3 digit string for that matter), if there are two olcSyncrepl/syncrepl attributes/directives then the first could be rid=000 and the second rid=001 (or rid=17) and so on. Thus, the rid parameter must be unique within this server. There is no relationship between the rid and the olcServerID/ServerID (a.k.a SID) value required in multi-master configurations.
saslmech=mech bindmethod=sasl - defines the SASL mechanism that will be used bfrom the compiled in options in openLDAP.
schemachecking schemachecking performs normal schema checks. The default is off.
scope=sub|one|base Defines the depth of the search and hnce what replication will occur. The default is sub which means all entries in the provider. A scope of one will only replication the seachbase and one level below which, depending on the DIT structure, may provide only a partial replication. A scope of base will only replication the seachbase entry which, depending on the DIT structure, will typically provide only a partial replication.
searchbase The content of the olcSyncrepl/syncrepl replica is defined using a standard LDAP search specification - thus it is possible for a consumer (slave) to replicate the whole or part of any DIT. The consumer server will send search requests to the provider server according to the search specification. The search specification is defined by searchbase (a quoted string), scope (default is sub), filter (default is (objectclass=*)), attrs (default "*,+") as modified by exattrs, sizelimit (default is unlimited), and timelimit (default is unlimited) parameters which have the same meanings as in a normal search specification.
# replicate whole DIT
# OLC (cn=config) form
olcSynrepl:
 ...
 searchbase="dc=example,dc=com"
 ...
# slapd.conf form
syncrepl
 ...
 searchbase="dc=example,dc=com"
 ...
 
# replicate subset of same DIT
# OLC (cn=config) form
olcSynrepl:
 ...
 searchbase="ou=people,dc=example,dc=com"
 ...
# slapd.conf form
syncrepl
 ...
 searchbase="ou=people,dc=example,dc=com"
 ...
secprops=properties Optional. Defines properties for Cyrus SASL and its documentation should be consulted for values.
sizelimit=number-of-entries | 0 (unlimited) Defines the maximum number of entries in each block that will be returned from the search. Multiple reads must be issued to get remaining data. The default is 0 = unlimited.
starttls=yes|critical Specifies use of the StartTLS extended operation to establish a TLS session before binding to the provider. May take the values yes (the connection will continue if the TLS handshake fails) or critical (the connection will be terminated if the TLS handshake fails). This parameter is only required if the provider parameter uses a scheme of ldap, for example, provider=ldap://ldap1.example.com. If the ldaps scheme is used, for example provider=ldaps://ldap1.example.com, the parameter is not required and should be omitted.
suffixmassage=rename-dn Allows the synchronized entries to have their DNs modified. When present that part of the DN on an incoming entry which matches the searchbase will be replaced with rename-DN:
# renames incoming DNs from dc=example,dc=com to dc=example,dc=net
# OLC (cn=config) form
olcSynrepl:
 ...
 searchbase="dc=example,dc=com"
 suffixmassage="dc=example,dc=net"
 ...
# slapd.conf form
syncrepl
 ...
 searchbase="dc=example,dc=com"
 suffixmassage="dc=example,dc=net"
 ...
syncdata

Optional syncdata is used to invoke delta synchronization (explanation and configuration examples) and is used to define the source of the changes to be applied to the replicated DIT. Valid valid values are default (no delta synchronization), changelog (an obsolete format) or accesslog (invoke delta synchronization). The logbase and logfilter parameters must be set appropriately for the log that will be used.

timelimit=seconds | 0 (unlimited) Defines the maximum time allowed for the search before it is deemed to have failed. The default is 0 = unlimited.
timeout=seconds

Optional. Defines the time in seconds after which any non-search operation times out. Value of 0 (default) means no time limit. Default is TIMEOUT in ldap.conf.

When using TLS normally, LDAP Server certificates will be validated against client Trusted Keystores and thus needs to be a globally acceptable, typically commercial, certificate. When operating in a provider/consumer environment this need not be the case since the relationship is peer-to-peer, thus, non-standard certificates (such as self-signed) can be used. The parameter set defined below additionally allows configuration on a connection-by-connection basis. Finally, to reiterate a previous point when acting in a consumer environment slapd is acting as a client and hence ldap.conf values are used as defaults (not cn=config/slapd.conf) if any parameter is undefined.

tls_cacert=/path/to/file

Root certificate/certificate bundle required to validate incoming TLS Server certificates - functional description and default is TLS_CACERT in ldap.conf.

tls_cacertdir=/path/to/directory >Optional. Alternative method defining root certificate - functional description and default is TLS_CACERTDIR in ldap.conf.

tls_cert=/path/to/file.ext

Optional. Only used in mutual authentication and defines the certificate to be sent to the server - functional description and default is TLS_CERT in ldap.conf.

tls_cipher_suite=cipher-spec

Optional. Allows selection of specific cipher suites to override defaults - functional description and default is TLS_CIPHER_SUITE in ldap.conf.

tls_crlcheck=none|peer|all

Optional. Only relevant if OpenLDAP build uses OpenSSL's CRL processing - functional description and default is TLS_CRLCHECK in ldap.conf.

tls_key=/path/to/file.ext

Optional. Only only required if client certificate to be sent (mutual authentication) - functional description and default is TLS_KEY in ldap.conf.

tls_protocol_min=major[.minor]

Optional. Defines the minimum protocol version that the peer must support if < than this version the connection is terminated. Thus, if tls_protocol_min=1.2 is specified and the peer (provider) only supports 1.1 or 1.0 the connection is terminated. If omitted the default is to accept any TLS version offered by the provider.

tls_reqcert=allow|demand|try

Optional. Indicates what will happen f the server fials to send a certiciate or sends an invalid certificate (or one that cannot be validated) - functional description and default is TLS_REQCERT in ldap.conf. Note: The never option of TLS_REQCERT is disalllowed in this parameter.

type The LDAP Content Synchronization protocol supports two operation types. In refreshOnly operation, the synchronization (search) operations are periodically scheduled at an interval. On completion of the synchronization session a syncCookie is returned by the provider and the connection is terminated. Another session is initiated by the consumer after interval time and the last session's syncCookie is provided to scope the changes - essentially only changes since the last session only are provided (if possible). When type is refreshAndPersist, the start of the session is the same as the refreshOnly type but once initial synchronization is completed the connection is maintained and changes (within the synchronization search scope searchbase) are sent from the provider to the consumer as they occur providing almost instantaneous update propagation. When a new replication is initiated there is no syncCookie so the scope of synchronization is the whole search base (typically the whole DIT) and thus permits a new replication to start with an empty consumer DIT. Where large DITs are involved this can take a considerable period of time.

The syncrepl replication mechanism is supported by database backends back-bdb and back-hdb only (2.4.31).

Examples:

The consumer will request updates from the master every 1 hour from master-ldap.example.com (using default port 389). In the event of failure to access the provider (master) the consumer will retry every 5 seconds for 5 attempts and then every 300 seconds (5 minutes) indefinitely. The whole DIT is covered (assuming the master suffix is dc=example,dc=com). All entries are transfered (no filter parameter) and all user and operational attributes (attrs="*,+"). The bind is simple with a cleartext password for cn=admin,ou=people,dc=example,dc=com. More information and configuration examples.

# OLC (cn=config) form
olcSuffix: rid=000 
  provider=ldap://master-ldap.example.com
  type=refreshOnly
  interval=00:1:00:00
  retry="5 5 300 +" 
  searchbase="dc=example,dc=com"
  attrs="*,+"
  bindmethod=simple
  binddn="cn=admin,ou=people,dc=example,dc=com"
  credentials=guess
	
# slapd.conf form
syncrepl rid=000 
  provider=ldap://master-ldap.example.com
  type=refreshOnly
  interval=00:1:00:00
  retry="5 5 300 +" 
  searchbase="dc=example,dc=com"
  attrs="*,+"
  bindmethod=simple
  binddn="cn=admin,ou=people,dc=example,dc=com"
  credentials=guess

© LV Project 2016. Creative Commons Attribution 4.0 International License.