The class of service (CoS) mechanism generates computed attributes as an entry is retrieved for a client application, which simplifies entry management and reduces storage requirements. The CoS mechanism allows attributes to be shared between entries, and as with groups and roles, CoS relies on helper entries.
For an explanation of how you can use CoS in your deployment, see Managing Attributes With Class of Service in Sun Java System Directory Server Enterprise Edition 6.0 Deployment Planning Guide.
For a description of how CoS is implemented in Directory Server, see Chapter 9, Directory Server Class of Service, in Sun Java System Directory Server Enterprise Edition 6.0 Reference.
Any search operation can test the existence of a CoS-generated attribute or compare the value of the attribute. The names of the computed attributes may be used in any filter string from a client search operation, except in an internal filter used in a filtered role.
The following sections describe the general principles for read and write protection of data in each of the CoS entries. The detailed procedure for defining individual access control instructions (ACIs) is described in Chapter 6, Directory Server Access Control.
Although the CoS definition entry does not contain the value of the generated attribute, it does provide the information to find that value. Reading the CoS definition entry reveals how to find the template entry that contains the value. Writing to this entry modifies how the computed attribute is generated.
You should therefore define both read and write ACIs for the CoS definition entries.
The CoS template entry contains the value of the generated CoS attribute. Therefore, at a minimum, the CoS attribute in the template must be protected by an ACI for both reading and updating.
In the case of pointer CoS, the single template entry should not be allowed to be renamed. In most cases, it is simplest to protect the entire template entry.
With classic CoS, all template entries have a common parent specified in the definition entry. If only templates are stored in this parent entry, access control to the parent entry protects the templates. However, if other entries beneath the parent require access, the template entries must be protected individually.
In the case of indirect CoS, the template can be any entry in the directory, including user entries that might still need to be accessed. Depending on your needs, you can either control access to the CoS attribute throughout the directory or ensure that the CoS attribute is secure in each entry that is used as a template.
All entries in the scope of a CoS definition, for which the computed CoS attribute is generated, also contribute to computing its value.
When the CoS attribute already exists in a target entry, by default, the CoS mechanism does not override this value. If you do not want this behavior, define your CoS to override the target entry, or protect the CoS attribute in all potential target entries.
Both indirect and classic CoS also rely on a specifier attribute in the target entry. This attribute specifies the DN or RDN of the template entry to use. You should use an ACI to protect this attribute either globally throughout the scope of the CoS or individually on each target entry where it is needed.
Computed CoS attributes can be defined in terms of other generated CoS attributes and roles. You must understand and protect these dependencies to ensure that your computed CoS attribute is protected.
For example, the CoS specifier attribute in a target entry could be nsRole. Therefore the role definition must also be protected by an ACI.
In general, any attribute or entry that is involved in the computation of the computed attribute value should have an ACI for both read and write access control. For this reason, complex dependencies should be well planned or simplified to reduce subsequent complexity of access control implementation. Keeping dependencies on other computed attributes to a minimum improves directory performance and reduces maintenance.
Because all configuration information and template data are stored as entries in the directory, you can use the LDAP command-line tools to configure and manage CoS definitions. This section shows how to create CoS definition entries and CoS template entries 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 that are associated with each type of CoS definition entry.
Table 9–1 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 objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosClassicDefinition cosTemplateDN: DN cosSpecifier: attributeName cosAttribute: attributeName override merge |
In all cases, cosAttribute is multivalued. Each value defines an attribute that is generated by the CoS mechanism.
You can use the following attributes in CoS definition entries. For more information about each of these attributes, see the individual attributes in Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference.
Table 9–2 CoS Definition Entry Attributes
Attribute |
Purpose Within the CoS Definition Entry |
---|---|
cosAttribute attributeName override merge |
Defines the name of the computed attribute for which you want to generate a value. This attribute is multivalued, and each value represents the name of an attribute whose value is generated from the template. The override and merge qualifiers specify how the CoS attribute value is computed in special cases described following this table. The attributeName cannot contain any subtypes. Attribute names with subtypes are ignored, but other values of cosAttribute are 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 attributeName can 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 attributeName can 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. This attribute is single-valued. |
The cosAttribute attribute allows two qualifiers following the name of the CoS attribute, the override qualifier and the merge qualifier.
The override qualifier describes the behavior when an attribute that is dynamically generated by CoS already physically exists in the entry. The override qualifier can be one of the following:
default (or no qualifier) - Indicates that the server does not override a real attribute value stored in the entry when the attribute is of the same type as the computed attribute.
override - Indicates that the server always returns the value generated by the CoS, even when a value is 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 to be returned. The operational qualifier has the same behavior as the override qualifier.
You can only make an attribute operational if the attribute 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 the description attribute is not marked operational in the schema.
The merge qualifier is either absent or merge-schemes. This qualifier allows the computed CoS attribute to be multivalued, either from multiple templates or multiple CoS definitions. For more information, see Multivalued CoS Attributes.
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 the entry 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 takes precedence over the value of the postalCode attribute if the attribute exists in a target entry.
If the CoS attribute is defined with the operational or override qualifiers, you cannot perform write operations on the “real” value of that attribute in any entry in the CoS scope.
When you specify the merge-schemes qualifier, the generated CoS attribute can be multivalued in two ways:
With indirect or classic CoS, the specifier attributes in target entries can be multivalued. In this case, each value determines a template, and the value from each template is part of the generated value.
Multiple CoS definition entries of any type can contain the same attribute name in their cosAttribute. In this case, if all definitions contain the merge-schemes qualifier, the generated attribute contains all values computed by each definition.
The two situations can occur together and define even more values. However, in all cases, duplicate values will only be returned one time in a generated attribute.
In the absence of the merge-schemes qualifier, the cosPriority attribute of the template entry is used to determine a single value among all templates for the generated attribute. This scenario is described in the next section.
The merge-schemes qualifier never merges a “real” value that is 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 can be specified in any order after the attribute name.
When there are multiple CoS definitions for the same attribute, the definitions 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.
If multiple CoS definitions or multivalued specifiers exist, but no merge-schemes qualifier, Directory Server uses a priority attribute to select a single template that defines the single value of the computed 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 that the templates define. The cosPriority attribute is defined on CoS template entries as described in the following section.
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.
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 class 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 or given the LDAPsubentry object class, but the target must have the auxiliary cosTemplate object class. The indirect CoS template is accessed only when the CoS is evaluated to generate a computed 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.
The following command creates a pointer CoS definition entry that has the cosPointerDefinition object class. This definition entry uses the CoS template entry that is stated in the example in the previous section to share a common postal code among all entries in the ou=People,dc=example,dc=com tree.
$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - 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 host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \ -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 |
Indirect CoS names an attribute in the cosIndirectSpecifier attribute to locate the template specific to each target. The template entry for indirect CoS may be any entry in the directory, including other user entries. This example 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. The manager’s user entry contains the value of the attribute to generate. The value is that of departmentNumber in this case.
The following command creates the indirect CoS definition entry, which contains the cosIndirectDefinition object class:
$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - 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 that they define the attribute to be generated. In this example, all manager entries are templates:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - 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) that contain the manager attribute automatically have the department number of their manager. The departmentNumber attribute is computed on the target entries because it does not exist in the server. However, the departmentNumber attribute is returned as part of the target entry. For example, if Babs Jensen’s manager is defined to be Carla Fuentes, her department number is the following:
$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \ -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 |
This example shows how to generate a postal address with a classic CoS. The generated value is specified in a template entry that is located 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 by using the cosClassicDefinition object class:
$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - 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 |
Using 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) that contain 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 is generated as follows:
$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \ -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 postalAddress: 7 Old Oak Street, Anytown, CA 95054 |
You can create classic CoS schemes that generate attribute values for an entry that is 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 is 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 is created as follows:
dn: cn=generateManagerQuota,ou=People,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosClassicDefinition cosTemplateDn: cn=managerCOS,ou=People,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",\ cn=managerCOS,ou=People,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: extensibleobject objectclass: 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 that are members of the role will have computed attributes generated by the role and by the CoS, for example:
$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -\ -b "ou=People,dc=example,dc=com" -s sub "(cn=*Fuentes)" dn: cn=Carla Fuentes,ou=People,dc=example,dc=comcn: Carla Fuentes isManager: TRUE...nsRole: cn=ManagerRole,ou=People,dc=example,dc=com mailboxquota: 1000000 |
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.
Directory Server enables you to monitor certain aspects of the CoS plug-in. CoS monitoring attributes are stored in the cn=monitor,cn=Class of Service,cn=plugins,cn=config entry. For details of the each attribute under this entry and the information that they provide, see Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference.
Directory Server logs warning messages when it is forced to make an arbitrary distinction among multiple applicable definition entries. Such warning messages takes this form:
Definition /defDN1/ and definition /defDN2/ compete to provide attribute '/type/' at priority /level/ |
You can also configure Directory Server to log informational messages when the server is forced to make an arbitrary distinction among multiple, potentially applicable definition entries. To do so, set the error log to include messages from plug-ins.
Because setting additional log levels can result in a heavy logging load, you might not want to set logging on a production server.
The content of informational messages takes the following form:
Definition /defDN1/ and definition /defDN2/ potentially compete to provide attribute '/type/' at priority /level/ |
You can then choose whether to resolve such cases of CoS ambiguity by setting CoS priorities appropriately on the definition entries.