Chapter 11 Directory Server Schema

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 of your requirements, you might need to extend the schema by creating new object classes and attributes. For an overview of the standard schema and for instructions on designing schema to suit your deployment, see the Sun Directory Server Enterprise Edition 7.0 Deployment Planning Guide.

This chapter describes how to manage your schema and covers the following topics:

• Managing Schema Checking

• Extending Directory Server Schema

• About Custom Schema

• Managing Attribute Types Over LDAP

• Managing Object Classes Over LDAP

• Replicating Directory Schema

Managing Schema Checking

When schema checking is on, Directory Server ensures that all import, add, and modify operations conform to the currently defined directory schema.

• The object classes and attributes of each entry conform to the schema.

• The entry contains all required attributes for all of its defined object classes.

• The entry contains only attributes that are allowed by its object classes.

When modifying an entry, Directory Server performs schema checking on the entire entry, not just on the attributes that are being modified. Therefore, the operation might fail if any object class or attribute in the entry does not conform to the schema.

However, schema checking does not verify the validity of attribute values with regard to their syntax.

Schema checking is turned on by default. In general, run Directory Server with schema checking turned on. Many client applications assume that having schema checking turned on is an indication that all entries conform to the schema. However, turning on schema checking does not cause Directory Server to verify the existing contents in the directory. The only way to guarantee that all directory contents conform to the schema is to turn on schema checking before adding any entries or reinitializing all entries.

One case where you might want to turn schema checking off is to accelerate import operations of LDIF files known to conform to the schema. However, there is a risk of importing entries that do not conform to the schema. If schema checking is off, imported entries that do not confirm to the schema are not detected.

See Replicating Directory Schema for details on using schema checking in replicated environments.

To Fix Schema Compliance Problems

When an entry does not conform to the schema, it might not be possible to search for this entry, and modification operations on the entry might fail. Follow the steps in this procedure to correct the problem.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

To avoid having to fix schema compliance issues, plan your schema ahead of your deployment to minimize schema changes. For more information, see the Sun Directory Server Enterprise Edition 7.0 Deployment Planning Guide.

1. To determine why the entry does not comply, retrieve the entry and manually compare it with the currently defined schema.

   See To View Attribute Types and To View an Object Class for details.

2. Modify the entry so that it complies with the schema, or modify the schema so that it complies with the entry.

Extending Directory Server Schema

When you add new attributes to your schema, you must create a new object class to contain the new attributes. Although it might seem convenient to just add the attributes to an existing object class that already contains most of the attributes you require, doing so compromises interoperability with LDAP clients.

Interoperability of Directory Server with existing LDAP clients relies on the standard LDAP schema. If you change the standard schema, you will also have difficulties when upgrading your server. For the same reasons, you cannot delete standard schema elements. For more information about general guidelines to customize schema, refer to About Custom Schema.

Directory Server schema are stored in attributes of the cn=schema entry. Like the configuration entry, this is an LDAP view of the schema that is read from files during server startup.

The method that you use to extend Directory Server schema depends on whether you want control over the file name where schema extensions are stored. It also depends whether you want to push changes to consumers through replication. See the following table to determine which procedure to follow in your specific case.

For more information about object classes, attributes, and the directory schema as well as guidelines for extending your schema, see Designing a Directory Schema in Sun Directory Server Enterprise Edition 7.0 Deployment Planning Guide. For information about standard attributes and object classes, see Sun Directory Server Enterprise Edition 7.0 Man Page Reference.

This section provides information about the various methods to extend the directory schema.

Extending Schema Through LDAP

Because the schema is defined by the LDAP view in cn=schema, you can view and modify the schema online using the ldapsearch and ldapmodify utilities. However, you can modify only schema elements that have the value ’user defined’ for the X-ORIGIN field. The server refuses any modification to the other definitions.

New element definitions, and changes that you make to user-defined elements, are saved in the file 99user.ldif.

To Extend Schema Through LDAP

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Modifying schema definitions from the command line is prone to error because of the long values that you must type exactly. However, you can use this functionality in scripts that need to update your directory schema.

1. Use the ldapmodify(1) command to add or delete individual attributeTypes attribute values.

   See To Create an Attribute Type or To Delete Attribute Types for details.

2. Use the ldapmodify(1) command to add or delete individual objectClasses attribute values.

   See To Create an Object Class or To Delete an Object Class for details.

