19 Managing Knowledge References and Referrals

This chapter explains how to configure knowledge references and referrals.

See Also:

Section 3.10, "Knowledge References and Referrals" for an overview of directory entries, directory information trees, distinguished names, and relative distinguished names

This Chapter contains these topics:

19.1 Introduction to Managing Knowledge References and Referrals

A knowledge reference, also called a referral, is represented in the directory as a particular type of entry. When you create a knowledge reference entry, you associate it with the referral object class the and extensibleObject object class. Typically, you create knowledge reference entries at the place in the DIT where you want to establish the partition.

A knowledge reference provides users with a referral containing an LDAP URL. You enter these URLs as values for the ref attribute. There can be multiple ref attributes specified for any knowledge reference entry. Similarly, there can be multiple knowledge reference entries in the DIT.

See Also:

Chapter 3, "Understanding Oracle Internet Directory Concepts and Architecture" for an overview of directory partitioning and knowledge references and a description of a smart knowledge reference and a default knowledge reference

Referral caching is the process of storing referral information so that it can be easily accessed again and again. Suppose that a client queries Server A, which returns a referral to Server B. The client chases this referral and contacts Server B which performs the operation and returns the results to the client. Without referral caching, the next time the client makes the same query to Server A, the entire procedure is repeated, an unnecessary consumption of time and system resources.

However, if the referral information can be cached, then, in each subsequent query, the referral information can be obtained from cache and Server B can be contacted directly. This speeds up the operation.

Client-side referral caching enables each client to cache this referral information and use it to speed up of referral processing.

Referral entries are stored in a configuration file on the client. When a client establishes a session, it reads the referral information from this configuration file and stores them in a cache. This cache remains static, with no further updates being added during the session. From this point on, for every operation, the client looks up referral information in the cache.

The directory administrator prepares this configuration file for clients to use.


The configuration file is optional for clients. If a file is not present, then client operations involving referrals still behave correctly. Thus it is not mandatory for administrator to prepare this file. The advantage of using the configuration file is that it speeds up the client/server operations involving referrals.

The configuration file consists of one or more referral sets. Each referral set consists of:

  • The host name where a particular directory server is running

  • One or more referral entries residing on that server

Each referral entry consists of a sequence of lines, each of which corresponds to one referral URL. The line separator is CR or LF.

referral_set=hostname       SEP      ref_entry_set   SEP
ref_entry_set=ref_entry     *(SEP    ref_entry)
ref_entry=1*(referralurl    SEP)

For example, consider two referral entries in a directory server running on host serverX:

dn: dc=example, dc=com 
ref: ldap://serverA:3060/dc=example, dc=com 
ref: ldap://serverB:3060/dc=example, dc=com 

dn: dc=oracle, dc=com 
ref: ldap://serverC:3060/dc=oracle, dc=com 
ref: ldap://serverD:3060/dc=oracle, dc=com

Consider the following referral entry in a directory server running on host serverY:-

dn: dc=fiction, dc=com
ref: ldap://serverE:3060/dc=fiction, dc=com 

The corresponding referral.ora file looks like this:

ldap://serverA:3060/dc=example, dc=com
ldap://serverB:3060/dc=example, dc=com

ldap://serverC:3060/dc=oracle, dc=com
ldap://serverD:3060/dc=oracle, dc=com

ldap://serverE:3060/dc=fiction, dc=com

19.2 Configuring Smart Referrals

A search result can contain regular entries along with knowledge references. When a user performs a search operation, Oracle Internet Directory looks for the knowledge reference entry within the specified scope of the search. If it finds the knowledge reference, then Oracle Internet Directory returns a referral to the client.

If a user performs an add, delete, or modify operation on an entry located below the knowledge reference entry, then Oracle Internet Directory returns the referral.

For example, suppose you want to partition the DIT based on the geographical location of the directory servers. In this example, assume that:

  • The c=us naming context is held locally on Server A and Server B in the United States.

  • The c=uk naming context is held locally on Server C and Server D in the United Kingdom.

In this case, you would configure knowledge references between these two naming contexts as follows:

  1. On Server A and B in the United States, configure a knowledge reference for the c=uk object on Server C and Server D:

    dn: c=uk
    c: uk
    ref: ldap://host C:3060/c=uk
    ref: ldap://host D:600/c=uk
    objectclass: top
    objectclass: referral
    objectClass: extensibleObject
  2. Configure a similar knowledge reference on Server C and D in the United Kingdom for the c=us object on Server A and Server B:

    dn: c=us
    c: us
    ref: ldap://host A:4000/c=us
    ref: ldap://host B:5000/c=us
    objectclass: top
    objectclass: referral
    objectClass: extensibleObject

Use the command-line:

ldapmodify -D cn=orcladmin -q -p portNum -h hostname -f ldifFile 


  • A client querying Server A or Server B with base o=foo,c=uk receives a referral.

  • A client querying Server C or Server D with base o=foo,c=us receives a referral.

  • An add operation of o=foo,c=uk on either Server A or Server B fails. Instead, Oracle Internet Directory returns a referral.

19.3 Configuring Default Referrals

Oracle Internet Directory uses the namingcontext attribute in the DSE to determine every directory naming context held locally by the server. Be sure that the namingContext attribute correctly reflects the naming context information.

You specify default referrals by entering a value for the ref attribute in the DSE entry. If the ref attribute is not in the DSE entry, then no default referral is returned.

When configuring a default referral, do not specify the DN in the LDAP URL.

For example, suppose that the DSE entry on Server A contains the following namingContext value:

namingcontext: c=us

Further, suppose that the default referral is:

Ref: ldap://host PQR:3060

Now, suppose that a user enters an operation on Server A that has a base DN in the naming context c=canada, for example:


This user would receive a referral to the host PQR. This is because Server A does not hold the c=canada base DN, and the namingcontext attribute in its DSE does not hold the value c=canada.

See Also:

Section 3.10, "Knowledge References and Referrals" for a conceptual discussion of knowledge references