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:
- Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
- 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:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open the menu.
- Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
- Select the suffix in the list, and open the Referrals tab.
- Click .
- Fill the fields to create the referral URL.
- Click .
