The sample scenarios described in this chapter offer a few different paths for stepping through the migration. The chapter also discusses constraints that can affect the migration.
It includes the following topics:
Single Server - Migrate to Compatibility Mode, Then to Native Mode
Multiple Servers - Migrate Incrementally to Compatibility Mode, Then to Native Mode
Each scenario emphasizes a priority such as keeping the servers and LDAP directory available (so that, for example, users can continue to send and receive email). The scenarios are not strict procedures. They provide guidelines to assist you in designing your own migration path.
As you read the scenarios and plan your migration path, keep in mind the following questions:
Is your system deployed on a single server or distributed across multiple servers?
Is it critical to minimize downtime?
Do you need to limit the time it takes to perform the migration?
Is it important to minimize the complexity of the migration process?
Are you running applications developed at your site that rely on LDAP Schema 1? (Have you created your own tools that provision directly against the LDAP directory and use Schema 1?) How complex a task would it be to convert your applications to use Schema 2?
These questions can help you to decide which scenario to use as a model for your own migration path. For example:
If you have a multiple-server deployment and your highest priority is to minimize downtime, your migration path might resemble Scenario D, Multiple Servers - Migrate Incrementally to Native Mode
If you have created your own provisioning tools that rely on Schema 1 and you have a multiple-server deployment, your migration path might resemble Scenario E, Multiple Servers - Migrate Incrementally to Compatibility Mode, Then to Native Mode
However, no single scenario is likely to correspond exactly to your situation. The scenarios are general examples. They do not attempt to replicate an actual user installation.
Read the assumptions and characteristics at the start of each scenario. Read all the steps in the scenarios that most closely resemble your situation. Then refine your specific migration strategy based on those guidelines.
The scenarios are as follows:
Scenario A: Single Server - Migrate to Native Mode
Scenario B: Single Server - Migrate to Compatibility Mode, Then to Native Mode
Scenario C: Multiple Servers - Migrate Directly to Native Mode
Scenario D: Multiple Servers - Migrate Incrementally to Native Mode
Scenario E: Multiple Servers - Migrate Incrementally to Compatibility Mode, Then to Native Mode
Once you have become familiar with your particular migration issues and designed your migration strategy, it is a good practice to migrate on a test system before you migrate your production LDAP directory and Messaging and Calendar servers.
Before you choose a migration strategy, you should understand the potential constraints on using the LDAP directory during the migration process.
Depending on the path you follow, old and new components might have to coexist during certain stages of the migration. Your installation temporarily could have a mixed environment, such as one of the following:
Schema 1; one or more servers upgraded to version 6; remaining servers running version 5.x.
Schema 2 (native mode or compatibility mode); one or more servers upgraded to version 6; remaining servers running version 5.x.
While your installation is in a mixed state, you might not be able to perform certain tasks such as domain provisioning. The following sections describe these issues in further detail.
The following provisioning tools are available:
To provision Schema 1:
For Messaging Server, use iPlanet Delegated Administrator.
For Calendar Server, use the command-line utilities provided with Calendar Server, as described in Appendix D, Calendar Server Command-Line Utilities Reference, in Sun Java System Calendar Server 6 2005Q4 Administration Guide.
To provision Schema 2, native mode or compatibility mode, use the Delegated Administrator console and command-line utility (commadmin). (In the Messaging Server 6 2004Q2 release, the Delegated Administrator utility was called User Management Utility.)
While the directory data is being migrated (while the Schema Migration Utility, commdirmig, is running), you cannot perform any provisioning tasks of any type.
Before and after the directory migration, your installation components can be in a mixed state, as described in Potential Restrictions During Migration. Constraints on provisioning depend on the relationships between the server version and configuration and the current schema level.
Provisioning Rules Before and After Schema Migration shows a matrix of the current directory schema level, the current server version and configuration, the provisioning tool you can use with each combination, and the provisioning constraints.
Table 2–1 Provisioning Constraints in a Mixed Environment
Directory Schema Level |
Server 5.x |
Server 6 - configured for Schema 1 |
Server 6 - configured for Schema 2 |
---|---|---|---|
Schema 1 |
1 For Messaging Server, use Delegated Administrator. For Calendar Server, use the Calendar Server command-line utilities. Full provisioning available. |
2 For Messaging Server, use Delegated Administrator. For Calendar Server, use the Calendar Server command-line utilities. Full provisioning available. |
3 Invalid combination for provisioning. * |
Schema 2, compatibility mode |
4 Use commadmin. Full provisioning available. |
5 Use commadmin. Full provisioning available. |
6 Invalid combination for provisioning. * |
Schema 2, native mode |
7 Invalid combination for provisioning. |
8 Use commadmin. No domain provisioning. No administrative provisioning. |
9 Use commadmin. Full provisioning available. |
* A Server 6 configured for Schema 2 will not run against a Schema 1 directory or a Schema 2, compatibility mode, directory. |
The following characteristics apply to the server-schema configurations shown in Provisioning Rules Before and After Schema Migration. They are numbered 1 - 9 for identification, not to indicate a required sequence of steps:
Configuration 1 is the beginning state of the migration.
Configuration 9 is the target state of the migration.
Configurations 2, 4, 5, and 8: These are interim states that can exist during the migration process (particularly when multiple servers are involved and you migrate one server at a time).
Configurations 3 and 6: You should never configure a server to use Schema 2 when the directory is Schema 1 or Schema 2, compatibility mode. Only configure a server to use Schema 2 after you migrate to Schema 2, native mode.
Configuration 7: Do not provision with this configuration. This state can exist temporarily during an incremental migration of multiple servers and directory domains, when some domains have been migrated to Schema 2 and others are still in Schema 1. However, you cannot use 5.x provisioning tools to provision against the Schema 2 domains.
Configurations 8: This state only works if you do not remove the DC Tree.
After you migrate the directory to Schema 2 (native mode or compatibility mode), user-developed applications and provisioning tools must use the following rules for provisioning new entries:
User entries must be underneath the people node in the Organization Tree.
Group entries must be underneath the group node in the Organization Tree.
Access Manager requires this hierarchy for provisioning user and group entries. Access Manager-based tools will not recognize users and groups provisioned under different nodes than the people node and group node, respectively.
In Schema 2, compatibility mode, a version 6 server and a 5.x server would provision using the DC Tree. In compatibility mode, the Messaging and Calendar servers continue to provision the LDAP directory exactly as they did in Schema 1.
During the migration from Schema 1 to Schema 2, compatibility mode, the inetDomainStatus attribute is copied to the organization/domain node in the Organization Tree.
In compatibility mode, two instances of inetDomainStatus exist, one in the DC Tree and one in the Organization Tree.
A 5.x server would reference inetDomainStatus in the DC Tree. A version 6 server would reference inetDomainStatus in the Organization Tree.
Access Manager-based provisioning tools such as the Delegated Administrator console and command-line utility (commadmin) ensure that the two copies of inetDomainStatus maintain the same value (active or inactive).
Your own provisioning tools (if you use any) also must ensure that the two copies of inetDomainStatus are set to the same value.
If a Calendar Server has configured separate LDAP directories for authentication and user preferences, you must run the Schema Migration Utility (commdirmig) against both directories.
To check if your Calendar Server deployment uses two different directories, examine the values for the following parameters in the Calendar Server configuration file, ics.conf:
local.authldapbasedn local.authldaphost
and
local.ugldapbasedn local.ugldaphost
If the basedn and host values for these parameters are different, Calendar Server is using two different LDAP directories.
While the Schema Migration Utility (commdirmig) is running, Messaging and Calendar servers can stay online and continue to look up user entries in the LDAP directory. (However, no provisioning should take place during the migration.)
In addition, commdirmig provides the following safety features that let you control and stage the migration:
You can migrate one domain (or selected domains) at a time.
You can perform a dry run of the migration.
By default, commdirmig operates in preview mode (performs a dry run). The commdirmig utility writes an LDIF-formatted audit file containing the changes to the directory data that would be made during an actual migration. The LDAP directory itself isn’t changed.
After the utility executes in preview mode, you can examine the LDIF audit file and review the intended changes to the directory data.
When you are satisfied that the changes are correct, you can use the ldapmodify tool to apply the LDIF entries to the LDAP directory. Or you can run commdirmig again in online mode, which directly migrates the directory data to Schema 2.
The commdirmig utility produces an undo file, which you can use to roll back the changes made to the LDAP directory.
If the migration is interrupted, you can run commdirmig again. The utility will resume the migration without changing any data that was properly migrated.
The commdirmig utility leaves the DC Tree in place.
The DC Tree is not used in Schema 2, but it does no harm to leave the deprecated DC Tree in the LDAP directory after the data has been migrated to Schema 2.
After you have completed the entire migration process, you can choose to remove the DC Tree with an LDAP command-line tool. Before you remove the DC Tree, be sure to verify that the migration was successful.
This scenario makes the following assumptions:
Your applications are running on a single-server system.
The following applications are installed on your system:
One installation of Messaging Server, or
One installation of Calendar Server, or
One installation each of Messaging Server and Calendar Server
The system does not include user-developed applications that rely on Schema 1.
Simple and straightforward migration method
The following steps outline how to migrate a single-server system directly to Schema 2, native mode:
Upgrade Messaging Server and Calendar Server from version 5.x to version 6 (if you have not already done so).
For information about upgrading Messaging Server, see Upgrading Messaging Server to Version 6
For information about upgrading Calendar Server, see Upgrading Calendar Server to Version 6
Be sure that the upgraded (version 6) servers are still configured for Schema 1.
During the server upgrade, you run the Communications Services Directory Server Setup Perl script, comm_dssetup.pl. The script asks you to specify the schema version Directory Server will use:
Specify Schema 1.
Set the comm_dssetup.pl -t option as follows: -t 1
You only need to run the comm_dssetup.pl once for each Directory Server used by the Messaging and Calendar servers, although it does no harm to run the script more than once.
For information about running comm_dssetup.pl, see Running the Directory Server Setup Script
Install Access Manager 6.1 or later.
Follow the Access Manager installation instructions in the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
Before you run the Java Enterprise System installation program, gather the information needed to install Access Manager with a provisioned directory. For details, see the Access Manager: Provisioned Directory Information in Sun Java Enterprise System 2005Q4 Installation Reference section of the Sun Java Enterprise System Installation Guide.
Part 1: Installation Configuration Information Access Manager Configuration Information Access Manager: Provisioned Directory Information
During the installation, you are asked if you want Access Manager to use an existing provisioned directory. Answer yes.
The installation program asks you to specify the following parameters associated with your directory:
Organization Object Marker Class: Object class defined for the organization in the existing provisioned directory. The default value is SunManagedOrganization.
Organization Naming Attribute: Naming attribute used to define organizations in the existing provisioned directory. The default value is o.
User Marker Object Class: Object class defined for users in the existing provisioned directory. The default value is inetorgperson.
User Naming Attribute: Naming attribute used for users in the existing provisioned directory. The default value is uid.
After you install Access Manager, configure Access Manager to operate with the existing directory. .
Follow the steps in “Chapter 4, Configuring Access Manager With an Existing Directory Server” in Sun Java System Access Manager 6 2005Q1 Migration Guide.
Do not provision your LDAP directory with Access Manager tools before you have migrated the directory to Schema 2. The Messaging and Calendar servers cannot recognize any new domain information provisioned by Access Manager tools until you perform the migration to Schema 2 and reconfigure the servers for Schema 2.
Install and configure the Communications Services Delegated Administrator console and utility (commadmin).
Use the Sun Java Enterprise System Installer to install Delegated Administrator.
After the installation, you must run the Delegated Administrator configuration program, config-commda.
For details, see Chapter 3, Configuring Delegated Administrator, in Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.
Back up the LDAP directory.
Migrate the LDAP directory from Schema 1 to Schema 2, native mode.
Use the Schema Migration utility, commdirmig, to perform the migration.
Do not provision the directory while commdirmig is running.
For information on running the commdirmig utility and on the utility options and syntax, see Chapter 3, Using the Migration Utility
Configure Messaging Server and Calendar Server to use Schema 2, native mode.
For information about reconfiguring Messaging Server, see Configuring Messaging Server for Schema 2
For information about reconfiguring Calendar Server, see Configuring Calendar Server to Use Schema 2
Stop and restart the Administration Server.
You can use the following commands:
/usr/bin/mpsadmserver stop |
/usr/bin/mpsadmserver start |
Verify that the following processes are functioning properly:
The servers are working with the migrated schema
Provisioning can take place successfully
If you wish, remove the DC Tree (the defunct Schema 1 directory elements).
Do not remove the DC Tree until you have verified that the migration was completed successfully (as described in the preceding “verify” step).
You can use an LDAP command-line tool to remove the DC Tree.
This step is optional. The DC Tree is not used in Schema 2, but it does no harm to leave the deprecated DC Tree in the LDAP directory after Schema 2 is in place.
This scenario makes the following assumptions:
Your applications are running on a single-server system.
The following applications are installed on your system:
One instance of Messaging Server, or
One instance of Calendar Server, or
One instance each of Messaging Server and Calendar Server
You are running user-developed applications (such as provisioning tools or scripts you have created at your site) that rely on Schema 1 and cannot easily be converted to use Schema 2.
While the directory is in Schema 2, compatibility mode:
User-developed applications can continue to use the LDAP directory exactly as if it were still in Schema 1.
Messaging and Calendar servers can continue to use the directory exactly as if it were Schema 1.
User-developed provisioning tools that rely on Schema 1 can only work on existing directory data.
The process is more complex than it is with a direct migration to Schema 2, native mode. The schema migration must be performed twice.
This scenario outlines how to migrate a single-server system as follows:
From Schema 1 to Schema 2, compatibility mode
From Schema 2, compatibility mode, to Schema 2, native mode
Take these steps:
Upgrade Messaging Server and Calendar Server from version 5.x to version 6 (if you have not already done so).
For information about upgrading Messaging Server, see Upgrading Messaging Server to Version 6
For information about upgrading Calendar Server, see Upgrading Calendar Server to Version 6
Be sure that the upgraded (version 6) servers are still configured for Schema 1.
During the server upgrade, you run the Communications Services Directory Server Setup Perl script, comm_dssetup.pl. The script asks you to specify the schema version Directory Server will use:
Specify Schema 1.
Set comm_dssetup.pl -t option as follows: -t 1
You only need to run the comm_dssetup.pl once for each Directory Server used by the Messaging and Calendar servers, although it does no harm to run the script more than once.
For information about running comm_dssetup.pl, see Running the Directory Server Setup Script
Install Access Manager 6.1 or later.
Follow the Access Manager installation instructions in the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
Before you run the Java Enterprise System installation program, gather the information needed to install Access Manager with a provisioned directory.
For details, see Access Manager: Provisioned Directory Information in Sun Java Enterprise System 2005Q4 Installation Reference section of the Sun Java Enterprise System Installation Guide.
During the installation, you are asked if you want Access Manager to use an existing provisioned directory. Answer yes.
The installation program asks you to specify the following parameters associated with your directory:
Organization Object Marker Class: Object class defined for the organization in the existing provisioned directory. The default value is SunManagedOrganization.
Organization Naming Attribute: Naming attribute used to define organizations in the existing provisioned directory. The default value is o.
User Marker Object Class: Object class defined for users in the existing provisioned directory. The default value is inetorgperson.
User Naming Attribute: Naming attribute used for users in the existing provisioned directory. The default value is uid.
After you install Access Manager, configure Access Manager to operate with the existing directory.
Follow the steps in “Chapter 4, Configuring Access Manager With an Existing Directory Server” in Sun Java System Access Manager 6 2005Q1 Migration Guide.
Do not provision your LDAP directory with Access Manager tools before you have migrated the directory to Schema 2. The Messaging and Calendar servers cannot recognize any new domain information provisioned by Access Manager tools until you perform the migration to Schema 2 and reconfigure the servers for Schema 2.
Install and configure the Communications Services Delegated Administrator console and utility (commadmin).
Use the Sun Java Enterprise System Installer to install Delegated Administrator.
After the installation, you must run the Delegated Administrator configuration program, config-commda.
For details, see Chapter 3, Configuring Delegated Administrator, in Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.
Back up the LDAP directory.
Migrate the LDAP directory from Schema 1 to Schema 2, compatibility mode.
Use the Schema Migration utility, commdirmig, to perform the migration.
Do not provision the directory while commdirmig is running.
For information on running commdirmig and on the utility options and syntax, see Chapter 3, Using the Migration Utility
You do not have to reconfigure the Messaging and Calendar servers to use Schema 2, compatibility mode.
When the LDAP directory has been migrated to Schema 2, compatibility mode, the servers should continue to be configured to use Schema 1.
Configure Access Manager to use Schema 2, compatibility mode by enabling Access Manager to use the DC Tree:
Start Access Manager Console as a user with administrator rights.
Click the Services Configuration tab.
Select Administration Services -> Global.
Check the box next to Enable Domain Component Tree.
Click Save.
For more information about these steps, see theSun Java System Access Manager 7 2005Q4 Administration Guide.
Check that the Access Manager configuration properties file contains the correct DC Tree root suffix by opening the Access Manager configuration properties file, AMConfig.properties. The default location of the file is /opt/SUNWam/lib.
The com.iplanet.am.domaincomponent property in the AMConfig.properties file sets the value of the DC Tree root suffix. If the value is incorrect, edit it and save the file.
Restart Access Manager.
For more information, see the Sun Java System Access Manager 7 2005Q4 Administration Guide .
Use the ldapmodify tool to add the inetdomain object class to all DC Tree nodes. (For example: dc=com,o=internet.)
Stop and restart the Administration Server.
You can use the following commands:
/usr/bin/mpsadmserver stop |
/usr/bin/mpsadmserver start |
Verify that the following processes are functioning properly:
The servers are working with the migrated schema
Provisioning can take place successfully
Upgrade your user-developed applications (in-house provisioning tools or scripts) to use Schema 2, native mode.
You do not have to perform this step (or the remaining steps). The Messaging and Calendar servers can continue to operate with Schema 2, compatibility mode, as long as your user-developed applications rely on the Schema 1 directory structure.
However, we recommend that you convert your applications to use Schema 2 at some time.
When you have converted the user-developed applications, proceed with the following steps:
Back up the LDAP directory.
Migrate the LDAP directory from Schema 2, compatibility mode to Schema 2, native mode.
Use the Schema Migration utility, commdirmig, to perform the migration.
Do not provision the directory while commdirmig is running.
For information on running commdirmig and on the utility options and syntax, see Chapter 3, Using the Migration Utility
Configure Access Manager to user Schema 2, native mode:
Start Access Manager Console as a user with administrator rights.
Click the Services Configuration tab.
Select Administration Services -> Global.
Uncheck the box next to Enable Domain Component Tree.
Click Save.
When the Enable Domain Component Tree box is not checked, Access Manager ignores the DC Tree root suffix value held in the com.iplanet.am.domaincomponent property in the AMConfig.properties file.
For more information about these steps, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.
Configure Messaging Server and Calendar Server to use Schema 2, native mode.
For more information on reconfiguring Messaging Server, see Configuring Messaging Server for Schema 2
For more information on reconfiguring Calendar Server, see Configuring Calendar Server to Use Schema 2
Stop and restart the Administration Server.
You can use the following commands:
/usr/bin/mpsadmserver stop |
/usr/bin/mpsadmserver start |
Verify that the following processes are functioning properly:
The servers are working with the migrated schema
Provisioning can take place successfully
If you wish, remove the DC Tree (the defunct Schema 1 directory elements).
Do not remove the DC Tree until you have verified that the migration was completed successfully (as described in the preceding “verify” step).
You can use an LDAP command-line tool to remove the DC Tree.
This step is optional. The DC Tree is not used in Schema 2, but it does no harm to leave the deprecated DC Tree in the LDAP directory after Schema 2 is in place.
This direct-migration scenario makes the following assumptions:
Messaging and Calendar Server are running in a two-tiered, multiple-server environment
The installation does not include user-developed applications that rely on Schema 1
Multiple Servers - Migrate Directly to Native Mode shows a simple example of a distributed environment. Two front-end servers handle incoming and outgoing traffic and three back-end servers look up entries in portions of the LDAP directory. Each back-end server manages two domains in the directory.
The entire LDAP directory is migrated in a single step.
Some downtime is required while you upgrade the servers to version 6.
The entire system can continue running while you upgrade the servers one at a time.
The following steps outline how to migrate a two-tiered, multiple-server environment directly to Schema 2, native mode:
Upgrade the Messaging Servers and Calendar Servers from version 5.x to version 6 (if you have not already done so).
In the example shown in Multiple Servers - Migrate Directly to Native Mode, upgrade the servers as follows:
Upgrade Front-end Server 1 (F1).
Upgrade Front-end Server 2 (F2).
Upgrade Back-end Server 1 (B1).
Upgrade Back-end Server 2 (B2).
Upgrade Back-end Server 2 (B3).
For information about upgrading Messaging Server, see Upgrading Messaging Server to Version 6
For information about upgrading Calendar Server, see Upgrading Calendar Server to Version 6
Be sure that the upgraded (version 6) servers are still configured for Schema 1.
During the server upgrade, you run the Communications Services Directory Server Setup Perl script, comm_dssetup.pl. The script asks you to specify the schema version Directory Server will use:
Specify Schema 1.
Set comm_dssetup.pl -t option as follows: -t 1
You only need to run the comm_dssetup.pl once for each Directory Server used by the Messaging and Calendar servers, although it does no harm to run the script more than once.
For information about running comm_dssetup.pl, see Running the Directory Server Setup Script
Install Access Manager 6.1 or later.
Follow the Access Manager installation instructions in the Access Manager: Provisioned Directory Information in Sun Java Enterprise System 2005Q4 Installation Referencesection of the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
Before you run the Java Enterprise System installation program, gather the information needed to install Access Manager with a provisioned directory.
For details, see the Access Manager: Provisioned Directory Information in Sun Java Enterprise System 2005Q4 Installation Reference section of the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX
During the installation, you are asked if you want Access Manager to use an existing provisioned directory. Answer yes.
The installation program asks you to specify the following parameters associated with your directory:
Organization Object Marker Class: Object class defined for the organization in the existing provisioned directory. The default value is SunManagedOrganization.
Organization Naming Attribute: Naming attribute used to define organizations in the existing provisioned directory. The default value is o.
User Marker Object Class: Object class defined for users in the existing provisioned directory. The default value is inetorgperson.
User Naming Attribute: Naming attribute used for users in the existing provisioned directory. The default value is uid.
After you install Access Manager, configure Access Manager to operate with the existing directory.
Follow the steps in “Chapter 4, Configuring Access Manager With an Existing Directory Server” in Sun Java System Access Manager 6 2005Q1 Migration Guide.
Do not provision your LDAP directory with Access Manager tools before you have migrated the directory to Schema 2. The Messaging and Calendar servers cannot recognize any new domain information provisioned by Access Manager tools until you perform the migration to Schema 2 and reconfigure the servers for Schema 2.
Install and configure the Communications Services Delegated Administrator console and utility (commadmin).
Use the Sun Java Enterprise System Installer to install Delegated Administrator.
After the installation, you must run the Delegated Administrator configuration program, config-commda.
For details, see Chapter Chapter 3, Configuring Delegated Administrator, in Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.
Back up the LDAP directory.
Migrate the LDAP directory from Schema 1 to Schema 2, native mode.
Use the Schema Migration utility, commdirmig, to perform the migration.
In a direct migration, you run commdirmig once to migrate the entire LDAP directory. Do not migrate individual domains.
Do not provision the directory while commdirmig is running.
For information on running the commdirmig utility and on the utility options and syntax, see Chapter 3, Using the Migration Utility
Configure the Messaging Servers and Calendar Servers to use Schema 2, native mode. In the example shown in Multiple Servers - Migrate Directly to Native Mode, configure the servers as follows:
Reconfigure Front-end Server 1 (F1).
Reconfigure Front-end Server 2 (F2).
Reconfigure Back-end Server 1 (B1).
Reconfigure Back-end Server 2 (B2).
Reconfigure Back-end Server 2 (B3).
For information about reconfiguring Messaging Server, see Configuring Messaging Server for Schema 2
For information about reconfiguring Calendar Server, see Configuring Calendar Server to Use Schema 2
Stop and restart the Administration Server.
You can use the following commands:
/usr/bin/mpsadmserver stop |
/usr/bin/mpsadmserver start |
Verify that the following processes are functioning properly:
The servers are working with the migrated schema
Provisioning can take place successfully
If you wish, remove the DC Tree (the defunct Schema 1 directory elements).
Do not remove the DC Tree until you have verified that the migration was completed successfully (as described in the preceding “verify” step).
You can use an LDAP command-line tool to remove the DC Tree.
This step is optional. The DC Tree is not used in Schema 2, but it does no harm to leave the deprecated DC Tree in the LDAP directory after Schema 2 is in place.
This incremental-migration scenario makes the following assumptions:
Messaging and Calendar Server are running in a two-tiered, multiple-server environment.
The installation does not include user-developed applications (or provisioning tools) that rely on Schema 1.
This scenario uses the sample distributed environment shown in Migration Steps
Server downtime is minimized. At any given time, most servers are running and available.
Most of the LDAP directory is available to the servers and for provisioning.
You migrate the LDAP directory in stages, selecting individual domains for migration.
The overall migration time is extended.
The migration process is somewhat more complex than that of a direct, all-at-once migration.
The scenario described in this section uses the sample distributed environment shown in Migration Steps.
In this example, each back-end server manages a unique portion of the LDAP directory, as follows:
Back-end Server 1 (B1) manages Domain 1 and 2.
Back-end Server 2 (B2) manages Domain 3 and 4.
Back-end Server 3 (B3) manages Domain 5 and 6.
This structure lends itself to incremental migration because each server can be upgraded and configured separately, and its corresponding domains can be migrated separately.
In the scenario, the migration proceeds in three stages corresponding to the three server-domain groups listed above.
The following rules apply to incremental migration of servers and LDAP directory domains:
When you migrate a domain, you also must upgrade and configure every server that manages any part of that domain.
When you upgrade and configure a server, you also must migrate every domain (or part of a domain) managed by the server.
If all the servers in your installation manage across domain boundaries (if multiple servers share access to each domain), your installation might not be a good candidate for incremental migration.
For example, suppose your installation contains two back-end servers in the following configuration:
Back-end Server 1 manages Domain 1, 2, and 3.
Back-end Server 2 manages Domain 2, 3, and 4.
This installation should migrate directly (both servers, the entire LDAP directory), not incrementally.
In a complex deployment with many back-end servers, you might still be able to migrate groups of domains incrementally. Your installation must fit the guidelines described in Rules for Incremental Migration.
A Complex Deployment Suitable for Incremental Migration shows one part of a large, complex server configuration and LDAP directory. It is assumed that the entire deployment includes many additional servers and domains not shown in the figure.
In the example shown in A Complex Deployment Suitable for Incremental Migration, Back-end servers 1, 2, and 3 manage across domain boundaries, as follows:
Back-end Server 1 manages Domain 1, 2, and 3.
Back-end Server 2 manages Domain 3, 4, and 5.
Back-end Server 3 manages Domain 4, 5, and 6.
No individual server exclusively manages a single domain.
Taken together, however, Back-end servers 1, 2, and 3 manage a unique set of domains that can be migrated incrementally.
In this example, when you run the Schema Migration Utility, you can specify Domains 1, 2, 3, 4, 5, and 6 in the migration to Schema 2. You can then reconfigure Back-end servers 1, 2, and 3 to use Schema 2.
Similarly, you could migrate and configure other groups of domains and servers that form distinct units within the deployment. In the example shown in A Complex Deployment Suitable for Incremental Migration, Back-end Server 4 and the domains it manages might be candidates for another stage in an incremental migration.
When you migrate directory domains incrementally, the front-end servers should remain configured to use Schema 1 until you have migrated the entire directory to Schema 2.
To look up user entries, the front-end servers might have to read information in any domain in the directory. The servers must be able to use the DC Tree to find user entries in the domains still in Schema 1. Once a front-end server is configured for Schema 2, it cannot recognize domain information held in the DC Tree.
After you migrate all domains to Schema 2 and reconfigure all the back-end servers to use Schema 2, you can reconfigure the front-end servers to use Schema 2.
If you must create a new domain during an incremental migration, create it in Schema 1, by using a 5.x (Schema 1) provisioning tool. Of course, the new domain must be managed by a server still configured to use Schema 1.
This rule assumes that the front-end servers are configured to use Schema 1 until the entire directory has been migrated to Schema 2. A front-end server configured for Schema 1 can look up user entries in an existing domain that was migrated to Schema 2; the front-end server uses the DC Tree, which still contains the old routing information to the user entries.
However, if you create a new domain with a Schema 2 provisioning tool, no domain information will exist in the DC Tree. The front-end server will be unable to find the new domain information in the Organization Tree and will not find the new user entries.
At some point in the migration, the new domain must be migrated to Schema 2 and its managing server(s) reconfigured to use Schema 2.
The following steps outline how to migrate a two-tiered, multiple-server deployment to Schema 2, native mode in three stages.
Migration Steps shows the sample configuration of servers and domains used in this scenario.
Upgrade Back-end Server 1 (B1) from version 5.x to version 6 (if you have not already done so).
For information about upgrading Messaging Server, see Upgrading Messaging Server to Version 6
For information about upgrading Calendar Server, see Upgrading Calendar Server to Version 6
Be sure that Server B1 is still configured for Schema 1.
During the server upgrade, you run the Communications Services Directory Server Setup Perl script, comm_dssetup.pl. The script asks you to specify the schema version Directory Server will use:
Specify Schema 1.
Set comm_dssetup.pl -t option as follows: -t 1
You only need to run the comm_dssetup.pl once for each Directory Server used by the Messaging and Calendar servers, although it does no harm to run the script more than once.
For information about running comm_dssetup.pl, see Running the Directory Server Setup Script
Install Access Manager 6.1 or later.
Follow the Access Manager installation instructions in the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX
Before you run the Java Enterprise System installation program, gather the information needed to install Access Manager with a provisioned directory.
For details, see Access Manager: Provisioned Directory Information in Sun Java Enterprise System 2005Q4 Installation Reference.
During the installation, you are asked if you want Access Manager to use an existing provisioned directory. Answer yes.
The installation program asks you to specify the following parameters associated with your directory:
Organization Object Marker Class: Object class defined for the organization in the existing provisioned directory. The default value is SunManagedOrganization.
Organization Naming Attribute: Naming attribute used to define organizations in the existing provisioned directory. The default value is o.
User Marker Object Class: Object class defined for users in the existing provisioned directory. The default value is inetorgperson.
User Naming Attribute: Naming attribute used for users in the existing provisioned directory. The default value is uid.
After you install Access Manager, configure Access Manager to operate with the existing directory.
Follow the steps in “Chapter 4, Configuring Access Manager With an Existing Directory Server” in Sun Java System Access Manager 6 2005Q1 Migration Guide.
Do not provision your LDAP directory with Access Manager tools before you have migrated the directory to Schema 2. The Messaging and Calendar servers cannot recognize any new domain information provisioned by Access Manager tools until you perform the migration to Schema 2 and reconfigure the servers for Schema 2.
Install and configure the Communications Services Delegated Administrator console and utility (commadmin).
Use the Sun Java Enterprise System Installer to install Delegated Administrator.
After the installation, you must run the Delegated Administrator configuration program, config-commda.
For details, see Chapter Chapter 3, Configuring Delegated Administrator, in Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.
Back up Domains 1 and 2 in the LDAP directory.
Migrate Domains 1 and 2 of the LDAP directory from Schema 1 to Schema 2, native mode. (Server B1 uniquely manages Domains 1 and 2.)
Use the Schema Migration utility, commdirmig, to perform the migration.
Use the -d Domain option to migrate Domains 1 and 2.
Do not provision Domains 1 and 2 while commdirmig is running. You can provision other domains in the directory.
For information on running the commdirmig utility and on the utility options and syntax, see Chapter 3, Using the Migration Utility
Do not remove the DC Tree for Domains 1 and 2 until all domains in the directory have been migrated to Schema 2, native mode, and all dependencies on the DC Tree are removed.
Reconfigure Server B1 to use Schema 2, native mode.
For information about reconfiguring Messaging Server, see Configuring Messaging Server for Schema 2
For information about reconfiguring Calendar Server, see Configuring Calendar Server to Use Schema 2
Stop and restart the Administration Server.
You can use the following commands:
/usr/bin/mpsadmserver stop |
/usr/bin/mpsadmserver start |
Verify that the following processes are functioning properly:
The upgraded server is working with the migrated domains
Provisioning can take place successfully
Repeat Migration Steps through Migration Steps for
Repeat Migration Steps through Migration Steps for:
Upgrade Front-end Server 1 (F1) and Front-end Server 2 (F2) from version 5.x to version 6 (if you have not already done so).
For information about upgrading Messaging Server, see Upgrading Messaging Server to Version 6
For information about upgrading Calendar Server, see Upgrading Calendar Server to Version 6
Run the comm_dssetup.pl script. The script asks you to specify the schema version Directory Server will use:
Specify Schema 2, native mode. Choose Schema 2 because you have already migrated all domains in the directory to Schema 2.
Set comm_dssetup.pl -t option as follows: -t 2
For information about running comm_dssetup.pl, see Running the Directory Server Setup Script
Reconfigure Server F1 and Server F2 to use Schema 2, native mode.
For information about reconfiguring Messaging Server, see Configuring Messaging Server for Schema 2
For information about reconfiguring Calendar Server, see Configuring Calendar Server to Use Schema 2
If you wish, remove the DC Tree (the defunct Schema 1 directory elements).
Do not remove the DC Tree until you have verified that the migration was completed successfully (as described in the preceding “verify” step).
You can use an LDAP command-line tool to remove the DC Tree.
This step is optional. The DC Tree is not used in Schema 2, but it does no harm to leave the deprecated DC Tree in the LDAP directory after Schema 2 is in place.
This incremental-migration scenario makes the following assumptions:
Messaging and Calendar Server are running in a two-tiered, multiple-server environment.
You are running user-developed applications (such as provisioning tools or scripts you have created at your site) that rely on Schema 1 and that cannot be converted immediately to use Schema 2
This scenario uses the sample distributed environment shown in Migration Steps
Server downtime is minimized. At any given time, most servers are running and available.
Most of the LDAP directory is available to the servers and for provisioning.
You migrate the LDAP directory in stages, selecting individual domains for migration.
The overall migration time is extended.
While the directory is in Schema 2, compatibility mode:
User-developed applications can continue to use the LDAP directory exactly as if it were still in Schema 1.
Messaging and Calendar servers can continue to use the directory exactly as if it were Schema 1.
User-developed provisioning tools that rely on Schema 1 can only work on existing directory data.
This migration process is the most complex of the scenarios; it is more complex than a direct migration to Schema 2, native mode, or an incremental migration to native mode. The schema migration must be performed twice.
For a discussion of the conditions best suited for migrating your installation incrementally, see Deployments Suitable for Incremental Migration.
The following steps outline how to migrate a two-tiered, multiple-server environment to Schema 2, native mode in stages.
Upgrade Back-end Server 1 (B1) from version 5.x to version 6 (if you have not already done so). Server B1 is shown in the example in Migration Steps.
For information about upgrading Messaging Server, see Upgrading Messaging Server to Version 6
For information about upgrading Calendar Server, see Upgrading Calendar Server to Version 6
Be sure that Server B1 is still configured for Schema 1.
During the server upgrade, you run the Communications Services Directory Server Setup Perl script, comm_dssetup.pl. The script asks you to specify the schema version Directory Server will use:
Specify Schema 1.
Set comm_dssetup.pl -t option as follows: -t 1
You only need to run the comm_dssetup.pl once for each Directory Server used by the Messaging and Calendar servers, although it does no harm to run the script more than once.
For information about running comm_dssetup.pl, see Running the Directory Server Setup Script
Install Access Manager 6.1 or later.
Follow the Access Manager installation instructions in the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
Before you run the Java Enterprise System installation program, gather the information needed to install Access Manager with a provisioned directory.
For details, see theAccess Manager: Provisioned Directory Information in Sun Java Enterprise System 2005Q4 Installation Reference.
During the installation, you are asked if you want Access Manager to use an existing provisioned directory. Answer yes.
The installation program asks you to specify the following parameters associated with your directory:
Organization Object Marker Class: Object class defined for the organization in the existing provisioned directory. The default value is SunManagedOrganization.
Organization Naming Attribute: Naming attribute used to define organizations in the existing provisioned directory. The default value is o.
User Marker Object Class: Object class defined for users in the existing provisioned directory. The default value is inetorgperson.
User Naming Attribute: Naming attribute used for users in the existing provisioned directory. The default value is uid.
After you install Access Manager, configure Access Manager to operate with the existing directory.
Follow the steps in “Chapter 4, Configuring Access Manager With an Existing Directory Server” in Sun Java System Access Manager 6 2005Q1 Migration Guide.
Do not provision your LDAP directory with Access Manager tools before you have migrated the directory to Schema 2. The Messaging and Calendar servers cannot recognize any new domain information provisioned by Access Manager tools until you perform the migration to Schema 2 and reconfigure the servers for Schema 2.
Install and configure the Communications Services Delegated Administrator console and utility (commadmin).
Use the Sun Java Enterprise System Installer to install Delegated Administrator.
After the installation, you must run the Delegated Administrator configuration program, config-commda.
For details, see Chapter Chapter 3, Configuring Delegated Administrator, in Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.
Back up Domains 1 and 2 in the LDAP directory.
Migrate Domains 1 and 2 of the LDAP directory from Schema 1 to Schema 2, compatibility mode. (Server B1 uniquely manages Domains 1 and 2.)
Use the Schema Migration utility, commdirmig, to perform the migration.
Use the -d Domain option to migrate Domains 1 and 2.
Do not provision Domains 1 and 2 while commdirmig is running. You can provision other domains in the directory.
For information on running the commdirmig utility and on the utility options and syntax, see Chapter 3, Using the Migration Utility.
You do not have to reconfigure the Messaging and Calendar servers to use Schema 2, compatibility mode.
When the LDAP directory has been migrated to Schema 2, compatibility mode, the servers should continue to be configured to use Schema 1.
Configure Access Manager to use Schema 2, compatibility mode by enabling Access Manager to use the DC Tree:
Start Access Manager Console as a user with administrator rights.
Click the Services Configuration tab.
Select Administration Services -> Global.
Check the box next to Enable Domain Component Tree.
Click Save.
For more information about these steps, see the Sun Java System Access Manager 7 2005Q4 Administration Guide
C check that the Access Manager configuration properties file contains the correct DC Tree root suffix value by opening the configuration properties file, AMConfig.properties. The default location of the file is /opt/SUNWam/lib
The com.iplanet.am.domaincomponent property in the AMConfig.properties file sets the value of the DC Tree root suffix. If the value is incorrect, edit it and save the file.
Restart Access Manager
For more information, see the Sun Java System Access Manager 7 2005Q4 Administration Guide
Use the ldapmodify tool to add the inetdomain object class to all DC Tree nodes. (For example: dc=com,o=internet.)
Stop and restart the Administration Server.
You can use the following commands:
/usr/bin/mpsadmserver stop |
/usr/bin/mpsadmserver start |
Verify that the following processes are functioning properly:
The upgraded server is working with the migrated domains
Provisioning can take place successfully
Repeat Migration Steps through Migration Steps for:
Server B2
Domains 3 and 4 in the LDAP directory
Repeat Migration Steps through Step Migration Steps for:
Server B3
Domains 5 and 6 in the LDAP directory
Upgrade Front-end Server 1 (F1) and Front-end Server 2 (F2) from version 5.x to version 6 (if you have not already done so).
For information about upgrading Messaging Server, see Upgrading Messaging Server to Version 6
For information about upgrading Calendar Server, see Upgrading Calendar Server to Version 6
Run the comm_dssetup.pl script. The script asks you to specify the schema version Directory Server will use:
Specify Schema 2, compatibility mode. (You do this because you have already migrated all domains in the directory to Schema 2, compatibility mode.)
Set comm_dssetup.pl -t option as follows: -t 1.5
For information about running comm_dssetup.pl, see Running the Directory Server Setup Script
Upgrade your user-developed applications (in-house provisioning tools or scripts) to use Schema 2, native mode.
You do not have to perform this step (or the remaining steps). The Messaging and Calendar servers can continue to operate with Schema 2, compatibility mode, as long as your user-developed applications rely on the Schema 1 directory structure.
However, we recommend that you convert your applications to use Schema 2 at some time.
When you have converted the user-developed applications, proceed with the following steps:
Back up Domains 1 and 2 in the LDAP directory.
Migrate Domains 1 and 2 from Schema 2, compatibility mode, to Schema 2, native mode.
Use the Schema Migration utility, commdirmig, to perform the migration.
Use the -d Domain option to migrate Domains 1 and 2.
Do not provision Domains 1 and 2 while commdirmig is running. You can provision other domains in the directory.
For information on running commdirmig and on the utility options and syntax, see Chapter 3, Using the Migration Utility
Do not remove the DC Tree for Domains 1 and 2 until all domains in the directory have been migrated to Schema 2, native mode, and all dependencies on the DC Tree are removed.
Configure Access Manager to user Schema 2, native mode:
Start Access Manager Console as a user with administrator rights.
Click the Services Configuration tab.
Select Administration Services -> Global.
Uncheck the box next to Enable Domain Component Tree.
Click Save.
When the Enable Domain Component Tree box is not checked, Access Manager ignores the DC Tree root suffix value held in the com.iplanet.am.domaincomponent property in the AMConfig.properties file.
For more information about these steps, see the Sun Java System Access Manager 7 2005Q4 Administration Guide .
Once you enable Access Manager to use Schema 2, native mode, you can only provision in the domains that have been migrated to Schema 2, native mode. Do not provision new entries in the domains that are still in Schema 2, compatibility mode.
Reconfigure Server B1 to use Schema 2, native mode.
For information about reconfiguring Messaging Server, see Configuring Messaging Server for Schema 2
For information about reconfiguring Calendar Server, see Configuring Calendar Server to Use Schema 2
Stop and restart the Administration Server.
You can use the following commands:
/usr/bin/mpsadmserver stop |
/usr/bin/mpsadmserver start |
Verify that the following processes are functioning properly:
The reconfigured server is working with the migrated domains
Provisioning can take place successfully
Repeat Migration Steps through Migration Steps for:
Server B2
Domains 3 and 4 in the LDAP directory
Repeat Migration Steps through Migration Steps for:
Server B3
Domains 5 and 6 in the LDAP directory
Reconfigure Server F1 and Server F2 to use Schema 2, native mode.
For information about reconfiguring Messaging Server, see Configuring Messaging Server for Schema 2
For information about reconfiguring Calendar Server, see Configuring Calendar Server to Use Schema 2
If you wish, remove the DC Tree (the defunct Schema 1 directory elements).
Do not remove the DC Tree until you have verified that the migration was completed successfully (as described in the preceding “verify” step).
You can use an LDAP command-line tool to remove the DC Tree.
This step is optional. The DC Tree is not used in Schema 2, but it does no harm to leave the deprecated DC Tree in the LDAP directory after Schema 2 is in place.