Searching entries

The PingDirectory server provides an ldapsearch tool to search for entries or attributes within your server.

The ldapsearch tool requires the LDAP connection parameters to bind to the server, including the baseDN option to specify the starting point of the search within the server, and the search scope. The searchScope option determines the depth of the search.

base: Searches only for the specified entry.
one: Searches only the children of the entry and not the entry itself.
sub: Searches the entry and its descendants.

The ldapsearch tool provides basic functionality specified by the RFC 2254 and provides additional features that use the PingDirectory server’s control mechanisms.

For more information, run the ldapsearch --help function.

Searching the root DSE

The root DSA-specific entry (DSE) is a special entry that resides at the root of the directory information tree (DIT). The entry holds operational information about the server and its supported controls.

About this task

Specifically, the root DSE entry provides information about the supported LDAP3 controls, Simple Authentication and Security Layer (SASL) mechanisms, password authentication schemes, supported LDAP protocols, additional features, naming contexts, extended operations, and server information.

The PingDirectory server provides an option to retrieve the Root DSE’s operational attributes and add them to the user attribute map of the generated entry. This feature allows client applications that have difficulty handling operational attributes to access the root DSE using the show-all-attributes configuration property. After you set this property, the associated attribute types are recreated and re-registered as user attributes in the schema (in memory, not on disk). After you set the property, you can use ldapsearch without "+" to view the root DSE.

Steps

To set the show-all-attributes property to TRUE, run the dsconfig tool.

Example:
```
$ bin/dsconfig set-root-dse-backend-prop --set show-all-attributes:true
```
Run the ldapsearch tool to view the root DSE entry on the PingDirectory server.

To display the operational attributes in the entry, use +.

Example:
```
$ bin/ldapsearch --baseDN "" --searchScope base "(objectclass=*)" "+"
```

Searching all entries in the PingDirectory server

Steps

To search all entries in the PingDirectory server, run the ldapsearch tool.

The filter "(objectclass=*)" matches all entries. If you do not specify the --searchScope subcommand, it defaults to a search scope of sub.

Example:
```
$ bin/ldapsearch --baseDN dc=example,dc=com \
  --searchScope sub "(objectclass=*)"
```

Searching for an access control instruction

Steps

To search the dc=example,dc=com base distinguished name (DN) entry, run the ldapsearch tool.

The filter "(aci=*)" matches all aci attributes under the base DN, and the aci attribute is specified so that only it is returned. The cn=Directory Manager bind DN has the privileges to view an access control instruction (ACI).

Example:

$ bin/ldapsearch --baseDN dc=example,dc=com "(aci=*)" aci

Result:

The system displays the following ACI information.

dn: dc=example,dc=com
aci: (targetattr!="userPassword")
  (version 3.0; acl "Allow anonymous read access for anyone";
    allow (read,search,compare) userdn="ldap:///anyone";)
aci: (targetattr="*")
  (version 3.0; acl "Allow users to update their own entries";
    allow (write) userdn="ldap:///self";)
aci: (targetattr="*")
  (version 3.0; acl "Grant full access for the admin user";
    allow (all) userdn="ldap:///uid=admin,dc=example,dc=com";)

Searching for the schema

Steps

To search the cn=schema entry, run the ldapsearch tool.

The base distinguished name (DN) is specified as cn=schema, and the filter "(objectclass=*)" matches all entries. The command uses a special attribute "+" to return all operational attributes.

Example:

$ bin/ldapsearch --baseDN cn=schema \
  --searchScope base "(objectclass=*)" "+"

Searching for a single entry using base scope and base DN

Steps

To search for a single entry, run the ldapsearch tool and specify the base scope and DN.

Example:

$ bin/ldapsearch --baseDN uid=user.14,ou=People,dc=example,dc=com \
  --searchScope base "(objectclass=*)"

Searching for a single entry using the search filter

Steps

To search for a single entry, specify the sub scope and a search filter that describes a single entry.

Example:
```
$ bin/ldapsearch --baseDN ou=People,dc=example,dc=com \
  --searchScope sub "(uid=user.14)"
```

Searching for all immediate children for restricted return values

Steps

To search for all immediate children of restricted return values, run the ldapsearch tool.

The special attribute "+" returns all operational attributes.

Example:

In this sample, the immediate children are ou=People,dc=example,dc=com, and the restricted returned values are sn and givenName.
```
$ bin/ldapsearch --baseDN ou=People,dc=example,dc=com \
  --searchScope one '(objectclass=*)' sn givenName "+"
```

Searching for all children of an entry in sorted order

Steps

To search for all children of an entry in the appropriate subtree, run the ldapsearch command.

Choose from:
- To sort the resulting entries by the server in ascending order, use sn.
- To sort the orders in descending order, use givenName.
  
  Example:
  
  For this example, the ldapsearchcommand searches for children in the ou=People,dc=example,dc=com subtree.
  $ bin/ldapsearch --baseDN ou=People,dc=example,dc=com \ --searchScope sub --sortOrder sn,-givenName '(objectclass=*)'

