Chapter 4 The Directory Information Tree

The directory information tree (DIT) provides a way to refer to the data stored in your directory. The types of information stored, the physical nature of your enterprise, the applications that use your directory, and the types of replication you use shape the design of the directory tree. This chapter outlines the steps for designing a directory tree, and includes the following sections:

Introduction to the Directory Tree

The directory tree provides a way for directory data to be named and referred to by client applications. The directory tree interacts closely with other design decisions, including how you distribute, replicate, or control access to directory data.

The directory tree structure follows the hierarchical LDAP model. The directory tree organizes data, for example, by group, by people, or by geographical location. It also determines how data is partitioned across multiple servers. Because data can only be partitioned at the suffix level, an appropriate directory tree structure is required to enable you to spread your data across multiple servers.

Directory tree design also has an impact on replication configuration. If you want to replicate only portions of your directory tree, this must be taken into account when you design the directory tree. If you plan to use access controls on branch points, you must also take this into account at design time.

To manage the directory tree, it is defined in terms of suffixes, subsuffixes, and chained suffixes. A suffix is a branch or subtree whose entire contents are treated as a unit for administrative tasks. For example, indexing is defined for an entire suffix, an entire suffix may be initialized in a single operation, and a suffix is the unit of replication. Data that you wish to access and manage in the same way should be located in the same suffix. A suffix may be located at the root of the directory tree where it is sometimes called a root suffix.

The following figure shows a directory with two root suffixes, each for a separate corporate entity:

A suffix may also be a branch of another in which case it is called a subsuffix. The parent suffix does not include the contents of the subsuffix for administrative operations, and the subsuffix is therefore managed independently of its parent. However, LDAP operation results contain no information about suffixes, and directory clients are unaware of whether entries are part of root suffixes or subsuffixes.

The following figure shows a directory with a single root suffix and multiple subsuffixes for a large corporate entity:

A suffix corresponds to an individual database within the server. However, databases and their files are now managed internally by the server. Database terminology is not used for Directory Server 5.2.

Chained suffixes create a virtual directory tree by referencing suffixes on other servers. With chained suffixes, Directory Server performs the operation on the remote suffix and returns the result as if it had been performed locally. The location of the data is transparent because the client is unaware that the suffix is chained and that the data is retrieved from a remote server. A root suffix on one server may have sub-suffixes that are chained to another server, thus creating a single tree structure from the client's point of view.

In the special case of cascading chaining, the chained suffix may reference another chained suffix on the remote server, and so on. Each server will forward the operation and eventually return the result to the server handling the client's request.

Designing the Directory Tree

Directory tree design involves choosing a suffix to contain your data, determining the hierarchical relationship between data entries, and naming the entries in the directory tree hierarchy. The following sections describe the design process in more detail:

Choosing a Suffix

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

A default Directory Server installation contains multiple suffixes, one for storing data and the others for data needed by internal directory operations (such as configuration information and directory schema). For more information on the default directory suffixes, refer to "Creating Your Directory Tree" in the Directory Server Administration Guide.

Suffix Naming Conventions

All directory entries should be located below a common base entry ( the suffix.) Each suffix name should be:

In a single enterprise environment, you should choose suffix name that aligns with a DNS or internet domain name. For example, if your enterprise owns the domain name Example.com, your suffix would be:

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

You can use any attribute to name your suffix. In a hosting environment, however, the suffix should contain only the following attributes:

The presence of these attributes enables interoperability with subscriber applications. For example, a hosting organization might use these attributes to create the following suffix for one of its clients, Example.com:

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

Working With Multiple Suffixes

Each suffix that you define constitutes a unique directory tree. You can create multiple directory trees, stored in separate databases. For example, you could create separate suffixes for Example.com and Example2.com and store them in separate databases, as illustrated in Figure 4-3:

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

Creating Your Directory Tree Structure

The structure of a directory tree can be flat or hierarchical. As a general rule, your directory tree should be as flat as possible. However, a degree of hierarchy may be required when you partition data across multiple databases, prepare replication, and set access controls.

Branching Your Directory

A branch point is a point at which you define a new subdivision within the directory tree. When deciding on branch points, avoid potential problematic name changes. The likelihood of a name changing is 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.

