Sun ONE logo     Previous     Contents     Index     Next    
Sun ONE Directory Server Administration Guide



Chapter 5   Advanced Entry Management

Beyond the hierarchical structure of data in a directory, managing entries that represent users often requires creating groups and sharing common attribute values. Sun ONE Directory Server provides this advanced entry management functionality through groups, roles and class of service (CoS).

Groups are entries that name other entries, either as a list of members or as a filter for members. Roles provide the same functionality, and more, through a mechanism that generates the nsrole attribute on each member of a role. CoS also generates a virtual attribute, allowing entries to share a common attribute value without having to store it in each entry.



Note

Sun ONE Directory Server 5.2 introduces the ability to perform searches based on the values of the roles and CoS virtual attributes. Filter strings used in any operation may now include the nsRole attribute or any attribute generated by a CoS definition and perform any of the comparison operations on the value of this attribute. However, virtual CoS attributes cannot be indexed and therefore any search involving a CoS-generated attribute will be unindexed.



To take full advantage of the features offered by roles and class of service, it is best to determine your directory topology in the planning phase of your directory deployment. Refer to Chapter 4, "Designing the Directory Tree," in the Sun ONE Directory Server Deployment Guide for a description of these mechanisms and how they can simplify your topology.

This chapter contains the following sections:

Managing Groups

Groups are a mechanism for associating entries for ease of administration, such as for defining ACIs. Groups definitions are special entries that either name their members in a static list or give a filter which defines a dynamic set of entries. See "Assigning Roles" for procedures that create equivalent role definitions.

The scope of possible members of a group is the entire directory, regardless of where the group definition entries are located. To simplify administration, all group definition entries are usually stored in a single location, usually ou=Groups under the root suffix.

The entry that defines a static group inherits from the groupOfUniqueNames object class. The group members are listed by their DN as multiple values of the uniqueMember attribute.

The entry that defines a dynamic group inherits from the groupOfUniqueNames and groupOfURLs object classes. Group membership is defined by one or more filters given in the multi-valued memberURL attribute. The members in a dynamic group are the entries that match any one of the filters whenever they are evaluated.

The following sections describe how to create and modify both static and dynamic groups using the console.

Adding a New Static Group

  1. On the top-level Directory tab of the Directory Server console, right-click the entry in the directory tree where you want to add the new group, and select the New>Group item.
  2. Alternatively, select the entry and choose the New>Group item from the Object menu.

  3. In the Create New Group dialog, you must type a name for your new group in the "Group Name" field, and you may add an optional description of the group in the "Description" field. The group name will become the value of the cn (common name) attribute for the new group entry and appear in its DN.
  4. Click Members in the left-hand list of the dialog. In the right panel, the Static Group tab is selected by default.
  5. Click Add to add new members to the group. The standard "Search users and groups" dialog box appears.
  6. In the Search drop-down list, select Users and enter a string to search for, and then click Search. Click the Advanced button to search specific attributes or specific attribute values.
  7. Select one or more of the entries in the results and click OK. Repeat this step to add all of the members you wish to this static group.



    Note

    Static group members may be remote due to chaining. You can use the referential integrity plug-in to ensure that deleted member entries are automatically deleted from the static group entry. For more information about using referential integrity with chaining, refer to "Configuring the Chaining Policy".



  8. Click Languages in the left-hand list to give your group a name and descriptions string in another language. These will be displayed when the console is using the corresponding locale.
  9. Click OK to create your new group. It appears as one of the children of the entry where it was created.

Adding a New Dynamic Group

  1. On the top-level Directory tab of the Directory Server console, right-click the entry in the directory tree where you want to add the new group, and select the New>Group item.
  2. Alternatively, select the entry and choose the New>Group item from the Object menu.

  3. In the Create New Group dialog, you must type a name for your new group in the "Group Name" field, and you may add an optional description of the group in the "Description" field. The group name will become the value of the cn (common name) attribute for the new group entry and appear in its DN.
  4. Click Members in the left-hand list of dialog and select the Dynamic Group tab in the right panel.
  5. Click Add to create a LDAP URL containing the filter string that will define group members. The standard "Construct and Test LDAP URL" dialog box appears.
  6. Enter an LDAP URL in the text field or select Construct to be guided through the construction of an LDAP URL containing the filter for your group. Click Test to view the list of entries that are returned by this filter.
  7. Click OK when you have constructed the URL. Repeat this step to add all of the URLs containing the filters that define your dynamic group.

  8. Click Languages in the left-hand list to give your group a name and descriptions string in another language. These will be displayed when the console is using the corresponding locale.
  9. Click OK to create your new group. It appears as one of the children of the entry where it was created.

Modifying a Group Definition

  1. On the top-level Directory tab of the Directory Server console, double-click the entry representing the group you want to modify.
  2. Alternatively, select the entry and choose Open from the Object menu.

  3. In the Edit Entry dialog, make your changes to the group information in the General, Members, or Languages categories. You may add or remove members of a static group or add, edit, or remove the URLs containing filters for a dynamic group.
  4. Click OK when you are done modifying the group definition.
  5. To view your changes in the console, select Refresh from the View menu.

Removing a Group Definition

To remove either type of group, simply delete the entry that defines it.

Assigning Roles

Roles are an alternate grouping mechanism that is designed to be more efficient and easier to use for applications. Roles are defined and administered like groups, but in addition, member entries also have a generated attribute that indicates the roles in which they participate. For example, an application can simply read the roles of an entry, rather than select a group and browse the members list.

By default, the scope of a role is limited to the subtree where it is defined. Sun ONE Directory Server 5.2 introduces extended scoping of the nested role, allowing it to nest roles located in other subtrees and have members anywhere in the directory.

About Roles

Each role has members, or entries that possess the role. As entries are retrieved from the directory, the roles mechanism automatically generates the nsRole attribute in every entry that is a member of any role. This multi-valued attribute contains the DN of all role definitions in which the entry is a member. The nsRole attribute is a computed attribute that is not stored with the entry itself but which is returned to the client application as a normal attribute in operation results.

Sun ONE Directory Server supports three types of roles:

  • Managed role - The administrator assigns a managed role by adding the nsRoleDN attribute to the desired member entries. The value of this attribute is the DN of the role definition entry. A managed role is similar to a static group except that membership is defined in each entry and not in the role definition entry.
  • Filtered role - These are equivalent to dynamic groups: they define a filter string in their nsRoleFilter attribute. The scope of a filtered role is the subtree in which it is located, rooted at the parent of its definition entry. When the server returns an entry in the scope of a filtered role that matches its filter, that entry will contain the generated nsRole attribute identifying the role.
  • Nested role - These are roles that name other role definitions, including other nested roles. The set of members of a nested role is union of all members of the roles it contains. Nested roles may also define extended scope to include the members of roles in other subtrees.

Roles allow client applications to know all role membership of an entry by directly reading its nsRole attribute. This simplifies client processing optimizes directory usage. Roles can be used in combination with the CoS mechanism to generate other attributes for role members (see "Creating Role-Based Attributes"). Roles can be used to define access control (see "Defining Role Access - roledn Keyword"). Roles also support other functionality such as activating or deactivating all of their members at once (see "Inactivating and Activating Users and Roles").

Searching the nsRole Attribute

