Directory Server, Version 6.1

---

 

Referrals

Referrals provide a way for servers to refer clients to additional directory servers. A referral specifies the URL of an alternate LDAP server. This alternate server handles any requests for objects that are not found within any of the subtrees of the current LDAP server.

A default referral can be used to point to:

• The immediate parent of this server (in a hierarchy)

• A "more knowledgeable" server, such as the uppermost server in the hierarchy

• A "more knowledgeable" server that possibly serves a disjoint portion of the namespace

With referrals we can:

• Distribute namespace information among multiple servers

• Provide knowledge of where data is located within a set of interrelated servers

• Route client requests to the appropriate server

All supported servers and clients for IBM® Tivoli® Directory Server versions 6.0 and above are enabled to support IPv6 and IPv4 formats. See Appendix E. IPv6 support for information about these two formats.

Some of the advantages of using referrals are the ability to:

• Distribute processing overhead, providing primitive load balancing

• Distribute administration of data along organizational boundaries

• Provide potential for widespread interconnection, beyond an organization's own boundaries

On the Linux®, Solaris, and HP-UX platforms, if a client hangs while chasing referrals, ensure that the environment variable LDAP_LOCK_REC has been set in your system environment. No specific value is required.

set LDAP_LOCK_REC=anyvalue

 

Setting up referrals to other LDAP directories

This section describes how to use the referral object class and the ref attribute to construct entries in an LDAP directory containing references to other LDAP directories. This section also describes how to associate multiple servers using referrals and provides an example.

 

Using the referral object class and the ref attribute

The referral object class and the ref attribute are used to facilitate distributed name resolution or to search across multiple servers. The ref attribute appears in an entry named in the referencing server. The value of the ref attribute points to an entry maintained in the referenced server.

 

Creating entries

Following is an example configuration that illustrates the use of the ref attribute.

Figure 3. Example of using the referral attribute

In the example, Server A holds references to two entries: o=ABC, c=US and o=XYZ, c=US. For the o=ABC, c=US entry, Server A holds a reference to Server B and for the o=XYZ, c=US entry, Server A holds a reference to Server C.

One setup of referrals is to structure the servers into a hierarchy based on the subtrees they manage. Then, provide "forward" referrals from servers that hold higher (closer to the root of the hierarchy) information and set the default referral to point back to its parent server.

 

Associating servers with referrals

To associate servers through referrals:

• Use referral objects to point to other servers for subordinate references.

• Define the default referral to point somewhere else, typically to the parent server.

Referral objects can be seen from command line by specifying the -M option. For more information about the command line utilities see the IBM Tivoli Directory Server version 6.1 Command Reference

Pointing to other servers

Use referral objects to point to the other servers for subordinate references, that is, portions of the namespace below this server that it does not service directly.

Referral objects, like other objects, go in the backend (DB2®). Referral objects consist of:

dn:

Specifies the distinguished name. It is the portion of the namespace served by the referenced server.

objectclass:

Specifies the value of the objectclass "referral".

ref:

Specifies the LDAP Web address of the server. This Web address consists of the ldap:// identifier, the hostname:port, and a DN. The identifier can be either a host name string or a TCP/IP address. The DN requires a slash (/) before it to delimit it from the hostname:port, and should match the DN of the referral object. The DN specified in the value of the referral attribute should match the DN of the referral object. Typically, it is an entry in a naming context at or below the naming context held by the referencing server.

dn:           o=sample
objectclass:  referral
ref:          ldap://9.130.25.51:389/o=sample

 

Binding with a distributed namespace

When performing searches, the same DN that was used to bind or log in to the original server is used to bind to the referred-to server, unless the IBM Directory application is designed to modify the bind DN and credentials. The correct access must be set up for the same DN to be able to bind to both servers for chasing the referrals. See Logging on to the console as the server administrator, a member of an administrative group or an LDAP user for additional information.

 

An example of distributing the namespace through referrals

Following are the steps involved in distributing the namespace using referrals.

1. Plan your namespace hierarchy.

   country - US
   company - IBM, Lotus
   organizationalUnit - IBM Austin, IBM Endicott, IBM HQ

2. Set up multiple servers, each containing portions of the namespace.
   Figure 4. Setting up the servers

   

   Server descriptions:

   Server A

   A server used to locate other servers in the U.S. With no other knowledge, clients can come here first to locate information for anyone in the U.S.

   Server B

   A hub for all data pertaining to IBM in the U.S. Holds all HQ information directly. Holds all knowledge (referrals) of where other IBM data is located.

   Server C

   Holds all IBM Austin information.

   Server D

   Holds all IBM Endicott information.

   Server E

   Holds all Lotus® information.

3. Set up referral objects to point to the descendants in other servers.
   Figure 5. Server A database (LDIF input)

   
   Servers can also define a default referral, which is used to point to a "more knowledgeable" server for anything that is not underneath them in the namespace.

   The default referral LDAP Web address does not include the DN portion.

Following is an arrangement of the same five servers, showing the referral objects in the database as well as the default referrals that are used for superior references.

Figure 6. Referral example summary

 

Creating default referrals

Using the Web Administration Tool is the recommended method to create and remove default referrals.

 

Using Web Administration:

1. If you have not already done so, use the Web Administration Tool to log on to the master server.

2. Add a referral entry by selecting the referral object class from the Structural object classes list on the Select object class panel. See Adding an entry for additional information.

3. On the Required attributes tab, click Manage Referral.

4. On the Manage referral panel, click Add to display the Add referral panel.

   For Admin referrals, the fields related to attributes and filter are not displayed. Admin referrals can be created by adding a referral from the Manage Server Properties panel in the Server Administration category.

5. From the Server hostname:port drop down list, select an LDAP server and port or enter a host name and port number of a server in the field in the hostname:port format.

6. Select Use SSL, if the referral is to a secure (SSL) server.

7. Enter the base DN in the directory information tree in the target server. For example ou=austin,o=sample.

8. Select the attributes you want to include in the referral URL and click Add. To remove an attribute from the referral URL, highlight the attribute in the Selected attributes field and click Remove.

9. Select the scope for the referral search.

   • Select Object to search only within the selected object.

   • Select Single level to search only within the immediate children of the selected object.

   • Select Subtree to search all descendants of the selected entry.

   • Select None to specify no scope.

10. Specify a search filter. See Search filters for more information.

11. Click OK.

12. Repeat these steps for additional referrals.

13. When you are finished, click Next on the Required attributes tab.

14. At the Optional attributes tab enter the values as appropriate for the other attributes.

15. Click Finish to create the entry.

You must restart the server for the changes to take effect.

 

Using the command line:

Define a default referral to reference a directory on another server.

The default referral LDAP URL does not include the DN portion. It includes only the ldap:// identifier and the hostname:port.

For example:

This example is of a local LDAP server on port 389.

idsldapadd -D <adminDN> -w <adminpw> -i <filename>

where <filename> contains:

# referral  
dn: cn=Referral, cn=Configuration
cn: Referral
ibm-slapdReferral: ldap://<additional hostname:port>/<baseDN>?<attributes>?
                   <scope>?<filter>
ibm-slapdReferral: ldap://<additional hostname:port>/<baseDN>?<attributes>?
                   <scope>?<filter>
ibm-slapdReferral: ldap://<additional hostname:port>/<baseDN>?<attributes>?
                   <scope>?<filter>
objectclass: ibm-slapdReferral
objectclass: top
objectclass: ibm-slapdConfigEntry

For example, to set up referrals to two servers, server1 and server2 (a secure server), listening on port 389, with a base of ou=austin,o=sample , with the attributes cn, sn, and description, a scope of base, and a filter of objectclass=*, the LDIF file is :

# referral  
dn: cn=Referral, cn=Configuration
cn: Referral
ibm-slapdreferral: ldap://server1.mycity.mycompany.com:389/
    ou=austin,o=sample?cn,sn,description?base?objectclass=*
ibm-slapdreferral: ldaps://server2.mycity.mycompany.com:389/
    ou=austin,o=sample?cn,sn,description?base?objectclass=*
objectclass: ibm-slapdReferral
objectclass: ibm-slapdConfigEntry
objectclass: top

SeeAppendix E. IPv6 support for more information about supported URL formats.

 

Modifying referrals

To edit a referral, use one of the following methods.

 

Using Web Administration:

1. If you have not already done so, use the Web Administration Tool to log on to the master server.

2. On the Required attributes tab of the Add an entry panel, click Manage Referral.

3. From the Current referrals section, select the referral you want to edit.

4. Click Edit.

5. We can modify the host name and port for the server to which this referral value is pointing.

6. We can modify Use SSL, if the referral is to a secure (SSL) server or not.

7. We can modify the base DN in the directory information tree in the target server. For example ou=austin,o=sample.

8. We can modify the attributes you want to include in the referral URL by adding or removing attributes from the referral URL.

9. We can modify the scope for the referral search.

10. We can modify the search filter. See Search filters for more information.

11. Click OK.

12. Repeat these steps for each referral you want to modify.

You must restart the server for the changes to take effect.

 

Using the command line:

To modify the referral to server1 in order to change the baseDN to ou=raleigh,o=sample, issue the command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=referral, cn= configuration
changetype: modify
replace: ibm-slapdReferral
ibm-slapdreferral: ldap://server1.mycity.mycompany.com:389/
    ou=raleigh,o=sample?cn,sn,description?base?objectclass=*

 

Removing referrals

To remove a referral, use one of the following methods.

 

Using Web Administration:

1. If you have not already done so, use the Web Administration Tool to log on to the master server.

2. Expand the Server Administration category in the navigation area of the Web Administration Tool, select Manage server properties.

3. Click Referrals.

   If you are working in another panel and are adding or modifying an entry that has an attribute that contains referrals we can click Manage referrals to access this panel.

4. From the Current referrals section, select the referral you want to remove.

5. Click Remove.

6. A confirmation panel is displayed. Click OK to remove the referral or click Cancel to return to the previous panel without making any changes.

7. Repeat this process for as many referrals as you want to remove or click Remove all to remove all of the current referrals.

8. When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit, or click Cancel to exit this panel without making any changes.

You must restart the server for the changes to take effect.

 

Using the command line:

To delete a single default referral, for example, austin.ibm.com:389, issue the command:

idsldapmodify -D <adminDN> -w <adminPW> -i <filename>

where <filename> contains:

dn: cn=referral, cn= configuration
changetype: modify
delete: ibm-slapdReferral
ibm-slapdReferral: ldap://referral.austin.ibm.com:389

To delete all default referrals:

idsldapdelete -D <adminDN> -w <adminPW> "cn=referral,cn=configuration"

[ Top of Page | Previous Page | Next Page | Contents | Index ]