See Also

To modify one of the values, you must delete the specific value and then add the value as a new value. This process is required because the attributes are multivalued. For details, see Modifying One Value of a Multi Valued Attribute.

Extending Schema With a Custom Schema File

To extend schema, modifying schema files is not recommended as this method of extending schema is error-prone. To make any changes to the Directory Serverschema, use the ldapmodify command, which is more reliable way to extend schema.

Schema files are LDIF files that are located in instance-path/config/schema/. The instance-path corresponds to the file system directory where the Directory Server instance resides. For example, the instance might be located in /local/dsInst/. The files define standard schema that are used by Directory Server and all servers that rely on Directory Server. The files and the standard schema are described in Sun Directory Server Enterprise Edition 7.0 Reference and Sun Directory Server Enterprise Edition 7.0 Man Page Reference.

Schema files are read once only at startup by the server. The LDIF contents of the files are added to the in-memory LDAP view of the schema in cn=schema . Because the order of schema definitions is important, schema file names are prepended with a number and loaded in alphanumerical order. Schema files in this directory are writable only by the system user who is defined during installation.

When defining the schema directly in an LDIF file, do not use the value ’user defined’ for the X-ORIGIN field. This value is reserved for schema elements that are defined through the LDAP view of cn=schema and that appear in the file 99user.ldif.

The 99user.ldif file contains additional ACIs for the cn=schema entry and all schema definitions that have been added from the command-line or using DSCC. The 99user.ldif file is overwritten when new schema definitions are added. If you want to modify this file, you must restart the server immediately to ensure that your changes are current.

Do not modify the standard schema that is defined in the other schema files. You can, however, add new files to define new attributes and object classes. For example, to define new schema elements in many servers, you could define the elements in a file named 98mySchema.ldif and copy this file to the schema directory on all servers. You would then restart all servers to load your new schema file.

To Extend Schema With a Custom Schema File

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. Create your own schema definition file, such as 98mySchema.ldif.

   The syntax of definitions in the schema files is described in RFC 4517.

   Read When Creating Custom Schema Files before creating custom schema files.

2. (Optional) If this server is a master replica that sends updates to other servers, copy your schema definition file to each server instance in the replication topology.

   The replication mechanism cannot detect any changes that you make directly to the LDIF files that contain the schema. Therefore, your changes are not replicated to consumers even after restarting the master.

3. Restart each Directory Server instance to which you copied your schema definition file.

   Your changes take effect when the servers restart and thus reload schema definitions.

When Creating Custom Schema Files

Keep the following in mind when creating custom schema files, especially when you are using replication:

• When adding new schema elements, all attributes must be defined before they can be used in an object class. You can define attributes and object classes in the same schema file.

• Each custom attribute or object class that you create should be defined in only one schema file. This practice prevents the server from overriding any previous definitions when the server loads the most recently created schema. Directory Server loads the schema files in numerical order first, then in alphabetical order.

• When defining new schema definitions manually, best practice is generally to add these definitions to the 99user.ldif file.

  When you update schema elements using LDAP, the new elements are written automatically to the 99user.ldif file. As a result, any other schema definition changes that you made in custom schema files might be overwritten. Using only the 99user.ldif file prevents possible duplications of schema elements and the danger of schema changes being overwritten.

• As Directory Server loads schema files in alphanumeric order with numbers loaded first, you should name custom schema files as follows:

  [00-99] filename.ldif

  The number is higher than any directory standard schema already defined.

  If you name your schema file with a number that is lower than the standard schema files, the server might encounter errors when loading the schema. In addition, all standard attributes and object classes are loaded only after your custom schema elements have been loaded.

• Make sure that custom schema file names are not numerically or alphabetically higher than 99user.ldif because Directory Server uses the highest sequenced file for its internal schema management.

  For example, if you created a schema file and named it 99zzz.ldif, the next time you update the schema, all of the attributes with an X-ORIGIN value of 'user defined' would be written to 99zzz.ldif. The result would be two LDIF files that contain duplicate information, and some information in the 99zzz.ldif file might be erased.

