Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide

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.

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.

Table 11–1 Ways to Extend Schema

Task 

Instructions 

You do not use replication. You intend to extend the schema by adding a custom schema file. 

To Extend Schema With a Custom Schema File

You intend to extend the schema through LDAP. 

To Extend Schema Through LDAP

You use replication. You intend to preserve the file name of your custom schema file on all servers. 

To Extend Schema With a Custom Schema File

You use replication. You intend to extend the schema by adding a custom schema file on a master replica. You then let the replication mechanism copy the schema extensions to consumer servers. 

To Extend Schema Using a Schema File and Replication

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 Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide. For information about standard attributes and object classes, see Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference.

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

Extending Schema With a Custom Schema File

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/ds/. 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 Java System Directory Server Enterprise Edition 6.2 Reference and Sun Java System Directory Server Enterprise Edition 6.2 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.

ProcedureTo 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.

  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.

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.

ProcedureTo 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 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.

ProcedureTo 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 schema_push command 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 schema_push(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 after running schema_push, however, the server loads all schema files and then the replication mechanism replicates the new schema to consumers.