Branch your tree to represent only the largest organizational subdivisions in your enterprise. These branch points should be limited to divisions (Corporate Information Services, Customer Support, Sales and Professional Services, and so forth). Make sure that your divisions are stable; do not perform this kind of branching if your enterprise reorganizes frequently.

Use functional or generic names rather than actual organizational names. 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, create a single branch point for that function instead of branching based on 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.

The following sections provide sample directory tree structures for an 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:

Figure 4-4 illustrates a directory tree organized using these objects in a sample enterprise, Example.com.

Try to use only the traditional branch point attributes (shown in Table 4-1). Using traditional attributes increases the likelihood of retaining compatibility with third-party LDAP client applications. In addition, traditional attributes 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
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. You should also use this attribute to represent a domain name as discussed in Suffix Naming Conventions.
ou	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.
st	A state or province name.
l	A locality, such as a city, country, office, or facility name.
dc	A domain component as discussed in Suffix Naming Conventions.

Branching in a Hosting Environment

For a hosting environment, create a tree that contains two entries of the organization(o) object class and one entry of the organizationalUnit(ou) object class beneath the suffix. A sample directory tree for an internet host, ExampleHost.com, is illustrated in Figure 4-5.

Identifying Branch Point Attributes

As you design your directory tree, you must decide what attributes will be used 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.com Corporation, appears as follows:

Each attribute-data pair represents a branch point in your directory tree. The directory tree for Example.com Corporation is illustrated in Figure 4-6.

Beneath the root suffix entry, o=ExampleHost.com,c=us, the tree is split into three branches. The ISP branch contains customer data and internal information for ExampleHost.com. The internet branch is the domain tree. The groups branch contains information about the administrative groups.

It is important to be consistent when choosing attributes for your branch points. Some LDAP client applications may be confused if the distinguished name (DN) format is inconsistent across your directory tree. For example, if l (localityName) is subordinate to o (organizationName) in one part of your directory tree, you must ensure that l is subordinate to o in all other parts of your directory.

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 in the entry itself.

Replication Considerations

When designing your directory tree, consider which entries will be replicated. 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.

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, Example.com Corporation has three primary networks known as flightdeck.Example.com, tickets.Example.com, and hangar.Example.com. They initially branch their directory tree as illustrated in Figure 4-8.

After creating the initial structure of the tree, they create additional branches as illustrated in Figure 4-9.

Figure 4-9 Detailed View of Three Primary Networks in Example.com Corporation DIT

ExampleHost.com, the internet hosting company, branch their directory as illustrated in Figure 4-10.

After creating the initial structure of their directory tree, they create additional branches as illustrated in Figure 4-11.

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 enable certain types of access control. As with replication, it is easier to group similar entries and then administer them from a single branch.

A hierarchical directory tree also enables distributed administration. For example, if you want 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, you can do so through your directory tree design.

You can also set access controls based on directory content, rather than the directory tree. The ACI filtered target mechanism enables you to 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. To make managing ACIs easier, Directory Server 5.2 enables you to obtain the effective rights of an entry, that is, the access control rights that a user has to directory entries and attributes. The effective rights functionality eases user administration, access control policy verification, and debugging. For more information, see Requesting Effective Rights Information.

Distinguished Names, Attributes, and Syntax

This section presents a brief summary of distinguished names, attributes, and syntax information.

Distinguished Names

A distinguished name (DN) is the string representation of an entry's name and location in an LDAP directory. A DN describes a path to a directory entry. Each user and group in your enterprise is represented in Directory Server by a DN. Whenever you make changes to user and group information in the directory, you use distinguished names.

A DN is made up of a number of components called relative distinguished names (RDNs). Each RDN identifies a specific entry in the directory. To ensure that every directory entry is unique, LDAP dictates that a single parent entry cannot have two identical RDNs below it.

The composition of a DN depends on the structure of the directory. Most directories are organized by more categories than just country designations and organization names. As a result, the DNs used to identify entries are longer and contain more specific attribute-data pairs. For example, the DNs for three employees or users in the same company might look like this:

In these examples, all three users work in different departments or organizational units (ou) and for the same company or organization (o), Example Corp. The third user works in a different state (st) from the first two users.

