Skip Headers
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
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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

The chapter covers the following topics:

7.1 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.2 instance and new instance refers to the 11g Release 1 (11.1.1.7.0) instance.

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

7.2 Migrating the Schema Manually

Directory Server 5.2 schema files are located in serverRoot/slapd-serverID/config/schema. Directory Server 11g 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 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 11g Release 1 (11.1.1.7.0) are identical to those provided in version 5.

To migrate the schema, perform the following steps:

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

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

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

7.3 Migrating Configuration Data Manually

Directory Server 5.2 configuration is specified in the file serverRoot/slapd-serverID/config/dsee.ldif. Directory Server 11g Release 1 (11.1.1.7.0) configuration is specified in the file instance-path/config/dsee.ldif.

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

7.3.1 Migration of Specific Configuration Attributes

The values of the following attribute types must be migrated.

7.3.1.1 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 11g Release 1 (11.1.1.7.0) 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

7.3.1.2 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

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

7.3.1.4 Mapping Tree Configuration Attributes

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

The Netscape Root database has long been deprecated, and does not exist in Directory Server 11g Release 1 (11.1.1.7.0). 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.

7.3.1.5 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:

7.3.1.5.1 Change Log Attributes

Table 7-1 Change Log Attribute Name Changes

Old Attribute Name Directory Server 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).

7.3.1.5.2 Fractional Replication Configuration Attributes

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

Table 7-2 Fractional Replication Attribute Name Changes

Old Attribute Name Directory Server 11g Release 1 (11.1.1.7.0) Attribute Name

dsFilterSPType == fractional_include

dsReplFractionalInclude

dsFilterSPType == fractional_exclude

dsReplFractionalExclude


7.3.1.5.3 Replica Configuration Attributes

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.

7.3.1.5.4 Replication Agreement Configuration

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 11g Release 1 (11.1.1.7.0). 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.

7.3.1.6 Password Policy Configuration Attributes

For details on configuration of the Directory Server 11g Release 1 (11.1.1.7.0) password policy, see Chapter 7, Directory Server Password Policy, in Administrator's Guide for Oracle Directory Server Enterprise Edition. The attributes that define the password policy are stored in the entry cn=Password Policy,cn=config. Note that in Directory Server 5.2, password policy attributes were located directly under cn=config.

The attributes of the pwdPolicy object class replace the old password policy attributes. For a description of these attributes see the pwdPolicy(5dsoc) man page.

By default, this 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 and about rewriting a suffix, see Administrator's Guide for Oracle Directory Server Enterprise Edition.

While Directory Server 11g Release 1 (11.1.1.7.0) 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 7-3 Mapping Between 5.2 and 11g Release 1 (11.1.1.7.0) Password Policy Attributes

Legacy Directory Server Attribute Directory Server 11g Release 1 (11.1.1.7.0) 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


7.3.1.7 SNMP Attributes

The entry cn=SNMP,cn=config does not exist in Directory Server 11g Release 1 (11.1.1.7.0). All attributes under this entry are therefore deprecated. For information about setting up SNMP in Directory Server 11g Release 1 (11.1.1.7.0), see Setting Up SNMP for Directory Server in Administrator's Guide for Oracle Directory Server Enterprise Edition.

7.3.1.8 UniqueID Generator Configuration Attributes

The nsState attribute under cn=uniqueid generator,cn=config must be migrated.

7.3.1.9 Database Configuration Attributes

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

7.3.1.10 Plug-In Configuration Attributes

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 Developer's Guide for Oracle Directory Server Enterprise Edition.

The following sections describe the standard plug-ins whose configuration must be migrated if you have changed it.

7.3.1.10.1 7-Bit Check Plug-In

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
7.3.1.10.2 Class of Service Plug-In

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
7.3.1.10.3 DSML Frontend Plug-In

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
7.3.1.10.4 Pass Through Authentication Plug-In

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.

7.3.1.10.5 Password Synchronization Plug-In

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

nsslapd-pluginenabled
7.3.1.10.6 Referential Integrity Plug-In

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
7.3.1.10.7 Retro Change Log Plug-In

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

7.4 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 11g Release 1 (11.1.1.7.0) certificate and key databases with the old databases, as described in this section, you must migrate the configuration first.

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

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

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

  3. 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
    
  4. 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
    
  5. Update the certificate database password.

    $ dsadm set-flags instance-path cert-pwd-prompt=on
    
  6. Copy the certificate mapping file from the existing instance to the new instance.

    $ cp serverRoot/shared/config/certmap.conf instance-path/alias/certmap.conf
    
  7. 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
    
  8. 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.

7.5 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, perform the following steps:

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

  2. 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 11g Release 1 (11.1.1.7.0) instance.

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

  4. 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
    
  5. If the retro change log was configured on the old 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.

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

7.6 Migrating User Plug-Ins Manually

User plug-ins cannot be migrated. If you have custom user plug-ins, recompile them and add them to the Directory Server 11g Release 1 (11.1.1.7.0) instance manually. For a detailed list of plug-in API changes, see C"hapter 2, Changes to the Plug-In API Since Directory Server 5.2" in Developer's Guide for Oracle Directory Server Enterprise Edition.

7.7 Tasks to be Performed After Manual Migration

If you have migrated your server manually, the following post-migration tasks are required before you can run the new server.