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 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 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 /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 6 (64-bit).
  • 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.

2.5.2. Setting Default Referrals

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. Setting a Default Referral Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Select the top entry in the navigation tree in the left pane.
  3. Select the Settings tab in the right pane.
  4. Enter an LDAP URL for the referral.
    Enter multiple referral URLs separated by spaces and in quotes:
    "ldap://dir1.example.com:389/dc=example,dc=com" "ldap://dir2.example.com/"
    For more information about LDAP URLs, see Appendix C, LDAP URLs. Setting a Default Referral from the Command Line

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.
  1. Run the ldapmodify utility and add the default referral to the dir2.example.com server:
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    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.

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,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. Creating Smart Referrals Using the Directory Server Console

  1. In the Directory Server Console, select the Directory tab.
  2. Browse through the tree in the left navigation pane, and select the entry for which to add the referral.
  3. Right-click the entry, and select Set Smart Referrals.
  4. Select the Enable Smart Referral check box. (Unchecking the option removes all smart referrals from the entry and deletes the referral object class from the entry.)
  5. In the Enter a new Smart Referral field, enter a referral in the LDAP URL format, and then click Add. The LDAP URL must be in the following format:
    server can be the host name, IPv4 address, or IPv6 address for the server. optional_dn is the explicit DN for the server to return to the requesting client application.
    Construct opens a wizard to direct the process of adding a referral.
    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.
  6. To set the referral to use different authentication credentials, click Authentication, and specify the appropriate DN and password. This authentication remains valid only until the Console is closed; then it is reset to the same authentication used to log into the Console. Creating Smart Referrals from the Command Line

Use the ldapmodify command-line utility 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 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.


When a suffix is configured to return referrals, the ACIs contained by the database associated with the suffix are ignored. Creating Suffix Referrals Using the Console

Referrals can be used to point a client application temporarily to a different server. For example, adding a referral to a suffix so that the suffix points to a different server allows the database associated with the suffix is taken off-line for maintenance without affecting the users of the Directory Server database.
To set referrals in a suffix:
  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left pane, select the suffix for which to add a referral.
  3. Click the Suffix Settings tab, and select the Return Referrals for ... Operations radio button.
    Selecting Return Referrals for Update Operations means that the directory redirects only update and write requests to a read-only database. For example, there may be a local copy of directory data, and that data should be available for searches but not for updates, so it is replicated across several servers. Enabling referrals for that Directory Server only for update requests means that when a client asks to update an entry, the client is referred to the server that owns the data, where the modification request can proceed.
  4. Click the Referrals tab. Enter an LDAP URL in the[1] in the Enter a new referral field, or click Construct to create an LDAP URL.
  5. Click Add to add the referral to the list.
    You can enter multiple referrals. The directory returns the entire list of referrals in response to requests from client applications. Creating Suffix Referrals from the Command Line

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 and add a suffix referral to the ou=people,dc=example,dc=com root suffix:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
dn: cn=ou=people,dc=example,dc=com,cn=mapping tree,cn=config
changetype: add
objectclass: extensibleObject
objectclass: 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, see Table 2.1, “Suffix Attributes”.

[1] Appendix C, LDAP URLs has more information about the structure of LDAP URLs.