Configure LDAP Referrals in 389 Directory Server

An LDAP referral tells a client where it can continue an operation. Directory Server returns one or more LDAP URLs either in an LDAP referral result (result code 10) or, during some searches, as search-result references. Smart-referral entries store these URLs in the ref attribute, but ordinary clients normally receive the URL as a referral rather than reading ref as a regular attribute. The original server does not fetch the remote data for the client. That behaviour belongs to database chaining.

LDAP client
    |
    | Request for remote data
    v
Directory Server 1 (ldap1)
    |
    | LDAP result 10 + referral URL
    v
LDAP client
    |
    | New request (client-dependent bind)
    v
Directory Server 2 (ldap2)

The client must recognize referral results or search-result references and follow the returned URL. If the application ignores them, the operation appears to fail even when the server configured the referral correctly.

Before you start:

• Install 389 Directory Server — instance ldap1 on port 389
• Run multiple instances — second instance ldap2 on port 1389
• Manage users and groups — uid=user1 under ou=people,dc=example,dc=com
• Suffixes and backends — create a sub-suffix backend before suffix referrals

Tested on: Rocky Linux 10.2; 389 Directory Server 3.2.0.

Understand LDAP referral types

Directory Server implements these flows through global configuration (nsslapd-referral), entry attributes (ref), backend state (--state=referral, --add-referral), and replication settings (--repl-add-ref).

Plan the referral lab

This guide uses two instances on one host. That is the same layout as the multiple instances chapter:

ldap2 uses suffix dc=lab,dc=example,dc=com from its install profile. The referral URLs therefore point at ou=Users,dc=lab,dc=example,dc=com on port 1389, not at the same dc=example,dc=com tree on both hosts.

Verify the destination LDAP URL, entry, and credentials before you configure referrals on ldap1. Referral URLs are consumed by LDAP clients, so the advertised hostname must resolve from every client that follows the referral. It must not resolve only from the Directory Server host. Using localhost or 127.0.0.1 in a referral URL would direct remote clients back to themselves.

Confirm the hostname resolves:

getent hosts ldap2.example.com

Sample output:

192.168.56.109  ldap2.example.com ldap2

Test the advertised endpoint with ldapsearch. Use the same hostname and port you plan to embed in referral URLs:

ldapsearch -LLL -x -H ldap://ldap2.example.com:1389 -D "cn=Directory Manager" -y /root/dm.pw -b "ou=Users,dc=lab,dc=example,dc=com" "(uid=user1)" dn cn

When that command fails with Can't contact LDAP server, the hostname does not reach the LDAP listener from this client. Fix DNS, firewall rules, or nsslapd-listenhost before you publish the name in a referral URL. On a single host running both instances, you can confirm ldap2 is answering with ldapsearch -H ldap://127.0.0.1:1389 first, then align DNS so ldap2.example.com reaches the same listener from client systems.

If the destination tree does not exist yet, create it on ldap2:

cat > /tmp/users-ou.ldif <<'EOF'
dn: ou=Users,dc=lab,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
ou: Users

dn: uid=user1,ou=Users,dc=lab,dc=example,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: User One
sn: One
uid: user1
EOF

Apply the destination subtree LDIF on ldap2:

ldapadd -x -H ldap://127.0.0.1:1389 -D "cn=Directory Manager" -y /root/dm.pw -f /tmp/users-ou.ldif

Sample output:

adding new entry "ou=Users,dc=lab,dc=example,dc=com"

adding new entry "uid=user1,ou=Users,dc=lab,dc=example,dc=com"

A direct search on ldap2 confirms the destination entry exists before ldap1 starts returning referral URLs.

Understand the LDAP referral URL

A referral URL uses standard LDAP URL syntax:

ldap://host:port/base-dn
ldaps://host:port/base-dn

An ldap:// referral URL does not itself require StartTLS. The client must be separately configured to issue StartTLS after connecting. Use ldaps:// when the referral must explicitly direct the client to an LDAP-over-TLS listener.

Special characters in the base DN must be URL-encoded. You can list multiple ref values or --add-referral URLs when alternative destinations should be offered.

Include the non-default port in this lab (1389 for ldap2). Omitting it makes clients default to port 389 and miss the second instance.

Configure a default referral

Use a default referral when the client requests a DN outside every naming context managed locally. Set the global nsslapd-referral attribute on ldap1:

dsconf ldap1 config replace nsslapd-referral="ldap://ldap2.example.com:1389/"

Sample output:

Successfully replaced value(s) for 'nsslapd-referral': 'ldap://ldap2.example.com:1389/'

Confirm the value:

dsconf ldap1 config get nsslapd-referral

Sample output:

nsslapd-referral: ldap://ldap2.example.com:1389/

Query a naming context the instance does not manage:

ldapsearch -x -H ldap://127.0.0.1:389 -b "dc=other,dc=org" -s base dn

Sample output:

# extended LDIF
#
# LDAPv3
# base <dc=other,dc=org> with scope baseObject
# filter: (objectclass=*)
# requesting: dn 
#

# search result
search: 2
result: 10 Referral
ref: ldap://ldap2.example.com:1389/

# numResponses: 1

Result code 10 with the ref line is the expected referral response. A default referral is a fallback for unknown namespaces. It must not redirect valid entries already stored under dc=example,dc=com. Confirm local data still resolves normally:

ldapsearch -LLL -x -H ldap://127.0.0.1:389 -b "dc=example,dc=com" -s base dn

Sample output:

dn: dc=example,dc=com

Configure a smart referral for an entry

A smart referral redirects one entry, or a subtree rooted at that entry, to a remote LDAP URL. The entry needs the referral object class and a ref attribute.

Add both on user1, then apply the referral with ldapmodify:

cat > /tmp/user1-referral.ldif <<'EOF'
dn: uid=user1,ou=people,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: referral
-
add: ref
ref: ldap://ldap2.example.com:1389/uid=user1,ou=Users,dc=lab,dc=example,dc=com
EOF

Apply the smart-referral modification on ldap1:

ldapmodify -x -H ldap://127.0.0.1:389 -D "cn=Directory Manager" -y /root/dm.pw -f /tmp/user1-referral.ldif

Sample output:

modifying entry "uid=user1,ou=people,dc=example,dc=com"

Inspect the locally stored referral entry with the Manage DSA IT control (-M). OpenLDAP tools use -M to send the Manage DSA IT control. This tells Directory Server to treat the referral object as an ordinary local entry instead of returning its referral URL:

ldapsearch -LLL -M -x -H ldap://127.0.0.1:389 -D "cn=Directory Manager" -y /root/dm.pw -b "uid=user1,ou=people,dc=example,dc=com" -s base objectClass ref

Sample output:

dn: uid=user1,ou=people,dc=example,dc=com
objectClass: referral
ref: ldap://ldap2.example.com:1389/uid=user1,ou=Users,dc=lab,dc=example,dc=com

The referral object class and ref attribute confirm the smart referral is stored on ldap1.

Now search without -M to see what an ordinary application receives:

ldapsearch -LLL -x -H ldap://127.0.0.1:389 -D "cn=Directory Manager" -y /root/dm.pw -b "uid=user1,ou=people,dc=example,dc=com" -s base ref

Sample output:

# refldap://ldap2.example.com:1389/uid=user1,ou=Users,dc=lab,dc=example,dc=com

ldapsearch prints the referral URL as a # ref… continuation line rather than listing ref as a normal attribute.

In this lab, uid=user1 is a leaf entry, so the referral affects only that DN. When a smart referral is placed on a container entry, it can redirect the tree rooted at that entry.

Converting an existing entry into a smart referral means ordinary clients no longer read its locally stored attributes in the usual way. Use a dedicated referral entry when the local data must remain independently accessible.

Configure a referral for a non-replicated suffix

A suffix referral puts an entire backend into referral state. Every request for that suffix DN and its descendants returns the configured LDAP URL. The local backend provides the mapping-tree referral only. The authoritative data must already exist on the destination server. Create the sub-suffix with suffixes and backends before you add the referral.

This lab uses an unused branch so it does not conflict with ou=people in userroot:

dsconf ldap1 backend create --suffix="ou=RemoteUsers,dc=example,dc=com" --be-name="remoteusersroot" --parent-suffix="dc=example,dc=com" --create-suffix

Sample output:

The database was sucessfully created

Add the referral URL to the new backend:

dsconf ldap1 backend suffix set --add-referral="ldap://ldap2.example.com:1389/ou=Users,dc=lab,dc=example,dc=com" remoteusersroot

