16.7 Using the LDAP Server to Search the Directory

This section contains information on the following:

16.7.1 Setting Search Limits

The following attributes on the LDAP server object control how the LDAP server searches the Directory:

Search Entry Limit

Limits the size of a search. The default is 0, for no limit on size. So that the LDAP server isn't overloaded, you can limit the number of entries that the LDAP server returns from a search request.

Scenario: Limiting the Size of a Search— Henri requests a search that could result in thousands of replies concerning objects that the search finds. However, you have set a limit of 10 results. LDAP server stops searching after returning 10 results. A system message informs Henri that the search has ended even though more data is available.
Search Time Limit

Limits the time that the server searches. The default is 0 seconds, for no time limit.

The following figure illustrates these attributes in NetIQ iManager.

In NetIQ iManager, click the Roles and Tasks button .
Click LDAP > LDAP Options > View LDAP Servers.
Click the LDAP server object > Searches.
Scroll to the Restrictions section, enter values, then click OK.

The client can also set limit search requests (for example, limiting the search to two seconds). If the client limit conflicts with the server limit, the LDAP server uses the lowest or smallest value from either request.

The search is based on Access Control Lists (ACLs). Therefore, an Anonymous search could yield the few entries that Public is allowed to view, even though thousands of entries exist in the Directory.

16.7.2 Using Referrals

A referral is a client-centric method to resolve names. An LDAP client sends a request to an LDAP server, which attempts to find the target entry of the operation locally. If the server can't find the target entry, the server uses the knowledge references that it has to generate a referral to a second LDAP server that knows more about the entry. The first server sends the referral information to the LDAP client.

The LDAP client then establishes a connection to the second LDAP server and retries the operation. If the second LDAP server has the target entry of the operation, it performs the operation. Otherwise, the second server also sends a referral back to the client. This process continues until one of the following occurs:

The client contacts a server that has the entry and can perform the desired operation
The LDAP server returns an error indicating that the entry doesn’t exist
The LDAP server indicates that no more referrals can be followed

A functionality introduced in LDAP for eDirectory 8.7 causes referrals to behave slightly differently than with earlier versions of eDirectory and NDS. The differences influence the way you configure LDAP Services.

Default Referrals

Typically, a default referral URL contains an LDAP URL that points to a server that holds the root of the tree. An LDAP URL has the following form: ldap://host:port.

You enter a default referral in the Default Referral URL field:

Historically, the eDirectory LDAP server sent the default referral in a number of failover situations. Many users find these behaviors strange and sometimes unpredictable. LDAP Services for eDirectory 8.8 let you control when the default referral is sent for any kind of subordinate referral.

The new option is a value (setting) held on the ldapDefaultReferralBehavior attribute on the LDAP server and LDAP Group objects. The value is an integer which is a bitmask of the following bits.

Bits	Value
0x00000001	The base DN is not found
0x00000002	The base DN is on an unavailable eDirectory server
0x00000004	An entry in the search scope is on an unavailable eDirectory server

If the LDAP server is configured to Always Refer for the operation, and if any of the conditions listed are met and the corresponding value is set, the default referral is returned.

Setting Referrals for Search Operations

You can configure the eDirectory LDAP server to return referrals to other eDirectory servers within the eDirectory tree. By default, the LDAP server chains all operations to other eDirectory servers on behalf of the user, and referrals are never returned.

Prior to eDirectory 8.7, the referral options only existed as settings on the LDAP Group object. With eDirectory 8.8 you can set these options on the LDAP server object also. Any setting on the LDAP server object overrides that setting on the LDAP Group object.

You set the Referral Option by manipulating the ldapSearchReferralOption attribute. Previous to LDAP Services for eDirectory 8.7, you could set this attribute to the following options:

These referral options apply only to referring and chaining to other eDirectory servers within the eDirectory tree. These configuration settings don’t control referrals that come from a nonauthoritative partition. Therefore, even though you select an option (for example, Always Chain) from the Referral Options drop-down list, referrals will still come from nonauthoritative partitions to other servers.

To support superior referrals to non-eDirectory DSAs, LDAP Services for eDirectory 8.7.a has an Always Chain option. See Always Chain.

The following figure illustrates the LDAP referral drop-down lists for searches and other operations.

“Other” eDirectory operations include referrals for the Add, Delete, Modify, and Bind operations.

