Chapter 7 Referrals, Aliases & Proxies (Chaining)

7.3 Referrals

Referral is the process by which an LDAP server, instead of returning a result will return a reference (a referral) to another LDAP server which may contain further information. A referral may be viewed as an inter-LDAP Server (DIT) jump. OpenLDAP documentation confusingly uses the terms superior and subordinate in the context of referrals. The conditions under which OpenLDAP will return a referral are:

Using a generic referral returned where the DN of a search filter does not exist in any suffix of the LDAP server. This feature is configured using olcReferral/referral in the global entry cn=config (OLC) or the global section of slapd.conf. More Info.
If a client attempts to update a slave (or consumer) DIT the server can be configured to return a referral using olcUpdateref/updateref in the database entry (OLC) or the database section of slapd.conf. More Info.
Use of the referral ObjectClass within a DIT. This allows for delegation of responsibity for parts of an LDAP system to one or more LDAP systems. More Info.

By default it is the LDAP client (LDAP browser or utility) which follows referrals. Optionally it is possible to configure OpenLDAP servers to follow (or chase) referral objectclass definitions rather than simply returning a referral. This feature uses the chain overlay. More Info.

7.3.1 Generic Referrals

If an LDAP client issues a request to an LDAP server with an invalid DN (the base of the DN does not exist in any suffix directive for the server) then it will return an error. The server can be configured to return a referral (an LDAP URI) to one or more servers which may be able to provide further services. This feature is defined using olcReferral/referral in the global section of cn=config or slapd.conf as shown in the following examples:

# olc cn=config or sladp.conf
# global section
...
# if the server receives a search for a DN
# which does not exist in any olcSuffix/suffix 
# for any database section it will return both LDAP URI's
# in this example case if a search DN does not terminate
# with dc=example,dc=net 

# OLC (cn=config entry)
olcReferral: ldap://ldap-master.example.com
olcReferral: ldap://ldap-services.example.com:10389

# assume a DIT definition 
# OLC olcDatabase={X}zzz,cn=config child entry with
olcSuffix: dc=example,dc=net


# slapd.conf file
referral ldap://ldap-master.example.com
referral ldap://ldap-services.example.com:10389
# databases section(s)
database bdb
...
suffix "dc=example,dc=net"
...

7.3.2 Slave (Consumer) Modify Referrals

If an LDAP client issues a write (modify) request to a syncrepl consumer (in master/slave configuration) it will be rejected. The server may be configured to supply a referral (an LDAP URI) that would typically point to the replication master or provider using the olcUpdateref/updateref as shown in the following example:

# OLC
# olcDatabase={X}zzz,cn=config
olcSyncrepl: ....
# refer to provider
olcUpdateref: ldap://ldap-master.example.com


# slapd.conf slave or consumer
...
# database section(s)
database bdb
...

# syncrepl directive
syncrepl ....
# refer to the DIT master (provider) server
updateref ldap://ldap-master.example.com
...

7.3.3 Referral Objects

Referrals may be explicitly defined in a DIT using the referral ObjectClass. This object class takes a single ref attribute (an LDAP URI).

To illustrate this process assume Figure 7.4-1 illustrates a delegated or referral based LDAP system:

Figure 7.3-1 - Referrals to LDAP2 and LDAP3

To define the referral in LDAP1 -> LDAP2 the following LDIF definition is used:

# definition creates o=grommets RDN
# and refers it to ldap2

dn: o=grommets,dc=example,dc=com
objectClass: referral
objectClass: extensibleObject
o: grommets
ref: ldap://ldap2.example.com/o=grommets,dc=example,dc=net

Notes:

The extensibleObject objectClass allows any attribute (in this case o (organizationName)) to be added to the referral objectClass.
A referral to LDAP2 will be returned (or followed) if LDAP1.example.com receives a search DN for:
```
cn=cheri,ou=uk,o=grommets,dc=example,dc=com
```

To define the referral LDAP2 -> LDAP3 the following LDIF definition is used:

# an organizationalUnit objectClass (entry) with an 
# attribute of organizationName (o) of grommets must be 
# defined in this server
# or the LDAP2 suffix is defined as o=grommets,dc=examnple,dc=com

# definition creates ou=uk RDN
# and refers it to ldap3

dn: ou=uk,o=grommets,dc=example,dc=com
objectClass: referral
objectClass: extensibleObject
ou: uk
ref: ldap://ldap3.example.com/ou=uk,o=grommets,dc=example,dc=net

Notes:

