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.

Table 11-1 Ways to Extend Schema

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 Oracle Directory Server Enterprise Edition Deployment Planning Guide. For information about standard attributes and object classes, see Oracle Directory Server Enterprise Edition 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

---

Caution - 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 Oracle Directory Server Enterprise Edition Reference and Oracle Directory Server Enterprise Edition 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.