LDAP allows organizations and organizational units to contain other organizations and organizational units, enabling the representation of complex enterprises. For example, the DN for a group within a large corporation might look like this:

cn=Technical Publications, ou=Super Server Group, ou=Server Division, o=Example Corporation, o=MegaCorp, dc=megacorp, dc=com

Table 4-2 Common RDN Keywords Used in DNs
RDN Keyword	Meaning in a DN	Description
c	country	Country in which the user or group resides. Examples: c=US c=GB
cn	common name or full name	Full name of person or object defined by the entry. Examples: cn=Wally Henderson cn=Database Administrators cn=printer 3b
dc	domain component	Part of a DNS domain. This keyword is typically used at the top levels of a directory tree. For example, a user in the example.com domain might have the following DN: cn=Barbara Jones,ou=Engineering, dc=example, dc=com
l	locality	Locality in which the user or group resides. This can be the name of a city, country, township, or other geographic regions. Examples: l=Tucson l=Pacific Northwest l=Anoka County
o	organization	Organization to which the user or group belongs. Examples: o=Sun Java System Software o=Public Power & Gas
ou	organizational unit	Unit within an organization. Examples: ou=Sales ou=Manufacturing
sn	surname	User's last name. Example: sn=Henderson
st	state or province	State or province in which the user or group resides. Examples: st=Iowa st=British Columbia

Attributes

Directory attributes hold descriptive information about an entry. For example, a user entry might have attributes for a user ID, email address, given name, and password.

Table 4-3 Common User and Group Directory Attributes
Attribute Keyword	Attribute Name	Description
givenName	given name	User's first name.
mail	email address	User's or group's email address.
streetAddress	street	Street number and address of user or group defined by the entry. Example: street=12 Main Street
telephoneNumber	telephone	User's or group's telephone number. Example: (800) 555-9SUN
title	title	User's job title. Examples: title=writer title=manager
uid	user ID	Name that uniquely identifies the person or object defined by the entry.
userPassword	password	A user's password.

A user entry can include many more attributes than those listed above. In addition, you can create new attributes to meet your company's needs. For more information on attributes, see Chapter 3, "Directory Server Schema."

DN and Attribute Guidelines and Syntax

Escape commas in RDN values (or enclose them in quotation marks.) If an RDN value contains a comma, enclose the part of the name that uses the comma in double-quotation marks or escape it with a backslash. For example, to include the string Ace Industry, Corp in a DN, use the form:

When schema checking is turned on, attributes must match directory schema. If schema checking is turned on, use RDN keywords and attributes that can be recognized by Directory Server and are allowed by the entry's object classes. If schema checking is turned off, you can use all attributes, regardless of an entry's object classes. For more information on schema checking, see Schema Checking.

Specify RDNs in the same sequence or path. Remember that a DN represents a path through a directory tree. If RDN keywords are not specified in the appropriate order, Directory Server may not be able to locate an entry. For example,

because the organizational unit (ou) and organization (o) keywords are not listed in the same order.

User IDs must be unique. Exercise caution when using the ldapmodify command to create users, since the utility does not check for duplicate user IDs unless an attribute uniqueness plug-in is enabled in the directory for the user ID attribute. For more information, see "Enforcing Attribute Value Uniqueness,"in the Directory Server Administration Guide.

Naming Entries

After designing your directory tree structure, you must 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 attributes you use depend on the type of entry you are naming.

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.

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:

While this naming method allows you to instantly recognize the person associated with the entry, the entry might not be unique in an organization where two people have identical names. This leads to a problem known as DN name collisions, which are multiple entries with the same distinguished name.

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

However, this naming method can be difficult to maintain, and can lead to awkward common names for large directories.

A better method is to identify person entries with some attribute other than cn. Consider using one of the following attributes:

Whatever attribute-data pair you use for person entry RDNs, make sure that they are unique, permanent values.

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.

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:

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

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:

Sometimes you need to name an entry whose object class does not support the commonName attribute. In this case, 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 and Managing Attributes

The directory tree organizes the information of entries hierarchically. This hierarchy is a type of grouping mechanism, though it is not well suited for associations between dispersed entries, for organizations that change frequently, or for data that is repeated in many entries. Directory Server provides two additional grouping mechanisms; groups and roles, which offer more flexible associations between entries.

