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: Section 2.5.1, "Starting the Server in Referral Mode" Section 2.5.2, "Setting Default Referrals" Section 2.5.3, "Creating Smart Referrals" Section 2.5.4, "Creating Suffix 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. /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: 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 : 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: 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 Database 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 Create Referral . Fill the fields to create the referral URL. Click Create Referral .

Commands:
ns-slapd refer -D /etc/dirsrv/slapd- instance_name [-p port ] -r referral_url
dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-referral="ldap://directory.example.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
dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --add-referral="ldap://directory.example.com/" database_name