Sun ONE Directory Server 5.2 now permits the use of the nsRole attribute in any search filter. You may search for a particular value for this attribute using any of the comparison operators. However, keep in mind the following considerations:

  • Searches involving the nsRole attribute may take significantly longer because all roles must be evaluated before the entries may be filtered.
  • The directory server is optimized for equality searches on membership in specific in managed roles. For example, the following search will be nearly as fast as a search on real attributes:
  • (&(objectclass=person)
      (nsRole=cn=managersRole,ou=People,dc=example,dc=com)

  • The nsRoleDN attribute used to define managed role membership is indexed by default in all suffixes. Optimizations for searching managed role membership will be lost if indexing for this attribute is disabled.
  • Searching for entries containing a filtered role involves an internal search using the role filter. This internal operation will be fastest if all attributes that appear in the role filter are indexed in all suffixes in the scope of the role.

Permissions on the nsRole Attribute

The nsRole attribute may only be assigned by the roles mechanism and is never writable nor modifiable by any directory user. However, you should keep in mind the following considerations:

  • The nsRole attribute is potentially readable by any directory user, and you may define access controls to protect it against reading.
  • The nsRoleDN attribute defines managed role membership and you should decide whether users may add or remove themselves from the role. See "Example of a Managed Role Definition" for the ACI that prevents users from modifying their own roles.
  • Filtered roles determine membership through filters that are based on the existence or the values of attributes in user entries. You should define carefully the user permissions of these attributes to control who may define membership in the filtered role.

For more information about how to use roles in your directory, refer to Chapter 4, "Designing the Directory Tree," in the Sun ONE Directory Server Deployment Guide.

Assigning Roles Using the Console

This section describes the procedures for creating and modifying roles.

Creating a Managed Role

Managed roles have a role definition entry and members are designated by adding the nsRoleDN attribute to each member entry. To create and add members to a managed role using the console:

  1. On the top-level Directory tab of the Directory Server console, right-click the entry in the directory tree where you want to add the new role definition, and select the New>Role item.
  2. Alternatively, select the entry and choose the New>Role item from the Object menu.

  3. In the Create New Role dialog, you must type a name for your new role in the "Role Name" field, and you may add an optional description of the role in the "Description" field. The group name will become the value of the cn (common name) attribute for the new role entry and appear in its DN.
  4. Click Members in the left-hand list of the dialog. In the right pane, the Managed Role radio button is selected by default.
  5. Click Add below the list of members to add new members to the role. The standard "Search users and groups" dialog box appears.
  6. In the Search drop-down list, select Users and enter a string to search for, and then click Search. Click the Advanced button to search specific attributes or specific attribute values.
  7. Select one or more of the entries in the results and click OK. Repeat this step to add all of the members you wish to this static group.

  8. When you have finished adding entries to the role, click OK. The new role appears in the directory tree with the icon for a managed role, and all member entries will be given the attribute nsRoleDN with the value of the DN of this new role entry.
  9. Once the role is created, you may also assign this role to any entry by adding the nsRoleDN attribute to the entry with the value of the DN of the role entry.

Creating a Filtered Role

Entries are members of a filtered role if they possess attributes or attribute values that are selected by the LDAP filter in the role's definition.



Note

The filter string of a filtered role may be based on any attribute, except other virtual attributes generated by the CoS mechanism (see "About CoS").



To create and add members to a filtered role using the console:

  1. On the top-level Directory tab of the Directory Server console, right-click the entry in the directory tree where you want to add the new role definition, and select the New>Role item.
  2. Alternatively, select the entry and choose the New>Role item from the Object menu.

  3. In the Create New Role dialog, you must type a name for your new role in the "Role Name" field, and you may add an optional description of the role in the "Description" field. The group name will become the value of the cn (common name) attribute for the new role entry and appear in its DN.
  4. Click Members in the left-hand list of the dialog and select the Filtered Role radio button in the right-hand panel.
  5. Enter an LDAP filter in the text field to define the filter that will determine role members. Or click Construct to be guided through the construction of an LDAP filter.
  6. If you click Construct, the Construct LDAP Filter dialog appears. Disregard the LDAP Server Host, Port, Base DN, and Search scope fields, because you cannot specify these in a filtered role definition.
    1. Search only for users in a filtered role. This will add the component (objectclass=person) to the filter. If you do not want this component, you must edit the LDAP filter in the text field of the Create New Role dialog.
    2. Refine the filter by selecting an attribute from the "Where" drop-down list and setting the matching criteria. To add additional filters, click More. To remove unnecessary filters, click Fewer.
    3. Click OK to use your filter in the filtered role definition. You may then edit the filter in the text field to modify any component.

  7. Click Test to try your filter. A Filter Test Result dialog will display the entries that currently match your filter.
  8. Click OK to create the new role entry. The new role appears in the directory tree with the icon for a filtered role.

Creating a Nested Role

Nested roles allow you to create roles that contain other roles and to extend the scope of existing 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. A nested role may contain another nested role, up to 30 levels of nesting. Beyond this fixed limit, the server will log an error when evaluating the role.

To create and add members to a nested role using the console:

  1. On the top-level Directory tab of the Directory Server console, right-click the entry in the directory tree where you want to add the new role definition, and select the New>Role item.
  2. Alternatively, select the entry and choose the New>Role item from the Object menu.

  3. In the Create New Role dialog, you must type a name for your new role in the "Role Name" field, and you may add an optional description of the role in the "Description" field. The group name will become the value of the cn (common name) attribute for the new role entry and appear in its DN.
  4. Click Members in the left-hand list of the dialog. and select the Nested Role radio button in the right panel.
  5. Click Add to add existing roles to the list of nested roles. In the Role Selector dialog box that appears, select one or more roles from the list of available roles and click OK.
  6. Click OK to create the nested role entry. The new role appears in the directory with the icon for a nested role.
  7. To modify the scope of the nested role, use the command-line procedure shown in "Example of a Nested Role Definition".

Viewing and Editing an Entry's Roles

  1. On the top-level Directory tab of the Directory Server console, browse the directory tree to display the entry for which you want to view or edit a role.
  2. Right-click the entry and select Set Roles from the pop-up menu. Alternatively, you may left-click the entry to select it and choose Set Roles from the Object menu.
  3. The Set Roles dialog is displayed.

  4. Select the Managed Roles tab to display the managed roles to which this entry belongs. You may perform the following actions:
  5. To add a new managed role, click Add and select an available role from the Role Selector window. Click OK in the Role Selector window.
  6. To remove a managed role, select it and click Remove.
  7. To edit a managed role associated with an entry, select it in the table and click Edit. The role is displayed in the custom editor for Roles. Make any changes to the role and click OK to save the new role definition.
  8. Select the Other Roles tab to view the filtered or nested roles to which this entry belongs. To change role membership in a filtered or nested role, you must edit the role definition:
  9. Select the role and click Edit to display the custom editor for Roles. Make changes to the role and click OK to save the new role definition.
  10. Click OK once you have finished modifying the roles to save your changes.

Modifying a Role Entry

  1. On the Directory Server console, select the Directory tab.
  2. Browse the navigation tree to locate the definition entry of an existing role. Roles are children of the entry where they were created. Double-click the role.
  3. The Edit Entry dialog box appears.

  4. Click General in the left pane to change the role name and description.
  5. Click Members in the left pane to change the members of managed and nested roles or to change the filter of a filtered role.
  6. Click OK to save your changes.

Deleting a Role

Deleting a role deletes only the entry of the role definition, not its members.

To delete a role:

  1. In the Directory Server console, select the Directory tab.
  2. Browse the navigation tree to locate the definition entry of your role. Roles are children of the entry where they were created.
  3. Right-click the role and select Delete.
  4. A dialog box appears asking you to confirm the deletion. Click Yes.

  5. The Deleted Entries dialog box appears to inform you that the role was successfully deleted. Click OK.


  6. Note

    Deleting a role deletes the role entry but does not delete the nsRoleDN attribute for each role member. To do this, enable the Referential Integrity Plug-In and configure it to manage the nsRoleDN attribute. For more information, see "Maintaining Referential Integrity".



Managing Roles From the Command Line

Roles are defined in entries that the directory administrator may access through command-line utilities. 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.

All role definitions inherit from the LDAPsubentry and nsRoleDefinition object classes. The following table lists additional object classes and associated attributes specific to each type of role.

Table 5-1    Object Classes and Attributes Used to Define 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)

