Directory Server 6.2 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.2 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:
The migration tool, dsmig, is delivered with the Directory Server 6.2 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.
In this section, old instance refers to the 5.1 or 5.2 instance and new instance refers to the Directory Server 6.2 instance.
Before you use dsmig to migrate an instance, ensure that the following tasks have been performed:
The Directory Server 6.2 packages (either zip, or native packages) have been installed.
The Directory Server 6.2 packages can be installed on the same machine that holds the Directory Server 5.1 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.
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.
Directory Server 5.1 or 5.2 schema files are located in serverRoot/slapd-instance-path/config/schema. Directory Server 6.2 schema files are located in INSTANCE-PATH/config/schema.
Directory Server 6.2 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).
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).
Directory Server 5.1 or 5.2 configuration is specified in the file serverRoot/slapd-instance-path/config/dse.ldif. Directory Server 6.2 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.2 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.
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.
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:
Retro Change Log
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 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 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.2 Administration Guide.
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 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.
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
In Directory Server 5.2, data is stored in serverRoot/slapd-instance-name/db. Directory Server 6.2 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).
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.
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.