サポートコンソール開発者トライアルの開始お問い合わせ

このコンテンツは選択した言語では利用できません。

Chapter 2. Configuring referrals to redirect requests to other hosts or entries

Referrals inform client applications to perform the operation on a different host, suffix, or entry. These pointers help maintain high availability and directory integrity by ensuring that requests for non-existent entries or offline databases redirect to active resources rather than failing.

2.1. Configure a referral for a replicated suffix to redirect requests to a different host by using the command line
リンクのコピー

In Red Hat Directory Server, replication handles the suffix level referrals. With the dsconf utility, you can add, delete, and list referrals for a replicated suffix.

The replicated suffix returns a referral in the following cases:

  • When the server attempts to perform a write operation over a read-only replica.
  • When the server attempts to perform an operation over a busy replica, for example, when an import or reindex task is in progress.

Prerequisites

  • The destination of the referral exists.
  • You have root permissions.

Procedure

  • Add a referral for a replicated suffix by using the dsconf command with the --repl-add-ref option: 

    # dsconf <server1_instance_name> replication set --suffix="ou=people,dc=example,dc=com" --repl-add-ref="ldap://server2.example.com:389"

    The command sets the referral for the ou=people,dc=example,dc=com suffix on the server1.example.com host that points to the server2.example.com host.

  • Delete a referral for a replicated suffix by using the dsconf command with the --repl-del-ref option: 

    # dsconf <server1_instance_name> replication set --suffix "ou=people,dc=example,dc=com" --repl-del-ref ldap://server2.example.com:389

    The command deletes the referral that points to the server2.example.com host.

Verification

  • List referrals for the replicated suffix: 

    # dsconf <server1_instance_name> replication get --suffix "ou=people,dc=example,dc=com" | grep nsDS5ReplicaReferral
     
    nsDS5ReplicaReferral: ldap://server2.example.com:389

2.2. Redirect requests for non-existent DNs to a different directory by using a default referral
リンクのコピー

Set up a default referral as a fallback solution when clients access a distinguished name (DN) that does not exist in the directory. This global redirect guides the client to a different LDAP server to continue the search.

This can occur, for example, after a migration to Red Hat Directory Server (RHDS) with a new directory structure. If a client application still expects the old directory structure, the default referral redirects these requests to the previous LDAP server when the application accesses DNs that do not exist.

Prerequisites

  • The LDAP directory RHDS refers to exists.
  • You have root permissions.

Procedure

  • Add the default referral: 

    # dsconf <server1_instance_name> config replace nsslapd-referral="ldap://server2.example.com/"

    The command adds a default referral to RHDS instance on server1, and if a client searches for an entry that does not exist, RHDS redirects the request to server2.example.com.

Verification

  • Search for a non-existent DN by using an LDAP client that can handle LDAP referrals.

    Note that the OpenLDAP client utilities do not support following LDAP referrals. For example, a search using the ldapsearch utility returns only the referral information and not the actual result from the destination directory: 

    # ldapsearch -H ldap://server1.example.com -x -D "cn=Directory Manager" -W -b "dc=<non_existent_DN>,dc=example,dc=com"
     
    ...
# search result
search: 2
result: 10 Referral
ref: ldap://server2.example.com/

2.3. Redirect requests for a specific entry to a different host or entry by using smart referrals
リンクのコピー

Configure smart referrals to automatically redirect a client request for an entry or a tree to a different LDAP server. The destination of the referral can be in the same directory or on a different host.

To use smart referrals, the entry you want to redirect, requires:

  • The referral object class
  • The ref attribute set to the destination LDAP URL

The procedure updates an existing directory entry. Red Hat Directory Server (RHDS) then redirects requests for this entry to an entry on a different host.

Prerequisites

  • The destination of the referral exists.
  • You have root permissions.

Procedure

  • Add the referral object class and the ref attribute to the entry that requires a redirect: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server1.example.com -x << EOF
dn: uid=example,ou=People,dc=example,dc=com
changetype: modify
add: objectclass
objectclass: referral
-
add: ref
ref: ldap://server2.example.com/uid=demo,ou=People,dc=example,dc=com
EOF
     
    modifying entry "uid=example,ou=People,dc=example,dc=com

    The ref: ldap://server2.example.com/uid=demo,ou=People,dc=example,dc=com statement in the uid=example,ou=People,dc=example,dc=com entry defines that RHDS redirects requests for uid=example,ou=People,dc=example,dc=com to the uid=demo,ou=People,dc=example,dc=com entry on server2.example.com.