Switch the backend into referral state so clients receive the URL instead of local data:

dsconf ldap1 backend suffix set --state=referral remoteusersroot

Each command updates backend configuration and exits without an LDAP error when the backend name is correct.

Query the referred suffix:

ldapsearch -x -H ldap://127.0.0.1:389 -b "ou=RemoteUsers,dc=example,dc=com" -s base dn

Sample output:

# extended LDIF
#
# LDAPv3
# base <ou=RemoteUsers,dc=example,dc=com> with scope baseObject
# filter: (objectclass=*)
# requesting: dn 
#

# search result
search: 2
result: 10 Referral
matchedDN: ou=RemoteUsers,dc=example,dc=com
ref: ldap://ldap2.example.com:1389/ou=Users,dc=lab,dc=example,dc=com

# numResponses: 1

Result code 10 with matchedDN and ref confirms the suffix referral is active for the whole branch.

Configure a referral for a replicated suffix

Replication referrals redirect clients when a write targets a read-only consumer or when a replica is temporarily busy during operations such as import or reindex. Full replication setup belongs in dedicated replication chapters. The commands below apply only after replication is enabled on a consumer. I did not execute them in the lab instance shown here, which reports no replicated suffixes.

On a consumer, add a replication referral URL with --repl-add-ref:

dsconf ldap1 replication set --suffix="dc=example,dc=com" --repl-add-ref="ldap://ldap2.example.com:1389"

The command adds the URL to nsDS5ReplicaReferral in the consumer's replication configuration for the selected suffix. A read-only consumer returns the configured URL for update requests it cannot accept. A temporarily busy replica can also return the referral while operations such as import or reindexing are in progress.

Verify the value after replication is enabled on the consumer:

dsconf ldap1 replication get --suffix="dc=example,dc=com" | grep -i nsDS5ReplicaReferral

Sample output on a configured consumer:

nsDS5ReplicaReferral: ldap://ldap2.example.com:1389

replication list only shows suffixes with replication enabled. It does not replace this check. A consumer can have a referral configured even when it has no outgoing replication agreement.

List whether replication is enabled before you rely on replication referrals:

dsconf ldap1 replication list

A lab instance with no replicated suffixes returns:

There are no replicated suffixes

When the suffix appears in that list, inspect agreements with dsconf ldap1 repl-agmt list --suffix="dc=example,dc=com" on the replicated topology before you change referral URLs in production.

Test the referral response

Test referrals in three layers: the URL ldap1 returns, direct access to the destination, and whether your client library follows referrals.

Read the suffix referral without chasing referrals (default ldapsearch behaviour):

ldapsearch -x -H ldap://127.0.0.1:389 -b "ou=RemoteUsers,dc=example,dc=com" -s base dn

The output should include result: 10 Referral and the ref: line pointing at ldap2.

Confirm the destination answers on the advertised hostname when that name is reachable from your client:

ldapsearch -LLL -x -H ldap://ldap2.example.com:1389 -D "cn=Directory Manager" -y /root/dm.pw -b "ou=Users,dc=lab,dc=example,dc=com" -s sub "(uid=user1)" dn

Sample output when the hostname reaches the listener:

dn: uid=user1,ou=Users,dc=lab,dc=example,dc=com

ldapsearch -C asks the OpenLDAP client to chase referrals. Referral chasing does not guarantee that the original authenticated identity will be reused on the destination. OpenLDAP command-line referral chasing has historically followed referrals anonymously, so the destination must either allow the operation anonymously or the application must implement its own rebind callback.

An anonymous chase can succeed only when anonymous search access is allowed on ldap2:

ldapsearch -C -LLL -x -H ldap://127.0.0.1:389 -b "ou=RemoteUsers,dc=example,dc=com" -s sub "(uid=user1)" dn

Do not treat this as guaranteed to work with the Directory Manager credentials supplied to the initial server.

Secure authentication and referral traffic

The server that returns the referral does not transfer the client's authenticated session to the destination. After an LDAP referral result or search-result reference, the client opens a new connection and must bind again unless anonymous access is sufficient on the remote suffix.

Check these items before production use:

• Whether the client rebinds to the referred server with the same or a service bind DN
• Whether the user entry exists on the destination with compatible object classes
• Whether anonymous read is acceptable on the referred subtree
• Whether the client supports referral credentials or SASL rebind
• Whether the destination certificate is trusted when the URL uses ldaps://
• Whether the hostname in the URL matches the certificate SAN

Plain ldap:// referrals expose the continued operation to network observers unless the client upgrades to StartTLS or LDAPS on the second hop.

Update or remove referrals

Restore the lab in reverse order when you created these objects only for this guide.

Remove the default referral with the explicit delete operation:

dsconf ldap1 config delete nsslapd-referral

Sample output:

Removed attribute 'nsslapd-referral' completely

Confirm it is unset:

dsconf ldap1 config get nsslapd-referral

The command returns no value when the default referral is removed. Repeat the unknown-suffix search and confirm it no longer returns the configured URL.

Remove the smart referral from user1 with Manage DSA IT so the server processes the entry locally:

ldapmodify -M -x -H ldap://127.0.0.1:389 -D "cn=Directory Manager" -y /root/dm.pw <<'EOF'
dn: uid=user1,ou=people,dc=example,dc=com
changetype: modify
delete: ref
-
delete: objectClass
objectClass: referral
EOF

Sample output:

modifying entry "uid=user1,ou=people,dc=example,dc=com"

Without -M, an ordinary ldapmodify against a smart-referral entry may return the referral URL instead of changing the local entry.

Return the suffix backend to normal state:

dsconf ldap1 backend suffix set --state=backend remoteusersroot

Remove the referral URL from the backend configuration:

dsconf ldap1 backend suffix set --del-referral="ldap://ldap2.example.com:1389/ou=Users,dc=lab,dc=example,dc=com" remoteusersroot

Delete the suffix-referral backend when it was lab-only:

dsconf ldap1 backend delete remoteusersroot --do-it

Sample output:

Deleting Backend cn=remoteusersroot,cn=ldbm database,cn=plugins,cn=config :
Type 'Yes I am sure' to continue: Yes I am sure
The database, and any sub-suffixes, were successfully deleted

Remove a replication referral when replication is configured:

dsconf ldap1 replication set --suffix="dc=example,dc=com" --repl-del-ref="ldap://ldap2.example.com:1389"

After cleanup, searches against the original DNs should no longer return result code 10.

Run the following commands only when the destination entries were created exclusively for this referral lab. Delete the referred user entry first:

ldapdelete -x -H ldap://ldap2.example.com:1389 -D "cn=Directory Manager" -y /root/dm.pw "uid=user1,ou=Users,dc=lab,dc=example,dc=com"

Remove the parent OU when it is no longer needed:

ldapdelete -x -H ldap://ldap2.example.com:1389 -D "cn=Directory Manager" -y /root/dm.pw "ou=Users,dc=lab,dc=example,dc=com"

Each delete succeeds when the DN exists on ldap2 and the hostname in the URI reaches the listener.

Referrals vs database chaining

Use referrals when clients can follow LDAP URLs and you want a simple redirect. Use database chaining when applications should see one directory tree and let the server fan out remote queries.

Troubleshoot LDAP referrals

Summary

1. Default referrals (nsslapd-referral) handle unknown directory namespaces outside local naming contexts.
2. Smart referrals add referral and ref on entries; use Manage DSA IT (-M) to inspect or remove them.
3. Suffix referrals combine --add-referral with --state=referral on a dedicated backend whose data lives on the destination server.
4. Replication referrals (--repl-add-ref) on consumers redirect operations from read-only or busy replicas.
5. The client, not the original server, normally follows the referral URL and must handle authentication to the destination.

What's Next

• Database chaining — server-side proxy instead of client-side referrals
• Directory views — virtual namespaces across physical backends
• Run multiple instances — lab layout for referral targets

References

• 389 Directory Server documentation — upstream project documentation
• Red Hat Directory Server 13 — Configuring referrals — Section 4.2 covers default, smart, suffix, and replication referrals
• Red Hat Directory Server 13 — Configuration and schema reference — nsslapd-referral, ref, and backend state attributes
• RFC 3296 — named subordinate references and Manage DSA IT
• RFC 4511 — referral results versus search-result references
• RFC 4516 — LDAP URL format
• dsconf(8) man page — config delete, backend suffix set, and replication set