Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

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'
Copy to Clipboard Toggle word wrap
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
Copier lien

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=*)"
Copy to Clipboard Toggle word wrap

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
Copier lien

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]
Copy to Clipboard Toggle word wrap
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=*)"
Copy to Clipboard Toggle word wrap

14.7.3. Performing Dereferencing Searches
Copier lien

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'
Copy to Clipboard Toggle word wrap
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.
Simple Dereferencing Search Command
View larger image
Simple Dereferencing Search Command

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
Copy to Clipboard Toggle word wrap

14.7.4. Using Simple Paged Results
Copier lien

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:

  1. 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.
  2. 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.
  3. 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.
  4. The server retrieves the requested number of records from the database and sends them together with a cookie to the client.
  5. 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
Copy to Clipboard Toggle word wrap
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
Copy to Clipboard Toggle word wrap
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
Copier lien

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=description 
dn: 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
Copy to Clipboard Toggle word wrap
Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat