Chapter 5 Advanced Entry Management

You can group the entries contained within your directory to simplify the management of user accounts. Netscape Directory Server (Directory Server) supports a variety of methods for grouping entries and sharing attributes between entries.

This chapter describes the following grouping mechanisms and their procedures:

To take full advantage of the features offered by roles and class of service, determine your directory topology in the planning phase of your directory deployment. Refer to the Netscape Directory Server Deployment Guide for more information.

Using Groups

Groups are a mechanism for associating entries for ease of administration. This mechanism was provided with previous versions of Directory Server and should be used primarily for compatibility with older versions of the server.

The following sections describe managing static and dynamic groups. For a conceptual overview of groups, refer to the Netscape Directory Server Deployment Guide. For more information about administering groups, refer to Managing Servers with Netscape Console.

Managing Static Groups

Static groups allow you to group entries by specifying the same group value in the DN attribute of any number of users. This section includes the following procedures for creating and modifying static groups:

Note

If you have a user that is remote from the definition of the static group, then you can use the Referential Integrity Plug-in to ensure that deleted user entries are automatically deleted from the static group.

For more information about using referential integrity with chaining, refer to Configuring the Chaining Policy.

Adding a New Static Group

In the Directory Server Console, select the Directory tab.
In the left pane, right-click the entry under which you want to add a new group, and select New > Group.

You can also go to the Object menu and select New > Group.
Click General in the left pane. Type a name for your new group in the "Group Name" field.

The group name is required.
Enter a description of the new group in the "Description" field.
Click Members in the left pane. In the right pane, select the Static Group tab. Click Add to add new members to the group.

The standard "Search users and groups" dialog box appears.
In the Search drop-down list, select what sort of entries to search for (users, groups, or both) then click Search. Select one of the entries returned, and click OK.
Click Languages in the left pane to add language-specific information for your group.
Click OK to create your new group. It appears in the right pane.

Modifying a Static Group

In the Directory Server Console, select the Directory tab.

The directory contents appear in the left pane.
Double-click the entry you want to modify, or select Open from the Object menu.

The Edit Group dialog box appears.
Make your changes to the group information. Click OK.

To view your changes, go to the View menu, and select Refresh.

Note

The Console for managing static groups may not display all possible selections during a search operation if there is no VLV index for users' search.

You may notice this problem only when the number of users is 1000 or more and there is no VLV index for search. To work around the problem, create a VLV index for the users suffix with filter (objectclass=person) and scope sub-tree.

Managing Dynamic Groups

Dynamic groups filter users based on their DN and include them in a single group. This section contains the following procedures for creating and modifying dynamic groups:

Adding a New Dynamic Group

Follow steps 1-4 of Adding a New Static Group.
Click Members in the left pane. In the right pane, select the Dynamic Group tab. Click Add to create a LDAP URL for querying the database.

The standard "Construct and Test LDAP URL" dialog box displays.
Enter an LDAP URL in the text field or select Construct to be guided through the construction of an LDAP URL.
Click Languages in the left pane to add language-specific information for your group.
Click OK to create your new group.

Your new group appears in the right pane.

Modifying a Dynamic Group

In the Directory Server Console, select the Directory tab.

The directory contents appear in the left pane.
Double-click the entry you want to modify, or select Properties from the Object menu.

The Edit Group dialog box appears.
Make your changes to the group information. Click OK.

To view your changes, go to the View menu, and select Refresh.

Note

The Console for managing dynamic groups may not display all possible selections during a search operation if there is no VLV index for users' search.

You may notice this problem only when the number of users is 1000 or more and there is no VLV index for search. To work around the problem, create a VLV index for the users suffix with filter (objectclass=person) and scope sub-tree.

Using Roles

Roles are a new entry grouping mechanism that unify the static and dynamic groups described in the previous sections. Roles are designed to be more efficient and easier to use for applications. For example, an application can locate the role of an entry, rather than select a group and browse the members list.

This section contains the following topics:

About Roles

Roles unify the static and dynamic group concept supported by previous versions of Directory Server.

You can use roles to:

Enumerate the members of a role.

Having an enumerated list of role members can be useful for resolving queries for role members quickly.

Determine whether a given entry possesses a particular role.

Knowing the roles possessed by an entry can help you determine whether the entry possesses the target role.

Enumerate all the roles possessed by a given entry.
Assign a particular role to a given entry.
Remove a particular role from a given entry.

With managed roles, you can do everything you would normally do with static groups, and you can filter members using filtered roles as you used to do with dynamic groups. Roles are easier to use than groups, more flexible in their implementation, and reduce client complexity.

However, evaluating roles is more resource-intensive because the server does the work for the client application. With roles, the client application can check role membership by searching the nsRole attribute. The nsRole attribute is a computed attribute, which identifies to which roles an entry belongs; the nsRole attribute is not stored with the entry itself. From the client application point of view, the method for checking membership is uniform and is performed on the server side.

Note

Use the nsRole attribute, not the nsRoleDN attribute, to evaluate role membership.

Each role has members, or entries that possess the role. You can specify members either explicitly or dynamically. How you specify role membership depends upon the type of role you are using. Directory Server supports three types of roles:

Managed roles -- A managed role allows you to create an explicit enumerated list of members.
Filtered roles -- A filtered role allows you to assign entries to the role depending upon the attribute contained by each entry. You do this by specifying an LDAP filter. Entries that match the filter are said to possess the role.
Nested roles -- A nested role allows you to create roles that contain other roles.

For more information about how roles work, refer to Netscape Directory Server Deployment Guide.

The concept of activating/inactivating roles is introduced to enable you to activate/inactivate groups of entries in just one operation. That is, you can temporarily disable the members of a role by inactivating the role to which they belong.

When a role is said to be inactivated, it does not mean that you cannot bind to the server using that role entry. The meaning of an inactivated role is that you cannot bind to the server using any of the entries that belong to that role--the entries that belong to an inactivated role will have the nsaccountlock attribute set to true.

In the case of the nested role, an inactivated nested role means that you cannot bind to the server using an entry that belongs to a role that is a member of the nested role. All the entries that belong to a role that directly or indirectly are members of the nested role (one may have several levels of nested roles) will have nsaccountlock set to true.

Managing Roles Using the Console

This section contains the following procedures for creating and modifying roles:

When you create a role, you need to decide whether a user can add themselves or remove themselves from the role. Refer to Using Roles Securely for more information about roles and access control.

Creating a Managed Role

Managed roles allow you to create an explicit enumerated list of members. Managed roles are added to entries by adding the nsRoleDN attribute to the entry.

To create and add members to a managed role:

In the Directory Server Console, select the Directory tab.
Browse the tree in the left navigation pane, and select the parent entry for your new role.
Go to the Object menu, and select New > Role.

You can also right click the entry and select New > Role.

The Create New Role dialog box is displayed.
Click General in the left pane. Type a name for your new role in the "Role Name" field.

The role name is required.
Enter a description of the new role in the "Description" field.
Click Members in the left pane.

A search dialog box appears briefly.
In the right pane, select Managed Role. Click Add to add new entries to the list of members.

The standard "Search users and groups" dialog box appears.
In the Search drop-down list, select Users from the Search drop-down list, then click Search. Select one of the entries returned, and click OK.
When you have finished adding entries to the role, click OK.

The new role appears in the right pane.

Creating a Filtered Role

You assign entries to a filtered role depending upon a particular attribute contained by each entry. You do this by specifying an LDAP filter. Entries that match the filter are said to possess the role.

To create and add members to a filtered role:

Follow steps 1-5 of Creating a Managed Role.
Click Members in the left pane.

A search dialog box appears briefly.
In the right pane, select Filtered Role.
Enter an LDAP filter in the text field, or click Construct to be guided through the construction of an LDAP filter.
If you click Construct, the standard LDAP URL construction dialog appears. Disregard the LDAP Server Host, Port, Base DN, and Search (as you cannot specify a search scope for filtered role definitions) fields.
1. Select the types of entries you want to filter from the "For" drop-down list.
  
  You can choose between users, groups, or both.
2. Select an attribute from the "Where" drop-down list. The two fields following it allow you to refine your search by selecting one of the qualifiers from the drop-down list (such as contains, does not contain, is, is not) and enter an attribute value in the text box. To add additional filters, click More. To remove unnecessary filters, click Fewer.
  
  Click OK to save your filter.
Click Test to try your filter.

A Filter Test Result dialog box displays the entries matching your filter.
Click OK.

The new role appears in the right pane.

Creating a Nested Role

Nested roles allow you to create roles that contain other roles. Before you create a nested role, another role must exist. When you create a nested role, the Console displays a list of the roles available for nesting. The roles nested within the nested role are specified using the nsRoleDN attribute.

