Chapter 1. About Directory Server Schema

This chapter provides an overview of some of the basic concepts of the directory schema and lists the files in which the schema is described. It describes object classes, attributes, and object identifiers (OIDs) and briefly discusses extending server schema and schema checking.

1.1. Schema Definitions

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.
Basically, the schema files are lists of the kinds of entries that can be create (the object classes) and the ways that those entries can be described (the attributes). The schema defines what the object classes and attributes are. The schema also defines the format that the attribute values contain (the attribute's syntax) and whether there can only be a single instance of that attribute.
Additional schema files can be added to the Directory Server configuration and loaded in the server, so the schema is customizable and can be extended as desired.
For more detailed information about object classes, attributes, and how the Directory Server uses the schema, see the Deployment Guide.

CAUTION

The Directory Server fails to start if the schema definitions contain too few or too many characters. Use exactly one space in those places where the LDAP standards allow the use of zero or many spaces; for example, the place between the NAME keyword and the name of an attribute type.

1.1.1. 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 (groupOfUniqueNames), 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 1.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 2256' )

1.1.1.1. Required and Allowed Attributes

Every object class defines a number of required attributes and of allowed attributes. 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 1.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.

NOTE

All entries require the objectClass attribute, which lists the object classes assigned to the entry.

1.1.1.2. Object Class Inheritance

An entry can have more than one object class. For example, the entry for a person is defined by the person object class, but the same person may also be described by attributes in the inetOrgPerson and organizationalPerson object classes.
Additionally, object classes can be hierarchical. 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 object class of the first.
The server's object class structure determines the list of required and allowed attributes for a particular entry. 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
When the inetOrgPerson object class is assigned to an entry, the entry automatically inherits the required and allowed attributes from the superior object classes.

1.1.2. 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 identified by the attributetypes line, then followed by its OID, name, a description, syntax (allowed format for its value), optionally whether the attribute is single- or multi-valued, and where the attribute is defined.

Example 1.2. description Attribute Schema Entry

attributetypes: ( 2.5.4.13 NAME 'description' DESC 'Standard LDAP attribute type' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'RFC 2256' )

Some attributes can be abbreviated. These abbreviations are listed as part of the attribute definition:
attributetypes: ( 2.5.4.3 NAME ( 'cn' 'commonName' ) ...

1.1.2.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. In the Directory Server Console, the syntax is referenced by its friendly name.
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.

Table 1.1. Supported LDAP Attribute Syntaxes

Name OID Definition
Binary 1.3.6.1.4.1.1466.115.121.1.5 Deprecated. Use Octet string instead.
Bit String 1.3.6.1.4.1.1466.115.121.1.6 For values which are bitstings, such as '0101111101'B.
Boolean 1.3.6.1.4.1.1466.115.121.1.7 For attributes with only two allowed values, TRUE or FALSE.
Country String 1.3.6.1.4.1.1466.115.121.1.11 For values which are limited to exactly two printable string characters; for example, US for the United States.
DN 1.3.6.1.4.1.1466.115.121.1.12 For values which are distinguished names (DNs).
Delivery Method 1.3.6.1.4.1.1466.115.121.1.14 For values which are contained a preferred method of delivering information or contacting an entity. The different values are separated by a dollar sign ($). For example:
telephone $ physical
Directory String 1.3.6.1.4.1.1466.115.121.1.15 For values which are valid UTF-8 strings. These values are not necessarily case-insensitive. Both case-sensitive and case-insensitive matching rules are available for Directory String and related syntaxes.
Enhanced Guide 1.3.6.1.4.1.1466.115.121.1.21 For values which contain complex search parameters based on attributes and filters.
Facsimile 1.3.6.1.4.1.1466.115.121.1.22 For values which contain fax numbers.
Fax 1.3.6.1.4.1.1466.115.121.1.23 For values which contain the images of transmitted faxes.
Generalized Time 1.3.6.1.4.1.1466.115.121.1.24 For values which are encoded as printable strings. The time zone must be specified. It is strongly recommended to use GMT time.
Guide 1.3.6.1.4.1.1466.115.121.1.25 Obsolete. For values which contain complex search parameters based on attributes and filters.
IA5 String 1.3.6.1.4.1.1466.115.121.1.26 For values which are valid strings. These values are not necessarily case-insensitive. Both case-sensitive and case-insensitive matching rules are available for IA5 String and related syntaxes.
Integer 1.3.6.1.4.1.1466.115.121.1.27 For values which are whole numbers.
JPEG 1.3.6.1.4.1.1466.115.121.1.28 For values which contain image data.
Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 For values which contain a combination value of a DN and (optional) unique ID.
Numeric String 1.3.6.1.4.1.1466.115.121.1.36 For values which contain a string of both numerals and spaces.
OctetString 1.3.6.1.4.1.1466.115.121.1.40 For values which are binary; this replaces the binary syntax.
OID 1.3.6.1.4.1.1466.115.121.1.37 For values which contain an object identifier (OID).
Postal Address 1.3.6.1.4.1.1466.115.121.1.41 For values which are encoded in the format postal-address = dstring * ("$" dstring). For example:
1234 Main St.$Raleigh, NC 12345$USA
Each dstring component is encoded as a DirectoryString value. Backslashes and dollar characters, if they occur, are quoted, so that they will not be mistaken for line delimiters. Many servers limit the postal address to 6 lines of up to thirty characters.
PrintableString 1.3.6.1.4.1.1466.115.121.1.58 For values which contain strings containing alphabetic, numeral, and select punctuation characters (as defined in RFC 4517).
Space-Insensitive String 2.16.840.1.113730.3.7.1 For values which contain space-insensitive strings.
TelephoneNumber 1.3.6.1.4.1.1466.115.121.1.50 For values which are in the form of telephone numbers. It is recommended to use telephone numbers in international form.
Teletex Terminal Identifier 1.3.6.1.4.1.1466.115.121.1.51 For values which contain an international telephone number.
Telex Number 1.3.6.1.4.1.1466.115.121.1.52 For values which contain a telex number, country code, and answerback code of a telex terminal.
URI For values in the form of a URL, introduced by a string such as http://, https://, ftp://, ldap://, and ldaps://. The URI has the same behavior as IA5 String. See RFC 4517 for more information on this syntax.

1.1.2.2. Single- and Multi-Valued Attributes

By default, most attributes are multi-valued. This means that an entry can contain the same attribute multiple times, with different values. For example:
dn: uid=jsmith,ou=marketing,ou=people,dc=example,dc=com
ou: marketing
ou: people
The cn, tel, and objectclass attributes, for example, all can have more than one value. Attributes that are single-valued — that is, only one instance of the attribute can be specified — are specified in the schema as only allowing a single value. For example, uidNumber can only have one possible value, so its schema entry has the term SINGLE-VALUE. If the attribute is multi-valued, there is no value expression.

1.2. Default Directory Server Schema Files

Template schema definitions for Directory Server are stored in the /etc/dirsrv/schema directory. These default schema files are used to generate the schema files for new Directory Server instances. Each server instance has its own instance-specific schema directory in /etc/dirsrv/slapd-instance_name/schema (/etc/opt/dirsrv/slapd-instance_name/schema on HP-UX). The schema files in the instance directory are used only by that instance.
To modify the directory schema, create new attributes and new object classes in the instance-specific schema directory. Because the default schema is used for creating new instances and each individual instance has its own schema files, it is possible to have slightly different schema for each instance, matching the use of each instance.
Any custom attributes added using the Directory Server Console or LDAP commands are stored in the 99user.ldif file; other custom schema files can be added to the /etc/dirsrv/slapd-instance_name/schema directory for each instance. Do not make any modifications with the standard files that come with Red Hat Directory Server.
For more information about how the Directory Server stores information and suggestions for planning directory schema, see the Deployment Guide.

Table 1.2. Schema Files

Schema File Purpose
00core.ldif Recommended core schema from the X.500 and LDAP standards (RFCs). This schema is used by the Directory Server itself for the instance configuration and to start the server instance.
01core389.ldif Recommended core schema from the X.500 and LDAP standards (RFCs). This schema is used by the Directory Server itself for the instance configuration and to start the server instance.
02common.ldif Standard-related schema from RFC 2256, LDAPv3, and standard schema defined by Directory Server which is used to configure entries.
05rfc2927.ldif Schema from RFC 2927, "MIME Directory Profile for LDAP Schema."
05rfc4523.ldif Schema definitions for X.509 certificates.
05rfc4524.ldif Cosine LDAP/X.500 schema.
06inetorgperson.ldif inetorgperson schema elements from RFC 2798, RFC 2079, and part of RFC 1274.
10rfc2307.ldif Schema from RFC 2307, "An Approach for Using LDAP as a Network Information Service."
20subscriber.ldif Common schema element for Directory Server-Nortel subscriber interoperability.
25java-object.ldif Schema from RFC 2713, "Schema for Representing Java Objects in an LDAP Directory."
28pilot.ldif Schema from the pilot RFCs, especially RFC 1274, that are no longer recommended for use in new deployments.
30ns-common.ldif Common schema.
50ns-admin.ldif Schemas used by the Admin Server.
50ns-certificate.ldif Schemas used by Red Hat Certificate System.
50ns-directory.ldif Schema used by legacy Directory Server 4.x servers.
50ns-mail.ldif Schema for mail servers.
50ns-value.ldif Schema for value items in Directory Server.
50ns-web.ldif Schema for web servers.
60autofs.ldif Object classes for automount configuration; this is one of several schema files used for NIS servers.
60eduperson.ldif Schema elements for education-related people and organization entries.
60mozilla.ldif Schema elements for Mozilla-related user profiles.
60nss-ldap.ldif Schema elements for GSS-API service names.
60pam-plugin.ldif Schema elements for integrating directory services with PAM modules.
60pureftpd.ldif Schema elements for defining FTP user accounts.
60rfc2739.ldif Schema elements for calendars and vCard properties.
60rfc3712.ldif Schema elements for configuring printers.
60sabayon.ldif Schema elements for defining sabayon user entries.
60sudo.ldif Schema elements for defining sudo users and roles.
60trust.ldif Schema elements for defining trust relationships for NSS or PAM.
99user.ldif Custom schema elements added through the Directory Server Console.

1.3. Object Identifiers (OIDs)

All schema elements have object identifiers (OIDs) assigned to them, including attributes and object classes. An OID is a sequence of integers, usually written as a dot-separated string. All custom attributes and classes must conform to the X.500 and LDAP standards.

CAUTION

If an OID is not specified for a schema element, Directory Server automatically uses ObjectClass_name-oid and attribute_name-oid. However, using text OIDs instead of numeric OIDs can lead to problems with clients, server interoperability, and server behavior, assigning a numeric OID is strongly recommended.
OIDs can be built on. The base OID is a root number which is used for every schema element for an organization, and then schema elements can be incremented from there. For example, a base OID could be 1. The company then uses 1.1 for attributes, so every new attribute has an OID of 1.1.x. It uses 1.2 for object classes, so every new object class has an OID of 1.2.x.
For Directory Server-defined schema elements, the base OIDs are as follows:
  • The Netscape base OID is 2.16.840.1.113730.
  • The Directory Server base OID is 2.16.840.1.113730.3.
  • All Netscape-defined attributes have the base OID 2.16.840.1.113370.3.1.
  • All Netscape-defined object classes have the base OID 2.16.840.1.113730.3.2.
For more information about OIDs or to request a prefix, go to the Internet Assigned Number Authority (IANA) website at http://www.iana.org/.

1.4. Extending the Schema

The Directory Server schema includes hundreds of object classes and attributes that can be used to meet most of directory requirements. This schema can be extended with new object classes and attributes that meet evolving requirements for the directory service in the enterprise by creating custom schema files.
When adding new attributes to the schema, a new object class should be created to contain them. Adding a new attribute to an existing object class can compromise the Directory Server's compatibility with existing LDAP clients that rely on the standard LDAP schema and may cause difficulties when upgrading the server.
For more information about extending server schema, see the Deployment Guide.

1.5. Schema Checking

Schema checking means that the Directory Server checks every entry when it is created, modified, or in a database imported using LDIF to make sure that it complies with the schema definitions in the schema files. Schema checking verifies three things:
  • Object classes and attributes used in the entry are defined in the directory schema.
  • Attributes required for an object class are contained in the entry.
  • Only attributes allowed by the object class are contained in the entry.
You should run Directory Server with schema checking turned on. For information on enabling schema checking, see the Administrator's Guide.

1.6. Syntax Validation

Syntax validation means that the Directory Server checks that the value of an attribute matches the required syntax for that attribute. For example, syntax validation will confirm that a new telephoneNumber attribute actually has a valid telephone number for its value.
With its basic configuration, syntax validation (like schema checking) will check any directory modification to make sure the attribute value matches the required syntax and will reject any modifications that violate the syntax. Optionally, syntax validation can be configured to log warning messages about syntax violations, and either reject the change or allow the modification process to succeed.
All syntaxes are validated against RFC 4514, except for DNs. By default, DNs are validated against RFC 1779 or RFC 2253, which are less strict than RFC 4514. Strict validation for DNs has to be explicitly configured.
This feature checks all attribute syntaxes listed in Table 1.1, “Supported LDAP Attribute Syntaxes”, with the exception of binary syntaxes (which cannot be verified) and non-standard syntaxes, which do not have a defined required format. The unvalidated syntaxes are as follows:
  • Fax (binary)
  • OctetString (binary)
  • JPEG (binary)
  • Binary (non-standard)
  • Space Insensitive String (non-standard)
  • URI (non-standard)
When syntax validation is enabled, new attribute values are checked whenever an attribute is added or modified to an entry. (This does not include replication changes, since the syntax would have been checked on the supplier server.) It is also possible to check existing attribute values for syntax violations by running the syntax-validation.pl script.
For information on options for syntax validation, see the Administrator's Guide.