Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท LDAP Protocol and Queries

Search Scope, Base DN and Search Parameters

Learn the parameters of an LDAP search: base DN, scope (base, one, sub), alias dereferencing, size and time limits, attribute selection and ldapsearch examples.

A filter says what to match. The other parameters of a search say where to look, how deep, how much to return and which attributes to include. Mastering these makes searches fast, precise and safe. This lesson covers every parameter, shows ldapsearch examples for each and lets you experiment with scopes and limits using a Python stand-in.

The parameters of a search request

Parameter Meaning ldapsearch option
Base object DN where the search starts -b
Scope How far below the base to look -s base, one, sub, children
Deref aliases Whether to follow alias entries -a never, always, search, find
Size limit Maximum number of entries returned -z
Time limit Maximum seconds for the search -l
Types only Return attribute names without values -A
Filter The condition last argument
Attributes Which attributes to return listed after the filter

Scope

The scope is measured from the base:

  • base: only the base entry itself.
  • one (one level): only the direct children of the base, not the base and not deeper entries.
  • sub (subtree): the base and all its descendants.
  • children (an OpenLDAP and AD-friendly extension): all descendants but not the base.

Given this tree:

TEXT
dc=example,dc=com
โ”œโ”€โ”€ ou=People
โ”‚   โ”œโ”€โ”€ uid=asmith
โ”‚   โ””โ”€โ”€ uid=bjones
โ””โ”€โ”€ ou=Groups
    โ””โ”€โ”€ cn=engineers
Base Scope Returned entries
ou=People,dc=example,dc=com base ou=People
ou=People,dc=example,dc=com one asmith, bjones
ou=People,dc=example,dc=com sub ou=People, asmith, bjones
dc=example,dc=com one ou=People, ou=Groups
dc=example,dc=com sub all six entries

Three scopes

base Just the base entry.
one Direct children only.
sub Base and everything below.

Smaller scope means a faster search

1 / 2

Choosing the narrowest base and scope is the most effective performance tip. Searching sub from the root for a known user is slow and noisy; searching sub from ou=People is much better, and base scope with the user's DN is the best of all.

Reading a single entry

To fetch one entry whose DN you know, use scope base:

Terminal
ldapsearch -x -LLL -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W \
  -b "uid=asmith,ou=People,dc=example,dc=com" -s base "(objectClass=*)"

(objectClass=*) is the conventional "match everything" filter because every entry has an object class. Some servers accept (objectClass=*) only; others also accept (&) or an empty form, so stick with the convention.

Reading the Root DSE

Terminal
ldapsearch -x -LLL -H ldap://localhost -s base -b "" "(objectClass=*)" namingContexts supportedLDAPVersion supportedControl supportedExtension

The empty base DN with base scope returns the Root DSE, which you can read anonymously on most servers. It is the first thing to check when you connect to an unfamiliar directory: it lists the naming contexts (so you know what base DNs exist) and the supported controls.

Requesting attributes

By default a search returns all user attributes. List attribute names after the filter to restrict them:

Terminal
ldapsearch -x -LLL -b "ou=People,dc=example,dc=com" "(uid=asmith)" cn mail

Special values:

  • * means all user attributes. It is the default.
  • + means all operational attributes (OpenLDAP and others).
  • 1.1 means no attributes, just DNs. Perfect for counting or existence checks.
  • *,+ returns everything.
  • -A (types only) shows attribute names without values.

Active Directory returns many attributes (hundreds on a user). Always name the ones you need, particularly in scripts and applications; it makes responses smaller and faster.

Limits

  • Size limit: the client may ask for at most N entries (-z 100); the server has its own maximum, which wins if smaller. Exceeding it yields result code 4 (sizeLimitExceeded) but you still receive the entries returned up to the limit. Active Directory's default MaxPageSize is 1000 and MaxResultSetSize is 262144, so a search for more than 1000 objects needs paging (Controls and Paging).
  • Time limit: seconds, with -l 10; code 3 (timeLimitExceeded) when exceeded.
  • Limits protect the server from expensive queries. Do not try to bypass them; narrow the search or page instead.

Aliases and referrals

An alias entry (object class alias) is a pointer to another entry. The deref setting decides whether searching follows it: never (default in most tools), search (while searching below the base), find (when locating the base) or always. Aliases are rare, especially in Active Directory, which does not use them.

A referral points to another server for part of the tree. Result code 10 contains the URLs. Many clients chase referrals automatically (-C in ldapsearch), which can cause surprising slow lookups or errors against a dead server. In Active Directory, referrals to other domains appear when searching from the forest root with the wrong base; use the Global Catalog (port 3268) for forest-wide searches.

Search scope experiments (Python stand-in)

The first block implements the scopes over a list of DNs, with a size limit that behaves like the server: it returns what it has and reports sizeLimitExceeded.

Python Scopes and size limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

This second stand-in assembles ldapsearch options from search settings, helping you remember the flags.

Python Build an ldapsearch line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

To count entries without transferring data, search with attribute 1.1 and pipe the output through grep -c '^dn:'.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which scope returns only the direct children of the base entry?

    one level returns direct children, not the base itself and not deeper entries.
  2. 2. How do you read the Root DSE?

    The Root DSE has an empty DN; a base-scope search on "" returns it.
  3. 3. What does the attribute list value 1.1 mean?

    1.1 asks for no attributes, which is perfect for existence checks and counting.
  4. 4. What happens when a search exceeds the size limit?

    Partial results come back together with sizeLimitExceeded. Use narrower searches or paging.

Summary

  • A search has a base DN, scope (base, one, sub, children), filter, attribute list and limits.
  • Use the narrowest base and scope; base scope reads one known entry.
  • Request only needed attributes: * for user, + for operational, 1.1 for none.
  • Size and time limits protect servers; exceeding them returns codes 4 or 3 with partial data.
  • Aliases and referrals are followed (or not) according to client settings.

Next: Modifying Entries: Add, Modify, Delete and Rename