You can use referrals to extend your directory service beyond a single server configuration. This chapter describes how you can use referrals for your directory service. This chapter contains information about referrals in the following sections:
"Understanding Referrals"
"Setting Default Referral URLs"
"Creating and Changing Smart Referrals"
In a replicated environment, the client attempts to modify an entry that is not mastered on the local server. That is, some other directory server supplies the entry to the local server. In this case, the consumer server returns a referral to the client that indicates which server mastered the entry. The client can then follow the referral to the supplier server and attempt the modification operation there.
If the client requests a directory entry that cannot reside on the local server, then the local server returns a referral based on the value of the slapd.conf Referral parameter. The directory server determines whether this kind of a referral should be returned by comparing the DN of the requested directory object against the directory suffixes supported by the local server. If the DN does not match any of the supported suffixes, the directory server returns a referral. You can manage this default referral mechanism from the Server Console. See "Setting Default Referral URLs" for more information.
You can manage this default referral mechanism from the Server Console. See "Setting Default Referral URLs" for more information.
If the client searches an entry, or tries to modify an entry, that contains a smart referral, then a referral is returned based on the LDAP URL contained in the smart referral. See "Creating and Changing Smart Referrals" for information.
For more information on how referrals are used by LDAP clients and servers, and for information on the reasons why you might want to use referrals, see the Planning Referrals chapter in the Netscape Directory Server Deployment Manual.
On the Directory Server Console, select the Configuration tab.
Select the root entry in the navigation tree in the left pane.
Select the Settings tab in the right pane.
Enter an LDAP URL in the "Referrals to" text box and click OK. For example: ldap://directory.airius.com:389/o=airius.com You can enter multiple referral URLs separated by spaces and in quotes as follows: "ldap://dir1.airius.com:389/o=airius.com" "ldap://dir2.airius.com:389/"
ldap://directory.airius.com:389/o=airius.com
You can enter multiple referral URLs separated by spaces and in quotes as follows:
Keep in mind that all special characters within a DN must be properly escaped. Commas must be escaped by two backslashes (\\). For example, if the DN includes o=Airius Bolivia, S.A., then the corresponding DN must be o=airius bolivia\\, S.A.
Keep in mind that all special characters within a DN must be properly escaped. Commas must be escaped by two backslashes (\\). For example, if the DN includes o=Airius Bolivia, S.A., then the corresponding DN must be
o=airius bolivia\\, S.A.
You create and manage smart referrals through the Directory Server Console (See "Creating Smart Referrals Using the Directory Server Console" for information) or by using ldapmodify (See "Creating Smart Referrals From the Command-line" for information.)
Creating Smart Referrals Using the Directory Server Console
To add a smart referral to an existing entry from the Directory Server Console:
On the Directory Server Console, select the Directory tab.
Browse through the tree in the navigation pane and select the entry for which you want to add the referral.
Right-click the entry and select Open from the pop-up menu. A dialog box or editor that allows you to change the properties of that entry appears. If you selected a person, group, or organizational unit entry, the Edit Entry dialog box appears. Click Advanced. The property editor dialog box appears containing the object class and attribute values for the entry. Figure 14.1 Edit Entry (Property Editor) dialog box
If you selected a person, group, or organizational unit entry, the Edit Entry dialog box appears. Click Advanced.
The property editor dialog box appears containing the object class and attribute values for the entry.
Figure 14.1 Edit Entry (Property Editor) dialog box
Right click the cell containing the attribute "Object class" and select Add Value from the pop-up menu. The Add Object Class dialog box displays.
The Add Object Class dialog box displays.
Select referral in the dialog box and click OK.
Select Show All Attributes from the View menu.
Scroll down the list of attributes to the ref attribute.
Enter the LDAP URL to which you want to refer queries about this entry in the format ldap://servername:portnumber/[optional_dn] in the ref text box. For example, ldap://directory.airius.com:389/cn=csarette,ou=people,o=airius.com
Where [optional_dn] is an explicitly specified DN you want the server to return to the requesting client. If you want the server to use the DN from the original search request instead, enter the LDAP URL in the format: ldap://servername:portnumber Do not include a trailing slash "/" after the URL. For more information on how the server handles referrals and in particular DNs in referrals, see the Netscape Directory Server Deployment Manual.
Where [optional_dn] is an explicitly specified DN you want the server to return to the requesting client. If you want the server to use the DN from the original search request instead, enter the LDAP URL in the format:
ldap://servername:portnumber
Do not include a trailing slash "/" after the URL. For more information on how the server handles referrals and in particular DNs in referrals, see the Netscape Directory Server Deployment Manual.
Click OK.
You use the ldapmodify command-line utility to create smart referrals from the command-line. (For more specific information about ldapmodify, see "Adding and Modifying Entries Using ldapmodify").
To create a smart referral, create the relevant directory entry and add the Referral object class. (See "Managing Entries Using the Command-Line Utilities" for information.) This object class allows a single attribute: ref. The ref attribute is expected to contain an LDAP URL.
For example, to return a smart referral for the existing entry uid=bjensen, ou=people, o=airius.com, add the following information to the entry:
objectclass: referral ref: ldap://directory.europe.airius.com/cn=babs%20jensen,ou=people,l=europe, o=airius.com
Note. Any information after a space in an LDAP URLs is ignored by the server. For this reason, you must use %20 instead of spaces in any LDAP URL you intend to use as a referral.
To add the entry uid=ssarette, ou=people, o=airius.com with a referral to directory.europe.airius.com, you would include the following in your LDIF file before importing:
dn: uid=ssarette, ou=people, o=airius.com objectclass: top objectclass: person objectclass: organizationalperson objectclass: inetOrgPerson objectclass: referral cn: somi sarette sn: sarette uid: ssarette ref: ldap://directory.europe.airius.com/cn=somi%20sarette,ou=people,l=europe,o=airius.com
Use the -M parameter with ldapmodify to cause the server to not return the smart referral, but treat the entry as a regular entry. For information on the -M parameter, see "Additional ldapmodify Parameters".
For more information on smart referrals, see Chapter 8 of the Netscape Directory Server Deployment Manual. For information on creating entries, see Chapter 9, "Managing Directory Entries," and for information on LDAP URLs, see Appendix A, "LDAP URLs."
Previous
