Product SiteDocumentation Site

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:

3.4.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 /usr/lib/dirsrv/slapd-instance_name [-p port] -r referral_url

3.4.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.

3.4.2.1. Setting a Default Referral Using the Console

Set a default referral to the directory, as follows:
  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 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.
  5. Click OK.

3.4.2.2. 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:[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.
  2. 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.

3.4.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.

3.4.3.1. Creating Smart Referrals Using the Directory Server Console

To configure smart referrals, do the following:
  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.
    The Edit Smart Referrals dialog box opens.
  4. 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.)
  5. 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.
  6. 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.
  7. 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.
  8. 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

NOTE

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.

3.4.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 a suffix is configured to return referrals, the ACIs contained by the database associated with the suffix are ignored.

3.4.4.1. Creating Suffix Referrals Using the Console

To create a suffix referral using the Console, do the following:
  1. Select the Configuration tab.
  2. Under Data in the left pane, click the suffix to which to add a referral.
  3. 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.
  4. 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.
  5. 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.
  6. Click Save.

3.4.4.2. 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.
  1. 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.
  2. 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”.