The extensibleObject objectClass allows any attribute (in this case o (organizationName) to be added to the referral objectClass.
A referral to LDAP2 will be returned (or followed) if LDAP2.example.com receives a search DN for:
```
cn=cheri,ou=uk,o=grommets,dc=example,dc=com
```

7.3.4 Deleting Referrals

Deleting referrals is a little tricky when using standard utilities such as ldapmodify. Recall that LDAP clients always follow referrals thus, when searching for the referral item to delete (or modify), the LDAP server detects the referral objectClass and immediately sends the referral which is then followed by the client - resulting in the referral entry not being found. In order to suppress this automatic referral behaviour in the LDAP server the client must use the Manage DSA IT control (OID 2.16.840.1.113730.3.4.2 defined in RFC 3296). In the case of ldapmodify the -M argument must be used to send this control when attempting to delete or modify a referral entry.

7.3.5 Referral Chaining & Proxies

In the normal case if an LDAP server encounters a referral object on the search path it will return a referral to the LDAP client. However, the server may be configured to follow (or chase) referrals and return a complete result to the user. This process is frequently called chaining and is configured in the server through the use of the chain overlay. Figure 7.4-2 show chaining and referral:

Figure 7.3-2 - Chaining to LDAP2 and LDAP3

The following example illustrates the configuration required at LDAP1 to chain (or follow) the two referrals shown in Figure 7.4-2: Full configuration information about the chain overlay).



# sladp.conf 
# global section
...
# generic referral for invalid DN cases
referral ldap:ldap-master.example.com
...
# databases section(s)
database bdb
...
suffix "dc=example,dc=com"
...

overlay chain
# allow two referrals - one in this DIT 
# and a second in the referral DIT
chain-max-depth 2
# return a referral in the case of an error
chain-return-error FALSE


overlay	chain
chain-uri "ldap://ldap2.example.com"
chain-rebind-as-user yes
chain-idassert-bind bindmethod="simple"
 binddn="cn=admin,dc=example,dc=com"
 credentials="secret"
 mode="self"
chain-uri "ldap://ldap3.example.com"
chain-rebind-as-user yes
chain-idassert-bind bindmethod="simple"
 binddn="cn=admin,dc=example,dc=com"
 credentials="secret"
 mode="self"

7.4 Aliases

An LDAP Alias (defined in RFC 4512) uses the STRUCTURAL objectClass alias to define the position within the current DIT and the attribute aliasedObjectName to define the DN of the entry that contains the information. The LDAP server automatically dereferences the alias and returns the entry pointed to by aliasedObjectName. The alias may be viewed as an intra-LDAP Server jump since its dereferencing uses only a DN (unlike the Referral objectclass which uses an LDAP URI). Aliases are defined as shown below:

# example 1
# classic Alias two names map to a single entry
# uses a single DIT (suffix dc=example,dc=com)
# tango music lovers would be outraged by this aliasing

dn: ou=candombe,ou=tango,dc=example,dc=com
objectClass: alias
objectClass: extensibleObject
ou: candombe
aliasedObjectName: ou=milonga,ou=tango,dc=example,dc=com

# data from ou=milonga,ou=tango,dc=example,dc=com is returned when
# ou=candombe,ou=tango,dc=example,dc=com is referenced

# example 2
# substitution of one DN with another DN
# following, say, a takeover of one company be another
# assumes both DITs on the server (dc=example,dc=de and dc=example,dc=kr)

dn: uid=jschmidt,ou=people,dc=example,dc=de
objectClass: alias
objectClass: extensibleObject
uid: jschmidt
aliasedObjectName: uid=jschmidt,ou=people,dc=example,dc=kr

# data from uid=jschmidt,ou=people,dc=example,dc=kr is returned when
# uid=jschmidt,ou=people,dc=example,dc=de is referenced

Notes:

The extensibleObject objectClass allows any attribute (in the first example ou (organizationalUnitName) in the second example uid) to be added to the alias objectClass.
The aliasedObjectName essentially repositions the LDAP server. Thus, in the first example above if the entry cn=Siga El Baile,ou=candombe,ou=tango,dc=example,dc=com was requested then the entry cn=Siga El Baile,ou=milonga,ou=tango,dc=example,dc=com would be returned.
Unlike Referrals, no special action is required to delete entries which use the alias objectClass, that is, when a delete operation is performed the LDAP server automatically inhibits dereferencing.

7.5 LDAP Proxy & Chaining

One day real soon now ™

7.6 Historical Information Only

OpenLDAP Slurpd Style Replication (Obsoleted in 2.4)

This information describes slurpd style replication which was obsoleted in OpenLDAP 2.4. It is of historical interest and is maintained for those users (pre OpenLDAP 2.4) who may have legacy operational systems.

Slurpd style replication used a 'push' replication strategy and is obsoleted from version 2.4. Documentation is maintained here for historical reasons and for anyone marooned on older versions of OpenLDAP. It is configured and controlled as shown in Figure 7.2-1:

7.5-1 Slurpd Style Replication

When slapd (1) running the Master DIT (7) receives a modify operation (9) it updates the DIT and a timestamped copy of the transaction is written to the log file (2) defined in the master's slapd.conf (5) file replogfile directive.

Slurpd (3) when initially loaded obtains its operational parameters from slapd.conf (5). At a periodic time defined by replicationinterval slurpd will read the log file (2) defined by the replogfile directive and write the updates (10) to one (or more) slave DITs (8) defined by the replica directive(s) in slapd.conf (5).

