Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 38 ยท LDAP Protocol and Queries

LDAP Controls, Paging, Sorting and Referrals

Learn LDAP controls: simple paged results, server-side sort, virtual list view, the ManageDsaIT and tree delete controls, referrals, and how to read a big directory safely.

Basic search and modify cover many tasks, but real directories raise other questions. How do you list 50,000 users when the server returns at most 1,000 at a time? How do you get results sorted? How do you handle a referral to another server? LDAPv3 answers these with controls: optional extras that modify how an operation runs.

This lesson explains what controls are, how the paged results control works (the one every script needs), what sorting and virtual list view add, which other controls you will meet and how referrals and continuation references behave. A Python stand-in implements paging so you can see the cookie mechanism in action.

What is a control?

A control is attached to a request (and sometimes to its response). It has:

  • an OID that names it,
  • a criticality flag: if true, the server must either honor the control or fail the whole operation (unavailableCriticalExtension); if false, the server may ignore it,
  • an optional value.

You can discover which controls a server offers by reading the Root DSE attribute supportedControl:

Terminal
ldapsearch -x -LLL -H ldap://localhost -s base -b "" supportedControl

Common controls:

OID Name Purpose
1.2.840.113556.1.4.319 Simple Paged Results Return results in chunks
1.2.840.113556.1.4.473 / 1.2.840.113556.1.4.474 Server-Side Sort request / response Sort on the server
2.16.840.1.113730.3.4.9 Virtual List View Jump to positions in a sorted list
2.16.840.1.113730.3.4.2 ManageDsaIT Treat referral entries as ordinary entries
1.2.840.113556.1.4.805 Tree Delete (Active Directory) Delete a subtree in one request
1.2.840.113556.1.4.417 Show Deleted (Active Directory) Include deleted objects in searches
1.3.6.1.1.12 Assertion Make a write conditional on a filter
1.3.6.1.1.13.1 / .2 Pre-read and post-read Get the entry before or after a modify
1.3.6.1.4.1.4203.1.9.1.1 Content Synchronization (syncrepl) Replication and change tracking

Controls extend operations

OID Names the control.
Critical? Must be honored if true.
Value Parameters such as page size.

Check supportedControl in the Root DSE

1 / 2

Simple Paged Results

Servers limit how many entries one search returns, as the previous lesson explained: Active Directory defaults to 1,000 per page and fails over that size unless paging is used. The Simple Paged Results control (RFC 2696) solves this:

  1. The client sends a search with the control: page size N and an empty cookie.
  2. The server returns up to N entries and a cookie, an opaque byte string saying where it stopped.
  3. The client sends the same search again with the cookie and gets the next page.
  4. When the server returns an empty cookie, the last page has been read.

Rules to remember:

  • Keep the same base, scope, filter and attributes on every page.
  • The cookie is only valid on the same connection and bind, and servers expire it after a while.
  • You can abandon the search by sending page size 0 and the last cookie.
  • Pages are not a consistent snapshot: entries added or removed while you page may or may not show up.

Command line tools show paging with ldapsearch -E pr=500 (OpenLDAP) and PowerShell handles it automatically (Get-ADUser -Filter * fetches all pages).

In Python with the ldap3 library, the paged search generator does the cookie handling for you:

Python
entries = conn.extend.standard.paged_search(
    search_base="dc=corp,dc=example,dc=test",
    search_filter="(objectClass=user)",
    attributes=["sAMAccountName"],
    paged_size=500,
    generator=True,
)

Server-side sorting and VLV

The Server-Side Sort control (RFC 2891) asks the server to sort results by one or more attributes with a matching ordering rule, for example ldapsearch -E sss=sn. It sorts the whole result set, so it can be expensive and servers often cap its size.

Virtual List View (VLV) builds on sort. It lets a client ask for a window into a sorted list: "give me 20 entries around position 4,200" or "starting with names near Smi". It powers address-book scroll bars. It needs a server-side index prepared by the administrator and is not available everywhere. Simple paging cannot jump to the middle; VLV can.

ManageDsaIT and referrals

A referral is an entry (object class referral) or a result that says "this part of the tree is on another server":

TEXT
ldap://other.example.com/ou=Sales,dc=example,dc=com

Normally the server returns a referral result (code 10) and the client may follow it. The ManageDsaIT control (ldapsearch -M) tells the server to treat the referral entry itself as an ordinary entry so administrators can read or edit it.

A search result reference (continuation reference) is returned in the middle of a search when part of the subtree lives elsewhere. Active Directory returns them when you search a domain that has child domains in the forest. Clients need to decide whether to follow them, and chasing referrals to unreachable hosts makes searches hang. Typical clients set "no referral chasing" and rely on the Global Catalog instead.

Other useful controls

  • Tree Delete (Active Directory) removes a whole subtree: ldapdelete -r in OpenLDAP uses a client loop, while Remove-ADObject -Recursive uses the control.
  • Show Deleted Objects reveals tombstoned or recycled objects. See the administration chapter for the AD Recycle Bin.
  • Assertion makes an update conditional ("change the phone number only if the title is still Engineer"), avoiding lost updates.
  • Pre/post read returns the entry as it was before or will be after an update, such as the new entryUUID assigned when adding.
  • Content Synchronization and DirSync (AD) let applications get only the entries that changed since the last time, which is how many sync tools and identity systems work.

If a control is marked critical and the server does not support it, the operation fails. Mark a control critical only when the operation would be wrong without it, such as a conditional delete.

Paging in action (Python stand-in)

This model keeps a cookie as the index where the last page ended. It mimics a server with a hard maximum of 1,000 entries per response, and a client that pages through 2,350 entries with page size 500.

Python Simple paged results

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.

The loop ends when the returned cookie is empty, exactly like a real client.

Sorting with an ordering rule

The server-side sort uses the attribute's ordering rule. Sorting text case-insensitively and numbers numerically are different rules, which the next stand-in shows with a client-side sort of the same data.

Python Why the ordering rule matters

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a client know it has read the last page with the paged results control?

    An empty cookie in the response means there are no more pages.
  2. 2. What does a control with criticality true require?

    If a critical control is unsupported, the server returns unavailableCriticalExtension.
  3. 3. Which feature lets a client jump to the middle of a sorted result list?

    VLV adds a window into a sorted result set; simple paging only moves forward.
  4. 4. How do you find the controls a server supports?

    The Root DSE lists supportedControl and supportedExtension OIDs.

Summary

  • Controls are OID-identified add-ons to operations, with a criticality flag and an optional value.
  • Simple Paged Results returns big result sets in chunks using a cookie until the cookie is empty.
  • Server-side sort and Virtual List View sort results and jump within them; both can be costly.
  • Referrals and search result references point to other servers; ManageDsaIT edits referral entries.
  • Active Directory adds Tree Delete, Show Deleted and DirSync controls for administration and sync.

Next: Domains, Trees and Forests