Setting Referrals

You can use referrals to tell client applications which server to contact if the information is not available locally. Referrals are pointers to a remote suffix or entry that Directory Server returns to the client, in place of a result. The client must then perform the operation again on the remote server named in the referral.

Redirection occurs in three cases:

• When a client application requests an entry that does not exist on the local server, and the server has been configured to return the default referral.

• When an entire suffix has been disabled for maintenance or security reasons.

  The server will return the referrals defined by that suffix. The suffix-level referrals are described in Setting Referrals and Making a Suffix Read-Only. Read-only replicas of a suffix also return referrals to the master servers when a client requests a write operation.

• When a client specifically accesses a smart referral.

  A smart referral is an entry that you create. The server will return the referral that the smart referral defines.

In all cases, a referral is an LDAP URL that contains the host name, port number, and optionally a DN on another server. For example, ldap://east.example.com:389.

For conceptual information about how you can use referrals in your directory deployment, see the Oracle Directory Server Enterprise Edition Deployment Planning Guide.

The following sections describe the procedures for setting your directory’s default referrals and for creating and defining smart referrals.

Setting the Default Referrals

Default referrals are returned to client applications that submit operations on a DN that is not contained on a suffix maintained by your Directory Server. The server will return all referrals that are defined, but the order in which they are returned is not defined.

To Set a Default Referral

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

• Use the dsconf command-line utility to set one or more default referrals.

  $ dsconf set-server-prop -h host -p port suffix-DN referral-url:referral-URL

  For example:

  $ dsconf set-server-prop -h host1 -p 1389 dc=example,dc=com \
   referral-url:ldap://east.example.com:1389

Setting Smart Referrals

Smart referrals allow you to map a directory entry or a directory tree to a specific LDAP URL. Using smart referrals, you can refer client applications to a specific server or to a specific entry on a specific server.

Often, a smart referral points to an actual entry with the same DN on another server. However, you may define the smart referral to any entry on the same server or on a different server. For example, you can define the entry with the following DN to be a smart referral:

uid=bjensen,ou=People,dc=example,dc=com

The smart referral points to another entry on the server east.example.com:

cn=Babs Jensen,ou=Sales,o=east,dc=example,dc=com

The way the directory uses smart referrals conforms to the standard specified in section 4.1.10 of RFC 4511 (http://www.ietf.org/rfc/rfc4511.txt).

To Create and Modify a Smart Referral

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. To create a smart referral, create an entry with referral and extensibleObject object classes.

   The referral object class allows the ref attribute that is expected to contain an LDAP URL. The extensibleObject object class allows you to use any schema attribute as the naming attribute, in order to match the target entry.

   For example, to define the following entry to return a smart referral instead of the entry uid=bjensen, use this command:

   $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
   Enter bind password:
   dn: uid=bjensen,ou=People,dc=example,dc=com
   objectclass: top
   objectclass: extensibleObject
   objectclass: referral
   uid: bjensen
   ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Sales,o=east,dc=example,dc=com

   ---

   Note - Any information after a space in an LDAP URL is ignored by the server. Thus, you must use %20 instead of spaces in any LDAP URL that you intend to use as a referral. Other special characters must be escaped.

   ---

   After you have defined the smart referral, modifications to the uid=bjensen entry will actually be performed on the cn=Babs Jensen entry on the other server. The ldapmodify command will automatically follow the referral, for example:

   $ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
   Enter bind password:
   dn: uid=bjensen,ou=People,dc=example,dc=com
   changetype: replace
   replace: telephoneNumber
   telephoneNumber: (408) 555-1234

2. (Optional) To modify the smart referral entry, use the -M option of ldapmodify:

   $ ldapmodify -M -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
   Enter bind password:
   dn: uid=bjensen,ou=People,dc=example,dc=com
   changetype: replace
   replace: ref
   ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Marketing,o=east,dc=example,dc=com