5.2.3. 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. This section contains the following topics:
5.2.3.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.
Table 5.2, “CoS Definition Entry Object Classes” lists the object classes associated with each type of CoS definition entry.
|
CoS Type
|
Object Classes
|
Description
|
|---|
|
Pointer CoS
|
cosPointerDefinition
|
Identifies the template entry associated with the CoS definition using the template entry's DN value. The DN of the template entry is specified in the cosTemplateDn attribute.
|
|
Indirect CoS
|
cosIndirectDefinition
|
Identifies the template entry using the value of one of the target entry's attributes. The attribute of the target entry is specified in the cosIndirectSpecifier attribute.
|
|
Classic CoS
|
cosClassicDefinition
|
Identifies the template entry using both the template entry's DN (as specified in the cosTemplateDn attribute) and the value of one of the target entry's attributes (as specified in the cosSpecifier attribute).
|
Table 5.2. CoS Definition Entry Object Classes
|
Attribute
|
Definition
|
|---|
|
cosAttribute
|
Provides the name of the attribute for which to generate a value. There can be more than one cosAttribute value. This attribute is used by all types of CoS definition entries.
|
|
cosIndirectSpecifier
|
Specifies the attribute value used by an indirect CoS to identify the template entry.
|
|
cosSpecifier
|
Specifies the attribute value used by a classic CoS, which, along with the template entry's DN, identifies the template entry.
|
|
cosTemplateDn
|
Provides the DN of the template entry associated with the CoS definition. Used for pointer CoS and classic CoS only.
|
Table 5.3. CoS Definition Entry Attributes
The cosAttribute attribute allows an additional qualifier after the attribute value. There are four possible qualifiers:
Default. This qualifier indicates that the server only returns a generated value if there is no corresponding attribute value stored with the entry.
Override. This qualifier indicates that the server always returns the value generated by the CoS, even when there is a value stored with the entry.
Operational. This qualifier indicates that the attribute will only be returned if it is explicitly requested in the search. Operational attributes do not need to pass a schema check in order to be returned. When operational is used as a qualifier, it works as if override and operational were specified.
NOTE
An attribute can only be made operational if it is also defined as operational in the schema. For example, if the CoS generates a value for the description attribute, it is not possible to use the operational qualifier because this attribute is not marked operational in the schema.
Operational-default. This qualifier indicates that the server only returns a generated value if there is no corresponding attribute value stored with the entry and if it is explicitly requested in the search.
If no qualifier is set, default is assumed.
For example, a pointer CoS definition entry that contains an override qualifier is created as follows:
dn: cn=pointerCoS,dc=example,dc=com
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com
cosAttribute: postalCode override
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.
NOTE
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 attributes, refer to the Directory Server Configuration, Command, and File Reference.
|
CoS Type
|
CoS definition
|
|---|
|
Pointer CoS
|
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn:DN_string
cosAttribute:list_of_attributes qualifier
|
|
Indirect CoS
|
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier:attribute_name
cosAttribute:list_of_attributes qualifier
|
|
Classic CoS
|
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn:DN_string
cosSpecifier:attribute_name
cosAttribute:list_of_attributes qualifier
|
Table 5.4. CoS Definitions
CoS definition entries are operational entries and are not returned by default with regular searches. This means that if a CoS is defined under ou=People,dc=example,dc=com, for example, the following ldapsearch command will not return them:
ldapsearch -s sub -b ou=People,dc=example,dc=com “(objectclass=*)”
To return the CoS definition entries, add the ldapSubEntry object class to the CoS definition entries. For example:
dn: cn=pointerCoS,ou=People,dc=example,dc=com
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
objectclass: ldapSubEntry
cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com
cosAttribute: postalCode override
Then use a special search filter, (objectclass=ldapSubEntry), with the search. This filter can be added to any other search filter using OR (|):
ldapsearch -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.
NOTE
The Console automatically shows CoS entries.
5.2.3.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
It is possible to create CoS templates that compete with each other to provide an attribute value. For example, there can be a multi-valued cosSpecifier attribute in the CoS definition entry. Specifying the template priority on each template entry determines which template provides the attribute value. Set the template priority using the cosPriority attribute. This attribute represents the global priority of a particular template. A priority of zero is the highest priority.
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. The behavior for negative cosPriority values is not defined in Directory Server; do not enter negative values. Also, the cosPriority attribute is not supported by indirect CoS.
The following sections provide examples of template entries along with examples of each type of CoS definition entry.