Previous     Contents     Index     DocHome     Next     
iPlanet Directory Server 5.1 Deployment Guide

Chapter 4   Designing the Directory Tree

Your directory tree provides a way to refer to the data stored by your directory. The types of information you store in your directory, the physical nature of your enterprise, the applications you use with your directory, and the types of replication you use shape the design of your directory tree.

This chapter outlines the steps for designing your own directory tree. It includes the following sections:

Introduction to the Directory Tree

Your directory tree provides a means for your directory data to be named and referred to by client applications. Your directory tree interacts closely with other design decisions, including the choices available to you when you decide how to distribute, replicate, or control access to your directory data. Taking the time to design your directory tree well before deployment saves headaches later if you find it inadequate after you have launched your directory.

A well-designed directory tree provides the following:

  • Simplified directory data maintenance

  • Flexibility in creating replication policies and access controls

  • Support for the applications using your directory

  • Simplified directory navigation for directory users

The structure of your directory tree follows the hierarchical LDAP model. Your directory tree provides a way to organize your data, for example, by group, by people, or by place. It also determines how you partition data across multiple servers. For example, each database needs data to be partitioned at the suffix level. Without the proper directory tree structure, you may not be able to spread your data across multiple servers as you would like.

In addition, replication is constrained by what sort of directory tree structure you use. You must carefully define partitions for replication to work. If you want to replicate only portions of your directory tree, you need to take that into account during the design process. If you plan to use access controls on branch points, that is also a consideration in your directory tree design.

Designing Your Directory Tree

This section guides you through the major decisions you make during the directory tree design process. The directory tree design process involves the following steps:

  • Choosing a suffix to contain your data

  • Determining the hierarchical relationship among data entries

  • Naming the entries in your directory tree hierarchy

The following sections describe the directory tree design process in more detail.

Choosing a Suffix

The suffix is the name of the entry at the root of your tree, below which you store your directory data. Your directory can contain more than one suffix. You may choose to use multiple suffixes if you have two or more directory trees of information that do not have a natural common root.

By default, the standard iPlanet 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 your directory schema). For more information on these standard directory suffixes, see the iPlanet Directory Server Administrator's Guide.

Suffix Naming Conventions

All entries in your directory should be located below a common base entry, the root suffix. Consider the following recommendations for naming the root directory suffix:

  • Globally unique

  • Static, so that it rarely changes, if ever

  • 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 your enterprise. For example, if your enterprise owns the domain name of, then you should use a directory suffix of:


The dc (domainComponent) attribute represents your suffix by breaking your domain name into its component parts.

Normally, you can use any attribute that you like to name your root suffix. However, for a hosting organization, we recommend that the root suffix contain only the following attributes:

  • c (countryName)

    Contains the two-digit code representing the country name, as defined by ISO.

  • l (localityName)

    Identifies the county, city, or other geographical area where the entry is located or which is associated with the entry.

  • st

    Identifies the state or province where the entry resides.

  • o (organizationName)

    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 the following root suffix for one of its clients, Company22:


Using an organization name followed by a country designation is typical of the X.500 naming convention for suffixes.

Naming Multiple Suffixes

Each suffix that you use with your directory is a unique directory tree. There are several ways that you can include multiple trees in your directory. The first is to create multiple directory trees stored in separate databases served by Directory Server. For example, you could create separate suffixes for the Company22 and the Company44 and store them in separate databases as follows:

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

Creating Your Directory Tree Structure

You need to decide whether to use a flat or hierarchical tree structure. As a general rule, strive to make your directory tree as flat as possible. However, a certain amount of hierarchy can be important later on when you partition data across multiple databases, prepare replication, and set access controls.

The structure of your tree involves the following steps and considerations:

Branching Your Directory

Design your 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 your directory tree hierarchy:

  • Branch your tree to represent only the largest organizational subdivisions in your enterprise.

    Any such branch points should be limited to divisions (Corporate Information Services, Customer Support, Sales and Professional Services, and so forth). Make sure that the divisions you use to branch your directory tree are stable; do not perform this kind of branching if your enterprise reorganizes frequently.

  • Use functional or generic names rather than actual organizational names for your branch points.

    Names change and you do not want to have to change your directory tree every time your enterprise renames its divisions. Instead, use generic names that represent the function of the organization (for example, use Engineering instead of Widget Research and Development).

  • If you have 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 you have multiple marketing organizations, each of which is responsible for a specific product line, create a single Marketing subtree. All marketing entries then belong to that tree.