The slave DIT (8) is a read only copy for all clients except a client which binds using the DN defined by updatedn. The slave server (4) returns the LDAP URI defined by updateref to all modify operations from clients (except those initiated using the DN in updatedn). Both updatedn and updateref are defined in the slapd.conf (6) file. The DN defined in updatedn in (6) MUST be the same as that defined in the replica directive (binddn= parameter) in (5) for this slave instance.

7.6.1 Slurpd Replication Errors (Obsoleted in 2.4)

If slurpd (3) fails to update the slave instance it creates a REJECTION file whose name is the same as that defined in the replogfile directive with .rej appended as shown below:

# slapd.conf reploglogfile directive
replogfile /var/log/ldap/slave1.log

# REJECTION file will be named
# /var/log/ldap/slave1.log.rej

Each error message in the REJECTION log file is the same as that used in the normal transaction log but is preceded by a line starting with the keyword ERROR containing the error message. An example is shown below:

ERROR: No such attribute
replica: slave1.example.com:389
time: 809618633
dn: uid=rsmith,dc=example,dc=com
changetype: modify
replace: description
description: clown
-
replace: modifiersName
modifiersName: uid=rsmith,dc=example,dc=com
-
replace: modifyTimestamp
modifyTimestamp: 20000805073308Z

To fix the errors either the slave may edited (in the case above to add a description attribute to the entry) or the REJECTION log may be edited to correct the errors (in the above example the replace: description line could be changed to add: description). There is no need to remove lines beginning with ERROR since these are ignored. After appropriate remedial action the REJECTION file may be re-applied by running slurpd in a single-shot mode (after stopping any currently running slurpd) using the following command:

slurpd -o -r /var/log/ldap/slave1.log.rej

# where -r defines the path to the REJECTION file 
# and -o indicates single-shot mode

Slurpd will apply the transactions in the defined (-r) file and exit. The normal slurpd should now be restarted.

Slurpd Configuration Examples:

Master slapd.conf configuration:

# slapd master
# global section - check file every 5 minutes
replicationinterval 300

# database section
database bdb
...
# simple security to slave located at ldap-rep1.example.com 
# with a cleartext password
# directive only used by slurpd
replica uri=ldap://ldap-rep1.example.com bindmethod=simple
  binddn="uid=admin,ou=admin,dc=example,dc=com" credentials=guess
	
# saves changes to specfied file
# directive used by both slapd and slurpd
replogfile /var/log/ldap/slavedit.log

Slave slapd.conf configuration (on host ldap-rep1.example.com):

# slapd slave
# global section - check file every 5 minutes


# database section
database bdb
...

# defines the dn that is used in the
# replica directive of the master
# directive only used by slurpd
updatedn "uid=admin,ou=admin,dc=example,dc=com"
	
# referral given if a client tries to update slave
updateref ldap://master-ldap.example.com

7.6.2 Syncing DIT before Slurpd Replication

Before slurpd replication can occur the DITs (Master and Slave(s)) must be known to be in the same state. A manual synchronization process must be performed first as itemised below:

Note: Slurpd was obsoleted in OpenLDAP 2.3 and is included here for completeness. In the case of OpenLDAP using syncrepl style replication a slave or multi-master can synchronize starting from an empty DIT. However, the process defined below may also be used and depending on the volumes involved may offer a more efficient (quicker) starting point.

Stop the LDAP server that will contain the master DIT instance. This is essential to prevent further DIT updates.
Create an LDIF copy of the DIT to be replicated using the appropriate off-line tools for the LDAP server.

(For OpenLDAP use slapcat).
Configure the server running the master DIT instance.

For OpenLDAP using slurp style replication - add the replica, replogfile and replicationinterval directives to the slapd.conf file. Do not restart the server at this time.

Note: If running OpenLDAP using the on-line configuration feature (cn=config) the server must be active.
Move the LDIF file created in step 2 above to the the server(s) that will run the slave or multi-master (applies to sysncrepl only) instance.
Stop the LDAP server that will run the slave or multi-master (applies to syncrepl only) instance .
Apply the LDIF file moved in step 4 to the server using the appropriate off-line tools for the LDAP server.

(For OpenLDAP use slapadd). Since the server has not been configured the -n (dbnum) option should be used.
Configure the server that will run the slave or multi-master (applies to syncrepl only) instance to act as either a slave or a multi-master (applies to syncrepl only).

For OpenLDAP using slurpd style replication only this will involve defining a database directive and all its associated directives (since the -n dbnum directive was used to add the DIT the order in which this is defined is very important - for replication specifically add the updatedn directive and the updateref directives.

Note: If running OpenLDAP using the run-time configuration feature (cn=config) the server must be active.
If a master-slave configuration, start the server running the slave DIT instance. Confirm it is working. If a multi-master configuration (applies to sysncrepl only) start this copy of the master and confirm it is running.
Start the server running the master instance of the DIT or the second master in a multi-master configuration (applies to sysncrepl only).
Perform a test transaction on the master (or one of the masters in a multi-master configuration - syncrepl only) and confirm it has been propagated to the slave (or second master - syncrepl only). If not, start looking at the logs. And panic. Always helps.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.