The current LDAP protocol specification does not include a way for servers to refer clients to additional directory servers. The assumption is that a client only needs to connect to one LDAP server and that server will do all of the work necessary to complete a request, possible including connecting to several other servers on the client's behalf. In the University of Michigan's LDAP 3.2 and later releases, support for referrals is included in both the LDAP client library and in the slapd server. This document describes why and how we implemented referrals. All implementation specific information is for the U-M LDAP 3.3 release.
See the LDAP Home Page for general information about LDAP.
There are several reasons why we thought it would be useful to add referrals to LDAP:
Some people have argued that it is better to keep all of the complexity in the server, since there will be many more clients than servers. The other side of this argument is the loss of flexibility for the client. It is hard to argue with the success of a referral-based model, since that is the model on which HTTP and the Web are based.
It is also worth noting that adding referrals to LDAP does not mean that they must always be used: servers do not have to return referrals; they are free to do whatever is necessary to carry out a client's request if they are able and willing to do so.
The next version of the LDAP protocol (LDAPv3) will officially include support for referrals, and the mechanism will differ from the one described here. It is expected that the LDAPv3 referral mechanism will be adopted by everyone and the mechanism described here will eventually be of historical interest only. Discussion of the LDAP protocol takes place on the IETF ASID group mailing list.
LDAP is currently at protocol version 2. We will refer to this as LDAPv2, and this is the protocol that is defined in RFC-1777. Please do not confuse this protocol version numbering scheme with the U-M LDAP implementation's version numbering scheme. All U-M LDAP releases from 3.0 on have used version 2 of the LDAP protocol (LDAPv2). The official LDAP protocol specification does not mention referrals at all; they are a University of Michigan extension.
In an attempt to be as compatible as possible with existing LDAP clients and servers, we changed the standard LDAPv2 protocol in only two ways:
The ldapPartialResults error is returned in place of ldapSuccess when referral information is included. It is important to note that if an error code other than ldapPartialResults is returned, there may still be referral information returned. In other words, the only time that a client can be sure that no referral information was returned is if the result code is ldapSuccess. For search operations, servers may return one or more entries followed by an LDAP result that includes referral information.
The optional referral information is included at the end of the errorMessage string, and it consists of one or more lines (the ASCII newline character - decimal 10 - is used to mark the end of lines). The first line of the referral information is always this (case is not significant):
Referral:
Each line that appears in the errorMessage after the "Referral" line specifies a single server to which the client has been referred. These lines are LDAP URLs with one restriction: only the "hostport" and "dn" portions of the URL may be included. The "hostport" specifies the server hostname and TCP port for the referral. The "dn" part is optional; if included, it specifies a new base to use when chasing the referral. LDAP URLs are fully defined in the Internet Draft document draft-ietf-asid-ldap-format-03.txt
Here's an example of an errorMessage string that refers the client to two other LDAP servers, one called "ldap.itd.umich.edu" and one called "ds.internic.net." The first server is listening on the default LDAP TCP port (389) and the second is on port 3000. The second referral also includes a "dn" portion, which says "use c=US as the base when you talk to the ds.internic.net server":
Partial results only - consider looking on the following LDAP servers. Referral: ldap://ldap.itd.umich.edu ldap://ds.internic.net:3000/c=US
Note that the text before the "Referral:" line is not required and should not to be interpreted in any way by clients.
Also note that by placing the referral information in the errorMessage string, we gain an important advantage: older clients that already display the errorMessage string to their users when errors occur will show the referral information.
The U-M LDAP client library, libldap, has been enhanced to support
referrals. If the library is compiled with LDAP_REFERRALS
defined (the default), the code that supports referrals is included and
automatic chasing of referrals is enabled by default. You can disable
referral processing by clearing the LDAP_OPT_REFERRALS bit
in the ld_options field within the LDAP structure (obtained
from a call to ldap_open()).
Note that when connectionless LDAP is used or when the
LDAP_OPT_REFERRALS bit within the ld_options
field is not set, libldap does not do any referral processing at all.
From the calling application's perspective, referral processing is
mostly hidden. The new error code LDAP_PARTIAL_RESULTS can
be returned for a given operation, which means "the server returned
some referrals, but it was not possible to contact all servers needed
to complete the request." In this case, the library attempts to
include un-followed referrals in the ld_error field of
the LDAP structure, prefixed with a "Referral:" marker line.
Libldap uses a simple "hop-count" mechanism to detect referral loops.
The hop-count starts at zero in the original request submitted by the
calling application. When a referral is followed, the hop-count is
incremented by one. If that referral generates additional referrals,
the hop-count is incremented again. When the count exceeds the value that
is in the ld_refhoplimit field of the LDAP structure, referral
processing on that "chain" of referrals is halted. The default value
for ld_refhoplimit is 5 (set inside ldap_open()).
When opening connections to additional servers in response to a referral,
libldap always performs an LDAP bind before re-submitting the referred
operation. By default, an unauthenticated simple bind is done. Applications
can optionally install a "rebind proc" that gets called to obtain bind
information that is used in place of the unauthenticated bind. This is done
using the ldap_set_rebind_proc API call. See the
ldap_bind(3) manual page for details.
The U-M slapd server (standalone LDAP server) returns the ldapPartialResults error under these circumstances:
In the first two cases above, the default referral that is specified in a "referral" slapd config. file line is returned (if there is one).
In the third case, the referrals returned are pulled from the referral entries. More information can be found in Distributing slapd DATA chapter within the SLAPD and SLURPD Administrator's Guide.
Note that the U-M ldapd server (LDAP front-end for X.500 DSAs) has not been changed. It still does all of the X.500 referral processing for the client, and will never return the ldapPartialResults error or include any referral information in the LDAPResult errorMessage string.
Some LDAPv2 clients will never support referrals, but a server may return referrals to such a client (since there is currently no way for a server to know if a client supports referrals or not).
The good news is that most clients will not be adversely effected. When they receive the new ldapPartialResults error (LDAP error code 9) they will probably report something like "unknown error." It is possible that some clients will crash when they receive the new error code, but this is unlikely.
Since the referrals themselves are carried in the existing errorMessage string, all LDAP clients should be happy to at the very least ignore them. LDAP clients that have the ability to display this string will show the referral information. This could be used to "manually" follow referrals (by reconfiguring the LDAP client to talk to the referred-to server and re-submitting the LDAP request).
This document was last modified Friday, 30-Aug-1996 12:42:15 EDT
Send comments about this page to: ldap-support@umich.edu