Example of a Managed Role Definition

To create a role that will be assigned to all marketing staff, run the following ldapmodify command:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=Marketing,ou=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 updating his entry with the following ldapmodify command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w secret
dn: cn=Bob Arnold,ou=marketing,ou=People,dc=example,dc=com
changetype: modify
add: nsRoleDN
nsRoleDN: cn=Marketing,
ou=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 identified by the DN of its role definition. To prevent users from adding or removing themselves from a managed role by modifying the nsRoleDN attribute, add the following access control instruction (ACI):

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 except
 for critical values
"; allow(write) userdn="ldap:///self";)

Example of a Filtered Role Definition

To set up a filtered role for sales managers, assuming they all have the isManager attribute, run the following ldapmodify command:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=ManagerFilter,ou=sales,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerFilter
nsRoleFilter: (isManager=True)
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 a filter that will find all employees in the ou=sales organization that have subordinates, for example:

ldapsearch -h host -p port -D "cn=Directory Manager" -w password \
-b "ou=People,dc=example,dc=com" -s sub "(cn=*Fuentes)"
dn: cn=Carla Fuentes,ou=sales,ou=People,dc=example,dc=com
cn: Carla Fuentes
isManager: TRUE
...
nsRole: cn=ManagerFilter,ou=sales,ou=People,dc=example,dc=com



Note

The filter string of a filtered role may be based on any attribute, except other virtual attributes generated by the CoS mechanism (see "About CoS").



When filtered role members are user entries, you may choose to restrict their ability to add or remove themselves from the role by protecting the filtered attributes with access control instructions (ACIs).

Example of a Nested Role Definition

The roles nested within the nested role are specified using the nsRoleDN attribute. To create a role that contains both the marketing staff and sales manager members of the roles created in the previous examples, use the following command:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=MarketingSales,ou=marketing,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsNestedRoleDefinition
cn: MarketingSales
nsRoleDN: cn=ManagerFilter,ou=sales,ou=People,dc=example,dc=com
nsRoleDN: cn=Marketing,ou=marketing,ou=People,dc=example,dc=com
nsRoleScopeDN: ou=sales,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 Carla, would be members of this new nested role.

The scope of this filter includes the default scope, which is the subtree where it is located, and the subtree below any values of the nsRoleScopeDN attribute. In this case, the ManagerFilter is in the ou=sales,ou=People,dc=example,dc=com subtree, and this subtree must be added to the scope.

Defining Class of Service (CoS)

The Class of Service (CoS) mechanism generates virtual attributes as an entry is retrieved for a client application. CoS simplifies entry management and reduces storage requirements.

As with groups and roles, CoS relies on helper entries in your directory and may be configured through the console or through the command line. The following sections describe CoS and provide the procedures for managing CoS in both ways.



Note

As a new feature in Directory Server 5.2, any search operation may test the existence of a CoS generated attribute or compare its value. The names of the virtual attributes may be used in any filter string, whether from a client search operation or an internal filter used in a filtered role. Directory Server 5.2 also supports virtual attributes in VLV (virtual list view) operations and in server-side sorting controls, just like any real attribute.



About CoS

A CoS defines a virtual attribute and its value for any entry within the scope of the CoS, called the target entries. Each CoS is comprised of the following entries in your directory:

  • CoS Definition Entry - Identifies the type of CoS you are using and the name of the CoS attribute that will be generated. Like the role definition entry, it inherits from the LDAPsubentry object class. The scope of the CoS is the entire subtree below the parent of the CoS definition entry. Multiple definitions may exist for the same CoS attribute which may therefore be multivalued.
  • Template Entry - Contains the values of one or more virtual attributes. All entries within the scope of the CoS will use the values defined here. There may also be multiple template entries in which case the generated attribute may be multivalued.

There are three types of CoS, each of which corresponds to a different interaction between the CoS definition and template entries:

  • Pointer CoS - The CoS definition entry directly identifies the template entry by its DN. All target entries will have the same value for the CoS attribute as given in the template.
  • Indirect CoS - The CoS definition identifies an attribute, called the indirect specifier, whose value in a target entry must contain the DN of a template. With indirect CoS, each target entry may use a different template and thus have a different value for the CoS attribute.
  • Classic CoS - The CoS definition identifies the base DN of the template and a specifier, which is the name of an attribute in target entries. The specifier attribute must contain an RDN (relative domain name) that when combined with the template base DN, determines the template containing the CoS values.

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

  • cosPointerDefinition
  • cosIndirectDefinition
  • cosClassicDefinition

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, if needed. 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.

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.

When possible, definition and template entries should be located in the same place for easier management. Also, you should name them in a way that suggests the functionality they provide. For example, a definition entry DN such as cn=ClCosGenerateEmployeeType,ou=People,dc=example,dc=com is more descriptive than cn=ClassicCos1,ou=People,dc=example,dc=com.

"Managing Attributes with Class of Service" in Chapter 4 of the Sun ONE Directory Server Deployment Guide describes each type of CoS in more detail and provides examples and deployment considerations. For more information about the object classes and attributes associated with each type of CoS, refer to "Managing CoS From the Command Line".

CoS Limitations

The creation and administration of CoS definition and template entries are subject to the following limitations. Further limitations related to the deployment of CoS virtual attributes are given in "CoS Limitations" in Chapter 4 of the Sun ONE Directory Server Deployment Guide.

Searches involving CoS generated attributes are unindexed. Any search filter may test the existence or compare the value of a virtual attribute. However, virtual attributes cannot be indexed and any filter component that involves a CoS generated attribute will result in an unindexed search with significant impact on performance.

Restricted subtrees. You cannot create CoS definitions in the cn=config nor in the cn=schema subtrees. Therefore, these entries cannot contain virtual attributes.

Restricted attribute types. You must not generate the following attribute types with the CoS mechanism, because they will not have the same behavior as real attributes of the same name:

  • userPassword - A CoS-generated password value cannot be used to bind to the directory server.
  • aci - The directory server will not apply any access control based on the contents of a virtual ACI value defined by CoS.
  • objectclass - The directory server will not perform schema checking on the value of a virtual object class defined by CoS.
  • nsRoleDN - A CoS-generated nsRoleDN value will not be used by the server to generate roles.

Attribute subtypes not supported. The CoS mechanism will not generate attributes with subtypes, such as languages or ;binary.

Real and virtual attribute values. The CoS mechanism never generates multivalued attributes containing "real" values defined in the entry and "virtual" values defined by the CoS template. The values of an attribute are either those stored in the entry or those generated by the CoS mechanism, as described in "Overriding Real Attribute Values" and "Multivalued CoS Attributes".

All templates must be local. The DNs of template entries, either in a CoS definition or in the specifier of the target entry, must refer to local entries in the directory server. Templates and the values they contain cannot be retrieved through directory chaining or referrals.

Managing CoS Using the Console

This section describes how to create and edit CoS definitions through the Directory Server console.

In addition, if your CoS values need to be secure, you should define access control instructions (ACIs) for both CoS definition and template entries, as well as for the specifier attribute in the target entries. See the Sun ONE Directory Server Deployment Guide for CoS security considerations and Chapter 6 "Managing Access Control," for procedures to create ACIs using the console.

Creating a New CoS