In addition to these grouping mechanisms, Directory Server provides the class of service (CoS) mechanism for managing attributes so that they are shared 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 to share data for coherence and space considerations.

These entry grouping and attribute management mechanisms and their associated advantages and limitations are described in the following sections:

Static and Dynamic Groups

A group is an entry that identifies the other entries that are its members. The scope of possible members of a group is the entire directory, regardless of where the group definition entry is located. Once you know the name of a group, it is easy to retrieve all of its member entries. The following list describes the characteristics of static and dynamic groups, and indicates when it is preferable to use each type:

Static groups explicitly name their member entries. An entry that 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. The member attribute contains a DN against which the server checks to establish group membership. The uniqueMember attribute contains a DN optionally followed by a hash (#) and a unique identifier label, against which the server checks membership.

Static groups are suitable for groups with few members, such as the group of directory administrators, and not for extremely large groups. You should avoid creating static groups with more than 20,000 members, because they will have very poor performance. For groups of this size and more, you should use dynamic groups or roles. If you must use static groups for 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 the filter are members of the group. These groups are dynamic because membership is defined each time the filter is evaluated. The definition entry of a dynamic group belongs to the groupOfUniqueNames and groupOfURLs object classes. The group members are listed by one or more filters represented as LDAP URL values of the memberURL attribute, or by one or more DNs as values of the uniqueMember attribute.



Note	Using the DN of another group as the uniqueMember attribute of a dynamic group enables you to place groups inside other groups. These groups are called nested groups.

Although both types of groups can identify members anywhere in the directory, group definitions should be located under an appropriately named node such as ou=Groups. 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.

Managed, Filtered, and Nested Roles

Roles are an entry grouping mechanism that enable you to determine role membership as soon as an entry is retrieved from the directory. This overcomes the main disadvantage of the group mechanism. Each role has members, or entries that possess the role. Every entry that belongs to a role is given the nsRole virtual attribute whose values are the DNs of all roles for which the entry is a member. As with groups, you can specify role members explicitly or dynamically.

The role mechanism is simple from a client perspective because the directory automatically computes role membership. The nsRole attribute is said to be virtual because it is generated on-the-fly by the server and not stored in the directory. This means that evaluating roles is more resource-intensive than evaluating groups, because the server does the work for the client application. However, checking role membership is uniform and is performed transparently on the server side.

Managed Roles

Managed roles are similar to static groups, except that membership is defined in each member entry and not in the role definition entry. With managed roles, the administrator assigns a role by adding the nsRoleDN attribute to the participating entries. The value of this attribute is the DN of the role definition entry. The static role definition entry only defines the scope of its effect. Members of the role are entries within that scope, that name the DN of the role definition entry in their nsRoleDN attribute.

Filtered Roles

Filtered roles are similar to dynamic groups: they define a filter that determines the members of the role. The value of their nsRoleFilter attribute defines the filtered role. When the server returns an entry in the scope of a filtered role that matches its filter string, that entry will contain the generated nsRole attribute identifying the role.

Nested Roles

Nested roles enable you to create roles that contain other roles. A nested role lists the definition entries of other roles and combines all the members of their roles. If an entry is a member of a role that is listed in a nested role, then the entry is also a member of the nested role.

Role Enumeration and Role Membership Enumeration

Role Enumeration

The nsRole attribute is read like any other attribute, and clients may use it to enumerate all roles to which an entry belongs. The nsRole attribute can only be used by the roles mechanism and is protected against all modifications. However, it can be read, so if you do not want to expose role membership, you should define access controls to protect it against reading.

Role Membership Enumeration

Because you can perform searches on virtual attributes, so you can search on the nsRole attribute and enumerate the members of a role. Note, however, that non-indexed attributes in a search operation may have a considerable performance impact.

Searches based on equality filters are likely to be indexed and as a result efficient, but negation searches will not be indexed and will result in poorer performance. The nsRoleDN attribute is indexed by default so searches on managed roles should be relatively efficient. For filtered and nested roles, where filters can contain both indexed and non-indexed attributes, you should ensure that the filter contains at least one indexed attribute so as not to launch a non-indexed search.

Role Scope

Directory Server provides an attribute that allows the scope of a role to be extended beyond the subtree of the role definition entry. This single-valued attribute, nsRoleScopeDN, contains the DN of the scope to be added to an existing role. The nsRoleScopeDN attribute can only be added to a nested role.

The nsRoleScopeDN attribute enables you to extend the scope of a role in one subtree to include an entry in another subtree. For example, imagine two main subtrees in the Example.com directory tree: o=eng,dc=example,dc=com ( the engineering subtree) and o=sales,dc=example,dc=com (the sales subtree.) A user in the engineering subtree requires access to a sales application governed by a role in the sales subtree (SalesAppManagedRole). To extend the scope of the role, you would:

The necessary permissions must be granted to the engineering user, so that he can access the SalesAppPlusEngNestedRole role, and in turn the sales application. In addition, the entire scope of the role must be replicated.

Role Limitations

When creating roles to support your directory service, be aware of the following limitations:

If your directory tree is distributed over several servers using the chaining feature, entries that define roles must be located on the same server as the entries possessing those roles. If one server, A, receives entries from another server, B, through chaining, those entries will contain the roles defined on B, but will not be assigned any of the roles defined on A.


Note	The restriction of extended scope to nested roles means that an administrator who previously managed roles in one domain will only have rights to use the roles that already exist in the other domain, and will not be able to create an arbitrary role in the other domain.

The filter string of a filtered role cannot be based on the values of a CoS virtual attribute. For more information see About CoS. However, the specifier attribute in a CoS definition may reference the nsRole attribute generated by a role definition. For information on creating role-based attributes, refer to "Creating Role-Based Attributes" in the Directory Server Administration Guide.

You can extend the scope of roles to different subtrees but they must be on the same server instance. Scoping roles to other servers is not supported.

Deciding Between Groups and Roles

The groups and roles mechanisms provide a degree of overlapping functionality, and both have advantages and disadvantages. Generally, the more recent roles mechanism is designed to provide frequently required functionality more efficiently. Because the choice of a grouping mechanism influences server complexity and determines how clients process membership information, you must plan your grouping mechanism carefully. You should understand the set membership queries and set management operations that will be performed, to decide which mechanism is more suitable.

Advantages of the Groups Mechanism

Static Groups are preferable to roles for enumerating members, when membership does not exceed 20,000 members.

If you only need to enumerate members of a given set, it is less costly to use static groups, provided that the number of members does not exceed 20,000. Static groups with more than 20,000 members have a negative performance impact. Enumerating members of a static group by retrieving the member attribute is easier than recovering all entries that share a role.

Static groups are preferable to roles for set management operations such as assigning and removing members.

Static groups are the simplest mechanism for assigning a user to a set or removing a user from a set, because special access rights are not required to add the user to the group.

Having the right to create the group entry automatically gives you the right to assign members to that group. This is not the case for managed and filtered roles, where the administrator must also have the right to write the nsroledn attribute to the user entry. The same access right restrictions also apply indirectly to nested roles, as the ability to create a nested role implies the ability to be able to pull together other roles that have already been defined.

Dynamic groups are preferable to roles for use in filter-based ACIs.

If you only need to find all members based on a filter, such as for designating bind rules in ACIs, use dynamic groups. Although filtered roles are similar to dynamic groups, they will trigger the roles mechanism and generate the virtual nsRole attribute. If your client does not need the nsRole value, opting for dynamic groups will avoid the overhead of this computation.

Groups are preferable to roles for adding or removing sets into or from existing sets.

If you want to add or remove a set into or from an existing set, the groups mechanism is simplest, as there are no nesting restrictions. The roles mechanism only allows nested roles to receive other roles.

Groups are preferable to roles if flexibility of scope for grouping entries is critical.

Groups are flexible in terms of scope as the scope for possible members is the entire directory, regardless of where the group definition entries are located. Although roles can also extend their scope beyond a given subtree, they can only do so by adding a scope-extending attribute nsRoleScopeDN to a nested role, which constitutes a scope extension limitation.

Advantages of the Roles Mechanism

Roles are preferable to groups if you want to enumerate members of a set and find all set membership for an entry.

Roles push membership information out to the user entry where it can be cached to make subsequent membership tests more efficient. 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. Roles can perform both operations more efficiently and with simpler clients than is possible with groups.

Roles are preferable to groups if you want to integrate your grouping mechanism with existing Directory Server functionality such as CoS, Password Policy, Account Inactivation and ACIs.

If you want to use the membership of a set "naturally" in the server, that is, take advantage of the membership computations that the server will do automatically, roles are a better option. Roles can be used in resource-oriented ACIs, as a basis for CoS, as part of more complex search filters, Password Policy, Account Inactivation, and so forth. Groups do not allow this kind of integration.

Managing Attributes with Class of Service (CoS)

The CoS mechanism enables you to share attributes between entries in a way that is transparent to applications. CoS generates virtual attributes on entries as they are retrieved, in the same way as the roles mechanism. CoS does not define membership, (it does not group entries in the way that the roles mechanism does,) but allows related entries to share data for coherence and space considerations. This section examines the CoS mechanism in more detail and is divided into the following topics:

About CoS

Imagine a directory containing thousands of entries that all have the same value for the facsimileTelephoneNumber attribute. Traditionally, to change the fax number, you would update each entry individually, a time consuming job for administrators. Using CoS, the fax number is stored in a single place, and 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. Also, because there are less values 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.


Note	As CoS virtual attributes are not indexed, referencing them in an LDAP search filter may have an impact on performance.

Generated CoS attributes can be multi-valued. Specifiers may designate several template entries, or there may be several CoS definitions for the same attribute. Alternatively, you can specify template priorities so that only one value is generated from all templates. For more information, refer to "Defining Class of Service (CoS)" in the Directory Server Administration Guide . Roles and 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 CoS template. You could use a role-based attribute to set the server look through limit on a role-by-role basis, for example.

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

You should also avoid changing CoS definitions more often than necessary. Modifications to CoS definitions do not take effect immediately, because the server caches CoS information. Although caching accelerates read access to generated attributes, when changes to CoS information occur, the server must reconstruct the cache. This task can take some time, usually in the order of seconds. During cache reconstruction, read operations may still access the old cached information, rather than the newly modified information, which means that if you change CoS definitions too frequently, you are likely to be accessing outdated data.

Cos Definition Entries and CoS Template Entries

The CoS mechanism relies on two types of entries; the CoS definition entry and the CoS template entry.

CoS Definition Entry

The CoS definition entry identifies the type of CoS and the names of the CoS attributes that will be generated. Like the role definition entry, it inherits from the LDAPsubentry object class. The location of the definition entry determines the scope of the CoS, which is the entire subtree below the parent of the CoS definition entry. All entries in the branch of the definition entry's parent are called target entries for the CoS definition. Multiple definitions may exist for the same CoS attribute, which, as a result, may be multi-valued.

The CoS definition entry is an instance of the cosSuperDefinition object class. The CoS definition entry also inherits from one of the following object classes to specify the type of CoS:

The CoS definition entry contains the attributes specific to each type of CoS for naming the virtual CoS attribute, the template DN, and the specifier attribute in target entries. By default, the CoS mechanism will not override the value of an existing attribute with the same name as the CoS attribute. However, the syntax of the CoS definition entry allows you to control this behavior.

CoS Template Entry

The CoS template entry contains the value that is generated for the CoS attribute. All entries within the scope of the CoS use the values defined here. There may be several templates, each with a different value, in which case the generated attribute may be multi-valued. The CoS mechanism selects one of these values based on the contents of both the definition entry and the target entry.


Note	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 is an instance of the cosTemplate object class. The CoS template entry contains the value or values of the attributes generated by the CoS mechanism. The template entries for a given CoS are stored in the directory tree at the same level as the CoS definition.

CoS Priorities


Note	When possible, definition and template entries should be located in the same place, for easier management. You should also name them in a way that suggests the functionality they provide. For example, a definition entry DN such as "cn=classicCosGenEmployeeType,ou=People,dc=example,dc=com" is more descriptive than "cn=ClassicCos1,ou=People,dc=example,dc=com". For more information about the object classes and attributes associated with each type of CoS, refer to "Defining Class of Service (CoS)" in the Directory Server Administration Guide.

It is possible to create CoS schemes that compete with each other to provide an attribute value. For example, you might have a multi-valued cosSpecifier in your CoS definition entry. In such a case, you can specify a template priority on each template entry to determine which template provides the attribute value. Set the template priority using the cosPriority attribute. This attribute represents the global priority of a particular template numerically. A priority of zero is the highest possible priority.

Templates that contain no cosPriority attribute are considered the lowest possible priority. In the case where two or more templates are considered to supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily.

Pointer CoS, Indirect CoS, and Classic CoS

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

Pointer CoS

Pointer CoS is the simplest type of CoS. The pointer CoS definition entry provides the DN of a specific template entry of the cosTemplate object class. All target entries have the same CoS attribute value, as defined by this template.

Pointer CoS Example

Figure 4-12 shows a pointer CoS that defines a common postal code for all of the entries stored under dc=example,dc=com. The CoS definition entry, CoS template entry and target entry are indicated.

The template entry is identified by its DN, cn=exampleUS,cn=data, in the CoS definition entry. Each time the postalCode attribute is queried on entries under dc=example,dc=com, Directory Server returns the value available in the template entry cn=exampleUS,cn=data. Therefore, the postal code will appear with the entry uid=wholiday,ou=people,dc=example,dc=com, but it is not stored there.

In a scenario where several shared attributes are generated by CoS for thousands or millions of entries, instead of existing as real attributes in each entry, the storage space savings and performance gains provided by CoS are considerable.

Indirect CoS

Indirect CoS allows any entry in the directory to be a template and provide the CoS value. The indirect CoS definition entry identifies an attribute, called the indirect specifier, whose value in a target entry determines the template used for that entry. The indirect specifier attribute in the target entry must contain a DN. With indirect CoS, each target entry may use a different template and thus have a different value for the CoS attribute.

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.

Indirect CoS Example


Caution	Because templates may be arbitrary entries anywhere in the directory tree, implementing access control for indirect CoS can become extremely complex. In deployments where performance is critical, you should also avoid overusing indirect CoS due to its resource intensive nature. In many cases, results that are similar to those made possible by indirect CoS can be achieved by limiting the location of the target entries with classic CoS or using the less flexible pointer CoS mechanism.

Figure 4-13 shows an indirect CoS that uses the manager attribute of the target entry to identify the template entry. In this way, the CoS mechanism can generate the departmentNumber attribute of all employees to be the same as their manager's, ensuring that it is always up to date.

The indirect CoS definition entry names the specifier attribute, which in this example, is the manager attribute. William Holiday's entry is one of the target entries of this CoS, and his manager attribute contains the DN of uid=cfuentes,ou=people,dc=example,dc=com. Therefore, Carla Fuentes' entry is the template, which in turn provides the departmentNumber attribute value of 318842.

Classic CoS

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

The template containing the CoS values is determined by the combination of the RDN (relative distinguished name) value of the specifier attribute in the target entry and the template's base DN.

Classic CoS templates are entries of the cosTemplate object class to avoid the performance issue associated with arbitrary indirect CoS templates.

Classic CoS Example

The classic CoS mechanism determines the DN of the template from the base DN given in the definition entry and the specifier attribute in the target entry. The value of the specifier attribute is taken as the cn value in the template DN. Template DNs for classic CoS must therefore have the following structure:

Figure 4-14 shows a classis CoS definition that generates a value for the postal code attribute.

In this example, the Cos definition entry's cosSpecifier attribute names the employeeType attribute. The combination of this attribute and the template DN identifies the template entry as cn=sales,cn=exampleUS,cn=data. The template entry then provides the value of the postalCode attribute to the target entry.

CoS Limitations

The CoS functionality is a complex mechanism which, for performance and security reasons, is subject to the following limitations.

The CoS cache is an internal Directory Server structure that keeps all CoS data in memory to improve performance. This cache is optimized for retrieving CoS data to be used in computing virtual attributes, even while CoS definition and template entries are being updated. Therefore, once definition and template entries have been added or modified, there may be a slight delay before they are taken into account. This delay depends on the number and complexity of CoS definitions, as well as the current server load, but it is usually in the order of a few seconds. Consider this latency before designing overly complex CoS configurations.

Other Directory Tree Resources

The following links provide additional information on designing your directory tree:

Previous Contents Index Next
Sun Java(TM) System Directory Server 5.2 2005Q1 Deployment Planning Guide