Limiting the number of returned search entries and search time

Steps

To search for a subset of the entries in the ou=People,dc=example,dc=com subtree, specify a compound filter.

Example:

In the following example, no more than 200 entries will be returned and the server will spend no more than 5 seconds processing the request. Returned attributes are restricted to a few operational attributes.
```
$ bin/ldapsearch --baseDN ou=People,dc=example,dc=com \
  --searchScope sub --sizeLimit 200 --timeLimit 5 \
  "(&(sn<=Doe)(employeeNumber<=1000))" ds-entry-unique-id entryUUID
```

Optimize paged searches using caching

When the server processes an indexed search using the simple paged results control, it builds the entire candidate set of entry IDs for entries that match the search before serving a subset of entries on a results page. By default, the server does this for every page. The larger the candidate set, the longer the search processing takes.

To improve paged search speed, you can configure the server to cache the generated candidate set using the simple-paged-results-id-set-cache-duration property. For example:

$ bin/dsconfig set-backend-prop \
  --backend-name userRoot \
  --set "simple-paged-results-id-set-cache-duration:1 m"

With this property configured, although the server still has to build the entire candidate set before serving the first page of results, it can cache and reuse that set when returning subsequent pages.

By default, the cache duration is set to 0 milliseconds, and no caching is performed. If you change the value to a non-zero duration, the server caches and reuses the candidate set for the subsequent pages of results, up to the point where the duration between requests for the next page of results exceeds the cache duration.

You should configure a duration that is long enough to ensure that the cached result set doesn’t expire before legitimate clients can make use of it, although making the duration too long can cause the server to hold onto the cached result sets longer than necessary, increasing the amount of memory required to hold them.

In most cases, we recommend setting a duration of 30–60 seconds.

When the cache is enabled, it’s not shared between server instances. If possible, clients should send requests for all pages of a paged search to the same server, whether caching is enabled or not. The PingDirectoryProxy server automatically tries to route requests to the same backend server for paged searches, but environments that use other forms of load balancing might not conform to this best practice by default. PingDirectory can properly handle cases where client requests for different pages are sent to different servers, although each server instance involved builds the paged search request candidate set independently.

When optimizing paged searches, you should make the previous configuration change for each local database backend where you expect searches with paged results and enable it for all servers in the topology that might process searches using the paged results request control.

Only enable simple paged results ID caching in environments where all servers support this feature. In a mixed-version topology that includes older versions of the PingDirectory server that don’t support paged results caching, those servers won’t be able to decode paged results cookies generated by newer servers that do support caching. If you disable paged results caching on the newer servers, the cookies these servers generate will be compatible with the older servers.

Getting information about how indexes are used in a search operation

Before you begin

The PingDirectory server uses indexes to improve database search performance and provide consistent search rates regardless of the number of database objects stored in the Directory Information Tree (DIT).

Steps

To search for how indexes are used in a search operation, you can either:

Choose from:

Issue a search request with the desired base distinguished name (DN), scope, and filter, and request that the server return the special debugsearchindex attribute using the ldapsearch command.

$ bin/ldapsearch --hostname ds.example.com \
 --port 389 --bindDN uid=admin,dc=example,dc=com \
 --bindPassword password \
 --baseDN dc=example,dc=com \
 --searchScope sub "(&(givenName=John)(sn=Doe))" debugsearchindex
 dn: cn=debugsearch
 debugsearchindex: 0.040 ms - Beginning index processing for search
     request with base DN 'dc=example,dc=com', scope wholeSubtree,
     and filter (&(givenName=John)(sn=Doe)).
 debugsearchindex: 0.067 ms - Unable to optimize the AND filter
     beyond what the client already provided.
 debugsearchindex: 0.834 ms - Candidate set obtained for single-key
     filter (givenName=John) from index dc_example_dc_com_givenName.equality.
     Candidate set:  CandidateSet(isDefined=true, isExploded=false,
     isResolved=true, size=2, originalFilter=(givenName=John),
     remainingFilter=null, matchingEntryCountType=UNEXAMINED_COUNT)
 debugsearchindex: 0.030 ms - Final candidate set for filter (givenName=John)
     obtained from an unexploded index key in dc_example_dc_com_givenName.equality.
     Since the scope of the search includes the entire entry container, there is
     no need to attempt to further pare down the results based on the search scope.
     Candidate set:  CandidateSet(isDefined=true, isExploded=false, isResolved=true,
     size=2, originalFilter=(givenName=John), remainingFilter=null,
     matchingEntryCountType=UNEXAMINED_COUNT)
 debugsearchindex: 0.020 ms - Short-circuiting index processing for AND filter
     (&(givenName=John)(sn=Doe)) after evaluating single-key component
     (givenName=John) because the current ID set size of 2 is within the
      short-circuit threshold of 5.
 debugsearchindex: 0.030 ms - Obtained a candidate set of size 2 for AND filter
     (&(givenName=John)(sn=Doe)) with remaining filter (sn=Doe).  Even though
     there is still more of the filter to evaluate, the current candidate set is
     within the short-circuit threshold of 5, so no additional index processing will
     be performed to try to pare down the results based on the remaining filter or the
     search scope.  Candidate set:  CandidateSet(isDefined=true, isExploded=false,
     isResolved=true, size=2, originalFilter=(&(givenName=John)(sn=Doe)),
     remainingFilter=(sn=Doe), matchingEntryCountType=UPPER_BOUND)
 debugsearchindex: 0.016 ms - Completed all index processing.  Candidate set:
     CandidateSet(isDefined=true, isExploded=false, isResolved=true, size=2,
     originalFilter=(&(givenName=John)(sn=Doe)), remainingFilter=(sn=Doe),
     matchingEntryCountType=UPPER_BOUND)

