Chapter 12. Managing the Directory Schema
Red Hat Directory Server comes with a standard schema that includes hundreds of object classes and attributes. While the standard object classes and attributes should meet most deployments' requirements, it can be necessary to extend the schema for specific directory data. Extending the schema is done by creating new object classes and attributes.
The Red Hat Directory Server 11 Configuration, Command, and File Reference is a reference for most the standard Directory Server attributes and object classes, with information on allowed and required attributes, which object classes take which attribute, and OID and value information. This is a good resource for identifying useful schema elements for a directory and determining what custom schema needs to be created.
12.1. Overview of Schema
The directory schema is a set of rules that defines how data can be stored in the directory. Directory information is stored discrete entries, and each entry is comprised of a set of attributes and their values. The kind of identity being described in the entry is defined in the entry's object classes. An object class specifies the kind of object the entry describes through the defined set of attributes for the object class.
In LDAP, an object class defines the set of attributes that can be used to define an entry. The LDAP standard provides object classes for many common types of entries, including people, groups, locations, organizations and divisions, and equipment. The identity is described in a directory entries with attributes and their values, pairs are called attribute-value assertions or AVAs. Any piece of information in the directory is associated with a descriptive attribute. Other aspects of the Directory Server configuration, including matching rules and LDAP controls, are also defined in the schema. All of these together are schema elements.
Every schema element is identified by a unique, dot-separated number. This is called the object identifier or OID.
12.1.1. Default Schema Files
The schema for Directory Server is defined in several different schema files (LDIF files which define schema elements). The Directory Server schema files are located in the
/usr/share/dirsrv/schema/directory. The files in this directory are used as templates for new Directory Server instances. Adding a new schema into this directory will make it available to any new instances.
The attributes used by the Directory Server to perform operations and manage entries is described with other configuration settings in the Red Hat Directory Server 11 Configuration, Command, and File Reference.
12.1.2. Object Classes
In LDAP, an object class defines the set of attributes that can be used to define an entry. The LDAP standard provides object classes for many common types of entries, such as people (
inetOrgPerson), groups (
groupOfNames), locations (
locality), organizations and divisions (
organizationalUnit), and equipment (
In a schema file, an object class is identified by the
objectclassesline, then followed by its OID, name, a description, its direct superior object class (an object class which is required to be used in conjunction with the object class and which shares its attributes with this object class), and the list of required (
MUST) and allowed (
This is shown in Example 12.1, “person Object Class Schema Entry”.
Example 12.1. person Object Class Schema Entry
objectClasses: ( 220.127.116.11 NAME 'person' DESC 'Standard LDAP objectclass' SUP top MUST ( sn $ cn ) MAY ( description $ seeAlso $ telephoneNumber $ userPassword ) X-ORIGIN 'RFC 4519' )
Every object class defines a number of required attributes (
MUSTkeyword in the schema) and of allowed attributes (
MAYkeyword in the schema). Required attributes must be present in entries using the specified object class, while allowed attributes are permissible and available for the entry to use, but are not required for the entry to be valid.
As in Example 12.1, “person Object Class Schema Entry”, the
personobject class requires the
objectClassattributes and allows the
An object class can inherit attributes from another class, in addition to its own required and allowed attributes. The second object class is the superior or parent object class of the first.
For example, a user's entry has to have the
inetOrgPersonobject class. In that case, the entry must also include the superior object class for
organizationalPerson, and the superior object class for
organizationalPerson, which is
objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson
An object class definition is an
objectclassesattribute for the
objectclassesattribute has the format:
objectclasses: ( definition )
The object class definition contains several components:
- An OID, usually a dot-separated number
- A unique name, in the form
- A description, in the form
- The superior, or parent, object class for this object class, in the form
SUPobject_class; if there is no related parent, use
- The word
AUXILIARY, which gives the type of entry to which the object class applies;
AUXILIARYmeans it can apply to any entry
- A list of required attributes, preceded by the word
MUST; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
- A list of allowed attributes, preceded by the word
MAY; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
Customer object class definitions are stored in the
/etc/dirsrv/slapd-instance_name/schema/99user.ldifwhen using the command line or the web console to modify
Directory entries are composed of attributes and their values. These pairs are called attribute-value assertions or AVAs. Any piece of information in the directory is associated with a descriptive attribute. For instance, the
cnattribute is used to store a person's full name, such as
cn: John Smith.
Additional attributes can supply additional information about John Smith:
givenname: John surname: Smith mail: firstname.lastname@example.org
In a schema file, an attribute is described by:
- syntax matching rule (optional)
- substring matching rules (optional)
- ordering rule (optional)
- description (optional)
- single-valued or multi-valued attribute
- details about where the attribute is defined
This is shown in Example 12.2, “
uidAttribute Schema Entry”.
uid Attribute Schema Entry
( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' ) EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 18.104.22.168.4.1.1422.214.171.124.15 X-ORIGIN 'RFC 4519' )
126.96.36.199. Directory Server Attribute Syntaxes
The attribute's syntax defines the format of the values which the attribute allows; as with other schema elements, the syntax is defined for an attribute using the syntax's OID in the schema file entry.
The Directory Server uses the attribute's syntax to perform sorting and pattern matching on entries.
For more information about LDAP attribute syntaxes, see RFC 4517.
Supported LDAP attribute syntaxes are covered in section Directory Server Attribute Syntaxes of the Red Hat Directory Server 10 Configuration, Command, and File Reference.
12.1.4. Extending the Schema
New, custom attributes and object classes can be added to a Directory Server instance to extend the schema, and there are several ways to add schema elements. Using LDAP tools adds schema elements to the default custom schema file for an instance,
99user.ldif. It is also possible to create a new, separate schema file and include it with the default schema files.
Adding new schema elements requires three things:
- Planning and defining OIDs for the new schema. Schema elements are recognized by the server by their OID, so it is important for the OIDs to be unique and organized. Directory Server itself does not manage OIDs, but there are some best practices described in Section 12.2, “Managing Object Identifiers”.
- Create the new attributes. Attribute definitions require a name, a syntax (the allowed format of the values), an OID, and a description of whether the attribute can only be used once per entry or multiple times.
- Create an object class to contain the new attributes. An object class lists the required attributes for that entry type and the allowed (permissible) attributes. Because the default schema should never be altered, if any new attributes are created, then they should be added to a custom object class.
The schema elements should be planned in advance; do not use multiple attributes for the same information. Whenever possible, use the standard Directory Server schema. Directory Server has hundreds of attributes and dozens of object classes defined in the default schema files. The Red Hat Directory Server 11 Configuration, Command, and File Reference lists and describes the standard attributes and object classes; all of the schema can be viewed in the schema files in
/usr/share/dirsrv/schema/. Become familiar with the available schema; then plan what information attributes are missing and how best to fill those gaps with custom attributes. Planning the schema is covered in the Deployment Guide.
The default object classes and attributes in Directory Server are based on LDAP and X.500 standards and RFCs. Using standard schema makes the Directory Server more easily integrated with other applications and servers and allows interoperability with LDAP clients, legacy Directory Server instances, and future release. It is inadvisable for you to edit the standard attributes or change the object classes.
Keep the following rules in mind when customizing the Directory Server schema:
- Keep the schema as simple as possible.
- Reuse existing schema elements whenever possible.
- Minimize the number of mandatory attributes defined for each object class.
- Do not define more than one object class or attribute for the same purpose.
- Do not modify any existing definitions of attributes or object classes.
Never delete or replace the standard schema. Doing so can lead to compatibility problems with other directories or other LDAP client applications.
The schema is loaded into the Directory Server instance when the instance is started; any new schema files are not loaded until the Directory Server is restarted or unless a reload task is initiated. The default custom schema file for an instance, 99user.ldif, is loaded as the last schema file. If it contains definitions already present in standard schema files, the custom definition will override the standard ones.
12.1.5. Schema Replication
When the directory schema is updated in the
cn=schemasub-tree, Directory Server stores the changes in the local
/etc/dirsrv/slapd-instance_name/schema/99user.ldiffile, including a change state number (CSN). The updated schema is not automatically replicated to other replicas. The schema replication starts when directory content is updated in the replicated tree. For example, if you update a user or group entry after modifying the schema, the supplier compares the CSN stored in the
nsSchemaCSNattribute with the one on the consumer. If the remote CSN is lower than the one on the supplier, the schema is replicated to the consumer. For a successful replication, all object classes and attribute types on the supplier must be a superset of the consumer's definition.
Example 12.3. Schema subsets and supersets
demoobject class allows the
demoobject class allows the
In Example 12.3, “Schema subsets and supersets”, the schema definition of the
demoobject class on
server1is a superset of the object class on
server2. During the validation phase, when the schema is being replicated or accepted, Directory Server retrieves the superset definitions. For example, if a consumer detects that an object class in the local schema allows less attributes than the object class in the supplier schema, the local schema is updated.
If the schema definitions are successfully replicated, the
nsSchemaCSNattributes are identical on both servers and no longer compared at the beginning of a replication session.
In the following scenarios, the schema is not replicated:
- The schema on one host is a subset of the schema of another host.For example, in Example 12.3, “Schema subsets and supersets”, the schema definition of the
demoobject class on
server2is a subset of the object class on
server1. Subsets can also occur for attributes (a single-value attribute is a subset of a multi-value attribute) and attribute syntaxes (
IA5is a subset of
- When definitions in supplier schema and consumer schema need to be merged.Directory Server does not support merging schemas. For example, if an object class on one server allows the
a4on the other, the schemas are not subsets and cannot be merged.
- Schema files other than
/etc/dirsrv/slapd-instance_name/schema/99user.ldifare used.Directory Server enables you to add additional schema files in the
/etc/dirsrv/slapd-instance_name/schema/directory. However, only the CSN in the
99user.ldiffile is updated. For this reasons, other schema file are only used locally and are not automatically transferred to replication partners. Copy the updated schema file manually to the consumers and reload the schema. For details, see Section 12.10, “Dynamically Reloading Schema”.To avoid duplicate schema definitions and to enable automatic replication, store all custom schema in the
/etc/dirsrv/slapd-instance_name/schema/99user.ldiffile. For further information about creating custom schema files, see Section 12.9, “Creating Custom Schema Files”.