In the case of pointer CoS and classic CoS, you must create the template entry before the definition entry:

  1. On the top-level Directory tab of the Directory Server console, right-click the entry in the directory tree where you want to add the new template entry, and select the New>Other item from the pop-up menu.
  2. Alternatively, select the parent entry and choose the New>Other item from the Object menu.

  3. In the New Object dialog, select costemplate from the list of object classes. The Generic Editor dialog opens with default values for certain attributes in the new template.
  4. Edit the new template object in the following manner:
    1. Add the LDAPsubentry and extensibleobject values to the objectclass attribute.
    2. Add the cn attribute and give it a value that will identify the template, for example, cosTemplateForHeadquartersFax.
    3. Change the naming attribute to the new cn attribute.
    4. You may add any other attribute and use it as the naming attribute instead, but using cn is common practice.

    5. Modify the cosPriority attribute by setting it to an integer value, or remove the priority attribute altogether if it is not needed. For more information, see "Cos Attribute Priority".
    6. Add the attribute and its value that you wish to be generated on target entries by the CoS mechanism.

  5. Click OK in the Generic Editor dialog to create the template entry.
  6. If you are going to define a pointer CoS for this template, select the new template entry in directory tree and select Edit>Copy DN from the menu.

The procedure for creating the definition entry is the same for all types of CoS:

  1. On the top-level Directory tab of the Directory Server console, right-click the entry in the directory tree where you want to add the new CoS definition, and select the New>Class of Service item from the pop-up menu.
  2. Alternatively, select the parent entry and choose the New>Class of Service item from the Object menu.

    The custom editor for Class of Service entries is displayed.

  3. Enter a name and optional description for your new Class of Service. The name will appear in the cn naming attribute for the CoS definition entry.
  4. Click the Attributes tab in the left-hand list. The dialog displays the list of attributes that will be generated by the CoS mechanism on the target entries.
  5. Click Add to browse the list of possible attributes and add them to the list.

  6. Once you have added an attribute to the list, the "Class of Service Behavior" column contains a drop-down list. Click in this cell to select the override behavior:
    • Does not override target entry attribute - The CoS attribute value will be generated only if there is no corresponding attribute value already stored in the same attribute of the target entry.
    • Overrides target entry attribute - The value of the attribute generated by the CoS will override any value for that attribute in the target entry.
    • Overrides target entry attribute and is operational - The attribute will override any target value and be an 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.



  7. Click the Template tab in the left-hand list. Select how the template entry is identified and then fill in the corresponding fields. This will determine the type of CoS you wish to define.
    • By its DN - This choice will define a pointer CoS: enter the DN of a template entry in the "Template DN" field. Click Browse to select the template DN from the directory, or type Ctrl-V to paste the DN that you copied after creating the template entry.
    • Using the value of one of the target entry's attributes - This choice will define an indirect CoS: enter the name of the specifier attribute in the "Attribute Name" field. Be sure to select an attribute which contains DN values. Click Change to select the attribute from a list.
    • Using both its DN and the value of one of the target entry's attributes - This choice will define a classic CoS: enter both the base DN for a template and an attribute name. Click Browse to select the parent entry of the potential target entries, and click Change to select the attribute from a list.

  8. Click OK to create the CoS definition entry.

Editing an Existing CoS

  1. On the top-level Directory tab of the Directory Server console, double-click the CoS definition entry or right-click on it and select Edit With Custom Editor from the pop-up menu.
  2. The custom editor for Class of Service entries is displayed.

  3. Edit the name and description fields as desired.
  4. Click the Attributes tab in the left-hand list to add or remove virtual attributes that will be generated by the CoS mechanism.
  5. Click the Template tab in the left-hand list to redefine the name of the template specifier attribute or the template entry DN. This dialog also allows you to redefine the type of your CoS definition.
  6. Click OK to save your changes.

Deleting a CoS

  1. On the top-level Directory tab of the Directory Server console, browse the directory tree to display the CoS definition entry.
  2. Right-click the CoS entry and select Delete from the pop-up menu. A dialog box appears asking you to confirm the deletion. Click Yes.

Managing CoS From the Command Line

Because all configuration information and template data is stored as entries in the directory, you can use the LDAP command-line tools to configure and manage your CoS definitions. This section shows how to create CoS definition and template entries from the command line.

In addition, if your CoS values need to be secure, you should define access control instructions (ACIs) for both CoS definition and template entries, as well as for the specifier attribute in the target entries. See Chapter 6 "Managing Access Control," for procedures to create ACIs from the command line.

Creating the CoS Definition Entry From the Command Line

All CoS definition entries have the LDAPsubentry object class and inherit from the cosSuperDefinition object class. In addition, each type of CoS inherits from specific object classes and contains the corresponding attributes. The following table lists the object classes and attributes associated with each type of CoS definition entry:

Table 5-2    Object Classes and Attributes in CoS Definition Entries 

CoS Type

CoS Definition Entry

Pointer CoS

objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDN:
DN
cosAttribute: attributeName override merge

Indirect CoS

objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier:
attributeName
cosAttribute: attributeName override merge

Classic CoS

objectclass: top
bbjectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDN:
DN
cosSpecifier: attributeName
cosAttribute: attributeName override merge