Following are specific guidelines for the enterprise and hosting environment.

Branching in an Enterprise Environment
Name changes can be avoided if you base your directory tree structure on information that is not likely to change. For example, base the structure on types of objects in the tree rather than organizations. Some of the objects you might use to define your structure are:

  • ou=people

  • ou=groups

  • ou=contracts

  • ou=employees

  • ou=services

A directory tree organized using these objects might appear as follows:

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 organizationalUnit(ou) object class beneath the root suffix. For example, the ISP I-Zed branches their directory as follows:

Identifying Branch Points

As you decide how to branch your directory tree, you will need to decide what attributes you will 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 Corporation, appears as follows:

cn=Barbara Jensen,ou=people,dc=siroe,dc=com

Each attribute-data pair represents a branch point in your directory tree. For example, the directory tree for the enterprise Corporation appears as follows:

The directory tree for I-Zed, an internet host, appears as follows:

Beneath the root suffix entry, o=i-zed,c=US, the tree is split into three branches. The ISP branch contains customer data and internal information for I-Zed. The internet branch is the domain tree. The groups branch contains information about the administrative groups.

There are some points to consider when choosing attributes for your branch points:

  • Be consistent.

    Some LDAP client applications may be confused if the distinguished name (DN) format is inconsistent across your directory tree. That is, if l is subordinate to o in one part of your directory tree, then make sure l is subordinate to o in all other parts of your directory.

  • Try to use only the traditional attributes (shown in Table 4-1).

    Using traditional attributes increases the likelihood of retaining compatibility with third-party LDAP client applications. Using the traditional attributes also means that they will be 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



    A country name.  


    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. You should also use this attribute to represent a domain name as discussed in "Suffix Naming Conventions".  


    An organizational unit. This attribute is typically used to represent a smaller divisional branching of your enterprise than an organization. Organizational units are generally subordinate to the preceding organization.  


    A state or province name.  


    A locality, such as a city, country, office, or facility name.  


    A domain component as discussed in "Suffix Naming Conventions".  

    Note A common mistake is to assume that you search your directory based on the attributes used in the distinguished name. However, the distinguished name is only a unique identifier for the directory entry and cannot be searched against.

    Instead, search for entries based on the attribute-data pairs stored on the entry itself. Thus, if the distinguished name of an entry is cn=Babs Jensen,ou=People,dc=siroe,dc=com, then a search for dc=siroe will not match that entry unless you have explicitly put dc: sun as an attribute in that entry.

Replication Considerations

During directory tree design, consider which entries you are replicating. A natural way to describe a set of entries to be replicated is to specify the distinguished name (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 you can organize your directory tree so that it corresponds to the network names in your enterprise. Network names tend not to change, so the directory tree structure will be stable. Further, using network names to create the top level branches of your directory tree is useful when you use replication to tie together different directory servers.

For example, Corporation has three primary networks known as,, and They initially branch their directory tree as follows:

After creating the initial structure of the tree, they create additional branches as follows:

As another example, ISP branch their directory as follows:

After creating the initial structure of their directory tree, they create additional branches as follows:

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

Access Control Considerations

Introducing hierarchy into your directory tree can be used to enable certain types of access control. As with replication, it is easier to group together similar entries and then administer them from a single branch.

You can also enable the distribution of administration through a hierarchical directory tree. For example, if you want give an administrator from the marketing department access to the marketing entries and an administrator from the sales department access to the sales entries, you can do so through your directory tree design.

You can set access controls based on the directory content rather than the directory tree. The ACI filtered target mechanism lets you define a single access control rule stating that a directory entry has access to all entries containing a particular attribute value. For example, you could set an ACI filter that gives the sales administrator access to all the entries containing the attribute ou=Sales.

However, ACI filters can be difficult to manage. You must decide which method of access control is best suited to your directory: organizational branching in your directory tree hierarchy, ACI filters, or a combination of the two.

Naming Entries

After designing the hierarchy of your directory tree, you need to 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 the left-most DN attribute value. The attributes you use depend on the type of entry you are naming.

Your entry names should adhere to the following rules:

  • The attribute you select for naming should be unlikely to change.

  • The name must be unique across your directory.

    A unique name ensures that a DN can refer to at most one entry in your directory.

When creating entries, define the RDN within the entry. By defining at least the RDN within the entry, you can locate the entry more easily. This is because searches are not performed against the actual DN but rather against 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 (locality) to represent an organization, or c (country) to represent an organizational unit.

The following sections provide tips on naming entries:

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=siroe,dc=com

While allowing you to instantly recognize the person associated with the entry, it might not be unique in an include people with identical names. This quickly leads to a problem known as DN name collisions, multiple entries with the same distinguished name.

You can avoid common name collisions by adding a unique identifier to the common name. For example:

cn=Babs Jensen+employeeNumber=23,dc=siroe,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 your person entries with some attribute other than cn. Consider using one of the following attributes:

  • uid

    Use the uid (userID) 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

    Use the mail attribute to contain the value for the person's email address. This option can lead to awkward DNs that include duplicate attribute values (for example:, dc=siroe,dc=com), so you should use this option only if you cannot find some unique value that you can use with the uid attribute. For example, you would use the mail attribute instead of the uid attribute if your 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 you decide to use for an attribute-data pair for person entry RDNs, you should make sure that they are unique, permanent values. Person entry RDNs should also be readable. For example, uid=bjensen, dc=siroe,dc=com is preferable to uid=b12r56A, dc=siroe,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
Here are some guidelines for placing people entries in your 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.

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. For example, you might name an organization entry as follows:


You can also use trademarks, however they are not guaranteed to be unique.

In a hosting environment, you need to include the following attributes in the organization's entry:

  • o (organizationName)

  • objectClass with values of top, organization, and nsManagedDomain

Naming Other Kinds of Entries

Your directory will contain 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 commonName (cn) attribute in the RDN if possible. For example, if you are naming a group entry, name it as follows:


However, sometimes you need to name an entry whose object class does not support the commonName attribute. Instead, use an attribute that is supported by the entry's object class.

There does not have to be any correspondence between the attributes used for the entry's DN and the attributes actually used in the entry. However, having identifying attributes visible in the DN simplifies the administration of your directory tree.

Grouping Directory Entries

Your directory tree organizes the information of your entries hierarchically. This hierarchy is a grouping mechanism, though it is not well suited for associations between dispersed entries, for often changing organizations, or for data that is repeated in many entries. Groups and roles provide more flexible associations between entries, and class of service simplifies the management of data that is shared within branches of your directory.

These grouping mechanisms are described in the following sections:

Static and Dynamic Groups

A group is an entry that identifies the other entries that are its members. When you know the name of a group, it is easy to retrieve all of its member entries.

  • Static groups explicitly name their member entries. An entry which defines a static group uses the groupOfNames or groupOfUniqueNames object class and contains the DN of each member as a value of the member or uniqueMember attribute, respectively. 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. We recommend that you do not create static groups with more than 20,000 members, because they will have very poor performance. For groups of this size and more, we recommend using dynamic groups or roles. If you must use static groups in defining groups having more than 20,000 members, use groups of groups rather than a single, large, static group.

  • Dynamic groups specify a filter, and all entries that match are members of the given group. These groups are dynamic because membership is defined every time the filter is evaluated. The definition entry of a dynamic group belongs to the groupOfURLs object class and contains one or more filters represented as LDAP URL values of the memberURL attribute.

Both types of groups may identify members anywhere in the directory. We recommend that the group definitions themselves be located under the ou=Groups branch. This makes them easy to find, for example when defining access control instructions (ACIs) that grant or restrict access when the bind credentials are members of a group.

The advantage of groups is that they make it easy to find all of their members. Static groups may simply be enumerated, and the filters in dynamic groups may simply be evaluated. The disadvantage of groups is that given an arbitrary entry, it is very difficult to name all the groups of which it is a member.

Managed, Filtered, and Nested Roles

Roles are a new entry grouping mechanism that automatically identifies all roles of which any entry is a member. When you retrieve any entry in the directory, you can immediately know the roles to which it belongs. This overcomes the main disadvantage of the group mechanism.

  • Managed roles are the equivalent of static groups, except membership is defined in each member entry and not in the role definition entry. The static role definition entry only defines the scope of its effect, which is the entire branch of its parent entry. Member of that role are entries in that branch that name the DN of the role definition entry in their nsRoleDN attribute.

  • Filtered roles are very similar to dynamic groups: they define a filter that determines the members of the role. Like all roles, the scope of the filter is defined by the location filtered role definition entry.

  • A nested role list the definition entries of other roles and combines all the members of their roles. In other words, if an entry is a member of a role that is listed in a nested role definition, the entry is also a member of the nested role.

The role mechanism is very simple to use from the client perspective because the directory server automatically computes all role membership. Every entry belonging to a role will be given the nsRole virtual attribute whose values are the DNs of all roles for which the entry is a member. The nsRole attribute is said to be virtual because it is generated on-the-fly by the server and never actually stored in the directory.

The nsRole attribute is read like any other attribute, and clients may use it to enumerate all roles to which any entry belongs. Thus it is simple to determine whether a given entry belongs to a particular role.

Deciding Between Groups and Roles

The groups and roles mechanisms provide some overlapping functionality which can lead to some ambiguity. Both methods of grouping entries have advantages and disadvantages. However, the newer roles mechanism is designed provide often needed functionality the most efficiently.

There are two general reasons to use a grouping mechanism:

  • Clients need to find all members of a group/role.

    This is what a group does most efficiently. It is more difficult to find all members of a role, because the nsRole attribute is virtual and cannot be used in a filter. However, a client can retrieve all entries in a branch and read the value of the nsRole attribute to find all role members.

  • Clients would like to know if an entry is a member of particular group/role.

    By nature, this is a computation-intensive task. In addition, it is very complex to implement based on groups. Roles were designed to solve this problem: given the structure and scope of a role definition, the server can compute membership much more efficiently than a client. Then, the client only needs to read the values of the generated nsRole attribute to find membership in any type of role.

We recommend the following designs, based on your needs:

  • If you only need to enumerate members, use static groups. Your clients can retrieve the static group definition and easily obtain the list of all member DNs.

  • If you only need to find all members based on a filter, such as for designating bind rules in ACIs, use dynamic groups. Filtered roles are equivalent to filtered groups but will trigger the roles mechanism generate the virtual nsRole attribute. If your client doesn't need the nsRole value, defining only dynamic groups will avoid the overhead of its computation.

  • If your client needs to find all the membership information about a particular entry, use roles. The server performs all computations, and the client only needs to read the values of the nsRole attribute. In addition, all types of roles appear in this attribute, allowing the client to process all roles uniformly.

  • If you have sets of entries and wish to enumerate members of a given set and to find all set membership of a given entry, use only roles. Overall, roles can do both more efficiently and with simpler clients than is possible with groups.

    Often, you can use the tree hierarchy to create sets of entries equivalent to groups. This avoids the difficulty of enumerating members of a role and maximizes the efficiency of the role-based design.

Because the choice of a grouping mechanism influences your server complexity and determines how your client processes membership information, plan your grouping mechanism carefully. Know which mechanism fits your needs and use it efficiently. Finally, consider documenting this design choice so that administrators can later maintain the policy consistently.

Class of Service

The class of service (CoS) mechanism allows you to share attributes between entries in a way that is invisible to applications. Like the role mechanism, CoS generates virtual attributes on the entries as they are retrieved. However, CoS does not define membership but rather allows related entries share data for coherence and space considerations.

For example, a directory may contain thousands of entries that all have the same value for the facsimileTelephoneNumber attribute. Traditionally, to change the fax number, you would need to update each entry individually, a large job for administrators that runs the risk of not updating all entries. Using CoS, the fax number stored in a single place, and the directory server automatically generates the facsimileTelephoneNumber attribute on every concerned entry as it is returned.

To client applications, a generated CoS attribute is retrieved just as any other attribute. However, directory administrators now have only a single fax value to manage. In addition, because there are less values actually stored in the directory, the database uses less disk space. The CoS mechanism also allows entries to override a generated value or to generate multiple values for the same attribute.

The CoS mechanism relies on two types of helper entries:

  • The CoS definition entry names the attribute that will be generated and how to determine its value. The location of the definition entry determines the scope of the CoS deviations: all entries in the branch of the definition entry's parent are called target entries for the CoS definition.

    When schema checking is turned on, the CoS attribute will be generated on all target entries that allow that attribute. When schema checking is turned off, the CoS attribute will be generated on all target entries.

  • The CoS template entry contains the value that will be generated for the CoS attribute. There may be several templates, each with a different value. The CoS mechanism will select one of them based on the contents of the definition entry and of the target entry.

There are three types of CoS that differ in how the template, and thus the generated value, is selected:

  • Pointer CoS is the simplest: the definition entry gives the DN of a specific template entry of the cosTemplate object class. All target entries will have the same CoS attribute value, as defined by this template.

  • Indirect CoS allows any entry in the directory to be a template and provide the CoS value. The definition entry names a specifier attribute that is present in target entries. This attribute must contain a DN, and its value gives the template used for a given target.

    For example, an indirect CoS that generates the departmentNumber attribute may use an employee's manager as the specifier. When retrieving a target entry, the CoS mechanism will use the DN value of the manager attribute as the template. It will then generate the departmentNumber attribute for the employee using the same value as the manager's department number.

    Avoid overusing indirect CoS. Because templates may be arbitrary entries anywhere in the directory tree, controlling access is much more difficult. Also, avoid indirect CoS particularly where performance is critical.

  • Classic CoS combines the pointer and indirect CoS behavior. The CoS definition gives both a template base DN and the name of a specifier attribute. The value of the specifier attribute in target entries is used to construct the DN of the template entry as follows:


    Classic CoS templates are entries of the cosTemplate object class to avoid the performance issue associated with arbitrary indirect CoS templates. We recommend keeping templates in the same place as the definition entries and giving them meaningful names to simplify the administration of the CoS mechanism.

The generated CoS attributes may be multivalued from several templates. Specifiers may designate several template entries, or there may be several CoS definitions for the same attribute. Alternatively, you may specify template priorities so that only one value is generated from all chosen templates. For more information, see the iPlanet Directory Server Administrator's Guide.

Roles and the Classic CoS can be used together to provide role-based attributes. These attributes appear on an entry because it possesses a particular role with an associated class of service template. For example, you could use a role-based attribute to set the server look through limit on an role-by-role basis.

CoS functionality can be used recursively. In other words, iPlanet Directory Server lets you generate attributes through CoS that depend on other attributes generated through CoS. Complex CoS schemes may simplify client application access to information and ease administration of repeated attributes, but they also increase management complexity and degrade server performance. Avoid overly complex CoS schemes, for example, many indirect CoS schemes can be redefined as classic or pointer CoS.

Finally, avoid changing CoS definitions more often than necessary. Modifications to CoS definitions do not take effect immediately, because the server caches CoS information. Caching accelerates read access to generated attribute entries. When changes to CoS information occur, the server must reconstruct the cache, a task that takes some time, usually on the order of seconds. During cache reconstruction, read operations may still access the old cached information, rather than the newly modified information.

Directory Tree Design Examples

The following sections provide examples of directory trees designed to support a flat hierarchy as well as several examples of more complicated hierarchies.

Directory Tree for an International Enterprise

To support an international enterprise, root your directory tree in your Internet domain name and then branch your tree for each country where your enterprise has operations immediately below that root point. In "Suffix Naming Conventions", you are advised to avoid rooting your directory tree in a country designator. This is especially true if your enterprise is international in scope.

Because LDAP places no restrictions on the order of the attributes in your DNs, you can use the c (countryName) attribute to represent each country branch as follows:

However, some administrators feel that this is stylistically awkward, so instead you could use the l (locality) attribute to represent different countries:

Directory Tree for an ISP

Internet service providers (ISPs) may support multiple enterprises with their directories. If you are an ISP, consider each of your customers as a unique enterprise and design their directory trees accordingly. For security reasons, each account should be provided with a unique directory tree that has a unique suffix and an independent security policy.

You can assign each customer a separate database, and store these databases on separate servers. Placing each directory tree in its own database allows you to back up and restore data for each directory tree without affecting your other customers.

In addition, partitioning helps reduce performance problems caused by disk contention, and reduces the number of accounts potentially affected by a disk outage.

For example, the directory tree for I-Zed, an ISP, appears as follows:

Other Directory Tree Resources

Take a look at the following links for more information about designing your directory tree:

Previous     Contents     Index     DocHome     Next     
Copyright © 2002 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated February 26, 2002