• As a general rule, identify the custom schema elements that you are adding with the following two items:

  • 'user defined' in the X-ORIGIN field of custom schema files,

  • A more descriptive label such as 'Example.com Corporation defined' in the X-ORIGIN field, so that the custom schema element is easy for other administrators to understand. For example X-ORIGIN ('user defined' 'Example.com Corporation defined').

    If you are adding schema elements manually and do not use 'user defined' in the X-ORIGIN field, the schema elements appear read-only in DSCC.

    The 'user defined' value is added automatically by the server if you add custom schema definitions by using LDAP or DSCC. However, if you do not add a more descriptive value in the X-ORIGIN field, you might later have difficulty understanding what the schema relates to.

  These changes are not replicated automatically. To replicate, you must propagate custom schema files manually to all your servers.

  When you change the directory schema, the server keeps a timestamp of when the schema was changed. At the beginning of each replication session the server compares its timestamp with its consumer’s timestamp and, if necessary, pushes any schema changes. For custom schema files, the server maintains only one timestamp, which is associated with the 99user.ldif file. This means that any custom schema file changes or additions that you make to files other than 99user.ldif will not be replicated. Therefore, you must propagate custom schema files to all other servers to ensure that all schema information is present throughout the topology.

Extending Schema Using a Schema File and Replication

For information about custom schema files, see Extending Schema With a Custom Schema File. The following procedure explains how to use the replication mechanism to propagate schema extensions to all the servers in a topology.

To Extend Schema Using a Schema File and Replication

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

1. Prepare your schema extensions in one of the following ways:

   • Create your own schema definition file, such as 98mySchema.ldif .

   • Add your schema extensions to 99user.ldif.

   The syntax of definitions in the schema files is described in RFC 4517.

2. Run the dsadm start or dsadm restart command with --schema-push on the master server where you put the schema definition file.

   This script does not actually push the schema to replicas. Instead the script writes a special attribute into the schema files so that the schema files are replicated as soon as they are loaded. For more information, see the dsadm(1M) man page.

3. Restart the master server where you put the schema definition file.

   The replication mechanism cannot detect any changes that you make directly to the LDIF files that contain the schema. When you restart the server, the server loads all schema files and then the replication mechanism replicates the new schema to consumers.

About Custom Schema

You can extend the standard schema if it is too limited for your directory needs. Follow these guidelines when customizing schema:

• Reuse existing schema elements whenever possible.

• Minimize the number of mandatory attributes that you define for each object class.

• Do not define more than one object class or attribute for the same purpose.

• Keep the schema as simple as possible.

When customizing the schema, do not modify, delete, or replace any existing definitions of attributes or object classes in the standard schema. Doing so can lead to compatibility problems with other directories and with LDAP client applications.

Do not modify any Directory Server internal operational attributes. You can, however, create your own operational variables for external applications.

Always define object classes instead of using objectClass: extensibleObject. Directory Server does not perform schema checking for entries that have the object class extensibleObject, so it does not constrain or check what attributes are present on the entry. Typos in applications, for example, giveName for the givenName attribute type, go unnoticed by Directory Server. Also, Directory Server must assume that all otherwise undefined attributes of extensibleObject entries are multivalued and have case-insensitive string syntax. Furthermore, some applications rely on entries having a particular object class. In general, if you have an application that requires an extension to an object class, do not relinquish schema management. Instead, create an auxiliary object class that contains the attributes that are required for the application.

This section contains information about the default directory schema, and about creating customized attributes and object classes.

Default Directory Server Schema

The schema provided with Directory Server is described in a set of files that are stored in the instance-path/config/schema/directory.

This directory contains all of the common schema for Directory Server and related products. The LDAP v3 standard user and organization schema is located in the 00core.ldif file. The configuration schema used by earlier versions of the directory is located in the 50ns-directory.ldif file. The user created elements such as objectclasses and attributes are stored in 99user.ldif.

Do not modify files in this directory. To manage Directory Server schema, use the ldapmodify(1) command.

Object Identifiers

Each LDAP object class or attribute must be assigned a unique name and object identifier (OID). When you define a schema, you need an OID that is unique to your organization. One OID is enough to meet all of your schema needs. You then add new branches on that OID for your attributes and object classes.

Obtaining and assigning OIDs in your schema involves doing the following:

• Obtaining an OID for your organization 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, you can obtain an OID from IANA.

• Creating an OID registry so you can track OID assignments.

  An OID registry is a list that you maintain, which gives the OIDs and OID descriptions that are used in your directory schema. A OID registry ensures that no OID is ever used for more than one purpose.

