Chapter 5. Designing the directory topology Red Hat Directory Server can store a large number of entries, and, as a result, you may need to distribute your entries across several servers. The directory topology describes how you divide your directory tree among multiple physical Directory Servers and how these servers are linked. 5.1. Topology overview Directory Server supports a distributed directory where you spread the directory tree you designed in Designing-the-directory-tree across multiple physical Directory Servers. How you divide the directory across those servers influences the following performance-related points: Performance for directory-enabled applications. Availability of the directory service. Management of the directory service. The directory topology has the following key meanings: Database The database is the basic unit for jobs such as replication, backups, and data restoration. You can divide a single directory into several pieces and assign them to separate databases. You can then distribute these databases between servers, reducing the workload for each server. You can store more than one database on a single server. For example, one server might contain three different databases. For more details about multiple databases, About using multiple databases . Suffix When you divide the directory tree across several databases, each database contains a portion of the directory tree called a suffix . For example, you can use one database to store only entries in the ou=people,dc=example,dc=com suffix (branch) of the directory tree. For more details about suffixes, see About suffixes . Knowledge references (referrals and chaining) Directory Server provides knowledge references mechanisms, such as referrals and chaining, for linking directory data stored in different databases. For more details about referrals and chaining, see Using referrals and Using chaining . 5.2. Distributing the directory data By distributing the directory data, you can scale the directory across multiple servers without physically containing directory entries on each server in the enterprise. A distributed directory can therefore hold a much larger number of entries than would be possible with a single server. Additionally, you can configure the directory to hide the distribution details from the user. 5.2.1. Using multiple databases in Directory Server Directory Server stores data in LDAP Database Manager (LDBM). Each database consists of a set of large files that contain all the data assigned to it. You can store different portions of the directory trees in different databases. For example, your directory tree can appear in the following way: Figure 5.1. Example directory tree The directory in the example consist of following three sub-suffixes: ou=people,dc=example,dc=com ou=groups,dc=example,dc=com ou=services,dc=example,dc=com You can store the data of the three sub-suffixes in three separate databases in the following way: Figure 5.2. Storing suffix data in separate databases DB1 for ou=people,dc=example,dc=com DB2 for ou=groups,dc=example,dc=com DB3 for ou=services,dc=example,dc=com When you divide the directory tree among several databases, you can distribute these databases across multiple servers to reduce the workload on each server. For example, you can store three databases ( DB1 , DB2 , and DB3 ) on two servers ( Server A and Server B ). Figure 5.3. Dividing suffix databases between separate servers Server A contains DB1 and DB2 , and Server B contains DB3 . Directory Server supports adding databases dynamically, without stopping the entire directory service. 5.2.2. Suffixes in Directory Server A database contains the data for a specific suffix (a portion of the directory tree). In Directory Server, you can create a root suffix or sub-suffix. Root suffix A root suffix is the entry at the top of a tree. It can be the root of your directory tree or part of a larger tree you have designed for your Directory Server. Sub-suffix A sub-suffix is a branch under a root suffix. For example, ExampleCom creates suffixes to represent the distribution of its directory data in the following way: Figure 5.4. Directory tree for ExampleCom ExampleCom spreads its directory tree across four different databases in the following way: Figure 5.5. Directory tree spread across multiple databases The four databases contain the data for the following suffixes: The root suffix dc=example,dc=com . Along with dc=example,dc=com data, this database contains and the data for the ou=marketing,dc=example,dc=com branch of the original directory tree. The ou=testing,dc=example,dc=com sub-suffix. The ou=development,dc=example,dc=com sub-suffix. The ou=partners,ou=development,dc=example,dc=com sub-suffix. Using multiple root suffixes The directory service can contain more than one root suffix. For example, an ISP called hosts several websites, one for example_a.com and one for example_b.com . ExampleISP has the following directory structure: Figure 5.6. Directory tree with multiple root suffixes The ISP creates the following root suffixes: dc=exampleISP,dc=com with the data for the following entries: dc=exampleISP,dc=com o=ISP,dc=exampleISP,dc=com o=internet,dc=exampleISP,dc=com ou=groups,dc=exampleISP,dc=com o=example_a.com with the data for the following entries: o=example_a.com,o=ISP,dc=exampleISP,dc=com ou=people,o=example_a.com,o=ISP,dc=exampleISP,dc=com ou=groups,o=example_a.com,o=ISP,dc=exampleISP,dc=com o=example_b.com with the data for the following entries: o=example_b.com,o=ISP,dc=exampleISP,dc=com ou=people,o=example_b.com,o=ISP,dc=exampleISP,dc=com ou=groups,o=example_b.com,o=ISP,dc=exampleISP,dc=com Additional resources Storing suffixes in separate databases 5.3. Knowledge references in Directory Server Knowledge references define the relationship between the distributed data. Knowledge references are pointers to directory information held in different databases. The Directory Server provides the following types of knowledge references to link the distributed data into a single directory tree: Referrals Directory Server returns a piece of information to the client application indicating that the client application needs to contact another server to fulfill the request. Chaining Directory Server contacts other servers on behalf of the client application and returns the combined results to the client application when the operation is finished. 5.4. Using referrals in Directory Server A referral is the information returned by Directory Server that informs a client application which server to contact to proceed with a request. This redirection mechanism occurs when a client application requests a directory entry that the local server does not contain. Directory Server supports the following types of referrals: Default referrals The directory returns a default referral when a client application requests for an entry that does not belong to the local tree. You can configure default referrals at the server and suffix levels. Smart referrals Directory Server stores smart referrals on entries within the directory. Smart referrals point to servers that contain information about the sub-tree whose DN matches the DN of the entry containing the smart referral. Directory Server returns all referrals in the format of an LDAP uniform resource locator, or LDAP URL. Additional resources Default referrals in Directory Server Smart referrals in Directory Server 5.4.1. The structure of an LDAP referral Directory Server returns all referrals in the format of an LDAP URL. The LDAP URL contains the following information: The host name of the server to contact. The port number on the server that is configured to listen for LDAP requests. The base DN (for search operations) or target DN (for add, delete, and modify operations). For example, a client application searches though dc=example,dc=com branch for entries with the surname Jensen . However, a part of the directory tree is stored on the European server. A referral returns the following LDAP URL to the client application: This referral instructs the client application to contact the host europe.example.com on port 389 and submit a new search though the European branch ou=people,l=europe,dc=example,dc=com . The LDAP client application you use determines how a referral is handled. Some client applications automatically retry the operation on the server to which they have been referred. Other client applications return the referral information to the user. Most LDAP client applications that Red Hat Directory Server provides, such as the command-line utilities, automatically follow the referral. Directory Server uses the same bind credentials supplied on the initial directory request to access the server. Most client applications follow a limited number of referrals, or hops . The limit on the number of referrals reduces the time a client application spends trying to complete a directory lookup request and helps to eliminate hung processes caused by circular referral patterns. 5.4.2. Default referrals in Directory Server Directory Server returns a default referral to clients when the server or database that was contacted does not contain the requested data. For example, a client requests the following directory entry: uid=bjensen,ou=people,dc=example,dc=com . However, the server only manages entries stored under the dc=europe,dc=example,dc=com suffix. The directory returns a referral to the client with information which server to contact for entries stored under the dc=example,dc=com suffix. The client then contacts the appropriate server and resubmits the original request. You can configure default referrals at the server and suffix levels: To set the server level referral, use the server level configuration attribute nsslapd-referral . Directory Server stores the attribute value in the dse.ldif configuration file. When the server is unavailable or a client does not have permission to access the data on the local server, Directory Server returns the default referrals. To set the suffix level referral, use the suffix configuration attributes nsslapd-referral and nsslapd-state . When an entire suffix goes offline, Directory Server returns the referrals to client requests made to that suffix. 5.4.3. Smart referrals in Directory Server In addition to default referrals, Directory Server supports smart referrals that associate a directory entry or directory tree with a specific LDAP URL. Therefore, Directory Server can forward client requests to any of the following: The same namespace contained on a different server. Different namespaces on a different server. Different namespaces on the same server. Unlike default referrals, Directory Server stores smart referrals within the directory, and not in the configuration file. For example, the directory for the American office of the ExampleCom contains the ou=people,dc=example,dc=com directory branch point. To redirect requests on this branch to the ou=people branch of the European office of ExampleCom you can specify a smart referral on the ou=people entry itself. The smart referral has the following value: ldap://europe.example.com:389/ou=people,dc=example,dc=com The requests to the ou=people branch of the American directory are redirected to the European directory in the following way: Figure 5.7. Using smart referrals to redirect requests You can use the same mechanism to redirect queries to a different server that uses a different namespace. For example, an employee working in the Italian office of ExampleCom makes a request to the European directory service for the phone number of an ExampleCom employee in America. Directory Server returns the following referral: ldap://america.example.com:389/ou=people,dc=example,dc=com The following diagram shows how a referral to a different namespace works: Figure 5.8. Redirecting a query to a different server and namespace Finally, when serving multiple suffixes on the same server, you can redirect queries from one namespace to another served on the same server. For example, to redirect all queries for o=example,c=us on the local server to dc=example,dc=com , set the smart referral ldap:///dc=example,dc=com on the o=example,c=us entry. The third slash in the LDAP URL indicates that the URL points to the same server. Note A referral from one namespace to another works only for clients whose searches are based at that distinguished name. Other types of operations, such as searches below ou=people,o=example,c=US , are not performed correctly. 5.4.4. Considerations in using smart referrals Consider the following points before using smart referrals: Keep the design simple. A complex referrals web makes administration difficult. Smart referrals overuse can also lead to circular referral patterns. For example, a referral points to an LDAP URL, which in turn points to another LDAP URL, and so on until a referral somewhere in the chain points back to the original server. The following diagram shows a circular referral pattern: Figure 5.9. A circular referral pattern Redirect at major branch points. To improve security and reduce maintenance costs, limit referral usage to handle redirection at the suffix and major branch points level. Do not use smart referrals as an aliasing mechanism. Consider the security implications. Access control does not cross referral boundaries. Even if the server where the request was sent originally allows access to an entry, when a smart referral sends a client request to another server, the client application may be denied access. In addition, a client application needs credentials to authenticate to the server to which the client is referred. 5.5. Using chaining Chaining is a method for redirecting requests to another server on behalf of the client application. Chaining is implemented in the server as a plug-in. The plug-in is enabled by default. Using this plug-in, you create database links, special entries that point to data stored remotely. When a client application requests data from a database link, the database link retrieves the data from the remote database and returns it to the client. Figure 5.10. Sending a client request to a server using chaining Each database link is associated with a remote server holding data. You can also configure alternate remote servers containing replicas of the data for the database link to use when a failure occurs. For more information about configuring database links, see Creating and maintaining database links . Database links provide the following features: Invisible access to remote data The database link resolves client requests, completely hiding data distribution from the client. Dynamic management You can add or remove a part of the directory from the system while the entire system remains available to client applications. You can use the database link to temporarily return referrals to the application until you redistribute entries across the directory. You can also implement this by using a suffix that returns a referral instead of forwarding a client application to the database. Access control The database link impersonates the client application, providing the appropriate authorization identity to the remote server. You can disable user impersonation on the remote servers when you do not need access control evaluation. For more information about database links and access control evaluation, see Database links and access control evaluation . 5.6. Deciding between referrals and chaining Choose between referrals and chaining based on the specific needs of your directory. Chaining reduces client complexity at the cost of increased server complexity. However, with chaining, client applications can interact with a single server and still access the data stored on several servers. Client applications do not need to authenticate to the servers to which their requests are chained. With referrals, the client application must locate the referral and resubmit search results. A client must also be able to authenticate correctly to referred server. In addition, sometimes referrals fail when a company network uses proxies. For example, a client application may have permission to communicate with only one server inside a firewall. If that application is referred to a different server, the application might not contact it successfully. However, referrals offer more flexibility for the writers of client applications, and developers can provide better feedback to users about the progress of a distributed directory operation. 5.6.1. Evaluating access controls Chaining evaluates access controls differently from referrals. With referrals, a client entry (bind DN) must exist on all of the target servers. With chaining, the client entry does not need to be on all of the target servers. 5.6.1.1. Performing search requests using referrals The following diagram shows a client request to a server using referrals: Figure 5.11. Sending a client request to a server using referrals A search request occurs in the following way: The client application first binds with Server A . Server A contains an entry for the client that provides a user name and password, so it returns a bind acceptance message. In order for the referral to work, the client entry must be present on Server A . The client application sends the operation request to Server A . However, Server A does not contain the requested information. Instead, Server A returns a referral to the client application instructing it to contact Server B . The client application then sends a bind request to Server B . To bind successfully, Server B must also contain an entry for the client application. The bind is successful, and the client application can now resubmit its search operation to Server B . This approach requires Server B to have a replicated copy of the client entry from Server A . 5.6.1.2. Performing search requests using chaining You can resolve the problem of replicating client entries across servers through chaining. Figure 5.12. Sending a client request to a server using chaining A search request occurs in the following way: The client application binds with Server A , and Server A tries to confirm that the user name and password are correct. Server A does not contain an entry corresponding to the client application. Instead, it contains a database link to Server B that contains the actual entry of the client. Server A sends a bind request to Server B . Server B sends an acceptance response to Server A . Server A then processes the client application request using the database link. The database link contacts a remote data store located on Server B to process the search operation. In a chained system, the entry corresponding to the client application does not need to be located on the same server as the data the client requests. The following diagrams shoes how two chained servers can be used to complete a client search request. Figure 5.13. Authenticating a client and retrieving data using two different servers A search request occurs in the following way: The client application binds with Server A , and Server A confirms that the user name and password are correct. Server A does not contain an entry corresponding to the client application. Instead, it contains a database link to Server B that contains the actual entry of the client. Server A sends a bind request to Server B . Server B sends an acceptance response to Server A . Server A then processes the client request using another database link. The database link contacts a remote data store located on Server C to process the search operation. 5.6.1.3. Unsupported access controls Database links do not support the following access controls: Controls that must access the content of the user entry when the user entry is located on a different server. This includes access controls based on groups, filters, and roles. Controls based on client IP addresses or DNS domains may be denied. This is because the database link impersonates the client when it contacts remote servers. If the remote database contains IP-based access controls, it evaluates them using the database link domain rather than the original client domain. 5.7. Using indexes to improve database performance Depending on the size of the databases, searches performed by client applications can take a lot of time and resources. Therefore, to improve search performance, you can use indexes. Indexes are files that directory databases store. Separate index files are maintained for each database in your directory. Each file is named according to the attribute it indexes. The index file for a particular attribute can contain multiple types of indexes. For example, a file called cn.db contains all of the indexes for the common name ( cn ) attribute. Use different types of indexes depending on the types of applications that use your directory. Different applications may frequently search for a particular attribute, or may search your directory in a different language, or may require data in a particular format. 5.7.1. Overview of directory index types Directory Server supports the following index types: Presence index Lists entries that possess a particular attribute, such as uid . Equality index Lists entries that contain a specific attribute value, such as cn=Babs Jensen . Approximate index Allows approximate (or "sounds-like") searches. For example, an entry might contain the attribute value of cn=Babs L. Jensen . An approximate search would return this value for searches against cn~=Babs Jensen , cn~=Babs , and cn~=Jensen . Note Approximate indexes require names to be written in English using ASCII characters. Substring index Allows searches against substrings within entries. For example, your search for cn=*derson would match common names like Bill Anderson, Norma Henderson, and Steve Sanderson that contain this string. International index Improves the performance of searches for information in international directories. You can configure the index to apply a matching rule by associating a locale (internationalization OID) with the attribute you are indexing. Browsing index or virtual list view (VLV) index Improves the display performance of entries in the web console. You can create a browsing index on any directory tree branch to improve the display performance. Additional resources Managing indexes 5.7.2. Evaluating the costs of indexing Consider the following points when using indexes to improve search performance: Indexes increase the time it takes to modify entries. The more indexes you maintain, the longer it takes the directory to update the database. Index files use disk space. The more attributes you index, the more files you create. In addition, if you create approximate and substring indexes for attributes that contain long strings, the index files can grow rapidly. Index files use memory. To run more efficiently, Directory Server puts as many index files into memory as possible. Index files use memory out of the pool available depending on the database cache size. A large number of index files requires a larger database cache. Index files take time to create. Although index files save time during searches, maintaining unnecessary indexes can waste time. Maintain only the files that client applications need when using the directory.

Commands:
ldap://europe.example.com:389/ou=people,l=europe,dc=example,dc=com