Verification

  • Search the entry that contains the newly added referral using an LDAP client that can handle referrals:

    Note that the OpenLDAP client utilities do not support following LDAP referrals. For example, a search using the ldapsearch utility returns only the referral information and not the actual result from the destination directory: 

    # ldapsearch -H ldap://server1.example.com -x -D "cn=Directory Manager" -W -b "uid=example,ou=People,dc=example,dc=com"
     
    ...
# search result
search: 2
result: 10 Referral
ref: ldap://server2.example.com/uid=demo,ou=People,dc=example,dc=com

2.4. Redirect requests for a non-replicated suffix to a different host or entry by using the command line
リンクのコピー

By using a suffix referral, you can redirect requests from a non-replicated suffix and its sub-entries to a specific LDAP URL. The destination of the referral can be in the same directory or on a different host.

For example, configure a referral for the ou=People,dc=example,dc=com non-replicated suffix on server1.example.com. After the referral is configured, Red Hat Directory Server redirects requests for this suffix and sub-entries to the ou=users,dc=example,dc=com entry on server2.example.com.

Prerequisites

  • The destination of the referral exists.
  • You have root permissions.

Procedure

  1. Optional: Identify the suffixes and databases that are already in use: 

    # dsconf <server1_instance_name> backend suffix list
dc=example,dc=com (userroot)
...

    The name in parentheses is the database that stores the data of the corresponding suffix. You must choose a unique database name for the new sub-suffix in the next step.

  2. Create the sub-suffix: 

    # dsconf <server1_instance_name> backend create --suffix="ou=people,dc=example,dc=com" --be-name="people" --parent-suffix="dc=example,dc=com"

    The command creates the ou=people,dc=example,dc=com sub-suffix along with the people database, under the dc=example,dc=com parent suffix.

  3. Add the referral to the people database that holds the suffix you want to redirect: 

    # dsconf <server1_instance_name> backend suffix set --add-referral="ldap://server2.example.com:389/ou=users,dc=example,dc=com" people

  4. Update the people database status: 

    # dsconf <server1_instance_name> backend suffix set --state=referral people

Verification

  • Use an LDAP client that can handle LDAP referrals, and search for the entry that contains the referral.

    Note that the OpenLDAP client utilities do not support following LDAP referrals. For example, a search using the ldapsearch utility returns only the referral information and not the actual result from the destination directory: 

    # ldapsearch -H ldap://server1.example.com -x -D "cn=Directory Manager" -W -b "ou=people,dc=example,dc=com"
     
    ...
# search result
search: 2
result: 10 Referral
ref: ldap://server2.example.com/ou=users,dc=example,dc=com

2.5. Redirect requests for a non-replicated suffix to a different host or entry by using the web console
リンクのコピー

By using a suffix referral, you can redirect requests for a non-replicated suffix and its sub-entries to a specific LDAP URL. The destination of the referral can be in the same directory or on a different host.

For example, configure a referral for the ou=People,dc=example,dc=com non-replicated suffix on server1.example.com. After the referral is configured, Red Hat Directory Server (RHDS) redirects requests for this suffix and sub-entries to the ou=users,dc=example,dc=com entry on server2.example.com.

Prerequisites

  • The destination of the referral exists.
  • You are logged in to the instance in the web console.

Procedure

  1. Open the Database menu.

  2. Create the sub-suffix that RHDS must redirect:

    1. Select an entry from the Suffixes list to which you want to add the sub-suffix.
    2. Click Suffix Tasks Create Sub Suffix.
    3. Enter the first part of the sub-suffix distinguished name (DN), ou=People, and a database name, such people.
    4. In the Initialization Option field, select Create The Top Suffix-Entry .
    5. Click Create Sub-Suffix.

  3. Create the referral for the new sub-suffix:

    1. Select the newly created sub-suffix from the list.
    2. Navigate to the Referrals tab and click Create Referral.

    3. Fill in the fields to create the referral URL:

      add referral
    4. Click Create Referral.

  4. Update the database state:

    1. Select the sub-suffix from the list.
    2. On the Settings tab, select Referral from the Backend State field.
    3. Click Save Configuration.

Verification

  • Use an LDAP client that can handle LDAP referrals, and search for the entry that contains the referral.

    Note that the OpenLDAP client utilities do not support following LDAP referrals. For example, a search using the ldapsearch utility returns only the referral information and not the actual result from the destination directory: 

    # ldapsearch -H ldap://server1.example.com -x -D "cn=Directory Manager" -W -b "ou=people,dc=example,dc=com"
...
# search result
search: 2
result: 10 Referral
ref: ldap://server2.example.com/ou=users,dc=example,dc=com
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

Legal Notice

Theme

© 2026 Red Hatトップに戻る