--- title: Searching entries description: The PingDirectory server provides an ldapsearch tool to search for entries or attributes within your server. component: pingdirectory version: 11.0 page_id: pingdirectory:pingdirectory_server_administration_guide:pd_ds_search_entries canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/pingdirectory_server_administration_guide/pd_ds_search_entries.html revdate: September 13, 2023 page_aliases: ["pd_ds_search_root_dse.adoc", "pd_ds_search_all_entries_in_server.adoc", "pd_ds_search_for_access_control_instruction.adoc", "pd_ds_search_for_schema.adoc", "pd_ds_single_entry_using_base_scope_dn.adoc", "pd_ds_single_entry_using_search_filter.adoc", "pd_ds_immediate_children_restricted_return.adoc", "pd_ds_all_children_entry_sorted_order.adoc", "pd_ds_limit_returned_search_entries_time.adoc", "pd_ds_optimize_paged_search_caching.adoc", "pd_ds_get_info_indexes_used_in_search.adoc"] section_ids: searching-the-root-dse: Searching the root DSE about-this-task: About this task steps: Steps example: Example: example-2: Example: searching-all-entries-in-the-pingdirectory-server: Searching all entries in the PingDirectory server steps-2: Steps example-3: Example: searching-for-an-access-control-instruction: Searching for an access control instruction steps-3: Steps example-4: Example: result: Result: searching-for-the-schema: Searching for the schema steps-4: Steps example-5: Example: searching-for-a-single-entry-using-base-scope-and-base-dn: Searching for a single entry using base scope and base DN steps-5: Steps example-6: Example: searching-for-a-single-entry-using-the-search-filter: Searching for a single entry using the search filter steps-6: Steps example-7: Example: searching-for-all-immediate-children-for-restricted-return-values: Searching for all immediate children for restricted return values steps-7: Steps example-8: Example: searching-for-all-children-of-an-entry-in-sorted-order: Searching for all children of an entry in sorted order steps-8: Steps choose-from: Choose from: example-9: Example limiting-the-number-of-returned-search-entries-and-search-time: Limiting the number of returned search entries and search time steps-9: Steps example-10: Example: optimize_paged_searches_caching: Optimize paged searches using caching getting-information-about-how-indexes-are-used-in-a-search-operation: Getting information about how indexes are used in a search operation before-you-begin: Before you begin steps-10: Steps choose-from-2: Choose from: --- # 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 1. To set the `show-all-attributes` property to TRUE, run the `dsconfig` tool. #### Example: ```shell $ bin/dsconfig set-root-dse-backend-prop --set show-all-attributes:true ``` 2. Run the `ldapsearch` tool to view the root DSE entry on the PingDirectory server. | | | | - | ------------------------------------------------------------ | | | To display the operational attributes in the entry, use `+`. | #### Example: ```shell $ 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: ```shell $ 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: ```shell $ 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: ```shell $ 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: ```shell $ 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: ```shell $ 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`. ```shell $ 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 and sort the results by one or more attributes, run the `ldapsearch` command and include the `--sortOrder` option. #### Choose from: * To sort the results in ascending order, supply an attribute name for the value of `--sortOrder`. * To sort the results in descending order, supply an attribute name preceded by a `-` for the value of `--sortOrder`. * To sort the results by multiple attributes, supply the attribute names for the value of `--sortOrder` as follows: * List the attributes in the order in which you want to sort the results. * Separate the attributes with commas. * Remember to prepend `-` to any attributes that represent a descending sort. #### Example For this example, the `ldapsearch` command searches for children in the `ou=People,dc=example,dc=com` subtree and sorts them first by `sn` (ascending) and then by `givenName` (descending): ```shell $ 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. ```shell $ 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: ```shell $ 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. ```shell $ 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.```shell $ 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`. ```shell $ 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 ```