6.3. About Knowledge References

After distributing the data over several databases, define the relationship between the distributed data using knowledge references, pointers to directory information held in different databases. The Directory Server provides the following types of knowledge references to help link the distributed data into a single directory tree:
  • Referrals — The server returns a piece of information to the client application indicating that the client application needs to contact another server to fulfill the request.
  • Chaining — The server contacts other servers on behalf of the client application and returns the combined results to the client application when the operation is finished.
The following sections describe and compare these two types of knowledge references in more detail.

6.3.1. Using Referrals

A referral is a piece of information returned by a server that informs a client application which server to contact to proceed with an operation request. This redirection mechanism occurs when a client application requests a directory entry that does not exist on the local server.
Directory Server supports two types of referrals:
  • Default referrals — The directory returns a default referral when a client application presents a DN for which the server does not have a matching suffix. Default referrals are stored in the configuration file of the server. One default referral can be set for the Directory Server and a separate default referral for each database.
    The default referral for each database is done through the suffix configuration information. When the suffix of the database is disabled, configure the directory service to return a default referral to client requests made to that suffix.
    For more information about suffixes, see Section 6.2.2, “About Suffixes”. For information on configuring suffixes, see the Red Hat Directory Server Administration Guide .
  • Smart referrals — Smart referrals are stored on entries within the directory service itself. Smart referrals point to Directory Servers that have knowledge of the subtree whose DN matches the DN of the entry containing the smart referral.
All referrals are returned in the format of an LDAP uniform resource locator, or LDAP URL. The following sections describe the structure of an LDAP referral, and then describe the two referral types supported by Directory Server.

6.3.1.1. The Structure of an LDAP Referral

An LDAP referral contains information in the format of an LDAP URL. An LDAP URL contains the following information:
  • The host name of the server to contact.
  • The port number on the server that is configured to listen for LDAP requests.
  • The base DN (for search operations) or target DN (for add, delete, and modify operations).
For example, a client application searches dc=example,dc=com for entries with a surname value of Jensen. A referral returns the following LDAP URL to the client application: 
ldap://europe.example.com:389/ou=people, l=europe,dc=example,dc=com
This referral instructs the client application to contact the host europe.example.com on port 389 and submit a search using the root suffix ou=people, l=europe,dc=example,dc=com.
The LDAP client application determines how a referral is handled. Some client applications automatically retry the operation on the server to which they have been referred. Other client applications return the referral information to the user. Most LDAP client applications provided by Red Hat Directory Server (such as the command-line utilities) automatically follow the referral. The same bind credentials supplied on the initial directory request are used to access the server.
Most client applications follow a limited number of referrals, or hops. The limit on the number of referrals that are followed reduces the time a client application spends trying to complete a directory lookup request and helps eliminate hung processes caused by circular referral patterns.

6.3.1.2. About Default Referrals

Default referrals are returned to clients when the server or database that was contacted does not contain the requested data.
Directory Server determines whether a default 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 the supported suffixes, the Directory Server returns a default referral.
For example, a directory client requests the following directory entry: uid=bjensen,ou=people,dc=example,dc=com
However, the server only manages entries stored under the dc=europe,dc=example,dc=com suffix. The directory returns a referral to the client that indicates which server to contact for entries stored under the dc=example,dc=com suffix. The client then contacts the appropriate server and resubmits the original request.
Configure the default referral to point to a Directory Server that has more information about the distribution of the directory service. Default referrals for the server are set by the nsslapd-referral attribute. Default referrals for each database in the directory installation are set by the nsslapd-referral attribute in the database entry in the configuration. These attribute values are stored in the dse.ldif file.
For information on configuring default referrals, see the Red Hat Directory Server Administration Guide.

6.3.1.3. Smart Referrals

The Directory Server can also use smart referrals. Smart referrals associate a directory entry or directory tree to a specific LDAP URL. This means that requests can be forwarded to any of the following:
  • The same namespace contained on a different server.
  • Different namespaces on a local server.
  • Different namespaces on the same server.
