7.2. Assigning Class of Service
A class of service definition (CoS) shares attributes between entries in a way that is transparent to applications. CoS simplifies entry management and reduces storage requirements.
Clients of the Directory Server read the attributes in a user's entry. With CoS, some attribute values may not be stored within the entry itself. Instead, these attribute values are generated by class of service logic as the entry is sent to the client application.
Each CoS is comprised of two types of entry in the directory:
- CoS definition entry. The CoS definition entry identifies the type of CoS used. Like the role definition entry, it inherits from the
LDAPsubentryobject 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.
7.2.1. About the CoS Definition Entry
The CoS definition entry is an instance of the
cosSuperDefinition object class. The CoS definition entry also contains one of three object class that specifies the type of template entry it uses to generate the entry. The target entries which interact with the CoS 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
managerattribute of a target entry. The value of themanagerattribute 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, see Section 7.2.10, “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, the CoS definition entry can control this behavior.
7.2.2. 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 definition.
- 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
cosIndirectSpecifierattribute. This type of template is associated with an indirect CoS definition. - 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 definition.
7.2.3. How a Pointer CoS Works
An administrator creates 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 7.2, “Sample Pointer CoS”.
Figure 7.2. 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.
7.2.4. How an Indirect CoS Works
An administrator creates 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 7.3, “Sample Indirect CoS”.
Figure 7.3. 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.
7.2.5. How a Classic CoS Works
An administrator creates 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 7.4, “Sample Classic CoS”:
Figure 7.4. 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.
7.2.6. Handling Physical Attribute Values
The
cosAttribute attribute contains the name of another attribute which is governed by the class of service. This attribute allows an override qualifier after the attribute value which sets how the CoS handles existing attribute values on entries when it generates attribute values.
cosAttribute: attribute_name override
There are four override qualifiers:
default: Only returns a generated value if there is no corresponding attribute value stored with the entry.override: Always returns the value generated by the CoS, even when there is a value stored with the entry.operational: Returns a generated attribute only if it is explicitly requested in the search. Operational attributes do not need to pass a schema check in order to be returned. Whenoperationalis used, it also overrides any existing attribute values.Note
An attribute can only be made operational if it is defined as operational in the schema. For example, if the CoS generates a value for thedescriptionattribute, it is not possible to use theoperationalqualifier because this attribute is not marked operational in the schema.operational-default: 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.
If no qualifier is set,
default is assumed.
For example, this pointer CoS definition entry indicates that it is associated with a template entry,
cn=exampleUS,ou=data,dc=example,dc=com, 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:
dn: cn=pointerCoS,dc=example,dc=com
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com
cosAttribute: postalCode overrideNote
If an entry contains an attribute value generated by a CoS, the value of the attribute cannot be manually updated if it is defined with the operational or override qualifiers.
For more information about the CoS attributes, see the Red Hat Directory Server Configuration, Command, and File Reference.
7.2.7. Handling Multi-valued Attributes with CoS
Any attribute can be generated using a class of service — including multi-valued attributes. That introduces the potential for confusion. Which CoS supplies a value? Any of them or all of them? How is the value selected from competing CoS templates? Does the generated attribute use a single value or multiple values?
There are two ways to resolve this:
- Creating a rule to merge multiple CoS-generated attributes into the target entry. This results in multiple values in the target entry.
- Setting a priority to select one CoS value out of competing CoS definitions. This generates one single value for the target entry.
Note
Indirect CoS do not support the
cosPriority attribute.
The way that the CoS handles multiple values for a CoS attribute is defined in whether it uses a merge-schemes qualifier.
cosAttribute: attribute override merge-schemes
Note
The merge-schemes qualifier does not affect how the CoS handles physical attribute values or the override qualifier. If there are multiple competing CoS templates or definitions, then the same merge-schemes and override qualifiers have to be set on every
cosAttribute for every competing CoS definition. Otherwise, one combination is chosen arbitrarily from all possible CoS definitions.
Using the merge-schemes qualifier tells the CoS that it will, or can, generate multiple values for the managed attribute. There are two possible scenarios for having a multi-valued CoS attribute:
- One CoS template entry contains multiple instances of the managed CoS attribute, resulting in multiple values on the target entry. For example:
dn: cn=server access template,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: cosTemplate accessTo: mail.example.com accessTo: irc.example.com
Note
This method only works with classic CoS. - Multiple CoS definitions may define a class of service for the same target attribute, so there are multiple template entries. For example:
dn: cn=mail template,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: cosTemplate accessTo: mail.example.com dn: cn=chat template,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: cosTemplate accessTo: irc.example.com
However, it may be that even if there are multiple CoS definitions, only one value should be generated for the attribute. If there are multiple CoS definitions, then the value is chosen arbitrarily. This is an unpredictable and unwieldy option. The way to control which CoS template to use is to set a ranking on the template — a priority — and the highest prioritized CoS always "wins" and provides the value.
It is fairly common for there to be multiple templates completing to provide a value. For example, there can be a multi-valued
cosSpecifier attribute in the CoS definition entry. The template priority is set using the cosPriority attribute. This attribute represents the global priority of a particular template. A priority of zero is the highest priority.
For example, a CoS template entry for generating a department number appears as follows:
dn: cn=data,dc=example,dc=com objectclass: top 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.
Templates that contain no
cosPriority attribute are considered the lowest priority. 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.
Note
The behavior for negative
cosPriority values is not defined in Directory Server; do not enter negative values.
7.2.8. Searches for CoS-Specified Attributes
CoS definitions provide values for attributes in entries. For example, a CoS can set the
postalCode attribute for every entry in a subtree. Searches against those CoS-defined attributes, however, do not behave like searches against regular entries.
If the CoS-defined attribute is indexed with any kind of index (including presence), then any attribute with a value set by the CoS is not returned with a search. For example:
If an
- The
postalCodeattribute for Ted Morris is defined by a CoS. - The
postalCodeattribute for Barbara Jensen is set in her entry. - The
postalCodeattribute is indexed.
ldapsearch command uses the filter (postalCode=*), then Barbara Jensen's entry is returned, while Ted Morris's is not.
If the CoS-defined attribute is not indexed, then every matching entry is returned in a search, regardless of whether the attribute value is set locally or with CoS. For example:
If an
- The
postalCodeattribute for Ted Morris is defined by a CoS. - The
postalCodeattribute for Barbara Jensen is set in her entry. - The
postalCodeattribute is not indexed.
ldapsearch command uses the filter (postalCode=*), then both Barbara Jensen's and Ted Morris's entries are returned.
CoS allows for an override, an identifier given to the
cosAttribute attribute in the CoS entry, which means that local values for an attribute can override the CoS value. If an override is set on the CoS, then an ldapsearch operation will return a value for an entry even if the attribute is indexed, as long as there is a local value for the entry. Other entries which possess the CoS but do not have a local value will still not be returned in the ldapsearch operation.
Because of the potential issues with running LDAP search requests on CoS-defined attributes, take care when deciding which attributes to generate using a CoS.
7.2.9. 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. This is the same restriction that applies to using CoS-generated attributes in search filters.
7.2.10. Managing CoS from the Command Line
Because all configuration information and template data is stored as entries in the directory, standard LDAP tools can be used for CoS configuration and management.
7.2.10.1. 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.
A pointer CoS uses the
cosPointerDefinition object class. This object class identifies the template entry using an entry DN value specified in the cosTemplateDn attribute, as shown in Example 7.2, “An Example Pointer CoS Entry”.
Example 7.2. An Example Pointer CoS Entry
dn: cn=pointerCoS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass:cosPointerDefinitioncosTemplateDn:DN_string cosAttribute:list_of_attributes qualifier cn: pointerCoS
An indirect CoS uses the
cosIndirectDefinition object class. This type of CoS identifies the template entry based on the value of one of the target entry's attributes, as specified in the cosIndirectSpecifier attribute. This is illustrated in Example 7.3, “An Example Indirect CoS Entry”.
Example 7.3. An Example Indirect CoS Entry
dn: cn=indirectCoS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass:cosIndirectDefinitioncosIndirectSpecifier:attribute_name cosAttribute:list_of_attributes qualifier cn: indirectCoS
A classic CoS uses the
cosClassicDefinition object class. This identifies the template entry using both the template entry's DN (set in the cosTemplateDn attribute) and the value of one of the target entry's attributes (set in the cosSpecifier attribute). This is illustrated in Example 7.4, “An Example Classic CoS Entry”.
Example 7.4. An Example Classic CoS Entry
dn: cn=classicCoS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass:cosClassicDefinitioncosTemplateDn:DN_stringcosSpecifier:attribute_name cosAttribute:list_of_attributes qualifier cn: classicCoS
For a class of service, the object class defines the type of CoS, and the supporting attributes identify which directory entries are affected by defining the CoS template. Every CoS has one additional attribute which can be defined for it:
cosAttribute. The purpose of a CoS is to supply attribute values across multiple entries; the cosAttribute attribute defines which attribute the CoS generates values for.
7.2.10.2. Creating the CoS Template Entry from the Command Line
Each template entry is an instance of the
cosTemplate object class.
Note
Consider adding the
LDAPsubentry object class to a new template entry. 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, such as a user entry, the LDAPsubentry object class does not need to be added to the template entry.
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,ou=data,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438
The following sections provide examples of template entries along with examples of each type of CoS definition entry.
7.2.10.3. Example of a Pointer CoS
Example Corporation's administrator is creating a pointer CoS that shares a common postal code with all entries in the
dc=example,dc=com tree.
- Add a new pointer CoS definition entry to the
dc=example,dc=comsuffix usingldapmodify:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=pointerCoS,dc=example,dc=com changetype: add objectclass: top objectclass: cosSuperDefinition objectclass: cosPointerDefinition cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com cosAttribute: postalCode
- Create the template entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=exampleUS,ou=data,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438
The CoS template entry (
cn=exampleUS,ou=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.
7.2.10.4. Example of an Indirect CoS
This indirect CoS uses the
manager attribute of the target entry to identify the CoS template entry, which varies depending on the different values of the attribute.
- Add a new indirect CoS definition entry to the
dc=example,dc=comsuffix usingldapmodify:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=indirectCoS,dc=example,dc=com changetype: add objectclass: top objectclass: cosSuperDefinition objectclass: cosIndirectDefinition cosIndirectSpecifier: manager cosAttribute: departmentNumber
If the directory or modify the manager entries already contain the
departmentNumber attribute, then no other attribute needs to be added to the manager entries. The definition entry looks in the target suffix (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). It then checks the departmentNumber value in the manager entry that is listed. The value of the departmentNumber attribute will automatically be relayed to all of the manager's subordinates that have the manager attribute. The value of departmentNumber will vary depending on the department number listed in the different manager's entries.
7.2.10.5. Example of a Classic CoS
The Example Corporation administrator is creating a classic CoS that automatically generates postal codes using a combination of the template DN and the attribute specified in the
cosSpecifier attribute.
- Add a new classic CoS definition entry to the
dc=example,dc=comsuffix usingldapmodify:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=classicCoS,dc=example,dc=com changetype: add objectclass: top objectclass: cosSuperDefinition objectclass: cosClassicDefinition cosTemplateDn: cn=classicCoS,dc=example,dc=com cosSpecifier: businessCategory cosAttribute: postalCode override
- Create the template entries for the sales and marketing departments. Add the CoS attributes to the template entry. The
cnof the template sets the value of thebusinessCategoryattribute in the target entry, and then the attributes are added or overwritten according to the value in the template:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=sales,cn=classicCoS,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438 - dn: cn=marketing,cn=classicCoS,dc=example,dc=com changetype: add objectclass: top 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 the businessCategory attribute found in the entry and the cosTemplateDn, 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.
7.2.10.6. Searching for CoS Entries
CoS definition entries are operational entries and, by default, not returned in regular searches. To return CoS definition entries in searches, add the
ldapSubEntry object class to the CoS definition entries. For example:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=pointerCoS,ou=People,dc=example,dc=com changetype: add objectclass: ldapSubEntry
Then use the
(objectclass=ldapSubEntry) filter with the ldapsearch utility to search for entries containing the ldapSubEntry object class. For example:
# ldapsearch -x -s sub -b ou=People,dc=example,dc=com "(|(objectclass=*)(objectclass=ldapSubEntry))"
This search returns all regular entries in addition to CoS definition entries in the
ou=People,dc=example,dc=com subtree.
7.2.10.7. The costargettree attribute
The
costargettree attribute defines the subtrees to which the CoS schema applies. The values for costargettree for the schema and for multiple CoS schema may overlap their target trees arbitrarily.
| OID | 2.16.840.1.113730.3.1.552 |
| Syntax | DirectoryString |
| Multi or Single-Valued | Single-valued |
| Defined in | Directory Server |
7.2.11. Creating Role-Based Attributes
Classic CoS schemes generate attribute values for an entry based on the role possessed by the entry. For example, role-based attributes can be used 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, CoS schemes can be defined that have more than one possible template entry. To resolve the ambiguity of which template entry to use, include the cosPriority attribute in the CoS template entry.
For example, this CoS allows members of the manager role to exceed the standard mailbox quota. The manager role entry is:
dn: cn=ManagerRole,ou=people,dc=example,dc=com objectclass: top objectclass: nsRoleDefinition objectclass: nsComplexRoleDefinition objectclass: nsFilteredRoleDefinition cn: ManagerRole nsRoleFilter: ou=managers Description: filtered role for managers
Warning
The
nsRoleFilter attribute cannot accept virtual attribute values.
Do not index the virtual attribute values. Running a search on a virtual attribute can result in unexpected system behaviors or incorrect search results. An unindexed search breaks the search action that uses virtual attributes in the search filter. Virtual attributes are generated dynamically and are not stored on the Directory Server backend. Therefore virual attributes do not support indexing.
The classic CoS definition entry looks like:
dn: cn=managerCOS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass: 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: extensibleObject objectclass: 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.