In all cases, cosAttribute is multi-valued, with each value defining an attribute that will be generated by the CoS mechanism.

You can use the following attributes in your CoS definition entries (for more information about these attributes, refer to the Sun ONE Directory Server Reference Manual.):

Table 5-3    CoS Definition Entry Attributes 

Attribute

Purpose Within the CoS Definition Entry

cosAttribute:
 attributeName override merge

Defines the name of the virtual attribute for which you want to generate a value. This attribute is multivalued, each value giving the name of an attribute whose value will be generated from the template. The override and merge qualifiers specify how the CoS attribute value is computed in special cases described below this table.

The attributeName may not contain any subtypes. Attribute names with subtypes will be ignored but other values of cosAttribute will be processed.

cosIndirectSpecifier:
 
attributeName

Defines the name of the attribute in target entries whose value is used by indirect CoS to identify the template entry. The named attribute is called the specifier and must contain a full DN string in each target entry. This attribute is single-valued but the specifier attribute may be multivalued to designate multiple templates.

cosSpecifier:
 
attributeName

Defines the name of the attribute in target entries whose value is used by classic CoS to identify the template entry. The named attribute is called the specifier and must contain a string that can be found in the RDN of template entries. This attribute is single-valued but the specifier attribute may be multivalued to designate multiple templates.

cosTemplateDN:
 
DN

Provides the full DN of the template entry for a pointer CoS definition or the base DN of the template entry for classic CoS.

The cosAttribute attribute allows two qualifiers following the name of the CoS attribute. The override qualifier has one of the following values:

  • default (or no qualifier) - Indicates that the server does not override a real attribute value stored in the entry when it has the same type as the virtual attribute.
  • override - Indicates that the server always returns the value generated by the CoS, even when there is a value stored with the entry.
  • operational - 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. It also has the same behavior as the override qualifier.
  • 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 use the operational qualifier because this attribute is not marked operational in the schema.

The merge qualifier is either absent or given with the following value:

  • merge-schemes - Allows the virtual CoS attribute to be multivalued, either from multiple templates or multiple CoS definitions. For more information, see "Multivalued CoS Attributes".

Overriding Real Attribute Values

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 the 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 of the postalCode attribute if it exists in a target entry.



Note

If the CoS attribute is defined with the operational or override qualifiers, you will not be able to perform write operations on the "real" value of that attribute in any entry in the CoS scope.



Multivalued CoS Attributes

When you specify the merge-schemes qualifier, the generated CoS attribute may be multivalued. There are two ways for a CoS attribute to be multivalued:

  • With indirect or classic CoS, the specifier attributes in target entries may be multivalued. In this case, each value determines a template and the value from each template is part of the generated value.
  • There can be multiple CoS definition entries of any type containing the same attribute name in their cosAttribute. In this case, if all definitions contain the merge-schemes qualifier, the generated attribute will contain all values computed by each definition.

The two situations may occur together and define even more values. However, in all cases, duplicate values will only be returned once in generated attribute.

In the absence of the merge-schemes qualifier, the cosPriority attribute of the template entry will be used to determine a single value among all templates for the generated attribute, as described in the next section.

The merge-schemes qualifier never merges a "real" value defined in the target with generated values from the templates. The merge qualifier is independent of the override qualifier, all pairings are possible and the behaviors implied by each are complimentary. Also, the qualifiers may be specified in any order after the attribute name.



Note

When there are multiple CoS definitions for the same attribute, they must all have the same override and merge qualifiers. When different pairs of qualifiers occur in CoS definitions, one of the combinations is selected arbitrarily among all definitions.



Cos Attribute Priority

If there are multiple CoS definitions or multivalued specifiers, but no merge-schemes qualifier the Directory Server uses a priority attribute to select a single template that defines the single value of the virtual attribute.

The cosPriority attribute represents the global priority of a particular template among all those being considered. A priority of zero is the highest priority. Templates that contain no cosPriority attribute are considered the lowest priority. When two or more templates provide an attribute value but have the same (or no) priority, a value is chosen arbitrarily.

Template priorities are not taken into account when using the merge-schemes qualifier. When merging, all templates being considered define a value regardless of any priority they define. The cosPriority attribute is defined on CoS template entries as described in the following section.



Note

The cosPriority attribute must not have a negative value. Also, attributes generated by indirect CoS do not support priority. Do not use cosPriority in template entries of an indirect CoS definition.



Creating the CoS Template Entry From the Command Line

When using pointer CoS or classic CoS, the template entry contains the LDAPsubentry and cosTemplate object classes. This entry must be created specifically for the CoS definition. Making the CoS template entry an instance of the LDAPsubentry object classes allows ordinary searches to be performed unhindered by the configuration entries.

The template of the indirect CoS mechanism is an arbitrary, existing entry in the directory. The target does not need to be identified ahead of time nor given the LDAPsubentry object class, but it must have the auxiliary cosTemplate object class. The indirect CoS template is accessed only when the CoS is evaluated to generate a virtual attribute and its value.

In all cases, the CoS template entry must contain the attribute and the value that is generated by the CoS on the target entries. The attribute name is specified in the cosAttribute attribute of the CoS definition entry.

The following example shows a template entry of the highest priority for a pointer CoS that generates the postalCode attribute:

dn: cn=ZipTemplate,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 95054
cosPriority: 0

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

Example of a Pointer CoS

The following command creates a pointer CoS definition entry that has the cosPointerDefinition object class. This definition entry uses the CoS template entry given above to share a common postal code among all entries in the ou=People,dc=example,dc=com tree.

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=pointerCoS,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=ZipTemplate,ou=People,dc=example,dc=com
cosAttribute: postalCode

The CoS template entry (cn=ZipTemplate,ou=People,dc=example,dc=com) supplies the value stored in its postalCode attribute to all entries located under the ou=People,dc=example,dc=com suffix. If you search for any entry that does not have a postal code in the same subtree, you will see the value of the generated attribute:

ldapsearch -h host -p port -D "cn=Directory Manager" -w password \
-b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
postalCode: 95054

Example of an Indirect CoS

Indirect CoS names an attribute in the cosIndirectSpecifier attributre to locate the template specific to each target. This indirect CoS uses the manager attribute of the target entry to identify the CoS template entry. The template entry is the manager's user entry, and it must contain the value of the attribute to generate.

The following command creates the indirect CoS definition entry, containing the cosIndirectDefinition object class:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=generateDeptNum,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier: manager
cosAttribute: departmentNumber

Next, add the cosTemplate object class to the template entries, and make sure they define the attribute to be generated. In this example, all manager entries will be templates:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=Carla Fuentes,ou=People,dc=example,dc=com
changetype: modify
add: objectclass
objectclass: cosTemplate
-
add: departmentNumber
departmentNumber: 318842

With this CoS, target entries (the entries under ou=People,dc=example,dc=com) containing the manager attribute will automatically have the department number of their manager. The departmentNumber attribute is virtual on the target entries because it does not exist in the server, but it is returned as part of the target entry. For example, if Babs Jensen's manager is defined to be Carla Fuentes, her department number will be the following:

ldapsearch -h host -p port -D "cn=Directory Manager" -w password \
-b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
manager: cn=Carla Fuentes,ou=People,dc=example,dc=com
departmentNumber: 318842

Example of a Classic CoS

This example shows how to generate a postal address with a classic CoS. The generated value is given in a template entry that is found by a combination of the cosTemplateDN in the CoS definition and the value of the cosSpecifier attribute in the target entry. The following command creates the definition entry using the cosClassicDefinition object class:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=classicCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: ou=People,dc=example,dc=com
cosSpecifier: building
cosAttribute: postalAddress

Continuing the same command, create the template entries that give the postal address for each building:

dn: cn=B07,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalAddres: 7 Old Oak Street$Anytown, CA 95054

With this CoS, target entries (the entries under ou=People,dc=example,dc=com) containing the building attribute will automatically have the corresponding postal address. The CoS mechanism searches for a template entry that has the specifier attribute value in its RDN. In this example, if Babs Jensen is assigned to building B07, her postal address will be generated as follows:

ldapsearch -h host -p port -D "cn=Directory Manager" -w password \
-b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
building: B07
postalAddres: 7 Old Oak Street$Anytown, CA 95054

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 multivalued, 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: (isManager=True)
Description: filtered role for managers

The classic CoS definition entry would be created as follows:

dn: cn=generateManagerQuota,ou=People,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 CoS template name must be a combination of the cosTemplateDn and the value of nsRole, which is the DN of the role. For example:

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

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. Target entries which are members of the role will have virtual attributes generated by the role and by the CoS, for example:

ldapsearch -h host -p port -D "cn=Directory Manager" -w password \
-b "ou=People,dc=example,dc=com" -s sub "(cn=*Fuentes)"
dn: cn=Carla Fuentes,ou=People,dc=example,dc=com
cn: Carla Fuentes
isManager: TRUE
...
nsRole: cn=ManagerRole,ou=People,dc=example,dc=com
mailboxquota: 1000000



Note

The role entry and the CoS definition entry should be located in the same place in the directory tree so that they have the same target entries in their scope. The CoS target entry should also be located in the same place so that it is easy to find and maintain.




Previous     Contents     Index     Next    
Copyright 2003 Sun Microsystems, Inc. All rights reserved.