Unlike default referrals, smart referrals are stored within the directory service itself. For information on configuring and managing smart referrals, see the Red Hat Directory Server Administration Guide.
For example, the directory service for the American office of the Example Corp. contains the ou=people,dc=example,dc=com directory branch point.
Redirect all requests on this branch to the ou=people branch of the European office of Example Corp. by specifying a smart referral on the ou=people entry itself. The smart referral is ldap://europe.example.com:389/ou=people,dc=example,dc=com.
Any requests made to the people branch of the American directory service are redirected to the European directory. This is illustrated below:
Using Smart Referrals to Redirect Requests

Figure 6.7. Using Smart Referrals to Redirect Requests

The same mechanism can be used to redirect queries to a different server that uses a different namespace. For example, an employee working in the Italian office of Example Corp. makes a request to the European directory service for the phone number of an Example Corp. employee in America. The directory service returns the referral ldap://europe.example.com:389/ou=US employees,dc=example,dc=com.
Redirecting a Query to a Different Server and Namespace

Figure 6.8. Redirecting a Query to a Different Server and Namespace

Finally, if multiple suffixes are served on the same server, queries can be redirected from one namespace to another namespace served on the same machine. For example, to redirect all queries on the local machine for o=example,c=us to dc=example,dc=com, then put the smart referral ldap:///dc=example,dc=com on the o=example,c=us entry.
Redirecting a Query from One Namespace to Another Namespace on the Same Server

Figure 6.9. Redirecting a Query from One Namespace to Another Namespace on the Same Server

Note

The third slash in this LDAP URL indicates that the URL points to the same Directory Server.
Creating a referral from one namespace to another works only for clients whose searches are based at that distinguished name. Other kinds of operations, such as searches below ou=people,o=example,c=US, are not performed correctly.
For more information on LDAP URLS and on how to include smart URLs on Directory Server entries, see to the Red Hat Directory Server Administration Guide.

6.3.1.4. Tips for Designing Smart Referrals

Even though smart referrals are easy to implement, consider the following points before using them:
  • Keep the design simple.
    Deploying the directory service using a complex web of referrals makes administration difficult. Overusing smart referrals can also lead to circular referral patterns. For example, a referral points to an LDAP URL, which in turn points to another LDAP URL, and so on until a referral somewhere in the chain points back to the original server. This is illustrated below:
    A Circular Referral Pattern

    Figure 6.10. A Circular Referral Pattern

  • Redirect at major branchpoints.
    Limit referral usage to handle redirection at the suffix level of the directory tree. Smart referrals redirect lookup requests for leaf (non-branch) entries to different servers and DNs. As a result, it is tempting to use smart referrals as an aliasing mechanism, leading to a complex and difficult method to secure directory structure. Limiting referrals to the suffix or major branch points of the directory tree limits the number of referrals that have to be managed, subsequently reducing the directory's administrative overhead.
  • Consider the security implications.
    Access control does not cross referral boundaries. Even if the server where the request originated allows access to an entry, when a smart referral sends a client request to another server, the client application may not be allowed access.
    In addition, the client's credentials need to be available on the server to which the client is referred for client authentication to occur.

6.3.2. Using Chaining

Chaining is a method for relaying requests to another server. This method is implemented through database links. A database link, as described in Section 6.2, “Distributing the Directory Data”, contains no data. Instead, it redirects client application requests to remote servers that contain the data.
During the chaining process, a server receives a request from a client application for data that the server does not contain. Using the database link, the server then contacts other servers on behalf of the client application and returns the results to the client application.
Each database link is associated with a remote server holding data. Configure alternate remote servers containing replicas of the data for the database link to use in the event of a failure. For more information on configuring database links, see the Red Hat Directory Server Administration Guide.
Database links provide the following features:
  • Invisible access to remote data.
    Because the database link resolves client requests, data distribution is completely hidden from the client.
  • Dynamic management.
    A part of the directory service can be added or removed from the system while the entire system remains available to client applications. The database link can temporarily return referrals to the application until entries have been redistributed across the directory service.
    This can also be implemented through the suffix itself, which can return a referral rather than forwarding a client application to the database.
  • Access control.
    The database link impersonates the client application, providing the appropriate authorization identity to the remote server. User impersonation can be disabled on the remote servers when access control evaluation is not required. For more information on configuring database links, see the Red Hat Directory Server Administration Guide.