• Creating branches in the OID tree to accommodate schema elements.

  Create at least two branches under the OID branch or your directory schema, using OID.1 for attributes and OID.2 for object classes. If you want to define your own matching rules or controls, you can add new branches as needed, such as OID.3.

Naming Attributes and Object Classes

When creating names for new attributes and object classes, make the name meaningful so your schema is easier to use.

Avoid naming collisions between custom schema elements and existing schema elements by including a unique prefix on custom elements. For example, Example.com Corporation might add the prefix Example before each of its custom schema elements. It might also add a special object class called ExamplePerson to identify Example.com employees in its directory.

Note that in LDAP, attribute type names and object class names are case insensitive. Applications should treat them as case insensitive strings.

When Defining New Object Classes

Add new object classes when the existing object classes do not support all of the information you need to store in a directory entry.

There are two approaches to creating new object classes:

• Create many new object classes, one for each object class structure to which you want to add an attribute.

• Create a single object class that supports all of the attributes that you create for your directory. You create this kind of an object class by defining it to be an AUXILIARY object class.

  Suppose your site wants to create the attributes ExampleDepartmentNumber and ExampleEmergencyPhoneNumber. You can create several object classes that allow some subset of these attributes. You can create an object class called ExamplePerson and have it allow the ExampleDepartmentNumber and ExampleEmergencyPhoneNumber attributes. The parent of ExamplePerson would be inetOrgPerson. You can then create an object class called ExampleOrganization and have it also allow the ExampleDepartmentNumber and ExampleEmergencyPhoneNumber attributes. The parent of ExampleOrganization would be the organization object class.

  Your new object classes would appear in LDAP v3 schema format as follows:

  objectclasses: (1.3.6.1.4.1.42.2.27.999.1.2.3 NAME 'ExamplePerson' DESC 'Example Person Object Class' SUP inetorgPerson STRUCTURAL MAY (ExampleDepartmentNumber $ ExampleEmergencyPhoneNumber) ) objectclasses: (1.3.6.1.4.1.42.2.27.999.1.2.4 NAME 'ExampleOrganization' DESC 'Example Organization Object Class' SUP organization STRUCTURAL MAY (ExampleDepartmentNumber $ ExampleEmergencyPhoneNumber) )

  Alternatively, you can create a single object class that allows all of these attributes. Then you can use the object class with any entry on which you want to use the attributes. The single object class would appear as follows:

  objectclasses: (1.3.6.1.4.1.42.2.27.999.1.2.5 NAME 'ExampleEntry' DESC 'Example Auxiliary Object Class' SUP top AUXILIARY MAY (ExampleDepartmentNumber $ ExampleEmergencyPhoneNumber) )

  The new ExampleEntry object class is marked AUXILIARY, meaning that it can be used with any entry regardless of its structural object class.

Consider the following when deciding how to implement new object classes.

• Multiple STRUCTURAL object classes result in more schema elements to create and maintain.

  Generally, the number of elements remains small and needs little maintenance. However, if you plan to add more than two or three object classes to your schema, you might find it easier to use a single object class.

• Multiple STRUCTURAL object classes require more careful and more rigid data design.

  Rigid data design forces you to consider the object class structure on which every piece of data is placed. You might find this restriction to be either helpful or cumbersome.

• Single AUXILIARY object classes simplify data design when you have data that you want to put on more than one type of object class structure.

  For example, suppose that you want preferredOS on both a person and a group entry. You might want to create only a single object class to allow this attribute.

• Design object classes that relate to real objects and group elements that constitute sensible groupings.

• Avoid required attributes for new object classes.

  Requiring attributes can make your schema inflexible. When you create a new object class, allow rather than require attributes.

  After defining a new object class, you need to decide which attributes the object class allows and requires, and from which object class or classes it inherits.

When Defining New Attributes

Add new attributes when the existing attributes do not support all of the information you need to store in a directory entry. Try to use standard attributes whenever possible. Search the attributes that already exist in the default directory schema and use those attributes in association with a new object class.

For example, you might find that you want to store more information on a person entry than the person, organizationalPerson, or inetOrgPerson object classes support. If you want to store birth dates in your directory, no attribute exists within the standard Directory Server schema. You can create a new attribute called dateOfBirth. Allow this attribute to be used on entries that represent people by defining a new auxiliary class that allows this attribute.

Managing Attribute Types Over LDAP

This section explains how to create, view, and delete attribute types over LDAP.

Creating Attribute Types

The cn=schema entry has a multivalued attribute, attributeTypes, that contains definitions of each attribute type in the directory schema. You can add to those definitions by using the ldapmodify(1) command.

New attribute type definitions, and changes that you make to user-defined attribute types, are saved in the file 99user.ldif.

For each attribute type definition, you must provide at least an OID to define your new attribute type. Consider using at least the following elements for new attribute types:

• Attribute OID. Corresponds to the object identifier for your attribute. An OID is a string, usually of dotted decimal numbers, that uniquely identifies the schema object.

  For strict LDAP v3 compliance, you must provide a valid numeric OID. To learn more about OIDs or to request a prefix for your enterprise, send email to the IANA (Internet Assigned Number Authority) at iana@iana.org, or see the IANA web site.

• Attribute name. Corresponds to a unique name for the attribute. Also called its attribute type. Attribute names must begin with a letter and contain only ASCII letters, digits, and hyphens.

  An attribute name can contain uppercase letters, but no LDAP client should rely on case to differentiate attributes. Attribute names must be handled in a case-insensitive manner according to section 2.5 of RFC 4512.

  You can optionally include alternate attribute names, also referred to as aliases, for your attribute type.

• Attribute description. Is short descriptive text that explains the attribute’s purpose.

• Syntax. Is referenced by the OID and describes the data to be held by the attribute.

  Attribute syntaxes with their OIDs are listed in RFC 4517.

• Number of values allowed. By default, attributes are multivalued, but you might want to restrict an attribute to a single value.

To Create an Attribute Type

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. Prepare your attribute type definition according to the syntax specified in RFC 4517.

2. Use the ldapmodify(1) command to add your attribute type definition.

   Notice that Directory Server adds X-ORIGIN 'user defined' to the definition that you provide.

Example 11–1 Creating an Attribute Type

The following example adds a new attribute type with Directory String syntax using the ldapmodify command:

$ cat blogURL.ldif 
dn: cn=schema
changetype: modify
add: attributeTypes
attributeTypes: ( 1.2.3.4.5.6.7 
 NAME ( 'blog' 'blogURL' ) 
 DESC 'URL to a personal weblog' 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 
 SINGLE-VALUE )

$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -f blogURL.ldif
Enter bind password: 
modifying entry cn=schema

$

In a production environment, you would provide a valid, unique OID, not 1.2.3.4.5.6.7.

Viewing Attribute Types

The cn=schema entry has a multivalued attribute, attributeTypes, that contains definitions of each attribute type in the directory schema. You can read those definitions by using the ldapsearch(1) command.

To View Attribute Types

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. Use the ldapsearch command to view all the attribute type definitions that currently exist in your directory schema.

Example 11–2 Viewing Attribute Types

The following command displays definitions for all attribute types:

$ ldapsearch -T -b cn=schema "(objectclass=*)" attributeTypes

The -T option prevents the ldapsearch command from folding LDIF lines, so you can more easily work with the output using commands such as grep or sed. If you then pipe the output of this command through the grep command, you can view only the user-defined extensions to directory schema. For example:

$ ldapsearch -T -b cn=schema "(objectclass=*)" attributeTypes | grep "user defined"
 attributeTypes: ( 1.2.3.4.5.6.7 NAME ( 'blog' 'blogURL' ) 
 DESC 'URL to a personal weblog' 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE 
 X-ORIGIN 'user defined' )

Deleting Attribute Types

The cn=schema entry has a multivalued attribute, attributeTypes, that contains definitions of each attribute type in the directory schema. You can delete definitions with X-ORIGIN 'user defined' by using the ldapmodify(1) command.

Because the schema is defined by the LDAP view in cn=schema, you can view and modify the schema online using the ldapsearch and ldapmodify utilities. However, you can delete only schema elements that have the value ’user defined’ for the X-ORIGIN field. The server will not delete other definitions.

Changes that you make to user-defined attributes are saved in the file 99user.ldif.

To Delete Attribute Types

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. View the definition of the attribute type to delete.

   See To View Attribute Types for details.

2. Use the ldapmodify(1) command to delete the attribute type definition as it appears in the schema.

Example 11–3 Deleting an Attribute Type

The following command deletes the attribute type that is created in Example 11–1:

$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: cn=schema
changetype: delete
delete: attributeTypes
attributeTypes: ( 1.2.3.4.5.6.7 NAME ( 'blog' 'blogURL' ) 
 DESC 'URL to a personal weblog' 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE 
 X-ORIGIN 'user defined' )
^D

Notice that you must include the X-ORIGIN 'user defined', which was added by Directory Server to classify this schema definition as an extension.

Managing Object Classes Over LDAP

This section explains how to create, view, and delete object classes over LDAP.

Creating Object Classes

The cn=schema entry has a multivalued attribute, objectClasses, that contains definitions of each object class in the directory schema. You can add to those definitions by using the ldapmodify(1) command.

New object class definitions, and changes that you make to user-defined object classes, are saved in the file 99user.ldif.

If you are creating several object classes that inherit from other object classes, you must create the parent object classes first. If your new object class uses custom attributes, you must also define those first.

For each object class definition, you must provide at least an OID. Consider using at least the following elements for new object classes:

• Object Class OID. Corresponds to the object identifier for your object class. An OID is a string, usually of dotted decimal numbers, that uniquely identifies the schema object.

  For strict LDAP v3 compliance, you must provide a valid numeric OID. To learn more about OIDs or to request a prefix for your enterprise, send email to the IANA (Internet Assigned Number Authority) at iana@iana.org, or see the IANA web site.

• Object class name. Corresponds to a unique name for the object class.

• Parent object class. Is an existing object class from which this object class inherits attributes.

  If you do not intend to have this object class inherit from another specific object class, use top.

  Typically, if you want to add new attributes for user entries, the parent would be the inetOrgPerson object class. If you want to add new attributes for corporate entries, the parent is usually organization or organizationalUnit. If you want to add new attributes for group entries, the parent is usually groupOfNames or groupOfUniqueNames.

• Required attributes. Lists and defines attributes that must be present for this object class.

• Allowed attributes. Lists and defines additional attributes that can be present for this object class.

To Create an Object Class

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. Prepare your object class definition according to the syntax specified in RFC 4517.

2. Use the ldapmodify(1) command to add your object class definition.

   Notice that Directory Server adds X-ORIGIN 'user defined' to the definition that you provide.

Example 11–4 Creating an Object Class

The following example adds a new object class using the ldapmodify command:

$ cat blogger.ldif 
dn: cn=schema
changetype: modify
add: objectClasses
objectClasses: ( 1.2.3.4.5.6.8 
 NAME 'blogger' 
 DESC 'Someone who has a blog' 
 SUP inetOrgPerson 
 STRUCTURAL 
 MAY blog )

$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -f blogger.ldif
Enter bind password: 
modifying entry cn=schema

$

In a production environment, you would provide a valid, unique OID, not 1.2.3.4.5.6.8.

Viewing Object Classes

The cn=schema entry has a multivalued attribute, objectClasses, that contains definitions of each object class in the directory schema. You can read those definitions by using the ldapsearch(1) command.

To View an Object Class

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. Use the ldapsearch command to view all the object class definitions that currently exist in your directory schema.

Example 11–5 Viewing Object Classes

The following command displays definitions for all object classes:

$ ldapsearch -T -b cn=schema "(objectclass=*)" objectClasses

The -T option prevents the ldapsearch command from folding LDIF lines, so you can more easily work with the output using commands such as grep or sed. If you then pipe the output of this command through the grep command, you can view only the user-defined extensions to directory schema. For example:

$ ldapsearch -T -b cn=schema "(objectclass=*)" objectClasses | grep "user defined"
objectClasses: ( 1.2.3.4.5.6.8 NAME 'blogger'
 DESC 'Someone who has a blog' STRUCTURAL MAY blog
 X-ORIGIN 'user defined' )
$ 

Deleting Object Classes

The cn=schema entry has a multivalued attribute, objectClasses, that contains definitions of each object class in the directory schema. You can delete definitions with X-ORIGIN 'user defined' by using the ldapmodify(1) command.

Because the schema is defined by the LDAP view in cn=schema, you can view and modify the schema online using the ldapsearch and ldapmodify utilities. However, you can delete only schema elements that have the value ’user defined’ for the X-ORIGIN field. The server will not delete other definitions.

Changes that you make to user-defined elements are saved in the file 99user.ldif .

To Delete an Object Class

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

1. View the definition of the object class to delete.

   See To View an Object Class for details.

