Sun Java System Directory Server Enterprise Edition 6.0 Migration Guide

Chapter 2 Automated Migration Using the dsmig Command

Directory Server 6.0 provides a command-line migration tool to help you migrate from a Directory Server 5.2 instance to a Directory Server 6.0 instance. You can only use the migration tool if your deployment satisfies the requirements for automatic migration described in Deciding on Automatic or Manual Migration.

The migration tool provides migration per instance. If several instances exist within the same server root, the migration tool must be run for each individual instance.

This chapter explains how to use the migration tool and covers the following topics:

About the Automatic Migration Tool

The migration tool, dsmig, is delivered with the Directory Server 6.0 packages. When these packages have been installed, dsmig is located in install-path/ds6/bin.

dsmig must be run on the machine on which the new Directory Server instance will be located. When the command is run, a migration directory is created within the new instance directory (new-instance-path/migration). This directory is a repository for data produced by the migration, including log files and migration status files.

dsmig includes a set of sub-commands and options, that map to the individual migration steps described in Outline of Migration Steps. For information about the usage of dsmig, see dsmig(1M).

Prerequisites for Running dsmig

In this section, old instance refers to the 5.2 instance and new instance refers to the Directory Server 6.0 instance.

Before you use dsmig to migrate an instance, ensure that the following tasks have been performed:

You can create and start the new instance manually, but is not mandatory to create the new instance before running dsmig. dsmig checks whether a new Directory Server instance exists in the specified path. If a new instance exists, the commands are carried out on this instance. If a new instance does exist, the instance is created automatically.

The new instance can be created anywhere except for the exact location of the old instance.

Using dsmig to Migrate the Schema

Directory Server 5.2 schema files are located in serverRoot/slapd-instance-path/config/schema. Directory Server 6.0 schema files are located in INSTANCE-PATH/config/schema.

Directory Server 6.0 provides a new schema file, 00ds6pwp.ldif, that contains new password policy attributes. In addition, certain configuration attributes have been added to 00core.ldif. Apart from these files, the standard schema files provided with Directory Server 6.0 are identical to those provided in 5.2.

To migrate the schema automatically, run the following command:

$ dsmig migrate-schema old-instance-path new-instance-path

When you run this command, any custom schema defined in the 99user.ldif file are copied to the new instance. If the new instance is already in production, and you have already modified the 99user.ldif file of the new instance, dsmig performs a best effort merge of the two files. Custom schema defined in any other files are also copied to the new instance.

During schema migration, all fractional replication information is moved from the schema files. Fractional replication must be redefined in the new instance.

For more information, see dsmig(1M).

Using dsmig to Migrate Security Data

To migrate the security settings automatically, run the following command:

$ dsmig migrate-security old-instance-path new-instance-path

During the migration of security settings, dsmig performs the following tasks:

For more information, see dsmig(1M).

Using dsmig to Migrate Configuration Data

Directory Server 5.2 configuration is specified in the file serverRoot/slapd-instance-path/config/dse.ldif. Directory Server 6.0 configuration is specified in the file instance-path/config/dse.ldif.

To migrate the configuration automatically, run the following command:

$ dsmig migrate-config old-instance-path new-instance-path

In this step, dsmig reads each LDIF entry in the configuration file (dse.ldif) of the 5.2 instance. If these entries exist in the corresponding Directory Server 6.0 configuration file, their values are updated. If the entries do not exist, they are created.

Migration of the configuration is done over LDAP. By default, dsmig binds to the new instance securely, issuing a StartTLS request.

Note –

By default, StartTLS is not enabled on Windows. If you are running dsmig on Windows, use the -e or -–unsecured option to specify an unsecure connection. Alternatively, use the -Z or --use-secure-port option to specify a secure connection over SSL. If you do not use either of these options on Windows, dsmig issues a warning and the migration process terminates with an error.

For more information see dsmig(1M). For details of the specific configuration attributes that are migrated, see Migration of Specific Configuration Attributes.

Plug-in Configuration Data

dsmig migrates configuration data for certain Directory Server plug-ins only. For most system plug-ins, configuration data is not migrated automatically.

dsmig migrates all configuration data for the CoS plug-in. In addition, dsmig migrates the enabled or disabled state for the following system plug-ins:

When you migrate the configuration in verbose mode, dsmig issues a warning indicating which system plug-in configurations are not migrated.

Plug-ins that you have created are not migrated. However, during the migration process user plug-in configuration data is dumped in the file new-instance-path/migration/old_userplugins_conf.ldif. These plug-ins must be recompiled when the migration is complete.

Chained Suffix Configuration Data

Configuration data for chained suffixes is not migrated. By default, the configuration data is dumped in the file new-instance-path/migration/old_chaining_conf.ldif. You can import the chaining configuration data from this file after migration, if required.

Configuration Data For Suffixes With Multiple Backends

Configuration data for suffixes with multiple backends is not migrated. If dsmig detects that a suffix has more than one backend, it does not migrate any of the configuration entries that belong to that suffix. This includes configuration entries for the mapping tree, replicas, replication agreements, LDBM instances, indexes, and encrypted attributes. Instead, all of these entries are dumped in the file new-instance-path/migration/old_distribution_conf.ldif. You can import the distribution configuration data from this file after migration, if required.

Replication Configuration Data

Configuration data for replication is not migrated by default. If you want this data to be migrated, select the -R option. By default, the data is dumped in the file new-instance-path/migration/old_replication_conf.ldif. You can import the replication configuration data from this file after migration, if required.

Configuration Data for o=netscapeRoot

Configuration data for the o=NetscapeRoot suffix is not migrated by default. If this information is required, use the -N to migrate the configuration data. If you do not use the -N option, the data is dumped in the file new-instance-path/migration/old_netscape_conf.ldif. You can import the configuration data from this file after migration, if required.

Configuration Attributes Not Migrated by dsmig

The following common configuration attributes are not migrated automatically.

This is not an exhaustive list. You might have used additional configuration attributes that must be migrated manually.


Using dsmig to Migrate User Data

In Directory Server 5.2, data is stored in serverRoot/slapd-instance-name/db. Directory Server 6.0 stores user data in instance-path/db.

To migrate data automatically, run the following command:

$ dsmig migrate-data old-instance-path new-instance-path

All suffixes are migrated by default, except the o=netscapeRoot suffix. dsmig copies the data, the indexes, and the transaction logs. The database context, that is, the state of the database, is not migrated.

In the new Directory Server administration model, there is no Configuration Directory Server. This means that the o=netscapeRoot suffix is no longer relevant, unless your deployment includes Identity Synchronization for Windows. By default, dsmig does not migrate the o=netscapeRoot database, unless specifically requested. To migrate the o=netscapeRoot database, use the -N option with the migrate-data subcommand.

For more information, see dsmig(1M).

Note –

During data migration, Directory Server checks whether nested group definitions exceed 30 levels. Deep nesting can signify a circular group definition, where a nested group contains a group that is also its parent. When a group with more than 30 nesting levels is encountered, Directory Server stops calculating the isMemberOf attributes for additional levels.

Each time this happens, Directory Server logs an error. You safely ignore these errors, although you should examine the definition of the group mentioned in the error message for potential circular definitions.

Tasks to be Performed After Automatic Migration

If you have used dsmig to migrate your server automatically, only the following two post-migration tasks must be completed: