3.4. Using Referrals
Referrals tell client applications which server to contact for a specific piece of information. This redirection occurs when a client application requests a directory entry that does not exist on the local server or when a database has been taken off-line for maintenance. This section contains the following information about referrals:
Referrals are used to redirect client applications to another server while the current server is unavailable or when the client requests information that is not held on the current server.
For example, starting Directory Server in referral mode while there are configuration changes being made to the Directory Server will refer all clients to another supplier while that server is unavailable. Starting the Directory Server in referral mode is done with the refer command.
Run nsslapd with the refer option.
/usr/sbin/ns-slapd refer -D /usr/lib/dirsrv/slapd-instance_name[-pport] -rreferral_url
/usr/lib/dirsrv/slapd- is the directory where the Directory Server configuration files are. This is the default location on Red Hat Enterprise Linux 5 i386; for the location on other platforms, see Section 1.1, “Directory Server File Locations”.
instance_name
port is the optional port number of the Directory Server to start in referral mode.
referral_url is the referral returned to clients. The format of an LDAP URL is covered in Appendix C, LDAP URLs.
Default referrals are returned to client applications that submit operations on a DN not contained within any of the suffixes maintained by the directory. The following procedures describes setting a default referral for the directory using the console and the command-line utilities.
Set a default referral to the directory, as follows:
In the Directory Server Console, select the Configuration tab.
Select the top entry in the navigation tree in the left pane.
Select the Settings tab in the right pane.
Enter an LDAP URL in the Referrals to text box.
For example:
ldap://directory.example.com:389/dc=example,dc=com
Enter multiple referral URLs separated by spaces and in quotes, as follows:
"ldap://dir1.example.com:389/dc=example,dc=com" "ldap://dir2.example.com/"
For more information about LDAP URLs, see Appendix C, LDAP URLs.
Click OK.
ldapmodify can add a default referral to the cn=config entry in the directory's configuration file. For example, to add a new default referral from one Directory Server, dir1.example.com, to a server named dir2.example.com, add a new line to the cn=config entry.
Run the ldapmodify utility:[2]
ldapmodify -h dir1.example.com -p 389 -D "cn=directory manager" -w secret
ldapmodify binds to the server and prepares it to change an entry in the configuration file.
Add the default referral to the dir2.example.com server:
dn: cn=config changetype: modify replace: nsslapd-referral nsslapd-referral: ldap://dir2.example.com/
After adding the default referral to the cn=config entry of the directory, the directory will return the default referral in response to requests made by client applications. The Directory Server does not need to be restarted.
Smart referrals map a directory entry or directory tree to a specific LDAP URL. Using smart referrals, client applications can be referred to a specific server or a specific entry on a specific server.
For example, a client application requests the directory entry uid=jdoe,ou=people,dc=example,dc=com. A smart referral is returned to the client that points to the entry cn=john doe,o=people,l=europe,dc=example,dc=com on the server directory.europe.example.com.
The way the directory uses smart referrals conforms to the standard specified in RFC 2251 section 4.1.11. The RFC can be downloaded at http://www.ietf.org/rfc/rfc2251.txt.
To configure smart referrals, do the following:
In the Directory Server Console, select the Directory tab.
Browse through the tree in the left navigation pane, and select the entry for which to add the referral.
Right-click the entry, and select Set Smart Referrals.
The Edit Smart Referrals dialog box opens.
Select the Enable Smart Referral option to define smart referrals for the selected entry. (Unchecking the option removes all smart referrals from the entry and deletes the referral object class from the entry.)
In the Enter a new Smart Referral field, enter a referral in the LDAP URL format, and then click Add to add the referral to the list. The LDAP URL must be in the following format:
ldap://hostname:portnumber/[optional_dn]
optional_dn is the explicit DN for the server to return to the requesting client application. For example, this LDAP URL references John Doe's entry:
ldap://directory.example.com:389/cn=john doe,o=people,l=europe,dc=example,dc=com
For the server to use the DN from the original search request instead, enter the LDAP URL in the format:
ldap://hostname:portnumber/
Clicking Construct opens a wizard to direct the process of adding a referral.
To allow a referral to be followed with different authentication, click Authentication, and specify the appropriate DN and password. Keep in mind that this authentication remains valid only until the Console is closed; then it's reset to the same authentication used to log into the Console.
The Smart Referral List lists the referrals currently in place for the selected entry. The entire list of referrals is returned to client applications in response to a request with the Return Referrals for All Operations or Return Referrals for Update Operations options in the Suffix Settings tab, which is available under the Configuration tab.
To modify the list, click Edit to edit the selected referral or Delete to delete the selected referral.
Click OK.
Use the ldapmodify command-line utility[2] to create smart referrals from the command-line.
To create a smart referral, create the relevant directory entry, and add the referral object class. This object class allows a single attribute, ref. The ref attribute must contain an LDAP URL.
For example, add the following to return a smart referral for an existing entry, uid=jdoe:
dn: uid=jdoe,ou=people,dc=example,dc=com objectclass: referral ref: ldap://directory.europe.example.com/cn=john%20doe,ou=people,l=europe,dc=example,dc=com
Any information after a space in an LDAP URL is ignored by the server. For this reason, use %20 instead of spaces in any LDAP URL used as a referral.
To add the entry uid=jdoe,ou=people,dc=example,dc=com with a referral to directory.europe.example.com, include the following in the LDIF file before importing:
dn: uid=jdoe, ou=people,dc=example,dc=com objectclass: top objectclass: person objectclass: organizationalperson objectclass: inetOrgPerson objectclass: referral cn: john doe sn: doe uid: jdoe ref: ldap://directory.europe.example.com/cn=john%20doe,ou=people, l=europe,dc=example,dc=com
Use the -M option with ldapmodify when there is already a referral in the DN path. For information about the ldapmodify utility, see the Directory Server Configuration, Command, and File Reference.
The following procedure describes creating a referral in a suffix. This means that the suffix processes operations using a referral rather than a database or database link.
When a suffix is configured to return referrals, the ACIs contained by the database associated with the suffix are ignored.
To create a suffix referral using the Console, do the following:
Select the Configuration tab.
Under Data in the left pane, click the suffix to which to add a referral.
In the Suffix Settings tab, select one of the following radio buttons:
Return Referrals for all Operations. This means that a referral will be returned when this suffix receives any request from a client application.
Return Referrals for Update Operations. This means a referral will be returned when this suffix receives an update request from a client application. This option is used to redirect update and write requests made by client applications to a read-only database.
Click the Referrals tab. Enter an LDAP URL in the Enter a new referral field, or click Construct to be guided through the creation of an LDAP URL.
For more information about the structure of LDAP URLs, see Appendix C, LDAP URLs.
Click Add to add the referral to the list.
You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.
Click Save.
Add a suffix referral to the root or sub suffix entry in the directory configuration file under the cn=mapping tree,cn=config branch.
Run ldapmodify.[2] For example:
ldapmodify -a -h example.com -p 389 -D "cn=directory manager" -w secret
The ldapmodify utility binds to the server and prepares it to add information to the configuration file.
Add a suffix referral to the ou=people,dc=example,dc=com root suffix, as follows:
dn: cn=ou=people,dc=example,dc=com,cn=mapping tree,cn=config objectclass: extensibleObject objectclasss: nsmappingtree nsslapd-state: referral nsslapd-referral: ldap://zanzibar.com/
The nsslapd-state attribute is set to referral, meaning that a referral is returned for requests made to this suffix. The nsslapd-referral attribute contains the LDAP URL of the referral returned by the suffix, in this case a referral to the zanzibar.com server.
The nsslapd-state attribute can also be set to referral on update. This means that the database is used for all operations except update requests. When a client application makes an update request to a suffix set to referral on update, the client receives a referral.
For more information about the suffix configuration attributes, refer to Table 3.1, “Suffix Attributes”.