Sun Java System Directory Server Enterprise Edition 6.3 Migration Guide

Chapter 2 Automated Migration Using the dsmig Command

Directory Server 6.3 provides a command-line migration tool to help you migrate from a Directory Server 5.1 or 5.2 instance to a Directory Server 6.3 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.3 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.1 or 5.2 instance and new instance refers to the Directory Server 6.3 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.

While creating a new instance, a DN and a password for the directory manager is stored in nsslapd-rootdn and nssalpd-rootpw attributes under cn=config. During the migration process, the values for these attributes from the 5.1 or 5.2 instance are not propagated as these attributes already hold a value for the new instance. The same behavior is applied to nsslapd-secureport and nsslapd-port attributes for the same reason.

Using dsmig to Migrate the Schema

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

Directory Server 6.3 provides a new schema file, 00ds6pwp.ldif, that contains new password policy attributes. In addition, certain configuration attributes have been added to 00core.ldif.

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.

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.1 or 5.2 configuration is specified in the file serverRoot/slapd-instance-path/config/dse.ldif. Directory Server 6.3 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.1 or 5.2 instance. If these entries exist in the corresponding Directory Server 6.3 configuration file, their values are updated.

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 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 should not import the old_chaining_conf.ldif file in the new instance but use it as a guideline to create the configuration data manually.

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.

The entries in the old_distribution_conf.ldif file refer to the old instance so should not be imported directly to the new instance. For more information about distribution, see Chapter 22, Directory Proxy Server Distribution, in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Replication Configuration Data

Configuration data for replication is not migrated by default. If you want this data to be migrated, use dsmig with 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 option 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.3 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.

Troubleshooting New Instances After Migration

After running dsmig migrate-data, if the error log of new instance contains lots of error messages, refer to the following steps:

  1. Stop all the Directory Server running instances.

  2. Remove nsslapd-infolog-area and nsslapd-infolog-level completely from the dse .ldif file.

  3. Start the Directory Server instances.

After the migration process, if you get an error while changing your password using the ldapmodify command, refer to the following steps:

  1. Check pwd-compat-mode using the following command:

    dsconf get-server-prop pwd-compat-mode
  2. If pwd-compat-mode is set to DS-6 mode, you must use the pwdPolicy objectclass while changing the password using the ldapmodify command.

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: