8.7. Dynamically Reloading Schema

By default, the schema files used by the Directory Server instance are loaded into the directory when it is started. This means that any new schema files added to the schema directory are not available for use unless the server is restarted. The Directory Server has a task which manually reloads the full schema for the Directory Server instance, including custom files, without requiring a server restart.
The schema reload task can be initiated in two ways:
  • Using the schema-reload.pl script
  • Adding a cn=schema reload task entry using ldapmodify

8.7.1. Reloading Schema Using schema-reload.pl

The schema-reload.pl script launches a special task to reload all of the schema files used by a specific Directory Server instance. This allows custom schema files to be loaded dynamically without having to add schema elements to 99user.ldif.
  1. Open the tool directory for the Directory Server instance, /usr/lib/dirsrv/slapd-instance_name/.
  2. Run the script, binding as the Directory Manager. 
    ./schema-reload.pl -D "cn=Directory Manager" -w secret
    The Directory Server responds that it has added the new reload task entry. 
    adding new entry cn=schema_reload_2009_1_6_17_52_4,cn=schema reload task,cn=tasks,cn=config
    This reloads the schema from the default schema directory, /etc/dirsrv/slapd-instance_name/schema, which is recommended. It is also possible to specify a different directory using the -d option. 
    ./schema-reload.pl -D "cn=Directory Manager" -w password -d /export/custom-schema

    Important

    All of the schema is reloaded with the schema reload task, not just the newest schema or modified schema. This means that whatever directory is specified should contain the full schema for the Directory Server, or the Directory Server instance may have serious performance problems.
The schema-reload.pl is described in more detail in the Configuration and Command-Line Tool Reference.

8.7.2. Reloading Schema Using ldapmodify

The schema-reload.pl script creates a special task entry in a Directory Server instance which reloads schema files; it is also possible to reload schema by creating the task entry directly. Task entries occur under the cn=tasks configuration entry in the dse.ldif file, so it is also possible to initiate a task by adding the entry using ldapmodify. As soon as the task is complete, the entry is removed from the directory.
To initiate a schema reload task, add an entry under the cn=schema reload task,cn=tasks,cn=config entry. The only required attribute is the cn for the specific task. 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example schema reload,cn=schema reload task,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn:example schema reload
The default schema directory from which the Directory Server instance reloads the schema is in /etc/dirsrv/slapd-instance_name/schema; it is possible to specify a different schema directory using the schemadir attribute, which is analogous to the -d option with schema-reload.pl. 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example schema reload,cn=schema reload task,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn:example schema reload
schemadir: /export/schema

Important

All of the schema is reloaded with the schema reload task, not just the newest schema or modified schema. This means that whatever directory is specified should contain the full schema for the Directory Server, or the Directory Server instance may have serious performance problems.
As soon as the task is completed, the entry is deleted from the dse.ldif configuration, so it is possible to reuse the same task entry continually.
The cn=schema reload task configuration is described in more detail in the Configuration and Command-Line Tool Reference.

8.7.3. Reloading Schema with Replication

The schema reload task is a local operation, so schema changes are not replicated in a multi-master environment if the schema is added to one supplier but not to the others. To load the new schema files on all of the supplier servers:
  1. Stop replication.
  2. Copy the new schema file over and run the schema reload task for every supplier and replica server.
  3. Restart replication.

8.7.4. Schema Reload Errors

When the schema reload task runs, the command prompt only shows that the task is initiated. 
adding new entry cn=schema reload task 1,cn=schema reload task,cn=tasks,cn=config
However, the task does not return whether it completed successfully. To verify the schema reload operation was successful, check the error logs. The schema reload has two tasks, first validating the schema file and then loading it.
A success message shows that the validation passed and the task finished. 
[06/Jan/2009:17:52:04 -0500] schemareload - Schema reload task starts (schema dir: default) ...
[06/Jan/2009:17:52:04 -0500] schemareload - Schema validation passed.
[06/Jan/2009:17:52:04 -0500] schemareload - Schema reload task finished.
If there is a failure, then the logs show which step failed and why. 
[..] schemareload - Schema reload task starts (schema dir: /bogus) ...
[..] schema - No schema files were found in the directory /bogus
[..] schema_reload - schema file validation failed
[..] schemareload - Schema validation failed.