Chapter 12. Managing the Directory Schema

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.

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.

This is shown in 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:

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.

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:

This is shown in 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' )

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:

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.

Keep the following rules in mind when customizing the Directory Server schema:

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.

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.

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: