2.5. 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:
For conceptual information on how to use referrals in the directory, see the Red Hat Directory Server Deployment Guide.

2.5.1. Starting the Server in Referral Mode

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 Directory Server will refer all clients to another supplier while that server is unavailable. Starting Directory Server in referral mode is done with the refer command.
Run nsslapd with the refer option. 
# ns-slapd refer -D /etc/dirsrv/slapd-instance_name [-p port] -r referral_url
  • /etc/dirsrv/slapd-instance_name/ is the directory where the Directory Server configuration files are. This is the default location on Red Hat Enterprise Linux.
  • port is the optional port number of 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.

2.5.2. Setting Default Referrals

Directory Server returns default referrals to client applications that submit operations on a DN not contained within any of the suffixes maintained by the directory. The following procedures describe setting a default referral for the directory using the command line.

2.5.2.1. Setting a Default Referral Using the Command Line

Use the dsconf config replace command, to set the default referral in the nsslapd-referral parameter. For example, to set ldap://directory.example.com/ as the default referral: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-referral="ldap://directory.example.com/"

2.5.3. Creating Smart Referrals

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,ou=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.

2.5.3.1. Creating Smart Referrals Using the Command Line

To create a smart referral, create the relevant directory entry with the referral object class and set the ref attribute to the referral LDAP URL.
For example, to create a smart referral named uid=user,ou=people,dc=example,dc=com that refers to ldap://directory.europe.example.com/cn=user,ou=people,ou=europe,dc=example,dc=com: 
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server2.example.com -x
dn: uid=user,ou=people,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: referral
sn: user
uid: user
cn: user
ref: ldap://directory.europe.example.com/cn=user,ou=people,ou=europe,dc=example,dc=com

Note

Directory Server ignores any information after a space in an LDAP URL. For this reason, use %20 instead of spaces in LDAP URLs used as a referral.
Use the -M option with ldapadd if there is already a referral in the DN path. For more information on smart referrals, see the Directory Server Deployment Guide.

2.5.4. Creating Suffix Referrals

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.

Warning

When you configure a suffix to return referrals, the ACIs contained in the database associated with the suffix are ignored. In addition, creating suffix referrals applies only to non-replicated suffixes.

2.5.4.1. Creating Suffix Referrals Using the Command Line

To create a suffix referral:
  1. Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. Add the referral to the suffix. For example: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --add-referral="ldap://directory.example.com/" database_name

2.5.4.2. Creating Suffix Referrals Using the Web Console

To create a suffix referral:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
  5. Select the suffix in the list, and open the Referrals tab.
  6. Click Create Referral.
  7. Fill the fields to create the referral URL.
  8. Click Create Referral.