Users must have access to the debugsearchindex operational attribute and the cn=debugsearch portion of the DIT with the following command.

$ bin/dsconfig set-access-control-handler-prop \
 --add "global-aci:(targetattr=\"debugsearchindex\")(target=\"ldap:///cn=debugsearch\")
    (version 3.0; acl \"Allow members of the Index Debugging Users group
    to request the debugsearchindex operational attribute \"; allow
    (read,search,compare) groupdn=\"ldap:///cn=Index Debugging
    Users,ou=Groups,dc=example,dc=com\";)"

Issue a search request with the desired base DN, scope, and filter, and include the matching entry count request control with the debug option set to true using ldapsearch.

$ bin/ldapsearch --hostname ds.example.com --port 389 \
 --bindDN uid=admin,dc=example,dc=com --bindPassword password \
 --baseDN dc=example,dc=com \
 --searchScope sub --matchingEntryCountControl examineCount=0:debug "(&(givenName=John)(sn=Doe))"
 Upper Bound on Matching Entry Count:  2
 Matching Entry Count Debug Messages:
 * naw-desktop:1389 - 0.104 ms - Beginning index processing for search request with
    base DN 'dc=example,dc=com', scope wholeSubtree, and filter (&(givenName=John)(sn=Doe)).
 * naw-desktop:1389 - 0.105 ms - Unable to optimize the AND filter beyond what the client already provided.
 * naw-desktop:1389 - 0.614 ms - Candidate set obtained for single-key filter (givenName=John) from index
    dc_example_dc_com_givenName.equality.  Candidate set:
    CandidateSet(isDefined=true, isExploded=false, isResolved=true,
    size=2, originalFilter=(givenName=John), remainingFilter=null, matchingEntryCountType=UNEXAMINED_COUNT)
 * naw-desktop:1389 - 0.090 ms - Final candidate set for filter
    (givenName=John) obtained from an unexploded index key in
    dc_example_dc_com_givenName.equality.  Since the scope of the search
    includes the entire entry container, there is no need
    to attempt to further pare down the results based on the search scope.
    Candidate set:  CandidateSet(isDefined=true, isExploded=false, isResolved=true,
    size=2, originalFilter=(givenName=John), remainingFilter=null, matchingEntryCountType=UNEXAMINED_COUNT)
 * naw-desktop:1389 - 0.045 ms - Short-circuiting index processing for AND filter
    (&(givenName=John)(sn=Doe)) after evaluating single-key component
    (givenName=John) because the current ID set size of 2 is within the short-circuit threshold of 5.
 * naw-desktop:1389 - 0.111 ms - Obtained a candidate set of size 2 for AND filter
    (&(givenName=John)(sn=Doe)) with remaining filter (sn=Doe).  Even though there is
    still more of the filter to evaluate, the current candidate set is within
    the short-circuit threshold of 5, so no additional index processing will be performed
    to try to pare down the results based on the remaining filter or the search scope.
    Candidate set:  CandidateSet(isDefined=true, isExploded=false, isResolved=true, size=2,
    originalFilter=(&(givenName=John)(sn=Doe)), remainingFilter=(sn=Doe),
    matchingEntryCountType=UPPER_BOUND)
 * naw-desktop:1389 - 0.040 ms - Completed all index processing.  Candidate set:
    CandidateSet(isDefined=true, isExploded=false, isResolved=true, size=2,
    originalFilter=(&(givenName=John)(sn=Doe)), remainingFilter=(sn=Doe),
    matchingEntryCountType=UPPER_BOUND)
 * naw-desktop:1389 - The search is partially indexed (candidatesAreInScope=true,
    unindexedFilterPortion=(sn=Doe))
 * naw-desktop:1389 - Constructing an UPPER_BOUND response with a count of 2