Chapter 3 Migrating Directory Server Manually

If your deployment does not satisfy the requirements for automatic migration
described in Deciding on Automatic or Manual Migration, you must migrate the servers manually. This chapter describes
the process for manual migration of each part of the server.

Before You Start a Manual Migration

Migrating an instance manually involves migrating each part of the server
in the same order as performed by the automatic migration tool (dsmig).
In this section, old instance refers to the version 5
instance and new instance refers to the 6.2
instance.

Before you start a manual migration, ensure that the following tasks
have been performed:

Directory Server 6.2 software has been
installed.

Directory Server 6.2 software can
be installed on the same machine that holds the Directory Server 5 instance,
or on a different machine.

The new instance has been created.

The new instance
can be created anywhere except for the exact location of the old instance.
The new instance can be installed on the same LDAP/LDAPS port or on a different
port. If you use different ports, any replication agreements to the new instance
must be changed accordingly.

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.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.

The old instance has been stopped correctly.

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

Migrating the Schema Manually

Directory Server 5 schema files are located in serverRoot/slapd-serverID/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. Apart from these files, the standard schema files provided with Directory Server 6.2
are identical to those provided in version 5.

To migrate the schema, perform the following steps:

Copy the 99user.ldif file from the existing
instance to the new instance. If you have already added custom schema to
the new instance, you will need to choose which version of the custom schema
to keep.

If you have defined custom schema in any other files, copy
these files to the new instance.

Any fractional replication information must be redefined in
the new instance.

Migrating Configuration Data Manually

Directory Server 5 configuration is specified in the
file serverRoot/slapd-serverID/config/dse.ldif. Directory Server 6.2 configuration is specified
in the file instance-path/config/dse.ldif.

To migrate data from 5.1, perform the following steps:

Run the migrateInstance5 migration script
to produce a 5.2 configuration.

Use dsmig to migrate the 5.2 configuration.

You can directly use dsmig to migrate 5.1 configuration
data.

For information on using migrateInstance5, see the Directory Server 5.2 2005Q1 Installation and Migration Guide.
For information on using dsmig to migrate the configuration,
see Using dsmig to Migrate Configuration Data.

The following section describes the specific configuration attributes
that must be migrated from the old instance to the new instance.

Migration of Specific Configuration Attributes

The values of the following attribute types must be migrated.

Global Configuration Attributes

The implementation of global scope ACIs requires all ACIs specific to
the rootDSE to have a targetscope field,
with a value of base (targetscope=”base”).
ACIs held in the rootDSE are specific to each Directory Server
instance and are not replicated. Therefore there should be no incompatibility
problems when running a Directory Server 6.2 server in
a topology containing servers of previous versions. For more information about
the changes made with regard to ACI scope, see Changes to ACIs.

In addition to the ACI change, the following attributes under cn=config must be migrated:

Security Configuration Attributes

All attributes under "cn=encryption,cn=config" must
be migrated.

If you are using certificate authentication or the secure port, the
key file path and certificate database file path under "cn=encryption,cn=config" must be updated. The values of the following attributes must be
migrated:

nsKeyfile
nsCertfile

Feature Configuration Attributes

The values of the aci attributes under "cn=features,cn=config" must be migrated.

In addition, the values of all identity mapping attributes must be migrated.

Mapping Tree Configuration Attributes

All entries under "cn=mapping tree,cn=config" must
be migrated.

The Netscape Root database has been deprecated in Directory Server 6.2.
If your old instance made specific use of the Netscape Root database, the
attributes under o=netscaperoot must be migrated. Otherwise,
they can be ignored.

Replication Configuration Attributes

Before migrating replication configuration attributes, ensure that there
are no pending changes to be replicated. You can use the insync command
to do this.

In addition to the configuration attributes, all entries under cn=replication,cn=config must be migrated. You must manually update the host and port on
all replication agreements to the new instance, as well as the path to the
change log database (nsslapd-changelogdir).

The following sections list the replication configuration attributes
that must be migrated:

Change Log Attributes

Table 3–1 Change Log Attribute Name Changes

Old Attribute Name

Directory Server 6.2 Attribute Name

nsslapd-changelogmaxage

dschangelogmaxage

nsslapd-changelogmaxentries

dschangelogmaxentries

