14.7. Searching with Specified Controls
The Directory Server has defined controls in its
supportedControls attribute in its DSE. Some of these define server operations like replication; other are allowed extended operations like get effective rights or dereferencing controls which clients can pass through LDAP operations to the server.
These controls can be specified using the
-E option by giving the control OID, its criticality for the ldapsearch, and any information required for the control operation.
-E '[!]control_OID:control_information'
Some controls, like server-side sorting and simple paged results, have an alias that can be used to pass the control to the search operation. When the control alias is used, then the results are formatted, since the control is recognized by the client.
14.7.1. Retrieving Effective User Rights
A get effective-rights search control is passed using the control OID. For example:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x -E '!1.3.6.1.4.1.42.2.27.9.5.2=:dn:uid=jsmith,ou=people,dc=example,dc=com' "(objectclass=*)"
Important
When a control is passed with its OID, the results from the search are unformatted.
Get effective rights searches are covered in much more detail in the access control chapter, Section 18.12, “Checking Access Rights on Entries (Get Effective Rights)”.
14.7.2. Using Server-Side Sorting
Server-side sorting is performed as other control operations, using the
-E flag and the sss control alias. The structure of the operation sets the attribute by which to sort the results and, optionally, the sort order and ordering rule.
-E sss=[-]attribute_name:[ordering_rule_OID]
The dash (
-) is an optional flag that reverses the sort order, which naturally runs descending. The matching rule tables in Section 14.3.4, “Using Matching Rules” contain the ordering rules supported by the Directory Server.
For example:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x -E sss=-uidNumber:2.5.13.15 "(objectclass=*)"
14.7.3. Performing Dereferencing Searches
A dereferencing search is a quick way to track back over cross-references in an entry and return information about the referenced entry. For example, a group entry contains references to its member's user entries. A regular search first searches for the group, then lists its members, and then requires a separate search for each member. A dereferencing search for the group entry returns information about the members — such as their locations, email addresses, or managers — along with the information for the group, all in a single search request.
Dereferencing simplifies many client operations and reduces the number of search operations that are performed. Cross-links show relationships between entries. Some operations may require getting a list of cross-links from one entry and then performing a series of subsequent searches to get information from each entry on the list. Dereferencing allows those sequences of searches to be consolidated into a single search.
Important
Dereferencing operations must be done using OpenLDAP command-line tools version 2.4.18 or later or other clients which support dereferencing searches.
The format of the dereference arguments is:
-E 'deref=deref_attribute:list_of_attributes'
The deref_attribute is the attribute in the search target that contains the reference. This can be any attribute which has a DN for its value, such as
member or manager.
Note
Not only must the value of the deref_attribute be a DN, but the actual defined syntax for the attribute must be DN syntax (
1.3.6.1.4.1.1466.115.121.1.12).
The list_of_attributes is one or more attributes in the referenced entry which will be returned along with the primary search results. Multiple attributes can be separated by commas, like
l,mail,cn.
Figure 14.1. Simple Dereferencing Search Command
The requested dereferenced information requested in the search argument is returned with the rest of the search results. For example, this dereferencing search tells the server to use the
member attribute in the search target entry (the Engineers group) as the deref_attribute. It then returns the locality attribute for each member.
# ldapsearch -x -D "cn=Directory Manager" -W -b "cn=Example,ou=Groups,dc=example,dc=com" -E 'deref=member:mail,cn' "(objectclass=*)" # Engineers, Groups, example.com dn: cn=Engineers,ou=Groups,dc=example,dc=com control: 1.3.6.1.4.1.4203.666.5.16 false MIQAAADNMIQAAAA1BAZtZW1iZXIEK2NuPURld mVsb3BlcnMsIG91PUdyb3VwcywgZGM9ZXhhbXBsZSxkYz1jb20whAAAADIEBm1lbWJlcgQoY249VG VzdGVycywgb3U9R3JvdXBzLCBkYz1leGFtcGxlLGRjPWNvbTCEAAAAVAQGbWVtYmVyBCp1aWQ9ZW5 nLCBvdT1lbmdpbmVlcmluZywgZGM9ZXhhbXBsZSxkYz1jb22ghAAAABowhAAAABQEAWwxhAAAAAsE CUNhbWJyaWRnZQ== # member: <mail=jsmith@example.com><cn=John Smith>;uid=jsmith,ou=people,dc=example,dc=com objectClass: top objectClass: inetuser objectClass: groupofnames cn: Engineers member: uid=jsmith,ou=people,dc=example,dc=com
14.7.4. Using Simple Paged Results
Search results can be very large, and a part of processing the results is organizing the results. One method of doing this is using simple paged results, a control that breaks the results into pages of a certain length.
The simple paged results control sets the number of entries to display at a time. The results can be scrolled through one page at a time which makes the results easier to digest. The full behavior of the control is described in RFC 2696.
Simple paged results are implemented as an LDAP control extension for the Directory Server. Its OID is
1.2.840.113556.1.4.319.
How Simple Paged Results Work
When you start a simple paged results search:
- The client sends the search to the server, together with the paged results control and with how many records to return in the first page.
- Before Directory Server starts returning data, the server generates an estimate how many records can be returned in total.The estimate of records is not an exact number. The total number of records returned can be lower than the estimate. The reasons for such a scenario include
- attributes used in the search filter do not exist in the index. For an optimal result, all queried attributes must be indexed.
- before an entry is send to the client, access control lists (ACL) are validated. Insufficient permissions can prevent the entry from being returned.
After generating the estimate, the server sends the first set of results, a cookie, and the estimated number of records. - The returned records are displayed in the client. The user can now enter how many records should be returned in the next request. The requested number is now sent, together with the cookie, to the server.
- The server retrieves the requested number of records from the database and sends them together with a cookie to the client.
- The previous two steps are repeated until all records are sent or the search is cancelled.
Simple Paged Results and OpenLDAP Tools
The format of the simple paged result search option with ldapsearch is:
-E pg=size
The size value is the page size, or the number of entries to include per page. For example:
ldapsearch -x -D "cn=Directory Manager" -W -b "ou=Engineers,ou=People,dc=example,dc=com" -E pg=3 "(objectclass=*)" cn dn: uid=jsmith,ou=Engineers,ou=People,dc=example,dc=com cn: John Smith dn: uid=bjensen,ou=Engineers,ou=People,dc=example,dc=com cn: Barbara Jensen dn: uid=hmartin,ou=Engineers,ou=People,dc=example,dc=com cn: Henry Martin Results are sorted. next page size (3): 5
The tag at the end shows the configured page size (the number in parentheses) from the search. After the colon, one enters the page size for the next page, so entering
5 as shown would open the next page of results with five entries.
Important
Simple paged results operations must be done using OpenLDAP command-line tools version 2.4.18 or later or other clients which support simple paged results, such as Perl Net::LDAP.
Simple Paged Results and Server-Side Sorting
Simple paged results can be used together with server-side sorting. Server-side sorting is a control which performs the sort process on the server rather than in a client; this is usually done for a search which uses a particular matching rule. (This behavior is defined in RFC 2891.) The OpenLDAP client tools do not support server-side sort with the simple paged results control, but other LDAP utilities such as Perl Net::LDAP do support both.
Multiple Simple Paged Results Requests on a Single Connection
Some clients may open a single connection to the Directory Server, but send multiple operation requests, including multiple search requests using the simple paged results extension.
Directory Server can manage and interpret multiple simple paged searches. Each search is added as an entry in an array. When the paged search request is first sent, there is a cookie created and associated with the search results. Each page of results is returned with that cookie, and that cookie is used to request the next page of results. On the last page, the cookie is empty, signalling the end of the results. This keeps each set of search results separate.
When there are multiple simple paged results on a single connection, the timeout limits are still observed, but all open search requests much reach their configured time limit before any paged search is disconnected.
Simple Paged Results, Contrasted with VLV Indexes
VLV indexes are similar to simple paged results in that they also return a usable browsing list of results. The main difference is in how that list is generated. Simple paged results are calculated per search, while VLV indexes are a permanent list. Overall, VLV indexes are faster for searches, but do require some server-side configuration and overhead for the server to maintain.
Note
Simple paged results and VLV indexes cannot be used on the same search. Simple paged results would attempt to manipulate the VLV index, which is already a browsing index. If the control is passed for a search using a VLV index, then the server returns an
UNWILLING_TO_PERFORM error.
For more information on VLV indexes, see Section 13.4, “Using virtual list view control to request a contiguous subset of a large search result”.
14.7.5. Pre- and Post-read Entry Response Controls
Red Hat Directory Server supports pre- and post-read entry response controls according to RFC 4527. If a client requests one or both response controls, an LDAP search entry is returned, that contains the attribute's value before and after the update.
When the pre-read control is used, an LDAP search query is returned containing the specified attribute's value before modification. When the post-read control is used, the query contains the attribute's value after modification. Both controls can be used at the same time. For example, to update the
description attribute and display the value before and after the modification:
#ldapmodify -D "cn=Directory Manager" -W -x \-e \!preread=description -e \!postread=descriptiondn: uid=user,ou=People,dc=example,dc=com changetype: modify replace: description description: new description modifying entry "uid=user,ou=People,dc=example,dc=com" control: 1.3.6.1.1.13.1 false ZCkEJXVpZD1qdXNlcixvdT1QZW9wbGUsZGM9ZXhhbXBsZSxk Yz1jb20wAA== # ==> preread dn: uid=user,ou=People,dc=example,dc=com description: old description # <== preread control: 1.3.6.1.1.13.2 false ZEsEJXVpZD1qdXNlcixvdT1QZW9wbGUsZGM9ZXhhbXBsZSxk Yz1jb20wIjAgBAtkZXNjcmlwdGlvbjERBA9uZXcgZGVzY3JpcHRpb24= # ==> postread dn: uid=user,ou=People,dc=example,dc=com description: new description # <== postread