6.3.3. Deciding Between Referrals and Chaining

Both methods of linking the directory partitions have advantages and disadvantages. The method, or combination of methods, to use depends upon the specific needs of the directory service.
The major difference between the two knowledge references is the location of the intelligence that knows how to locate the distributed information. In a chained system, the intelligence is implemented in the servers. In a system that uses referrals, the intelligence is implemented in the client application.
While chaining reduces client complexity, it does so at the cost of increased server complexity. Chained servers must work with remote servers and send the results to directory clients.
With referrals, the client must handle locating the referral and collating search results. However, referrals offer more flexibility for the writers of client applications and allow developers to provide better feedback to users about the progress of a distributed directory operation.
The following sections describe some of the more specific differences between referrals and chaining in greater detail.

6.3.3.1. Usage Differences

Some client applications do not support referrals. Chaining allows client applications to communicate with a single server and still access the data stored on many servers. Sometimes referrals do not work when a company's network uses proxies. For example, a client application may have permissions to communicate with only one server inside a firewall. If that application is referred to a different server, it is not able to contact it successfully.
A client must also be able to authenticate correctly when using referrals, which means that the servers to which clients are being referred need to contain the client's credentials. With chaining, client authentication takes place only once. Clients do not need to authenticate again on the servers to which their requests are chained.

6.3.3.2. Evaluating Access Controls

Chaining evaluates access controls differently from referrals. With referrals, an entry for the client must exist on all of the target servers. With chaining, the client entry does not need to be on all of the target servers.
Performing Search Requests Using Referrals

The following diagram illustrates a client request to a server using referrals:

Sending a Client Request to a Server Using Referrals

Figure 6.11. Sending a Client Request to a Server Using Referrals

In the illustration above, the client application performs the following steps:
  1. The client application first binds with Server A.
  2. Server A contains an entry for the client that provides a user name and password, so it returns a bind acceptance message. In order for the referral to work, the client entry must be present on server A.
  3. The client application sends the operation request to Server A.
  4. However, Server A does not contain the requested information. Instead, Server A returns a referral to the client application instructing it to contact Server B.
  5. The client application then sends a bind request to Server B. To bind successfully, Server B must also contain an entry for the client application.
  6. The bind is successful, and the client application can now resubmit its search operation to Server B.
This approach requires Server B to have a replicated copy of the client's entry from Server A.
Performing Search Requests Using Chaining

The problem of replicating client entries across servers is resolved using chaining. On a chained system, the search request is forwarded multiple times until there is a response.

Sending a Client Request to a Server Using Chaining

Figure 6.12. Sending a Client Request to a Server Using Chaining

In the illustration above, the following steps are performed:
  1. The client application binds with Server A, and Server A tries to confirm that the user name and password are correct.
  2. Server A does not contain an entry corresponding to the client application. Instead, it contains a database link to Server B, which contains the actual entry of the client. Server A sends a bind request to Server B.
  3. Server B sends an acceptance response to Server A.
  4. Server A then processes the client application's request using the database link. The database link contacts a remote data store located on Server B to process the search operation.
In a chained system, the entry corresponding to the client application does not need to be located on the same server as the data the client requests.
Authenticating a Client and Retrieving Data Using Different Servers

Figure 6.13. Authenticating a Client and Retrieving Data Using Different Servers

In this illustration, the following steps are performed:
  1. The client application binds with Server A, and Server A tries to confirm that the user name and password are correct.
  2. Server A does not contain an entry corresponding to the client application. Instead, it contains a database link to Server B, which contains the actual entry of the client. Server A sends a bind request to Server B.
  3. Server B sends an acceptance response to Server A.
  4. Server A then processes the client application's request using another database link. The database link contacts a remote data store located on Server C to process the search operation.
Unsupported Access Controls

Database links do not support the following access controls:

  • Controls that must access the content of the user entry are not supported when the user entry is located on a different server. This includes access controls based on groups, filters, and roles.
  • Controls based on client IP addresses or DNS domains may be denied. This is because the database link impersonates the client when it contacts remote servers. If the remote database contains IP-based access controls, it evaluates them using the database link's domain rather than the original client domain.