Always Chain

The Always Chain option is a “never refer” option. If you select this option, the eDirectory LDAP server never returns referrals to other eDirectory servers in the eDirectory tree. The LDAP server checks with other LDAP servers on behalf of the requesting client and sends the referral to the client.

The Always Chain option will be most beneficial to you if you have an eDirectory deployment that participates as subordinate servers in a global federated tree.

These referral options only apply to the way referrals are handled within the eDirectory tree. They have no bearing on referral behavior to non-eDirectory servers.

The reason for blocking referrals to other eDirectory servers is subtle, but may prove invaluable. If the nonauthoritative data on an eDirectory 8.7 or later server is replicated to another, older eDirectory server, a referral to the older server might cause a client application to get a distorted view of the global tree.

For example, assume that an LDAP client caches referrals to LDAP servers and sends requests to the server it last communicated with. If the client is configured to send requests to an eDirectory server that supports superior referrals, the client's view of the global tree should be normal.

However, LDAP servers earlier than eDirectory 8.7 don’t understand nonauthoritative areas and superior referrals. Therefore, if the client follows a referral to an earlier-version eDirectory server in the eDirectory tree, and continues to send requests to that earlier-version server, the earlier-version LDAP server will present the nonauthoritative data as if it were the actual directory tree data.

An intelligent client should, however, interrogate the supportedFeatures attribute of the rootDSE to ascertain whether or not the server supports superior referrals.

Prefer Chaining

The Prefer Chaining option indicates that search operations will not normally return referrals. Instead, the LDAP server progresses the search operation across all eDirectory DSAs required to complete it.

The exception is a search operation that is accompanied by the persistent search control. In this case, because the NetIQ implementation of persistent search does not support chaining, referrals are sent if the scope of the search operation is not all held locally.

The LDAP server receives a search operation. If the entry in the tree is not stored locally, the server automatically chains to other servers. After the entry has been located, the LDAP server acts as proxy for the LDAP client. Using the same identify that the LDAP client is bound with, the LDAP server authenticates to the remote server and continues the search operation there.

The LDAP server that received the original search request sends the LDAP client all search entries and the search result. Because the LDAP server fully takes care of the request, the LDAP client is unaware that other servers were involved.

Through chaining on eDirectory, an LDAP server that doesn’t have much data can appear to hold the data of the entire tree.

Prefer Chaining is important concerning partitions.

Scenario: Finding Information in another Partition— At the Digital Airlines Company, Luc selects the Prefer Chaining option for LDAP server DAir43. DAir43 is in Partition A. Partition B is a subpartition of A and contains LDAP server DAir44.

An LDAP client requests a search. DAir43 searches locally for the entry but only finds part of the data. DAir43 automatically chains to DigitalAir44, which has the needed entry. DAir44 sends the data to DAir43, and DAir43 sends the entry to the LDAP client.

The Prefer Chaining option causes the LDAP server to chain to other servers for search requests (when needed) unless the operation is a Persistent Search. For information on Persistent Search, see Persistent Search: Configuring for eDirectory Events.

Prefer Referrals

The Prefer Referrals options indicates that search operations will return referrals to other eDirectory servers in the eDirectory tree when needed. Referrals are sent only if the local server can ensure that the server holding the data is operational and that the LDAP service is running. Otherwise, the operation is chained to the other server, or the operation fails if the other server in inoperable.

You have two partitions and are doing a subtree search. You get down to a point where the search entries are no longer held on the local server. Therefore, the search must go to another server. If the server that holds the replica of that data (that partition) is also running nldap.nlm, the LDAP server builds an LDAP referral and sends it back to the LDAP client.

If the server holding the replica isn't running nldap.nlm, LDAP server chains the request to the other server, thereby completing the search.

When nldap.nlm starts up, the LDAP server communicates to eDirectory that the LDAP server is a referral point. If a client has received referrals but the referrals stop, the LDAP server is not running.

Always Refer

The Always Refer option follows the same logic as Prefer Referrals, except that the Default Referral is sent under various failover situations (for example, an object is not found or the server is down).

If another server that holds the rest of the data isn't running the LDAP service, the first LDAP server won't chain the request to the second server.

If you mark the Always Refer option, you are allowed to enter a default referral. The Default Referral field enables you to glue two different vendor LDAP servers together and build your own Directory tree.

Scenario: Using a Default Server— You have an LDAP tree. One part of the tree is serviced by eDirectory. A subordinate partition is serviced by iPlanet. In the Default Referral field, you place a URL that references the iPlanet server. An LDAP client requests a search.

Unable to resolve the base DN, the LDAP server sends the client the string in the Default Referral field. The referral instructs the LDAP client to look in the place specified in the URL The LDAP client contacts the iPlanet server, which completes the search.

Whenever a default referral is configured and the server doesn’t find the base DN being searched for, the client receives the default referral.

The format for a referral is an LDAP URL. For example, LDAP://123.23.45.6:389.

When the LDAP server sends a default referral to a client (because the base DN was unavailable), the server appends an additional forward slash (/) and the DN that the client was looking for. The default referral and the appended information go to the client. The client sends the search request to the server specified in the default referral.

The LDAP Group object has a string field for the default referral. The LDAP server treats that data as a string. There is no validation. Whatever is entered is prepended to the referral. Some data is appended to the referral. The LDAP server expects the string to look like a URL.

When clients get referrals to other eDirectory servers that are running LDAP, the client receives two referrals per server:

A referral directing the client to the clear-text port
A referral directing the client to the secure port

To differentiate between the two referrals, the clear-text referral states ldap:// and the secure port displays ldaps://.

A referral from the server appends the port number.

Setting Referrals for Other Operations

The historical referral option setting only applied to the search operation. To provide a comparable option for other operations, the ldapOtherReferralOption attribute is used. This attribute allows the same values and controls the behavior for non-search operations (excluding bind, which never sends a referral).

Referral Filtering

If you have multiple replica servers running in a tree and have configured LDAP server(s) to return referrals using the Prefer Referrals/Always Refer option, then the LDAP server will return referrals if the object identified by DN in the requested operation is not present locally. In such a case, LDAP client sends a request to the server, and the server returns a referral list of all the LDAP servers holding that object. Using this referral list, LDAP clients will follow any of these referrals to perform the operation. If the client chooses to follow the referral to a resource-starved server or a server that is located across a slow link, clients would see a slow response from the server. This in turn affects the performance of the LDAP client. Since LDAP application developers will not have complete knowledge about the servers and network configurations, the solution for this problem is to provide a referral filtering mechanism at the LDAP server to return the referrals of specific server(s). Administrators would have the requisite knowledge, e.g. the nature of LDAP servers in the network and network link speeds to make appropriate configuration of referral filtering.

Set up the referral filter on the LDAP Group object using the attributes “referralIncludeFilter” and “referralExcludeFilter”. Setting these filters in these attributes will be applicable to all the LDAP servers belonging to this LDAP Group object. The LDAP server will return all the LDAP referrals matching with the referralIncludeList filter and drop the ones that match the referralExcludeFilter filter.

If only referralIncludeFilter is specified, the LDAP referrals which match the referralIncludeFilter values will be returned to the LDAP clients and all other referrals will be excluded from the referral list. Similarly, if only referralExcludeFilter is specified, the LDAP referrals which do not match the referralExcludeFilter values will be returned to the LDAP clients. If both filters exist and the referral does not match any of these filters, it will be excluded.

If all available referrals are disallowed by the filter, the server will behave as if no referrals are available and return LDAP_OTHER (80), which some client tools report as “Unknown error.” After adding or modifying these filter attributes, if the LDAP server is not refreshed, changes will take place after the subsequent automatic refresh.

Currently, adding or modifying these filter attributes can be done only with the tab available in iManager.

Format to Specify LDAP Referral Filtering —The LDAP referral filter format is a simple IP address format:

[ldap://] | [ldaps://] IPAdress[:port]

Here, specifying the clear text port or TLS port will be same as pre-pending ldap:// or ldaps:// strings. If neither ldap or ldaps is specified, the match filter is applicable for both clear text as well as TLS referrals.

Examples:

Examples	Description
1.2.3.4	# matches both LDAP and LDAPS referrals on any port
1.2.	# matches all IP addresses of 1.2.X.Y
1.2.3.	# matches all IP addresses of 1.2.3.Y
ldap:// or ldap://*	# matches all the clear text port LDAP referrals
ldaps:// or ldap://*	# matches all the ssl port LDAP referrals
*	# matches all
ldaps://5.6.7.8:636	# matches for SSL port 636 on IP addresses 5.6.7.8

These filter attributes (referralIncludeFilter and referralExcludeFilter) are multi-valued. You can choose as many matching filters as you need.

Example Scenarios

To make an LDAP server return only referrals with the IP address 1.2.X.Y where X = {0 to 255} and Y = {0 to 255} and exclude all others, enter the following:

referralIncludeFilter = { 1.2 }
To make an LDAP server return referral, that exclude all the referrals that match IP address 164.99.X.Y, where X is not equal to 100 and match 164.99.100.Y, enter the following:

referralIncludeFilter = { 164.99.100., "*"}

referralExcludeFilter = { 164.99. }

Here, even though the IP address 164.99.100.Y matches referralExcludeFilter, since these IP addresses have more matched fields, these referrals will be returned to the LDAP clients.

NOTE:While specifying a partial IP address, the trailing “.” can be omitted.
To make an LDAP server return only clear text port referrals and drop SSL port referrals, enter the following:

referralIncludeFilter = { "ldap://" }

OR

referralExcludeFilter = { "ldaps://" }
To make an LDAP server return from a set of IP addresses and drop all other IP address referrals, enter the following:

referralIncludeFilter = { 1.2.3.4, 2.3.4.5:389, 3.4.5.6:636, ldaps://4.5.6.7 }

referralExcludeFilter = { "*" }

NOTE:Here, referralExcludeFilter is not required. Any populated referralIncludeFilter implies to exclude all others.
There are two filters, as follows:

referralIncludeFilter = { 1.2.3.4 }

referralExcludeFilter = { 2.3.4.5 }

A referral with IP address 3.4.5.6 will be excluded as it does not match the referralInclude filter, even though it does not match the referralExcludeFilter as well.

Invalid Filters —The following filters are not supported.

“.2.3.4” or “*.2.3.4” will not match the IP addresses X.2.3.4.

“2.3.4*” will not match the IP addresses like 2.3.41 or 2.3.42.

DNS names like sever1.mydomain.com, or *.mydomain.com are not supported. Adding the port ranges to the filters like allow referral IP address on the port start-to-end is not supported.There are no validation checks done before adding these filter values to these attributes. But in case of an invalid filter, the LDAP server will ignore those filters and log the information into ndsd.log file.

Known Issues —The LDAP rootDSE search returns altServers if there are any replica servers in the LDAP URL format. These URLs do not get filtered using this mechanism.

No Support for ManageDsaIT

In LDAP Services for eDirectory 8.8, the distributed relationships between eDirectory servers in an eDirectory tree are managed by means other than the use of the ManageDsaIT control. The ManageDsaIT control won't allow the LDAP client to interrogate or update eDirectory subordinate or cross references.

Functionality Not Supported

LDAP Services for eDirectory 8.8 doesn’t support subordinate references. You cannot reliably create a nonauthoritative partition that is subordinate to an authoritative partition and have it send referrals. If you elect to do this, referrals are only sent when resolving the base DN for an operation. SearchResultReferences are not sent.

There is no support for distributed updates of data in the nonauthoritative area. If a name change occurs on the root server, there is no built-in mechanism to copy that name change to the eDirectory server holding that same data in a nonauthoritative area.

16.7.3 Searching Filtered Replicas

A filter restricts the amount of data that the replica holds. Therefore, a filtered replica does not have complete view of real data held in the directory. The following are examples of filters applied to a replica:

The replica only contains User objects.
The replica contains all User objects, but the objects only contain telephone numbers and mailing addresses.

Because data in a filtered replica is incomplete, an LDAP search could produce constrained results. Therefore, by default an LDAP search request does not examine filtered replicas.

While performing filtered replica search, the search might not return the results as per the replica filter in the following cases:

If the objects matching the search filter are not present on the local filtered replica server then the results may not match with the filter of the local replica as the results may be fetched from a full replica server.
When the search base is not local to the filtered replica server, the objects matching the search filter may be obtained from a full replica server and these might not match with the filter of the local replica.

However, if you are certain that a filtered replica holds data that you need, you can configure an LDAP server to search filtered replicas.

In NetIQ iManager, click the Roles and Tasks button .
Click LDAP > LDAP Options.
Click View LDAP Server, then click the name of an LDAP server.
Click Searches.
Select Include filtered replicas in search, then click Apply.