To create and add members to a nested role:

Follow steps 1-5 of Creating a Managed Role.
Click Members in the left pane.

A search dialog box appears briefly.
In the right pane, select Nested Role.
Click Add to add roles to the list.The members of the nested role are members of other existing roles.

The Role Selector dialog box appears.
Select a role from the "Available roles" list, and click OK.
Click OK.

The new role appears in the right pane.

Viewing and Editing an Entry's Roles

To view or edit a role associated with an entry from the Console:

In the Directory Server Console, select the Directory tab.
In the left navigation pane, browse the tree, and select the entry for which you want to view or edit a role.
Select Set Roles from the Object menu.

The Roles dialog box displays.
Select the Managed Roles tab to display the managed roles to which this entry belongs.

To add a new managed role, click Add, and select an available role from the Role Selector window. Click OK.

To remove a managed role, select it, and click Remove.

To edit a managed role associated with an entry, click Edit. The Edit Entry dialog box displays. Make any changes to the general information or members and click OK.
Select the Other Roles tab to view the filtered or nested roles to which this entry belongs.

Click Edit to make changes to any filtered or nested roles associated with the entry. Click OK to save your changes.
Click OK to save your changes once you have finished modifying the roles.

Modifying a Role Entry

To edit an existing role:

In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for your role. Roles appear in the right pane with other entries.
Double-click the role.

The Edit Entry dialog box appears.
Click General in the left pane to change the role name and description.
Click Members in the left pane to change the members of managed and nested roles or to change the filter of a filtered role.
Click OK to save your changes.

Making a Role Inactive

You can temporarily disable the members of a role by inactivating the role to which they belong. Inactivating a role inactivates the entries possessed by the role, not the role itself.

To temporarily disable the members of a role:

In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for your role. Roles appear in the right pane with other entries.
Select the role. Select Inactivate from the Object menu.

You can also right-click the role and select Inactivate from the menu.

The role is inactivated.

To see the inactivated entries, select Inactivation State from the View menu. A red slash through the role icon indicates that the role has been inactivated.

Reactivating a Role

To reactivate a disabled role:

In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for your role. Roles appear in the right pane with other entries.
Select the role. Select Activate from the Object menu.

You can also right-click the role and select Activate from the menu.

The role is reactivated.

To see inactivated entries, select Inactivation State from the View menu.The role icon appears as normal, indicating that the role is active.

Deleting a Role

Deleting a role deletes the role only, not its members.

To delete a role:

In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for your role. Roles appear in the right pane with other entries.
Right-click the role, and select Delete.

A dialog box appears asking you to confirm the deletion. Click Yes.
The Deleted Entries dialog box appears to inform you that the role was successfully deleted. Click OK.

Note

Deleting a role deletes the role entry but does not delete the nsRoleDN attribute for each role member. If you want to delete the nsRoleDN attribute for each role member, enable the Referential Integrity Plug-in, and configure it to manage the nsRoleDN attribute. For more information on the Referential Integrity Plug-in, see Maintaining Referential Integrity.

Managing Roles Using the Command-Line

Roles inherit from the ldapsubentry object class, which is defined in the ISO/IEC X.509 standard. In addition, each type of role has two specific object classes that inherit from the nsRoleDefinition object class. Once you create a role, you assign members to it as follows:

Members of a managed role have the nsRoleDN attribute in their entry.
Members of a filtered role are entries that match the filter specified in the nsRoleFilter attribute.
Members of a nested role are members of the roles specified in the nsRoleDN attributes of the nested role definition entry.

Table 5-1 lists the new object classes and attributes associated with each type of role.

Table 5-1 Object Classes and Attrributes for Roles


Role Type	Object Classes	Attributes
Managed Role	nsSimpleRoleDefinition nsManagedRoleDefinition	Description. Optional.
Filtered Role	nsComplexRoleDefinition nsFilteredRoleDefinition	nsRoleFilter Description. Optional.
Nested Role	nsComplexRoleDefinition nsNestedRoleDefinition	nsRoleDN Description. Optional.

Note

In some cases, you need to protect the value of the nsRoleDN attribute with an ACI, as the attribute is writable. For more information about security and roles, refer to Using Roles Securely.

Examples: Managed Role Definition

You want to create a role to be assigned to all marketing staff. Run the ldapmodify script as follows:

ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389

Specify the managed role as follows:

