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 (person and inetOrgPerson), groups (groupOfNames), locations (locality), organizations and divisions (organization and organizationalUnit), and equipment (device).
In a schema file, an object class is identified by the objectclasses line, 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 (MAY) attributes.

Example 12.1. person Object Class Schema Entry

objectClasses: ( 2.5.6.6 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 (MUST keyword in the schema) and of allowed attributes (MAY keyword 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 person object class requires the cn, sn, and objectClass attributes and allows the description, seeAlso, telephoneNumber, and userPassword attributes.
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 inetOrgPerson object class. In that case, the entry must also include the superior object class for inetOrgPerson, organizationalPerson, and the superior object class for organizationalPerson, which is person:
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
An object class definition is an objectclasses attribute for the cn=schema entry. The objectclasses attribute 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 NAME name
  • A description, in the form DESC description
  • The superior, or parent, object class for this object class, in the form SUP object_class; if there is no related parent, use SUP top
  • The word AUXILIARY, which gives the type of entry to which the object class applies; AUXILIARY means 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.ldif when using the command line or the web console to modify cn=schema entries.

12.1.3. Attributes

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 cn attribute 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: jsmith@example.com
In a schema file, an attribute is described by:
  • OID
  • name
  • syntax matching rule (optional)
  • substring matching rules (optional)
  • ordering rule (optional)
  • description (optional)
  • syntax
  • single-valued or multi-valued attribute
  • details about where the attribute is defined

Example 12.2. uid Attribute Schema Entry

( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' ) EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'RFC 4519' )

12.1.3.1. 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:
  1. 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”.
  2. 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.
  3. 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.

Warning

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.

Note

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=schema sub-tree, Directory Server stores the changes in the local /etc/dirsrv/slapd-instance_name/schema/99user.ldif file, 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 nsSchemaCSN attribute 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

  • On server1, the demo object class allows the a1, a2, and a3 attributes.
  • On server2, the demo object class allows the a1 and a3 attributes.
In Example 12.3, “Schema subsets and supersets”, the schema definition of the demo object class on server1 is 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 nsSchemaCSN attributes 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 demo object class on server2 is 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 (IA5 is a subset of Octet_string).
  • 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 a1, a2, and a3 attributes and a1, a3, and a4 on the other, the schemas are not subsets and cannot be merged.
  • Schema files other than /etc/dirsrv/slapd-instance_name/schema/99user.ldif are 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.ldif file 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.ldif file. For further information about creating custom schema files, see Section 12.9, “Creating Custom Schema Files”.