2. Use the ldapmodify(1) command to delete the object class definition as it appears in the schema.

Example 11–6 Deleting an Object Class

The following command deletes the object class that was created in Example 11–4:

$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: cn=schema
changetype: delete
delete: objectClasses
objectClasses: ( 1.2.3.4.5.6.8 NAME 'blogger' DESC 'Someone who has a blog' 
 STRUCTURAL MAY blog X-ORIGIN 'user defined' )
^D

Notice that you must include X-ORIGIN 'user defined', which was added by Directory Server to classify this schema definition as an extension.

Replicating Directory Schema

Whenever you configure the replication of one or more suffixes between two servers, schema definitions are automatically replicated as well. The automatic replication of schema definitions ensures that all replicas have a complete, identical schema that defines all object classes and attributes that can be replicated to the consumers. Master servers therefore also contain the master schema.

However, schema replication is not instantaneous, even when you modify schema over LDAP. Schema replication is triggered either by updates to directory data or at the start of the first replication session after the schema is modified.

To enforce the schema on all replicas, you must at least enable schema checking on all masters. As the schema is checked on the master where the LDAP operation is performed, the schema does not need to be checked when updating the consumer. To improve performance, the replication mechanism bypasses schema checking on consumer replicas.

Do not turn off schema checking on hubs and dedicated consumers. Schema checking has no performance impact on a consumer. Keep schema checking on to indicate that the replica contents conform to its schema.

Master servers replicate the schema automatically to their consumers during consumer initialization. Master servers also replicate the schema automatically any time the schema is modified through DSCC or through the command-line tools. By default, the entire schema is replicated. Any additional schema elements that do not yet exist on the consumer are created on the consumer and stored in the 99user.ldif file.

For example, assume that a master server contains schema definitions in the 98mySchema.ldif file when the server is started. Also assume that you then define replication agreements to other servers, either masters, hubs, or dedicated consumers. When you subsequently initialize the replicas from this master, the replicated schema contains the definitions from 98mySchema.ldif, but the definitions are stored in 99user.ldif on the replica servers.

After the schema has been replicated during consumer initialization, modifying the schema in cn=schema on the master also replicates the entire schema to the consumer. Therefore, any modifications to the master schema through the command-line utilities or through DSCC are replicated to the consumers. These modifications are stored in 99user.ldif on the master, and by the same mechanism as described previously, the modifications are also stored in 99user.ldif on the consumers.

Consider the following guidelines for maintaining consistent schema in a replicated environment:

• Do not modify the schema on a consumer server.

  Modifications to the schema on the consumer server can cause replication errors. This is because differences in the schema on the consumer can result in updates from the supplier not conforming to schema on the consumer.

• In a multimaster replication environment, modify schema on a single master server.

  When you modify the schema on two master servers, the master most recently updated propagates its version of the schema to the consumer. The schema on the consumer might then become inconsistent with the schema on the other master.

When configuring fractional replication, also consider the following guidelines:

• As schema is pushed by suppliers in fractional replication configurations, schema on a fractional consumer replica are a copy of the master replica’s schema. Therefore, schema might not correspond to the fractional replication configuration being applied.

• In general, Directory Server replicates all required attributes for each entry as defined in the schema to avoid schema violations. When you configure fractional replication to filter out required attributes, you must disable schema checking.

• If schema checking is enabled with fractional replication, you might not be able to initialize the replica offline. Directory Server does not allow you to load data from LDIF if required attributes are filtered out.

• If you have disabled schema checking on a fractional consumer replica, schema checking is not enforced on the whole server instance on which that fractional consumer replica resides. As a result, avoid configuring supplier replicas on the same server instance as a fractional consumer.

Limiting Schema Replication

By default, whenever the replication mechanism replicates the schema, it sends the entire schema to its consumers. In the following situation, it is not desirable to send the entire schema to consumers:

Modifications to cn=schema using DSCC or from the command-line are limited to the user-defined schema elements, and all of the standard schema are unchanged. If you modify the schema often, sending the large set of unchanged schema elements every time has a performance impact. You might be able to improve replication and server performance by replicating only the user-defined schema elements.

To Limit Schema Replication

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

1. Limit schema replication so that only the user-defined schema is replicated.

   $ dsconf set-server-prop -h host -p port repl-user-schema-enabled:on

   The default value, off, causes the entire schema to be replicated when necessary.