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.
The chapter covers the following topics:
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.1 instance.
Before you start a manual migration, ensure that the following tasks have been performed:
Directory Server 6.1 software has been installed.
Directory Server 6.1 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.
Directory Server 5 schema files are located in serverRoot/slapd-serverID/config/schema. Directory Server 6.1 schema files are located in instance-path/config/schema.
Directory Server 6.1 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.1 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.
Directory Server 5 configuration is specified in the file serverRoot/slapd-serverID/config/dse.ldif. Directory Server 6.1 configuration is specified in the file instance-path/config/dse.ldif.
If you are migrating from 5.1, you must migrate the configuration files manually. The easiest way to do this is to run the migrateInstance5 migration script to produce a 5.2 configuration, and then to migrate the 5.2 configuration using dsmig. 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.
The values of the following attribute types must be migrated.
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.1 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:
nsslapd-accesscontrol nsslapd-accesslog-level nsslapd-accesslog-logbuffering nsslapd-accesslog-logexpirationtime nsslapd-accesslog-logexpirationtimeunit nsslapd-accesslog-logging-enabled nsslapd-accesslog-logmaxdiskspace nsslapd-accesslog-logminfreediskspace nsslapd-accesslog-logrotationtime nsslapd-accesslog-logrotattiontimeunit nsslapd-accesslog-maxlogsize nsslapd-accesslog-maxlogsperdir nsslapd-attribute-name-exceptions nsslapd-auditlog-logexpirationtime nsslapd-auditlog-logexpirationtimeunit nsslapd-auditlog-logging-enabled nsslapd-auditlog-logmaxdiskspace nsslapd-auditlog-logminfreediskspace nsslapd-auditlog-logrotationtime nsslapd-auditlog-logrotattiontimeunit nsslapd-auditlog-maxlogsize nsslapd-auditlog-maxlogsperdir nsslapd-certmap-basedn nsslapd-ds4-compatible-schema nsslapd-enquote-sup-oc nsslapd-errorlog-level nsslapd-errorlog-logexpirationtime nsslapd-errorlog-logexpirationtimeunit nsslapd-errorlog-logging-enabled nsslapd-errorlog-logmaxdiskspace nsslapd-errorlog-logminfreediskspace nsslapd-errorlog-logrotationtime nsslapd-errorlog-logrotattiontimeunit nsslapd-errorlog-maxlogsize nsslapd-errorlog-maxlogsperdir nsslapd-groupevalnestlevel nsslapd-idletimeout nsslapd-infolog-area nsslapd-infolog-level nsslapd-ioblocktimeout nsslapd-lastmod nsslapd-listenhost nsslapd-maxbersize nsslapd-maxconnections nsslapd-maxdescriptors nsslapd-maxpsearch nsslapd-maxthreadsperconn nsslapd-nagle nsslapd-readonly nsslapd-referral nsslapd-referralmode nsslapd-reservedescriptors nsslapd-return-exact-case nsslapd-rootpwstoragescheme nsslapd-schema-repl-useronly nsslapd-schemacheck nsslapd-search-tune nsslapd-securelistenhost nsslapd-security nsslapd-sizelimit nsslapd-threadnumber nsslapd-timelimit ds-start-tls-enabled
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
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.
All entries under "cn=mapping tree,cn=config" must be migrated.
The Netscape Root database has been deprecated in Directory Server 6.1. 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.
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:
Old Attribute Name |
Directory Server 6.1 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).
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.1Attribute Name |
---|---|
dsFilterSPType == fractional_include |
dsReplFractionalInclude |
dsFilterSPType == fractional_exclude |
dsReplFractionalExclude |
The values of the following replica configuration attributes must be migrated:
ds5ReferralDelayAfterInit nsDS5Flags nsDS5ReplicaBindDN nsDS5ReplicaId nsDS5ReplicaLegacyConsumer nsDS5ReplicaName nsDS5ReplicaPurgeDelay nsDS5ReplicaReferral nsDS5ReplicaRoot nsDS5ReplicaTombstonePurgeInterval aci
The dschangelogmaxage and dschangelogmaaxentries attributes are added to the replica entry.
The values of the following attributes must be migrated for each replication agreement:
description ds5agreementEnable ds5ReplicaTransportCompressionLevel ds5ReplicaTransportGroupSize ds5ReplicaTransportWindowSize nsDS5ReplicaBindDN nsDS5ReplicaBindMethod nsDS5ReplicaCredentials nsDS5ReplicaHost nsDS5ReplicaPort nsDS5ReplicaRoot nsDS5ReplicaTimeout nsDS5ReplicaTransportInfo nsDS5ReplicaUpdateSchedule aci
Issues can arise when you migrate the nsDS5ReplicaCredentials attribute. For more information, see Manual Reset of Replication Credentials.
There is no ds5PartialReplConfiguration attribute in Directory Server 6.1. This attribute must be removed.
If you are using fractional replication, the dsReplFractionalInclude and dsReplFractionalExclude attributes are added for each replication agreement.
All attributes under "cn=replication,cn=config" are migrated.
Directory Server 6.1 implements a new password policy. For details on configuration of the new password policy, see Chapter 7, Directory Server Password Policy, in Sun Java System Directory Server Enterprise Edition 6.1 Administration Guide. The attributes that define the password policy are stored in the entry cn=Password Policy,cn=config. Note that in Directory Server 5.1, password policy attributes were located directly under cn=config.
Directory Server 6.1 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.1 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.
Table 3–3 Mapping Between 5 and 6.1 Password Policy Attributes
Legacy Directory Server Attribute |
Directory Server 6.1 Attribute |
---|---|
passwordMinAge |
pwdMinAge |
passwordMaxAge |
pwdMaxAge |
passwordExp |
pwdMaxAge |
passwordInHistory |
pwdInHistory |
passwordSyntax |
pwdCheckQuality |
passwordMinLength |
pwdMinLength |
passwordWarning |
pwdExpireWarning |
- |
pwdGraceLoginLimit |
passwordMustChange |
pwdMustChange |
passwordChange |
pwdAllowUserChange |
- |
pwdSafeModify |
passwordStorageScheme |
passwordStorageScheme |
passwordExpireWithoutWarning |
- |
passwordLockout |
pwdLockout |
passwordLockoutDuration |
pwdLockoutDuration |
passwordUnlock |
pwdLockoutDuration |
passwordMaxFailure |
pwdMaxFailure |
passwordResetFailureCount |
pwdFailureCountInterval |
The entry cn=SNMP,cn=config does not exist in Directory Server 6.1. All attributes under this entry are therefore deprecated. For information about setting up SNMP in Directory Server 6.1, see Setting Up SNMP for Directory Server in Sun Java System Directory Server Enterprise Edition 6.1 Administration Guide.
The nsState attribute under cn=uniqueid generator,cn=config must be migrated.
General database configuration attributes are stored under cn=config,cn=ldbm database,cn=plugins,cn=config. The following attributes must be migrated:
nsslapd-lookthroughlimit nsslapd-allidsthreshold nsslapd-cache-autosize nsslapd-cache-autosize-split nsslapd-cachesize nsslapd-db-checkpoint-interval nsslapd-db-circular-logging nsslapd-db-durable-transactions nsslapd-db-idl-divisor nsslapd-db-locks nsslapd-db-logbuf-size nsslapd-db-logfile-size nsslapd-db-page-size nsslapd-db-transaction-batch-val nsslapd-db-tx-max nsslapd-dbncache nsslapd-import-cachesize nsslapd-exclude-from-export nsslapd-disk-low-threshold nsslapd-disk-full-threshold
Database-specific attributes are stored in entries of the form cn=database instance name,cn=ldbm database,cn=plugins,cn=config. The following attributes must be migrated:
nsslapd-suffix nsslapd-cachesize nsslapd-cachememsize nsslapd-readonly nsslapd-require-index
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.
All index configuration attributes must be migrated, except for system indexes. Index configuration attributes are stored in entries of the sort cn=index name, cn=index, cn=database instance name, cn=ldbm database, cn=plugins, cn=config.
All attribute encryption configuration attributes must be migrated.
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.
nsAbandonedSearchCheckInterval nsBindConnectionsLimit nsBindRetryLimit nsBindTimeout nsCheckLocalACI nsConcurrentBindLimit nsConcurrentOperationsLimit nsConnectionLife nsHopLimit nsmaxresponsedelay nsmaxtestresponsedelay nsOperationConnectionslimit nsProxiedAuthorization nsReferralOnScopedSearch nsslapd-sizelimit nsslapd-timelimit
If you have changed the configuration of any standard plug-in, you must update that configuration. You must also update the configuration of all custom plug-ins. At a minimum, you must recompile all custom plug-ins and add their configuration to the directory. For a detailed list of plug-in API changes, see Chapter 2, Changes to the Plug-In API Since Directory Server 5.2, in Sun Java System Directory Server Enterprise Edition 6.1 Developer’s Guide.
The following sections describe the standard plug-ins whose configuration must be migrated if you have changed it.
The configuration of this plug-in is stored under cn=7-bit check,cn=plugins,cn=config. The following attributes must be migrated:
nsslapd-pluginarg* nsslapd-pluginenabled
The configuration of this plug-in is stored under cn=Class of Service,cn=plugins,cn=config. The following attributes must be migrated:
nsslapd-pluginarg0 nsslapd-pluginenabled
The configuration of this plug-in is stored under cn=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config. The following attributes must be migrated:
ds-hdsml-port ds-hdsml-iobuffersize ds-hdsml-requestmaxsize ds-hdsml-responsemsgsize ds-hdsml-poolsize ds-hdsml-poolmaxsize ds-hdsml-clientauthmethod ds-hdsml-rooturl ds-hdsml-soapschemalocation ds-hdsml-dsmlschemalocation nsslapd-pluginenabled
The configuration of this plug-in is stored under cn=Pass Through Authentication,cn=plugins,cn=config. The following attribute must be migrated:
nsslapd-pluginenabled
The nsslapd-pluginarg* attributes must be migrated only if you require the configuration for o=netscapeRoot to be migrated.
The configuration of this plug-in is stored under cn=pswsync,cn=plugins,cn=config. The following attribute must migrated:
nsslapd-pluginenabled
The configuration of this plug-in is stored under cn=Referential Integrity Postoperation,cn=plugins,cn=config. The following attributes must be migrated:
nsslapd-pluginarg* nsslapd-pluginenabled
The configuration of this plug-in is stored under cn=Retro Changelog PlugIn,cn=plugins,cn=config. The following attributes must be migrated:
nsslapd-changelogmaxage nsslapd-changelogmaxentries nsslapd-pluginarg* nsslapd-pluginenabled
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
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.1 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.
$ cp serverRoot/alias/slapd-serverID-cert8.db instance-path/alias/slapd-cert8db $ cp serverRoot/alias/slapd-serverID-key3.db instance-path/alias/slapd-key3.db
For 5.1 servers and earlier releases of 5.2 servers, the certificate database to be copied is serverRoot/alias/slapd-serverID-cert7.db.
Copy the password file from the existing instance to the new instance.
$ cp serverRoot/alias/slapd-serverID-pin.txt instance-path/alias/slapd-pin.txt
Update the certificate database password.
$ dsadm set-flags instance-path cert-pwd-prompt=on
Copy the certificate mapping file from the existing instance to the new instance.
$ cp serverRoot/shared/config/certmap.conf instance-path/alias/certmap.conf
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.
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.1 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.
The following example exports two suffixes to a single LDIF file.
$ serverRoot/slapd-serverID/db2ldif -a example.ldif \ -r -s "ou=people,dc=example,dc=com" -s "ou=departments,dc=example,dc=com"
In this example, -a specifies the resulting LDIF file, -r indicates that replication information should be exported, and -s specifies the suffixes to be included in the export.
On the new instance, import the LDIF files by using the dsadm import command. For example, the following commands import the LDIF file created previously into the two suffixes that were exported.
$ dsadm import instance-path example.ldif ou=people,dc=example,dc=com $ dsadm import instance-path example.ldif ou=departments,dc=example,dc=com
If the retro change log was configured on the 5.2 instance, export the retro change log to LDIF by using the db2ldif command.
$ serverRoot/slapd-serverID/db2ldif -a changelog.ldif \ -s "cn=changelog"
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.
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.
User plug-ins cannot be migrated. If you have custom user plug-ins, recompile them and add them to the Directory Server 6.1 instance manually. For a detailed list of plug-in API changes, see Chapter 2, Changes to the Plug-In API Since Directory Server 5.2, in Sun Java System Directory Server Enterprise Edition 6.1 Developer’s Guide.
If you have migrated your server manually, the following post-migration tasks are required before you can run the new server.
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 Chapter 4, Migrating a Replicated Topology.
If you have customized backup, recovery, and installation scripts, you need to rewrite these scripts to comply with the new version.