dn: cn=Marketing,ou=people,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsSimpleRoleDefinition
objectclass: nsManagedRoleDefinition
cn: Marketing
description: managed role for marketing staff

Notice that the nsManagedRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsSimpleRoleDefinition object classes.

Assign the role to a marketing staff member named Bob by doing an ldapmodify as follows:

ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389
dn: cn=Bob,ou=people, dc=example,dc=com
changetype: modify
add: nsRoleDN
nsRoleDN: cn=Marketing,ou=people, dc=example,dc=com

The nsRoleDN attribute present in the entry indicates that the entry is a member of a managed role, the marketing managed role cn=Marketing,ou=people, dc=example,dc=com.

Example: Filtered Role Definition

You want to set up a filtered role for sales managers. Run the ldapmodify script as follows:

ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389

Specify the filtered role as follows:

dn: cn=SalesManagerFilter,ou=people,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: SalesManagerFilter
nsRoleFilter: o=sales managers
Description: filtered role for sales managers

Notice that the nsFilteredRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsComplexRoleDefinition object classes. The nsRoleFilter attribute specifies the o (organization) attributes that contain the value of sales managers.

The following entry matches the filter (possesses the o attribute with the value sales managers), and, therefore, it is a member of this filtered role:

dn: cn=Pat,ou=people,dc=example,dc=com
objectclass: person
cn: Pat
sn: Pat
userPassword: bigsecret
o: sales managers

Example: Nested Role Definition

You want to create a role that contains both the marketing staff and sales managers contained by the roles you created in the previous examples. The nested role you created using ldapmodify appears as follows:

dn: cn=MarketingSales,ou=people,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsNestedRoleDefinition
cn: MarketingSales
nsRoleDN: cn=SalesManagerFilter,ou=people,dc=example,dc=com
nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com

Notice the nsNestedRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsComplexRoleDefinition object classes. The nsRoleDN attributes contain the DN of the marketing managed role and the sales managers filtered role.

Both of the users in the previous examples, Bob and Pat, would be members of this new nested role.

Using Roles Securely

Not every role is suitable for use in a security context. When creating a new role, consider how easily the role can be assigned to and removed from an entry. Sometimes it is appropriate for users to be able to add or remove themselves easily from a role. For example, if you had an interest group role called Mountain Biking, you would want interested users to add themselves or remove themselves easily.

However, in some security contexts, it is inappropriate to have such open roles. Consider account inactivation roles. By default, account inactivation roles contain ACIs defined for their suffix. When creating a role, the server administrator decides whether a user can assign themselves to or remove themselves from the role.

For example, user A possesses the managed role, MR. The MR role has been locked using account inactivation through the command-line. This means that user A cannot bind to the server because the nsAccountLock attribute is computed as true for that user. However, suppose the user was already bound and noticed that he is now locked through the MR role. If there are no ACIs preventing him, the user can remove the nsRoleDN attribute from his entry and unlock himself.

To prevent users from removing the nsRoleDN attribute, use the following ACIs depending upon the type of role being used.

Managed roles. For entries that are members of a managed role, use the following ACI to prevent users from unlocking themselves by removing the appropriate nsRoleDN:

aci: (targetattr="nsRoleDN")
(targattrfilters= "
add=nsRoleDN:(!(nsRoleDN=cn=AdministratorRole, dc=example,dc=com )),
del=nsRoleDN:(!(nsRoleDN=cn=nsManagedDisabledRole, dc=example,dc=com ))")
(version3.0;aci "allow mod of nsRoleDN by self
but not to critical values";
allow(write)
userdn="ldap:///self";)

Filtered roles. The attributes that are part of the filter should be protected so that the user cannot relinquish the filtered role by modifying an attribute. The user should not be allowed to add, delete, or modify the attribute used by the filtered role. If the value of the filter attribute is computed, then all attributes that can modify the value of the filter attribute should be protected in the same way.
Nested roles. A nested role is comprised of filtered and managed roles, so the above points should be considered for each of the roles that comprise the nested role.

For more information about account inactivation, see Inactivating Users and Roles.

Assigning Class of Service

A class of service (CoS) allows you to share attributes between entries in a way that is transparent to applications. CoS simplifies entry management and reduces storage requirements.

There are two methods for creating and managing CoS: with Directory Server Console or through the command-line. The following sections describe CoS in more detail and provide the procedures for managing CoS through both the Console and the command-line:

About CoS

Clients of the Directory Server read the attributes on a user's entry. With CoS, some attribute values may not be stored with the entry itself. Instead, they are generated by class of service logic as the entry is sent to the client application.

Each CoS is comprised of the following two types of entry in your directory:

CoS Definition Entry -- The CoS definition entry identifies the type of CoS you are using. Like the role definition entry, it inherits from the LDAPsubentry object class. The CoS definition entry is below the branch at which it is effective.
Template Entry -- The CoS template entry contains a list of the shared attribute values. Changes to the template entry attribute values are automatically applied to all the entries within the scope of the CoS. A single CoS might have more than one template entry associated with it.

The CoS definition entry and template entry interact to provide attribute information to their target entries, any entry within the scope of the CoS.

Note

LDAP search requests containing a filter that references an attribute defined by a CoS may return unexpected results. Take care when deciding which attributes to generate using a CoS.

The following sections describe the entries that make up a CoS in more detail and provide examples of each type of CoS.

About the CoS Definition Entry

The CoS definition entry is an instance of the cosSuperDefinition object class. The CoS definition entry also contains an object class that specifies the type of template entry it uses to generate the entry. You can specify three different object classes depending upon the type of CoS you want to use. The target entries share the same parent as the CoS definition entry.

There are three types of CoS, defined using three types of CoS definition entries:

Pointer CoS -- A pointer CoS identifies the template entry using the template DN only.
Indirect CoS -- An indirect CoS identifies the template entry using the value of one of the target entry's attributes. For example, an indirect CoS might specify the manager attribute of a target entry. The value of the manager attribute is then used to identify the template entry.

The target entry's attribute must be single-valued and contain a DN.

Classic CoS -- A classic CoS identifies the template entry using a combination of the template entry's base DN and the value of one of the target entry's attributes.

For more information about the object classes and attributes associated with each type of CoS, refer to Managing CoS from the Command-Line.

If the CoS logic detects that an entry contains an attribute for which the CoS is generating values, the CoS, by default, supplies the client application with the attribute value in the entry itself. However, you can use the CoS definition entry to control this behavior.

About the CoS Template Entry

The CoS template entry contains the value or values of the attributes generated by the CoS logic. The CoS template entry contains a general object class of cosTemplate. The CoS template entries for a given CoS are stored in the directory tree along with the CoS definition.

The relative distinguished name (RDN) of the template entry is determined by one of the following:

The DN of the template entry alone.

This type of template is associated with a pointer CoS.

The value of one of the target entry's attributes.

The attribute used to provide the relative DN to the template entry is specified in the CoS definition entry using the cosIndirectSpecifier attribute. This type of template is associated with an indirect CoS.

By a combination of the DN of the subtree where the CoS performs a one level search for templates and the value of one of the target entry's attributes.

This type of template is associated with a classic CoS.

How a Pointer CoS Works

You create a pointer CoS that shares a common postal code with all of the entries stored under dc=example,dc=com. The three entries for this CoS appear as illustrated in Figure 5-1.

Figure 5-1 Sample Pointer CoS

In this example, 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 the entry cn=wholiday,ou=people,dc=example,dc=com, the Directory Server returns the value available in the template entry cn=exampleUS,cn=data.

How an Indirect CoS Works

You can create an indirect CoS that uses the manager attribute of the target entry to identify the template entry.

The three CoS entries appear as illustrated in Figure 5-2.

Figure 5-2 Sample Indirect CoS

In this example, the target entry for William Holiday contains the indirect specifier, the manager attribute. William's manager is Carla Fuentes, so the manager attribute contains a pointer to the DN of the template entry, cn=Carla Fuentes,ou=people,dc=example,dc=com. The template entry in turn provides the departmentNumber attribute value of 318842.

How a Classic CoS Works

You can create a classic CoS that uses a combination of the template DN and a CoS specifier to identify the template entry containing the postal code.

The three CoS entries appear as illustrated in Figure 5-3:

Figure 5-3 Sample Classic CoS

In this example, the Cos definition entry's cosSpecifier attribute specifies the employeeType attribute. This attribute, in combination with the template DN, identify 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.

Managing CoS Using the Console

This section describes creating and editing CoS through the Directory Server Console. It includes the following sections:

Creating a New CoS

In the Directory Server Console, select the Directory tab.
Browse the tree in the left navigation pane, and select the parent entry for your new class of service.
Go to the Object menu, and select New > Class of Service.

You can also right click the entry and select New > Class of Service.

The Create New Class of Service dialog displays.
Select General in the left pane. In the right pane, enter the name of your new class of service in the "Class Name" field. Enter a description of the class in the Description field.
Click Attributes in the left pane. The right pane displays a list of attributes generated on the target entries.

Click Add to browse the list of possible attributes and add them to the list.

Once you have added an attribute to the list, a drop-down list appears in the "Class of Service Behavior" column.

Select "Does not override target entry attribute" to tell the directory to only return a generated value if there is no corresponding attribute value stored with the entry.

Select "Overrides target entry attribute" to make the value of the attribute generated by the CoS override the local value.
Select "Overrides target entry attribute and is operational" to make the attribute override the local value and to make the attribute operational, so that it is not visible to client applications unless explicitly requested.
Select "Does not override target entry attribute and is operational" to tell the directory to return a generated value only if there is no corresponding attribute value stored with the entry and to make the attribute operational (so that it is not visible to client applications unless explicitly requested).

Note

You can only make an attribute operational if it is also defined as operational in the schema.

For example, if your CoS generates a value for the description attribute, you cannot select "Overrides target entry attribute and is operational" because this attribute is not marked operational in the schema.

Click Template in the left pane. In the right pane, select how the template entry is identified.
- By its DN. If you choose to have the template entry identified by only its DN (a pointer CoS), enter the DN of the template in the "Template DN" field. Click Browse to locate the DN on your local server.
- Using the value of one of the target entry's attribute. If you choose to have the template entry identified by the value of one of the target entry's attributes (an indirect CoS), enter the attribute name in the "Attribute Name" field. Be sure to select an attribute which contains DN values. Click Change to select a different attribute from the list of available attributes.
- Using both its DN and the value of one of the target entry's attributes. If you choose to have the template entry identified by both its DN and the value of one of the target entry's attributes (a classic CoS), enter both a template DN and an attribute name.
Click OK.

Editing an Existing CoS

The following procedure describes changing the description and attributes generated on the target entry of an existing class of service.

To edit an existing CoS:

In the Directory Server Console, select the Directory tab.
Browse the tree in the left navigation pane, and select the parent entry that contains your class of service.

The CoS appears in the right pane with other entries.
Double-click the CoS.

The Edit Entry dialog box appears.
Click General in the left pane to change the CoS name and description.
Click Attributes in the left pane to add or remove attributes generated by the CoS.
Click OK to save your changes.

The target entries of the CoS are automatically updated.

Deleting a CoS

The following procedure describes deleting a CoS:

In the Directory Server Console, select the Directory tab.
Browse the tree in the left navigation pane, and select the parent entry that contains your class of service.

The CoS appears in the right pane with other entries.
Right-click the CoS, and select Delete. A dialog box appears asking you to confirm the deletion. Click Yes.
The Deleted Entries dialog box appears to inform you that the CoS was successfully deleted. Click OK.

Managing CoS from the Command-Line

Because all configuration information and template data is stored as entries in the directory, you can use standard LDAP tools for CoS configuration and management. This section contains the following topics:

Creating the CoS Definition Entry from the Command-Line

Each type of CoS requires a particular object class to be specified in the definition entry. All CoS definition object classes inherit from the LDAPsubentry object class and the cosSuperDefinition object class. Table 5-2 lists the object classes associated with each type of CoS definition entry.

Table 5-2 CoS Definition Entry Object Classes


CoS Type	Object Classes	Description
Pointer CoS	cosPointerDefinition	Identifies the template entry associated with the CoS definition using the template entry's DN value. The DN of the template entry is specified in the cosTemplateDn attribute.
Indirect CoS	cosIndirectDefinition	Identifies the template entry using the value of one of the target entry's attributes. The attribute of the target entry is specified in the cosIndirectSpecifier attribute.
Classic CoS	cosClassicDefinition	Identifies the template entry using both the template entry's DN (as specified in the cosTemplateDn attribute) and the value of one of the target entry's attributes (as specified in the cosSpecifier attribute).

Table 5-3 lists attributes that you can use in your CoS definition entries.

Table 5-3 CoS Definition Entry Attributes


Attribute	Definition
cosAttribute	Provides the name of the attribute for which you want to generate a value. You can specify more than one cosAttribute value. This attribute is used by all types of CoS definition entries.
cosIndirectSpecifier	Specifies the attribute value used by an indirect CoS to identify the template entry.
cosSpecifier	Specifies the attribute value used by a classic CoS, which, along with the template entry's DN, identifies the template entry.
cosTemplateDn	Provides the DN of the template entry associated with the CoS definition. Used for pointer CoS and classic CoS only.

The cosAttribute attribute allows an additional qualifier after the attribute value. You can use the following qualifiers:

Default

This qualifier indicates that the server only returns a generated value if there is no corresponding attribute value stored with the entry.

Override

This qualifier indicates that the server always returns the value generated by the CoS, even when there is a value stored with the entry.

Operational

This qualifier indicates that the attribute will only be returned if it is explicitly requested in the search. Operational attributes do not need to pass a schema check in order to be returned. When you use operational as a qualifier, it works as if override and operational were specified.

Operational-default

This qualifier indicates that the server only returns a generated value if there is no corresponding attribute value stored with the entry and if it is explicitly requested in the search.

Note

You can only make an attribute operational if it is also defined as operational in the schema. For example, if your CoS generates a value for the description attribute, you use the operational qualifier because this attribute is not marked operational in the schema.

If you do not indicate a qualifier, default is assumed.

For example, you might create a pointer CoS definition entry that contains an override qualifier as follows:

dn: cn=pointerCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=exampleUS,cn=data
cosAttribute: postalCode override

This pointer CoS definition entry indicates that it is associated with a template entry, cn=exampleUS,cn=data, that generates the value of the postalCode attribute. The override qualifier indicates that this value will take precedence over the value stored by the entries for the postalCode attribute.

Note

If an entry contains an attribute value generated by a CoS, you cannot manually update the value of the attribute if it is defined with the operational or override qualifiers.

For more information about the attributes, refer to the Netscape Directory Server Configuration, Command, and File Reference.

Now that you have been introduced to the object classes and attributes used by a CoS definition, it is time to put them together to create the definition entry itself. Table 5-4 describes the CoS definition for each type of CoS.

Table 5-4 CoS Definitions


CoS Type	CoS definition
Pointer CoS	objectclass: top objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosPointerDefinition cosTemplateDn: DN_string cosAttribute: list_of_attributes qualifier
Indirect CoS	objectclass: top objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosIndirectDefinition cosIndirectSpecifier: attribute_name cosAttribute: list_of_attributes qualifier
Classic CoS	objectclass: top objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosClassicDefinition cosTemplateDn: DN_string cosSpecifier: attribute_name cosAttribute: list_of_attributes qualifier

Creating the CoS Template Entry from the Command-Line

The CoS template entry also inherits from the LDAPsubentry object class. Each template entry is an instance of the cosTemplate object class.

Note

Making the CoS template entry an instance of the LDAPsubentry object classes allows ordinary searches to be performed unhindered by the configuration entries. However, if the template entry already exists and is used for something else (for example, if it is a user entry), you do not need to make it an instance of the LDAPsubentry object class.

The CoS template entry also contains the attribute generated by the CoS (as specified in the cosAttribute attribute of the CoS definition entry) and the value for that attribute.

For example, a CoS template entry that provides a value for the postalCode attribute follows:

dn:cn=exampleUS,cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 44438

It is possible to create CoS templates 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. A priority of zero is the highest priority.

Templates that contain no cosPriority attribute are considered the lowest 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. The behavior for negative cosPriority values is not defined in Directory Server; do not enter negative values. Also, the cosPriority attribute is not supported by indirect CoS.

For example, a CoS template entry for generating a department number appears as follows:

dn: cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
departmentNumber: 71776
cosPriority: 0

This template entry contains the value for the departmentNumber attribute. It has a priority of zero, meaning this template takes precedence over any other conflicting templates that define a different departmentNumber value.

The following sections provide examples of template entries along with examples of each type of CoS definition entry.

Example of a Pointer CoS

You want to create a pointer CoS that shares a common postal code with all entries in the dc=example,dc=com tree.

To add a new pointer CoS definition entry to the dc=example,dc=com suffix, you do an ldapmodify as follows:

ldapmodify -a -D "cn=directory manager" -w secret -h host -p 389

The ldapmodify utility binds to the server and prepares it to add information to the configuration file.

Next, you add the pointer CoS definition to the dc=example,dc=com root suffix as follows:

Next, you create the template entry as follows:

dn: cn=exampleUS,cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 44438

The CoS template entry (cn=exampleUS,cn=data,dc=example,dc=com) supplies the value stored in its postalCode attribute to any entries located under the dc=example,dc=com suffix. These entries are the target entries.

Example of an Indirect CoS

This indirect CoS uses the team attribute of the target entry to identify the CoS template entry.

First, you add a new indirect CoS definition entry to the dc=example,dc=com suffix, using ldapmodify as follows:

ldapmodify -a -D "cn=directory manager" -w secret -h host -p 389

The ldapmodify utility binds to the server and prepares it to add information to the configuration file.

Next, you add the indirect CoS definition to the dc=example,dc=com root suffix as follows:

dn: cn=indirectCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier: manager
cosAttribute: departmentNumber

Next, you create the template entry for manager Carla Fuentes as follows:

dn:cn=Carla Fuentes,cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
departmentNumber: 318842

You create a second template entry for manager Sue Jacobs as follows:

dn:cn=Sue Jacobs,cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
departmentNumber: 71776

The definition entry looks in the target entries (the entries under dc=example,dc=com) for entries containing the manager attribute (because this attribute is specified in the cosIndirectSpecifier attribute of the definition entry). The manager attribute of the target entry can point to one of two templates, cn=Carla Fuentes,cn=data,dc=example,dc=com and cn=Sue Jacobs,cn=data,dc=example,dc=com. The department number is different depending upon the manager.

Example of a Classic CoS

You want to create a classic CoS that automatically generates postal codes using a combination of the template DN and the attribute specified in the cosSpecifier attribute.

First, you add a new classic CoS definition entry to the dc=example,dc=com suffix, using ldapmodify as follows:

ldapmodify -a -D "cn=directory manager" -w secret -h host -p 389

The ldapmodify utility binds to the server and prepares it to add information to the configuration file.

Next, you add the indirect CoS definition to the dc=example,dc=com root suffix as follows:

dn: cn=classicCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: cn=exampleUS,cn=data,dc=example,dc=com
cosSpecifier: employeeType
cosAttribute: postalCode override

Next, you create the template entries for the sales and marketing departments as follows:

dn: cn=sales,cn=exampleUS,cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 44438

dn: cn=marketing,cn=exampleUS,cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 99111

The classic CoS definition entry applies to all entries under the dc=example,dc=com suffix. Depending upon the combination of employeeType attribute found in the entry and the cosTemplate DN, it can arrive at one of two templates. One, the sales template, provides a postal code specific to employees in the sales department. The marketing template provides a postal code specific to employees in the marketing department.

Creating Role-Based Attributes

You can create classic CoS schemes that generate attribute values for an entry based on the role possessed by the entry. For example, you could use role-based attributes to set the server look through limit on an entry-by-entry basis.

To create a role-based attribute, use the nsRole attribute as the cosSpecifier in the CoS definition entry of a classic CoS. Because the nsRole attribute can be multi-valued, you can define CoS schemes that have more than one possible template entry. To resolve the ambiguity of which template entry to use, you can include the cosPriority attribute in your CoS template entry.

For example, you can create a CoS that allows members of the manager role to exceed the standard mailbox quota. The manager role exists as follows:

dn: cn=ManagerRole,ou=people,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerRole
nsRoleFilter: o=managers
Description: filtered role for managers

The classic CoS definition entry would look as follows:

dn: cn=managerCOS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectlass: cosClassicDefinition
cosTemplateDn: cn=managerCOS,dc=example,dc=com
cosSpecifier: nsRole
cosAttribute: mailboxquota override

The cosTemplateDn attribute provides a value that, in combination with the attribute specified in the cosSpecifier attribute (in the example, the nsRole attribute of the target entry), identifies the CoS template entry. The CoS template entry provides the value for the mailboxquota attribute. An additional qualifier of override tells the CoS to override any existing mailboxquota attributes values in the target entry.

The corresponding CoS template entry looks as follows:

dn:cn= "cn=ManagerRole,ou=people,dc=example,dc=com" ,cn=managerCOS,
dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectlass: cosTemplate
mailboxquota: 1000000

The template provides the value for the mailboxquota attribute, 1000000.

Note

The role entry and the CoS definition and template entries should be located at the same level in the directory tree.

Access Control and CoS

The server controls access to attributes generated by a CoS in exactly the same way as regular stored attributes. However, access control rules depending upon the value of attributes generated by CoS will not work.

Contents

Index

DocHome

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

last updated November 26, 2004