In addition, these attributes must be moved from cn=changelog5,cn=config to cn=replica,cn=suffixname,cn=mapping tree,cn=config entries
(for each suffix name).

Fractional Replication Configuration Attributes

If your topology uses fractional replication, the following attribute
names must be changed.

Table 3–2 Fractional Replication Attribute Name
Changes

Old Attribute Name

Directory Server 6.2Attribute Name

dsFilterSPType == fractional_include

dsReplFractionalInclude

dsFilterSPType == fractional_exclude

dsReplFractionalExclude

Replica Configuration Attributes

The values of the following replica configuration attributes must be
migrated:

Directory Server 6.2 introduces the new pwdPolicy object class. The attributes of this object class replace the old
password policy attributes. For a description of these new attributes see
the pwdPolicy(5dsoc) man page.

By default, the new password policy is backward compatible with the
old password policy. However, because backward compatibility is not guaranteed
indefinitely, you should migrate to the new password policy as soon as is
convenient for your deployment. For information about password policy compatibility,
see Password Policy Compatibility.

While Directory Server 6.2 automatically manages
coexistence between new and old password policies and entry operational attributes
during migration and subsequent operations, you need to migrate any applications
that refer to the old password policy attributes. The following table provides
a mapping of the legacy password policy configuration attributes to the new
attributes.

If your deployment uses the NetscapeRoot suffix,
you must migrate the attributes under cn=netscapeRoot,cn=ldbm database,cn=plugins,cn=config. You must also replace the database location (nsslapd-directory) with the location of the new Directory Server 6 instance.

All default index configuration attributes must be migrated, except
for system indexes. Default index configuration attributes are stored in the
entry cn=default indexes,cn=ldbm database,cn=plugins,cn=config.
Indexes for the NetscapeRoot database do not need to be
migrated.

Chained Suffix Attributes

All chained suffix configuration attributes must be migrated. The following
configuration attributes are common to all chained suffixes. These attributes
are stored in the entry cn=config,cn=chaining database,cn=plugins,cn=config.

nsActivechainingComponents
nsTransmittedControls

The following configuration attributes apply to a default instance of
a chained suffix. These attributes are stored in the entry cn=default
instance config, cn=chaining database,cn=plugins,cn=config.

UID Uniqueness Plug-In

The configuration of this plug-in is stored under cn=UID Uniqueness,cn=plugins,cn=config. The following attributes must be migrated:

nsslapd-pluginarg*
nsslapd-pluginenabled

Migrating Security Settings Manually

When you migrate an instance manually, the order in which you perform
the migration of the security and the migration of the configuration is different
to when you migrate using dsmig. If you migrate the security
settings by replacing the default Directory Server 6.2
certificate and key databases wit the old databases, as described in this
section, you must migrate the configuration first.

To migrate the security settings manually, perform the following steps:

If you have already started using the new instance, stop the
instance.

Back up the certificate database and key database files on
the new instance.

Copy the certificate database and key database files from
the existing instance to the new instance.

If the existing instance uses an external security token,
copy the security module database and the external token library to the new
instance.

$ cp serverRoot/alias/secmod.db instance-path/alias/secmod.db

Start the new instance.

The security configuration attributes are migrated when you migrate
the rest of the configuration attributes. In this sense, migration of the
security settings is not complete until you have migrated the configuration.
Migration of the configuration is described in the following section.

Migrating User Data Manually

If your topology does not support automatic data migration, you must
migrate the data manually. This involves exporting the data from the existing
instance and re-importing it to the new instance.

To migrate data manually from an existing version 5 instance, perform
the following steps:

If you already have data in the new instance, back up any
conflicting suffixes in the new instance.

If you are migrating a master server instance in a replicated
topology, make sure that the master is synchronized with all servers that
are direct consumers of that master.

It is not possible to migrate
the change log manually. A new change log is created in the 6.2
instance.

Export the required suffixes to LDIF by using the db2ldif command. This command exports all the suffix contents to an LDIF
file, when the server is either running or stopped.

In this example, -a specifies the resulting LDIF file,
and -s specifies the changelog suffix.

On the new instance, import the retro change log using the dsadm import command. For example, the following command imports
the change log LDIF file created previously.

$ dsadm import instance-path changelog.ldif cn=changelog

Start the new instance.

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.