Show Table of Contents
3.4. Customizing the Schema
The standard schema can be extended if it is too limited for the directory needs. The web console in Directory Server can be used to extend the schema by easily adding attributes and object classes. It is also possible to create an LDIF file and add schema elements manually. For more information, see the Red Hat Directory Server Administration Guide.
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 (data).
- Do not modify any existing definitions of attributes or object classes.
When customizing the schema, never delete or replace the standard schema. Doing so can lead to compatibility problems with other directories or other LDAP client applications.
Custom object classes and attributes are defined in the
99user.ldiffile. Each individual instance maintains its own
99user.ldiffile in the
/etc/dirsrv/slapd-instance_name/schema/directory. It is also possible to create custom schema files and dynamically reload the schema into the server.
3.4.1. When to Extend the Schema
While the object classes and attributes supplied with the Directory Server should meet most common corporate needs, a given object class may not store specialized information about an organization. Also, the schema may need extended to support the object classes and attributes required by an LDAP-enabled application's unique data needs.
3.4.2. Getting and Assigning Object Identifiers
Each LDAP object class or attribute must be assigned a unique name and object identifier (OID). When a schema is defined, the elements require a base OID which is unique to your organization. One OID is enough to meet all schema needs. Simply add another level of hierarchy to create new branches for attributes and object classes. Getting and assigning OIDs in schema involves the following steps:
- Obtain an OID from the Internet Assigned Numbers Authority (IANA) or a national organization.In some countries, corporations already have OIDs assigned to them. If your organization does not already have an OID, one can be obtained from IANA. For more information, go to the IANA website at http://www.iana.org/cgi-bin/enterprise.pl.
- Create an OID registry to track OID assignments.An OID registry is a list of the OIDs and descriptions of the OIDs used in the directory schema. This ensures that no OID is ever used for more than one purpose. Then publish the OID registry with the schema.
- Create branches in the OID tree to accommodate schema elements.Create at least two branches under the OID branch or the directory schema, using OID
.1for attributes and OID
.2for object classes. To define custom matching rules or controls, add new branches as needed (OID
.3, for example).
3.4.3. Naming Attributes and Object Classes
When creating names for new attributes and object classes, make the names as meaningful as possible. This makes the schema easier to use for Directory Server administrators.
Avoid naming collisions between schema elements and existing schema elements by including a unique prefix on all schema elements. For example, Example Corp. might add the prefix
examplebefore each of their custom schema elements. They might add a special object class called
examplePersonto identify Example Corp. employees in their directory.
3.4.4. Strategies for Defining New Object Classes
There are two ways to create new object classes:
- Create many new object classes, one for each object class structure to which to add an attribute.
- Create a single object class that supports all of the custom attributes created for the directory. This kind of object class is created by defining it as an auxiliary object class.
It may be easiest to mix the two methods.
For example, suppose an administrator wants to create the attributes
exampleVicePresident. A simple solution is to create several object classes that allow some subset of these attributes.
- One object class,
examplePerson, is created and allows
examplePreferredOS. The parent of
- A second object class,
exampleVicePresident. The parent of
The new object classes appear in LDAPv3 schema format as follows:
objectclasses: ( 2.16.840.1.117370.922.214.171.124 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetorgPerson MAY (exampleDateOfBirth $ examplePreferredOS) ) objectclasses: ( 2.16.840.1.117370.9126.96.36.199 NAME 'exampleOrganization' DESC 'Organization Object Class' SUP organization MAY (exampleBuildingFloor $ exampleVicePresident) )
Alternatively, create a single object class that allows all of these attributes and use it with any entry which needs these attributes. The single object class appears as follows:
objectclasses: (2.16.840.1.117370.9188.8.131.52 NAME 'exampleEntry' DESC 'Standard Entry Object Class' SUP top AUXILIARY MAY (exampleDateOfBirth $ examplePreferredOS $ exampleBuildingFloor $ exampleVicePresident) )
exampleEntryobject class is marked
AUXILIARY, meaning that it can be used with any entry regardless of its structural object class.
The OID of the new object classes in the example (
2.16.840.1.117370) is based on the former Netscape OID prefix. To create custom object classes, obtain an OID as described in Section 3.4.2, “Getting and Assigning Object Identifiers”.
There are several different ways to organize new object classes, depending on the organization environment. Consider the following when deciding how to implement new object classes:
- Multiple object classes result in more schema elements to create and maintain.Generally, the number of elements remains small and needs little maintenance. However, it may be easier to use a single object class if there are more than two or three object classes added to the schema.
- Multiple object classes require a more careful and rigid data design.Rigid data design forces attention to the object class structure under which every piece of data is placed, which can be either helpful or cumbersome.
- Single object classes simplify data design when there is data that can be applied to more than one type of object class, such as both people and asset entries.For example, a custom
preferredOSattribute may be set on both a person and a group entry. A single object class can allow this attribute on both types of entries.
- Avoid required attributes for new object classes.Specifying
allowfor attributes in new object classes can make the schema inflexible. When creating a new object class, use
requireas much as possible.After defining a new object class, decide what attributes it allows and requires, and from what object classes it inherits attributes.
3.4.5. Strategies for Defining New Attributes
For both application compatibility and long-term maintenance, try to use standard attributes whenever possible. Search the attributes that already exist in the default directory schema and use them in association with a new object class or check out the Directory Server Schema Guide. However, if the standard schema does not contain all the information you need, then add new attributes and new object classes.
For example, a person entry may need more attributes than the
inetOrgPersonobject classes support by default. As an example, no attribute exists within the standard Directory Server schema to store birth dates. A new attribute,
dateOfBirth, can be created and set as an allowed attribute within a new auxiliary object class,
attributetypes: ( dateofbirth-oid NAME 'dateofbirth' DESC 'For employee birthdays' SYNTAX 184.108.40.206.4.1.14220.127.116.11.15 X-ORIGIN 'Example defined') objectclasses: ( 2.16.840.1.117370.918.104.22.168 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetorgPerson MAY (exampleDateOfBirth $ cn) X-ORIGIN 'Example defined')
One important thing to remember: Never add or delete custom attributes to standard schema elements. If the directory requires custom attributes, add custom object classes to contain them.
3.4.6. Deleting Schema Elements
Do not delete the schema elements included by default with Directory Server. Unused schema elements represent no operational or administrative overhead. Deleting parts of the standard LDAP schema can cause compatibility problems with future installations of Directory Server and other directory-enabled applications.
However, unused custom schema elements can be deleted. Before removing the object class definitions from the schema, modify each entry using the object class. Removing the definition first might prevent the entries that use the object class from being modified later. Schema checks on modified entries also fails unless the unknown object class values are removed from the entry.
3.4.7. Creating Custom Schema Files
Administrators can create custom schema files for the Directory Server to use, in addition to the
99user.ldiffile provided with Directory Server. These schema files hold new, custom attributes and object classes that are specific to the organization. The new schema files should be located in the schema directory,
All standard attributes and object classes are loaded only after custom schema elements have been loaded.
Custom schema files should not be numerically or alphabetically higher than
99user.ldifor the server could experience problems.
After creating custom schema files, there are two ways for the schema changes to be distributed among all servers:
- Manually copy these custom schema files to the instance's schema directory,
/etc/dirsrv/slapd-instance/schema. To load the schema, restart the server or reload the schema dynamically by running the
- Modify the schema on the server with an LDAP client such as the web console or
- If the server is replicated, then allow the replication process to copy the schema information to each of the consumer servers.With replication, all of the replicated schema elements are copied into the consumer servers'
99user.ldiffile. To keep the schema in a custom schema file, like
90example_schema.ldif, the file has to be copied over to the consumer server manually. Replication does not copy schema files.
If these custom schema files are not copied to all of the servers, the schema information are only replicated to the replica (consumer server) when changes are made to the schema on the supplier server using an LDAP client such as the web console or
When the schema definitions are replicated to a consumer server where they do not already exist, they are stored in the
99user.ldiffile. The directory does not track where schema definitions are stored. Storing schema elements in the
99user.ldiffile of consumers does not create a problem as long as the schema is maintained on the supplier server only.
If the custom schema files are copied to each server, changes to the schema files must be copied again to each server. If the files are not copied over again, it is possible the changes will be replicated and stored in the
99user.ldiffile on the consumer. Having the changes in the
99user.ldiffile may make schema management difficult, as some attributes will appear in two separate schema files on a consumer, once in the original custom schema file copied from the supplier and again in the
99user.ldiffile after replication.
For more information about replicating schema, see Section 7.4.4, “Schema Replication”.
3.4.8. Custom Schema Best Practices
When using schema files, be sure to create schema which will be compatible and easy to manage.
22.214.171.124. Naming Schema Files
When naming custom schema files, use the following naming format:
Name custom schema files lower (numerically and alphabetically) than
99user.ldif. This lets Directory Server write to
99user.ldif, both through LDAP tools and the web console.
99user.ldiffile contains attributes with an
'user defined'; however, the Directory Server writes all
'user defined'schema elements to the highest named file, numerically then alphabetically. If there is a schema file called
99zzz.ldif, the next time the schema is updated (either through LDAP command-line tools or the web console) all of the attributes with an
'user defined'are written to
99zzz.ldif. The result is two LDIF files that contain duplicate information, and some information in the
99zzz.ldiffile might be erased.
126.96.36.199. Using 'user defined' as the Origin
Do not use
'user defined'in the
X-ORIGINfield of custom schema files (such as
'user defined'is used internally by the Directory Server when a schema is added over LDAP. In custom schema files, use something more descriptive, such as
'Example Corp. defined'.
However, if the custom schema elements are added directly to the
'user defined'as the value of
X-ORIGIN. If a different
X-ORIGINvalue is set, the server simply may overwrite it.
'user defined'ensures that schema definitions in the
99user.ldiffile are not removed from the file by the Directory Server. The Directory Server does not remove them because it relies on an
'user defined'to tell it what elements should reside in the
attributetypes: ( exampleContact-oid NAME 'exampleContact' DESC 'Example Corporate contact' SYNTAX 188.8.131.52.4.1.14184.108.40.206.15 X-ORIGIN 'Example defined')
After the Directory Server loads the schema entry, it appears as follows:
attributetypes: ( exampleContact-oid NAME 'exampleContact' DESC 'Example Corporate contact' SYNTAX 220.127.116.11.4.1.1418.104.22.168.15 X-ORIGIN ('Example defined' 'user defined') )
22.214.171.124. Defining Attributes before Object Classes
When adding new schema elements, all attributes need to be defined before they can be used in an object class. Attributes and object classes can be defined in the same schema file.
126.96.36.199. Defining Schema in a Single File
Each custom attribute or object class should be defined in only one schema file. This prevents the server from overriding any previous definitions when it loads the most recently created schema (as the server loads the schema in numerical order first, then alphabetical order). Decide how to keep from having schema in duplicate files:
- Be careful with what schema elements are included in each schema file.
- Be careful in naming and updating the schema files. When schema elements are edited through LDAP tools, the changes are automatically written to the last file (alphabetically). Most schema changes, then, write to the default file
99user.ldifand not to the custom schema file, such as
60example.ldif. Also, the schema elements in
99user.ldifoverride duplicate elements in other schema files.
- Add all the schema definitions to the
99user.ldiffile. This is useful if your are managing the schema through the web console.