Oracle® Fusion Middleware Upgrade and Migration Guide for Oracle Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0) Part Number E28971-01 |
|
|
PDF · Mobi · ePub |
dsmig
CommandOracle Directory Server Enterprise Edition11g Release 1 (11.1.1.7.0) provides a command-line migration tool to help you migrate from a Directory Server 5.2 instance to an ODSEE 11g Release 1 (11.1.1.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:
The migration tool, dsmig
, is delivered with the Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0). When these ODSEE 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.
dsmig
In this section, old instance refers to the 5.2 instance and new instance refers to the Directory Server 11g Release 1 (11.1.1.7.0) instance.
Before you use dsmig
to migrate an instance, ensure that the following tasks have been performed:
The Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0) has been installed.
The Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0) 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 not exist, the instance is created automatically.
The new instance can be created anywhere except for the exact location of the old instance.
Note:
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.
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.
dsmig
to Migrate the SchemaDirectory Server 5.2 schema files are located in serverRoot
/slapd-
instance-path
/config/schema
. Directory Server 11g Release 1 (11.1.1.7.0) schema files are located in INSTANCE-PATH
/config/schema
.
Directory Server 11g Release 1 (11.1.1.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.
dsmig
to Migrate Security DataTo 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.
dsmig
to Migrate Configuration DataDirectory Server 5.2 configuration is specified in the file serverRoot
/slapd-
instance-path
/config/dsee.ldif
. Directory Server 11g Release 1 (11.1.1.7.0) configuration is specified in the file instance-path
/config/dsee.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 (dsee.ldif
) of the old instance. If these entries exist in the corresponding Directory Server 11g Release 1 (11.1.1.7.0) configuration file, their values are updated.
Note:
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.
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. For details of the specific configuration attributes that are migrated, see Migration of Specific Configuration Attributes.
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 back ends 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 Administrator's Guide for Oracle Directory Server Enterprise Edition.
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.
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.
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
dsmig
to Migrate User DataIn Directory Server 5.2, data is stored in serverRoot
/slapd-
instance-name
/db
. Directory Server 11g Release 1 (11.1.1.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.
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.
After running dsmig migrate-data
, if the error log of new instance contains lots of error messages, refer to the following steps:
Stop all the Directory Server running instances.
Remove nsslapd-infolog-area
and nsslapd-infolog-level
completely from the dsee.ldif
file.
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:
Check pwd-compat-mode
using the following command:
dsconf get-server-prop pwd-compat-mode
If pwd-compat-mode
is set to DS-6 mode
, you must use the pwdPolicy
object class while changing the password using the ldapmodify
command.
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.