4.2. Designing the Directory Tree

There are several major decisions to plan in the directory tree design:
  • Choosing a suffix to contain the data.
  • Determining the hierarchical relationship among data entries.
  • Naming the entries in the directory tree hierarchy.

4.2.1. Choosing a Suffix

The suffix is the name of the entry at the root of the directory tree, and the directory data are stored beneath it. The directory can contain more than one suffix. It is possible to use multiple suffixes if there are two or more directory trees of information that do not have a natural common root.
By default, the standard Directory Server deployment contains multiple suffixes, one for storing data and the others for data needed by internal directory operations (such as configuration information and the directory schema). For more information on these standard directory suffixes, see the Red Hat Directory Server Administrator's Guide.

4.2.1.1. Suffix Naming Conventions

All entries in the directory should be located below a common base entry, the root suffix. When choosing a name for the root directory suffix, consider these four points to make the name effective:
  • Globally unique.
  • Static, so it rarely, if ever, changes.
  • Short, so that entries beneath it are easier to read on screen.
  • Easy for a person to type and remember.
In a single enterprise environment, choose a directory suffix that aligns with a DNS name or Internet domain name of the enterprise. For example, if the enterprise owns the domain name of example.com, then the directory suffix is logically dc=example,dc=com.
The dc attribute represents the suffix by breaking the domain name into its component parts.
Normally, any attribute can be used to name the root suffix. However, for a hosting organization, limit the root suffix to the following attributes:
  • dc defines an component of the domain name.
  • c contains the two-digit code representing the country name, as defined by ISO.
  • l identifies the county, city, or other geographical area where the entry is located or that is associated with the entry.
  • st identifies the state or province where the entry resides.
  • o identifies the name of the organization to which the entry belongs.
The presence of these attributes allows for interoperability with subscriber applications. For example, a hosting organization might use these attributes to create a root suffix for one of its clients, example_a, such as o=example_a, st=Washington,c=US.
Using an organization name followed by a country designation is typical of the X.500 naming convention for suffixes.

4.2.1.2. Naming Multiple Suffixes

Each suffix used with the directory is a unique directory tree. There are several ways to include multiple trees in the directory service. The first is to create multiple directory trees stored in separate databases served by Directory Server.
For example, create separate suffixes for example_a and example_b and store them in separate databases.
Including Multiple Directory Trees in a Database

Figure 4.1. Including Multiple Directory Trees in a Database

The databases could be stored on a single server or multiple servers depending on resource constraints.

4.2.2. Creating the Directory Tree Structure

Decide whether to use a flat or a hierarchical tree structure. As a general rule, try to make the directory tree as flat as possible. However, a certain amount of hierarchy can be important later when information is partitioned across multiple databases, prepare replication, and set access controls.
The structure of the tree involves the following steps and considerations:

4.2.2.1. Branching the Directory

Design the hierarchy to avoid problematic name changes. The flatter a namespace is, the less likely the names are to change. The likelihood of a name changing is roughly proportional to the number of components in the name that can potentially change. The more hierarchical the directory tree, the more components in the names, and the more likely the names are to change.
Following are some guidelines for designing the directory tree hierarchy:
  • Branch the tree to represent only the largest organizational subdivisions in the enterprise.
    Any such branch points should be limited to divisions (such as Corporate Information Services, Customer Support, Sales and Professional Services, and Engineering). Make sure that the divisions used to branch the directory tree are stable; do not perform this kind of branching if the enterprise reorganizes frequently.
  • Use functional or generic names rather than actual organizational names for the branch points.
    Names change. While subtrees can be renamed, it can be a long and resource-intensive process for large suffixes with many children entries. Using generic names that represent the function of the organization (for example, use Engineering instead of Widget Research and Development) makes it much less likely that you will need to rename a subtree after organizational or project changes.
  • If there are multiple organizations that perform similar functions, try creating a single branch point for that function instead of branching based along divisional lines.
    For example, even if there are multiple marketing organizations, each of which is responsible for a specific product line, create a single ou=Marketing subtree. All marketing entries then belong to that tree.
Branching in an Enterprise Environment

Name changes can be avoided if the directory tree structure is based on information that is not likely to change. For example, base the structure on types of objects in the tree rather than organizations. This helps avoid shuffling an entry between organizational units, which requires modifying the distinguished name (DN), which is an expensive operation.

There are a handful of common objects that are good to use to define the structure:
  • ou=people
  • ou=groups
  • ou=services
A directory tree organized using these objects might appear as shown below.
Example Environment Directory Tree

Figure 4.2. Example Environment Directory Tree

Branching in a Hosting Environment

For a hosting environment, create a tree that contains two entries of the object class organization (o) and one entry of the object class organizationalUnit (ou) beneath the root suffix. For example, Example ISP branches their directory as shown below.

Example Hosting Directory Tree

Figure 4.3. Example Hosting Directory Tree

4.2.2.2. Identifying Branch Points

When planning the branches in the directory tree, decide what attributes to use to identify the branch points. Remember that a DN is a unique string composed of attribute-data pairs. For example, the DN of an entry for Barbara Jensen, an employee of Example Corp., is uid=bjensen,ou=people,dc=example,dc=com.
Each attribute-data pair represents a branch point in the directory tree, as shown in Figure 4.4, “The Directory Tree for Example Corp.” for the directory tree for the enterprise Example Corp.
The Directory Tree for Example Corp.

Figure 4.4. The Directory Tree for Example Corp.

Figure 4.5, “Directory Tree for Example ISP” shows the directory tree for Example ISP, an Internet host.
Directory Tree for Example ISP

Figure 4.5. Directory Tree for Example ISP

Beneath the suffix entry c=US,o=example, the tree is split into three branches. The ISP branch contains customer data and internal information for Example ISP. The internet branch is the domain tree. The groups branch contains information about the administrative groups.
Consider the following when choosing attributes for the branch points:
  • Be consistent.
    Some LDAP client applications may be confused if the distinguished name (DN) format is inconsistent across the directory tree. That is, if l is subordinate to ou in one part of the directory tree, then make sure l is subordinate to ou in all other parts of the directory service.
  • Try to use only the traditional attributes (shown in Section 4.2.2.2, “Identifying Branch Points”).
    Using traditional attributes increases the likelihood of retaining compatibility with third-party LDAP client applications. Using the traditional attributes also means that they are known to the default directory schema, which makes it easier to build entries for the branch DN.

Table 4.1. Traditional DN Branch Point Attributes

Attribute Name Definition
dc An element of the domain name, such as dc=example; this is frequently specified in pairs, or even longer, depending on the domain, such as dc=example,dc=com or dc=mtv,dc=example,dc=com.
c A country name.
o An organization name. This attribute is typically used to represent a large divisional branching such as a corporate division, academic discipline (the humanities, the sciences), subsidiary, or other major branching within the enterprise, as in Section 4.2.1.1, “Suffix Naming Conventions”.
ou An organizational unit. This attribute is typically used to represent a smaller divisional branching of the enterprise than an organization. Organizational units are generally subordinate to the preceding organization.
st A state or province name.
l or locality A locality, such as a city, country, office, or facility name.

Note

A common mistake is to assume that the directory is searched based on the attributes used in the distinguished name. The distinguished name is only a unique identifier for the directory entry and cannot be used as a search key. Instead, search for entries based on the attribute-data pairs stored on the entry itself. Thus, if the distinguished name of an entry is uid=bjensen,ou=People,dc=example,dc=com, then a search for dc=example does not match that entry unless dc:example has explicitly been added as an attribute in that entry.

4.2.2.3. Replication Considerations

During the directory tree design process, consider which entries are being replicated. A natural way to describe a set of entries to be replicated is to specify the DN at the top of a subtree and replicate all entries below it. This subtree also corresponds to a database, a directory partition containing a portion of the directory data.
For example, in an enterprise environment, one method is to organize the directory tree so that it corresponds to the network names in the enterprise. Network names tend not to change, so the directory tree structure is stable. Further, using network names to create the top level branches of the directory tree is useful when using replication to tie together different Directory Servers.
For instance, Example Corp. has three primary networks known as flightdeck.example.com, tickets.example.com, and hangar.example.com. They initially branch their directory tree into three main groups for their major organizational divisions.
Initial Branching of the Directory Tree for Example Corp.

Figure 4.6. Initial Branching of the Directory Tree for Example Corp.

After creating the initial structure of the tree, they create additional branches that show the breakdown of each organizational group.
Extended Branching for Example Corp.

Figure 4.7. Extended Branching for Example Corp.

The Example ISP branches their directory in an asymmetrical tree that mirrors their organization.
Directory Branching for Example ISP

Figure 4.8. Directory Branching for Example ISP

After creating the initial structure of their directory tree, they create additional branches for logical subgroups.
Extended Branching for Example ISP

Figure 4.9. Extended Branching for Example ISP

Both the enterprise and the hosting organization design their data hierarchies based on information that is not likely to change often.

4.2.2.4. Access Control Considerations

Introducing a hierarchy into the directory tree can be used to enable certain types of access control. As with replication, it is easier to group similar entries and then administer them from a single branch.
It is also possible to enable the distribution of administration through a hierarchical directory tree. For example, to give an administrator from the marketing department access to the marketing entries and an administrator from the sales department access to the sales entries, design the directory tree according to those divisions.
Access controls can be based on the directory content rather than the directory tree. The filtered mechanism can define a single access control rule stating that a directory entry has access to all entries containing a particular attribute value. For example, set an ACI filter that gives the sales administrator access to all the entries containing the attribute value ou=Sales.
However, ACI filters can be difficult to manage. Decide which method of access control is best suited to the directory: organizational branching in the directory tree hierarchy, ACI filters, or a combination of the two.

4.2.3. Naming Entries

After designing the hierarchy of the directory tree, decide which attributes to use when naming the entries within the structure. Generally, names are created by choosing one or more of the attribute values to form a relative distinguished name (RDN). The RDN is a single component within the DN. This is the very first component shown, so the attribute used for that component is the naming attribute, because it sets the unique name for the entry. The attributes to use depends on the type of entry being named.
The entry names should adhere to the following rules:
  • The attribute selected for naming should be unlikely to change.
  • The name must be unique across the directory.
    A unique name ensures that a DN can see at most one entry in the directory.
When creating entries, define the RDN within the entry. By defining at least the RDN within the entry, the entry can be located more easily. This is because searches are not performed against the actual DN but rather the attribute values stored in the entry itself.
Attribute names have a meaning, so try to use the attribute name that matches the type of entry it represents. For example, do not use l to represent an organization, or c to represent an organizational unit.

4.2.3.1. Naming Person Entries

The person entry's name, the DN, must be unique. Traditionally, distinguished names use the commonName, or cn, attribute to name their person entries. That is, an entry for a person named Babs Jensen might have the distinguished name of cn=Babs Jensen,dc=example,dc=com.
While using the common name makes it easier to associated the person with the entry, it might not be unique enough to exclude people with identical names. This quickly leads to a problem known as DN name collisions, multiple entries with the same distinguished name.
Avoid common name collisions by adding a unique identifier to the common name, such as cn=Babs Jensen+employeeNumber=23,dc=example,dc=com.
However, this can lead to awkward common names for large directories and can be difficult to maintain.
A better method is to identify the person entries with some attribute other than cn. Consider using one of the following attributes:
  • uid
    Use the uid attribute to specify some unique value of the person. Possibilities include a user login ID or an employee number. A subscriber in a hosting environment should be identified by the uid attribute.
  • mail
    The mail attribute contains a person's email address, which is always unique. This option can lead to awkward DNs that include duplicate attribute values (such as mail=bjensen@example.com,dc=example,dc=com), so use this option only if there is not some other unique value to use with the uid attribute. For example, use the mail attribute instead of the uid attribute if the enterprise does not assign employee numbers or user IDs for temporary or contract employees.
  • employeeNumber
    For employees of the inetOrgPerson object class, consider using an employer assigned attribute value such as employeeNumber.
Whatever is used for an attribute-data pair for person entry RDNs, make sure that they are unique, permanent values. Person entry RDNs should also be readable. For example, uid=bjensen,dc=example,dc=com is preferable to uid=b12r56A,dc=example,dc=com because recognizable DNs simplify some directory tasks, such as changing directory entries based on their distinguished names. Also, some directory client applications assume that the uid and cn attributes use human-readable names.
Considerations for Person Entries in a Hosted Environment

If a person is a subscriber to a service, the entry should be of object class inetUser, and the entry should contain the uid attribute. The attribute must be unique within a customer subtree.

If a person is part of the hosting organization, represent them as an inetOrgPerson with the nsManagedPerson object class.
Placing Person Entries in the DIT

The following are some guidelines for placing person entries in the directory tree:

  • People in an enterprise should be located in the directory tree below the organization's entry.
  • Subscribers to a hosting organization need to be below the ou=people branch for the hosted organization.

4.2.3.2. Naming Group Entries

There are four main ways to represent a group:
  • A static group explicitly defines is members. The groupOfNames or groupOfUniqueNames object classes contain values naming the members of the group. Static groups are suitable for groups with few members, such as the group of directory administrators. Static groups are not suitable for groups with thousands of members.
    Static group entries must contain a uniqueMember attribute value because uniqueMember is a mandatory attribute of the groupOfUniqueNames object. This object class requires the cn attribute, which can be used to form the DN of the group entry.
  • A dynamic group uses an entry representing the group with a search filter and subtree. Entries matching the filter are members of the group.
  • Roles unify the static and dynamic group concept. See Section 4.3, “Grouping Directory Entries” for more information.
In a deployment containing hosted organizations, consider using the groupOfUniqueNames object class to contain the values naming the members of groups used in directory administration. In a hosted organization, we also recommend that group entries used for directory administration be located under the ou=Groups branch.

4.2.3.3. Naming Organization Entries

The organization entry name, like other entry names, must be unique. Using the legal name of the organization along with other attribute values helps ensure the name is unique, such as o=example_a+st=Washington,o=ISP,c=US.
Trademarks can also be used, but they are not guaranteed to be unique.
In a hosting environment, use the organization (o) attribute as the naming attribute.

4.2.3.4. Naming Other Kinds of Entries

The directory contains entries that represent many things, such as localities, states, countries, devices, servers, network information, and other kinds of data.
For these types of entries, use the cn attribute in the RDN if possible. Then, for naming a group entry, name it something like cn=administrators,dc=example,dc=com.
However, sometimes an entry's object class does not support the commonName attribute. Instead, use an attribute that is supported by the entry's object class.
The attributes used for the entry's DN do not have to correspond to the attributes actually used in the entry. However, having some correlation between the DN attributes and attributes used by the entry simplifies administration of the directory tree.

4.2.4. Renaming Entries and Subtrees

Section 4.2.3, “Naming Entries” talks about the importance of naming entries in Red Hat Directory Server. The entry names, in a sense, define the directory tree structure. Each branch point (each entry which has entries beneath it) creates a new link in the hierarchy.

Example 4.1. Building Entry DNs

                                                                  dc=example,dc=com  =>  root suffix
                                                        ou=People,dc=example,dc=com  =>  org unit
                                          st=California,ou=People,dc=example,dc=com  =>  state/province
                          l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  city
           ou=Engineering,l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  org unit
uid=jsmith,ou=Engineering,l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  leaf entry
When the naming attribute of an entry, the leftmost element of the DN, is changed, this is a modrdn operation. That's a special kind of modify operation because, in a sense, it moves the entry within the directory tree. For leaf entries (entries with no children), modrdn operations are lateral moves; the entry has the same parent, just a new name.
modrdn Operations for a Leaf Entry

Figure 4.10. modrdn Operations for a Leaf Entry

For subtree entries, the modrdn operation not only renames the subtree entry itself, but also changes the DN components of all of the children entries beneath the subtree.
modrdn Operations for a Subtree Entry

Figure 4.11. modrdn Operations for a Subtree Entry

Important

Subtree modrdn operations also move and rename all of the child entries beneath the subtree entry. For large subtrees, this can be a time- and resource-intensive process. Plan the naming structure of your directory tree hierarchy so that it will not require frequent subtree rename operations.
A similar action to renaming a subtree is moving an entry from one subtree to another. This is an expanded type of modrdn operation, which simultaneously renames the entry (even if it is the same name) and sets a newsuperior attribute which moves the entry from one parent to another.
modrdn Operations to a New Parent Entry

Figure 4.12. modrdn Operations to a New Parent Entry

Both new superior and subtree rename operations are possible because of how entries are stored in the entryrdn.db4 index. Each entry is identified by its own key (a self-link) and then a subkey which identifies its parent (the parent link) and any children. This has a format that lays out the directory tree hierarchy by treating parents and children as attribute to an entry, and every entry is describes by a unique ID and its RDN, rather than the full DN. 
numeric_id:RDN => self link  
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
P#:RDN => parent link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
C#:RDN => child link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
For example, the ou=people subtree has a parent of dc=example,dc=com and a child of uid=jsmith. 
4:ou=people
   ID: 4; RDN: "ou=People"; NRDN: "ou=people"
P4:ou=people
   ID: 1; RDN: "dc=example,dc=com"; NRDN: "dc=example,dc=com"
C4:ou=people
   ID: 10; RDN: "uid=jsmith"; NRDN: "uid=jsmith"
There are some things to keep in mind when performing rename operations:
  • You cannot rename the root suffix.
  • Subtree rename operations have minimal effect on replication. Replication agreements are applied to an entire database, not a subtree within the database, so a subtree rename operation does not require re-configuring a replication agreement. All of the name changes after a subtree rename operation are replicated as normal.
  • Renaming a subtree may require any synchronization agreements to be re-configured. Sync agreements are set at the suffix or subtree level, so renaming a subtree may break synchronization.
  • Renaming a subtree requires that any subtree-level ACIs set for the subtree be re-configured manually, as well as any entry-level ACIs set for child entries of the subtree.
  • You can rename a subtree with children, but you cannot delete a subtree with children.
  • Trying to change the component of a subtree, like moving from ou to dc, may fail with a schema violation. For example, the organizationalUnit object class requires the ou attribute. If that attribute is removed as part of renaming the subtree, then the operation will fail.