Chapter 1. Creating a custom schema using the dsconf utility
You can add custom attributes and object classes to Directory Server by extending the schema. You can extend the schema:
-
Using the
dsconf
utility on the command line. This process is described in this section. - Using the Directory Server web console.
- Manually by creating schema files.
1.1. Workflow of a schema extension
Adding new schema elements requires:
Planning and defining unique object identifiers (OID) for the new schema. Directory Server recognizes schema elements by their OID, but you must manage the OIDs manually.
An OID is a dot-separated number that identifies the schema element to the server. OIDs can be hierarchical with a base OID that can be expanded to accommodate different branches. For example, the base OID could be
1
, and there can be a branch for attributes at1.1
and for object classes at1.2
.ImportantEven if not required, Red Hat recommends to use numeric OIDs for custom schemas for better forward compatibility and performance.
- Request OIDs from the Internet Assigned Numbers Authority (IANA). For details, see https://pen.iana.org/pen/PenApplication.page.
- Create a OID registry to track OID assignments and to ensure that no OID is used for more than one purpose. An OID registry is a list of all OIDs used in the directory schema including descriptions. Publish the OID registry with the custom schema.
- Define the new attributes.
- Define the object classes that contain the new attributes. However, never update the default schema. If you create new attributes, always add them to a custom object class.
Directory Server loads the schema when the instance starts. To load new schema files, restart the instance or initiate a reload task.
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.
Do not update or delete the standard schema to avoid compatibility problems with other directories or LDAP client applications.
1.2. How Directory Server manages schema updates in a replication environment
When you update the directory schema in the cn=schema
tree, Directory Server stores the changes in the /etc/dirsrv/slapd-instance_name/schema/99user.ldif
file, including a change state number (CSN).
Directory Server does not directly replicate the schema changes to other replicas. Schema replication starts when directory content is updated in the replicated tree. For example, if you update a user after modifying the schema, the supplier compares the CSN stored in the nsSchemaCSN
attribute with the one on the consumer. If the value of the nsSchemaCSN
attribute on the consumer is lower than the one on the supplier, Directory Server replicates the schema 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 1.1. Schema subsets and supersets
-
On
server1
, theexample
object class allows thea1
,a2
, anda3
attributes. -
On
server2
, theexample
object class allows thea1
anda3
attributes.
In the previous example, the schema definition of the example
object class on server1
is a superset of the object class on server2
. During the validation phase, when Directory Server replicates or accepts the schema, the 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, Directory Server updates the local schema.
If the schema definitions are successfully replicated, the nsSchemaCSN
attributes are identical on both servers and the schema definitions, such as object classes and attributes types, are no longer compared at the beginning of a replication session.
In the following scenarios, Directory Server does not replicate the schema:
The schema on one host is a subset of the schema of another host.
For example, the schema definition of the
example
object class onserver2
is a subset of the object class onserver1
. Subsets can also occur for attributes (a single-value attribute is a subset of a multi-value attribute) and attribute syntaxes.- 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
, anda3
attributes anda1
,a3
, anda4
on the other, the schemas are not subsets and cannot be merged. You use schema files other than
/etc/dirsrv/slapd-instance_name/schema/99user.ldif
.Directory Server enables you to add additional schema files to the
/etc/dirsrv/slapd-instance_name/schema/
directory. However, only the CSN in the/etc/dirsrv/slapd-instance_name/schema/99user.ldif
file is updated. For this reasons, other schema file are used only locally and not automatically transferred to replication partners.ImportantTo enable Directory Server to automatically replicate the schema and to avoid duplicate schema definitions, store the custom schema in the
/etc/dirsrv/slapd-instance_name/schema/99user.ldif
file.
1.3. Using dsconf to create a custom schema for an attribute and object class
This procedure demonstrates how to use the dsconf
utility to create a custom schema with:
-
A single-valued attribute named
dateOfBirth
with OID2.16.840.1.1133730.2.1.123
and syntaxDirectory String
(OID1.3.6.1.4.1.1466.115.121.1.15
) -
An object class named
exampleperson
without parent object class (SUP top
), OID2.16.840.1.1133730.2.1.99
that must contain thedateOfBirth
attribute.
Procedure
Create the
dateOfBirth
attribute:#
dsconf -D "cn=Directory Manager" ldap://server.example.com schema attributetypes add --oid="2.16.840.1.1133730.2.1.123" --desc="For employee birthdays" --syntax="1.3.6.1.4.1.1466.115.121.1.15" --single-value --x-origin="Example defined" dateOfBirth
Create the
exampleperson
object class:#
dsconf -D "cn=Directory Manager" ldap://server.example.com schema objectclasses add --oid="2.16.840.1.1133730.2.1.99" --desc="An example person object class" --sup="top" --must="dateOfBirth" examplePerson
Run a schema reload task:
#
dsconf -D "cn=Directory Manager" ldap://server.example.com schema reload
Verification
Monitor the
/var/log/dirsrv/slapd-instance_name/errors
file:If the build succeeds, Directory Server logs:
[23/Sep/2021:13:47:33.334241406 +0200] - INFO - schemareload - schemareload_thread - Schema reload task starts (schema dir: default) ... [23/Sep/2021:13:47:33.415692558 +0200] - INFO - schemareload - schemareload_thread - Schema validation passed. [23/Sep/2021:13:47:33.454768148 +0200] - INFO - schemareload - schemareload_thread - Schema reload task finished.
- If the build fails, Directory Server logs which step failed and why.