The Class of Service (CoS) mechanism allows attributes to be shared between entries. CoS values are calculated dynamically when they are requested. For information about CoS, see the following sections:
Imagine a directory containing thousands of entries that all have the same value for the facsimileTelephoneNumber attribute. Traditionally, to change the fax number, you would update each entry individually, a time consuming job for administrators. Using CoS, the fax number is stored in a single place, and the facsimileTelephoneNumber attribute is automatically generated on every entry as it is returned.
To client applications, a CoS attribute is generated in the same ways as any other attribute. However, directory administrators now have only a single fax value to manage. Also, because there are fewer values stored in the directory, the database uses less disk space. The CoS mechanism also allows entries to override a generated value or to generate multiple values for the same attribute.
Because CoS virtual attributes are not indexed, referencing them in an LDAP search filter may have an impact on performance.
Generated CoS attributes can be multivalued. Specifiers can designate several template entries, or there can be several CoS definitions for the same attribute. Alternatively, you can specify template priorities so that only one value is generated from all templates.
Roles and classic CoS can be used together to provide role-based attributes. These attributes appear on an entry because it possesses a particular role with an associated CoS template. You could use a role-based attribute to set the server look through limit on a role-by-role basis, for example.
CoS functionality can be used recursively; you can generate attributes through CoS that depend on other attributes generated through CoS. Complex CoS schemes can simplify client access to information and ease administration of repeated attributes, but they also increase management complexity and degrade server performance. Avoid overly complex CoS schemes; many indirect CoS schemes can be redefined as classic or pointer CoS, for example.
You should also avoid changing CoS definitions more often than necessary. Modifications to CoS definitions do not take effect immediately, because the server caches CoS information. Although caching accelerates read access to generated attributes, when changes to CoS information occur, the server must reconstruct the cache. This task can take some time, usually in the order of seconds. During cache reconstruction, read operations may still access the old cached information, rather than the newly modified information, which means that if you change CoS definitions too frequently, you are likely to be accessing outdated data.
The CoS mechanism relies on two types of entries, the CoS definition entry and the CoS template entry. This section describes the CoS definition entry and the CoS template entry.
The CoS definition entry identifies the type of CoS and the names of the CoS attributes that will be generated. Like the role definition entry, the CoS definition entry inherits from the LDAPsubentry object class. Multiple definitions may exist for the same CoS attribute, which, as a result, may be multivalued.
The CoS definition entry is an instance of the cosSuperDefinition object class. The CoS definition entry also inherits from one of the following object classes to specify the type of CoS:
The CoS definition entry contains the attributes specific to each type of CoS for naming the virtual CoS attribute, the template DN, and the specifier attribute in target entries. By default, the CoS mechanism will not override the value of an existing attribute with the same name as the CoS attribute. However, the syntax of the CoS definition entry allows you to control this behavior.
When schema checking is turned on, the CoS attribute will be generated on all target entries that allow that attribute. When schema checking is turned off, the CoS attribute will be generated on all target entries.
The location of the definition entry determines the scope of the CoS, which is the entire subtree below the parent of the CoS definition entry. All entries in the branch of the definition entry’s parent are called target entries for the CoS definition.
The following figure shows a CoS definition entry at the root of the ou=people subtree. The scope of the CoS is only the two subtrees beneath the root. The CoS does not extend above this root, or to other subtrees in the DIT.
The CoS template entry contains the value that is generated for the CoS attribute. All entries within the scope of the CoS use the values defined here. There may be several templates, each with a different value, in which case the generated attribute may be multivalued. The CoS mechanism selects one of these values based on the contents of both the definition entry and the target entry.
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. You should also name them in a way that suggests the functionality they provide. For example, a definition entry DN such as "cn=classicCosGenEmployeeType,ou=People,dc=example,dc=com" is more descriptive than "cn=ClassicCos1,ou=People,dc=example,dc=com". For more information about the object classes and attributes associated with each type of CoS, see Class of Service in Sun Java System Directory Server Enterprise Edition 6.1 Administration Guide.
The following types of CoS differ in how the template, and therefore the generated value, is selected:
Pointer CoS is the simplest type of CoS. The pointer CoS definition entry provides the DN of a specific template entry of the cosTemplate object class. All target entries have the same CoS attribute value, as defined by this template.
The following figure shows a pointer CoS that defines a common postal code for all of the entries stored under dc=example,dc=com. The CoS definition entry, CoS template entry and target entry are indicated.
The template entry is identified by its DN, cn=exampleUS,cn=data, in the CoS definition entry. Each time the postalCode attribute is queried on entries under dc=example,dc=com, Directory Server returns the value available in the template entry cn=exampleUS,cn=data. Therefore, the postal code will appear with the entry uid=wholiday,ou=people,dc=example,dc=com, but it is not stored there.
In a scenario where several shared attributes are generated by CoS for thousands or millions of entries, instead of existing as real attributes in each entry, the storage space savings and performance gains provided by CoS are considerable.
Indirect CoS allows any entry in the directory to be a template and provide the CoS value. The indirect CoS definition entry identifies an attribute, called the indirect specifier, whose value in a target entry determines the template used for that entry. The indirect specifier attribute in the target entry must contain a DN. With indirect CoS, each target entry may use a different template and thus have a different value for the CoS attribute.
For example, an indirect CoS that generates the departmentNumber attribute may use an employee’s manager as the specifier. When retrieving a target entry, the CoS mechanism will use the DN value of the manager attribute as the template. It will then generate the departmentNumber attribute for the employee using the same value as the manager’s department number.
Because templates may be arbitrary entries anywhere in the directory tree, implementing access control for indirect CoS can become extremely complex. In deployments where performance is critical, you should also avoid overusing indirect CoS due to its resource intensive nature.
In many cases, results that are similar to those made possible by indirect CoS can be achieved by limiting the location of the target entries with classic CoS or using the less flexible pointer CoS mechanism.
The following figure shows an indirect CoS that uses the manager attribute of the target entry to identify the template entry. In this way, the CoS mechanism can generate the departmentNumber attribute of all employees to be the same as their manager’s, ensuring that it is always up to date.
The indirect CoS definition entry names the specifier attribute, which in this example, is the manager attribute. William Holiday’s entry is one of the target entries of this CoS, and his manager attribute contains the DN of uid=cfuentes,ou=people,dc=example,dc=com. Therefore, Carla Fuentes’s entry is the template, which in turn provides the departmentNumber attribute value of 318842.
Classic CoS combines the pointer and indirect CoS behavior. The classic CoS definition entry identifies the base DN of the template and a specifier attribute. The value of the specifier attribute in the target entries is then used to construct the DN of the template entry as follows:
The template containing the CoS values is determined by the combination of the RDN (relative distinguished name) value of the specifier attribute in the target entry and the template’s base DN.
Classic CoS templates are entries of the cosTemplate object class to avoid the performance issue associated with arbitrary indirect CoS templates.
The classic CoS mechanism determines the DN of the template from the base DN given in the definition entry and the specifier attribute in the target entry. The value of the specifier attribute is taken as the cn value in the template DN. Template DNs for classic CoS must therefore have the following structure:
The following figure shows a classic CoS definition that generates a value for the postal code attribute.
In this example, the cosSpecifier attribute names the employeeType attribute. The combination of the cosSpecifier attribute and the template DN identifies the template entry as cn=sales,cn=exampleUS,cn=data. The template entry then provides the value of the postalCode attribute to the target entry.
It is possible to create CoS schemes that compete with each other to provide an attribute value. For example, you might have a multivalued cosSpecifier in your CoS definition entry. In such a case, you can specify a template priority on each template entry to determine which template provides the attribute value. Set the template priority using the cosPriority attribute. This attribute represents the global priority of a particular template numerically. A priority of zero is the highest possible priority.
Templates that contain no cosPriority attribute are considered the lowest possible priority. In the case where two or more templates are considered to supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily. Directory Server can be configured to log messages when it is forced to choose a template arbitrarily.
The CoS functionality is a complex mechanism which, for performance and security reasons, is subject to the following limitations:
You cannot create CoS definitions in either the cn=config or cn=schema subtrees.
Searches in suffixes where an attribute is declared as a CoS-generated attribute will result in an unindexed search. This may have a significant impact on performance. In suffixes where the same attribute is NOT declared as a CoS attribute, the search will be indexed.
Restricted attribute types
The following attributes should not be generated by CoS because they do not have the same behavior as real attributes of the same name.
userPassword - A CoS-generated password value cannot be used to bind to Directory Server.
aci - Directory Server will not apply any access control based on the contents of a virtual ACI value defined by CoS.
objectclass - 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.
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. Templates and the values they contain cannot be retrieved through directory chaining or referrals.
CoS virtual values cannot be combined with real values
The values of a CoS attribute are never a combination of real values from the entry and virtual values from the templates. When the CoS overrides a real attribute value, it replaces all real values with those from the templates. However, the CoS mechanism can combine virtual values from several CoS definition entries. For more information, see “CoS Limitations” in the Sun Java System Directory Server Enterprise Edition 6.1 Administration Guide.
The filter string of a filtered role cannot be based on the values of a CoS virtual attribute. However, the specifier attribute in a CoS definition may reference the nsRole attribute generated by a role definition. For more information, see “Creating Role-Based Attributes” in the Sun Java System Directory Server Enterprise Edition 6.1 Administration Guide.
The server controls access to attributes generated by a CoS in exactly the same way as regular, stored attributes. However, access control rules that depend on the value of attributes generated by CoS are subject to the conditions described in CoS Limitations.
The CoS cache is an internal structure that keeps all CoS data in memory to improve performance. This cache is optimized for retrieving CoS data to be used in computing virtual attributes, even while CoS definition and template entries are being updated. Therefore, once definition and template entries have been added or modified, there may be a slight delay before they are taken into account. This delay depends on the number and complexity of CoS definitions, as well as the current server load, but it is usually in the order of a few seconds. Consider this latency before designing overly complex CoS configurations.