Chapter 3 Automated Migration Using the dsmig Command

Directory Server 7.0 provides a command-line migration tool to help you migrate from a Directory Server 5.2 instance to a Directory Server 7.0 instance. You can use the migration tool only 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

• Prerequisites for Running dsmig

• Using dsmig to Migrate the Schema

• Using dsmig to Migrate Security Data

• Using dsmig to Migrate Configuration Data

• Using dsmig to Migrate User Data

• Tasks to be Performed After Automatic Migration

About the Automatic Migration Tool

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

The dsmig command 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.

The dsmig command 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 7.0 instance.

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

• The Directory Server Enterprise Edition 7.0 packages (either zip, or native packages) have been installed.

  The Directory Server Enterprise Edition 7.0 packages can be installed on the same machine that holds the old instance, or on a different machine.

• The old instance must have been stopped correctly.

  A disorderly shutdown of the old instance will cause problems during the migration. Even if the old and new instance are on different machines, the old instance must be stopped before the migration is started.

• dsmig has access to the old instance files.

• If the old and new instances are on different machines, a complete image of the old instance must be created on the machine that hosts the new instance.

  The complete image includes all the files required for migration of the instance (schema, configuration, security and database files). The complete image files must be located in the same directories as they were under the original Server Root. You can run cp -r to achieve this, provided none of the files have been relocated outside the Server Root.

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.

The dsmig command uses the 389 and 636 ports, by default, when creating an instance. If these ports are already in use, provide different ports to create an instance. For more information, see dsmig(1M).

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 old 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.2 schema files are located in serverRoot/slapd-instance-path/config/schema. Directory Server 7.0 schema files are located in INSTANCE-PATH/config/schema.

Directory Server 7.0 provides a schema file, 00ds6pwp.ldif, that contains 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:

• Backs up the certificate and database files in the new instance.

• Copies the certificate database and key database files from the old instance to the new instance.

• Copies the password file from the old instance to the new instance.

• Copies the certificate mapping file from the old instance to the new instance.

• Copies the security module database.

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 7.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 old instance. If these entries exist in the corresponding Directory Server 7.0 configuration file, their values are updated.

The dsmig migrate-config command resets the server to the read-write mode. After migration, you can switch the server in the read-only mode by running the following command:

$ dsconf set-server-prop read-write-mode:read-only

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

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:

• CoS

• 7–bit Check

• DSML Frontend

• Pass-Through Authentication

• Referential Integrity

• Retro Change Log

• UID Uniqueness

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.

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 21, Directory Proxy Server Distribution, in Sun Directory Server Enterprise Edition 7.0 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.

ds-hdsml-dsmlschemalocation
ds-hdsml-soapschemalocation
dsKeyedPassword
dsMappedDN
dsMatching-pattern
dsMatching-regexp
dsSaslPluginsEnable
dsSaslPluginsEnable
dsSaslPluginsPath
dsSearchBaseDN
dsSearchFilter
nsabandonedsearchcheckinterval
nsbindconnectionslimit
nsbindretrylimit
nsbindtimeout
nschecklocalaci
nsconcurrentbindlimit
nsconcurrentoperationslimit
nsconnectionlife
nshoplimit
nsMatchingRule
nsmaxresponsedelay
nsmaxtestresponsedelay
nsoperationconnectionslimit
nspossiblechainingcomponents
nspossiblechainingcomponents
nspossiblechainingcomponents
nspossiblechainingcomponents
nspossiblechainingcomponents
nspossiblechainingcomponents
nsproxiedauthorization
nsreferralonscopedsearch
nsslapd-db-durable-transaction
nsslapd-db-home-directory
nsslapd-db-replication-batch-val
nsslapd-db-transaction-logging
nsslapd-directory
nsslapd-disk-full-threshold
nsslapd-disk-low-threshold
nsslapd-exclude-from-export
nsslapd-localhost
nsslapd-localuser
nsslapd-mode
nsslapd-port
nsslapd-rewrite-rfc1274
nsslapd-secureport
nsslapd-security
nsSSL2
nsSSL3
nsSSLActivation
nsSSLServerAuth
nsSSLSessionTimeout
nsState
nstransmittedcontrols
plugin-order-preoperation-finish-entry-encode-result

Using dsmig to Migrate User Data

In Directory Server 5.2, data is stored in serverRoot/slapd-instance-name/db. Directory Server 7.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 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).

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:

• If you have customized user plug-ins, these need to be recompiled and added to the new server manually.

• If the migrated server was part of a replicated topology, see Issues Related to Migrating Replicated Servers.