Chapter 1 Planning the Migration

This chapter provides an overview and discussion on how to plan for converting users, roles, domains, components, templates, providers, channels, properties files, and packs from Sun ONE Portal Server 3.0 to Sun™ ONE Portal Server 6.2.


Note	All instances of the Sun™ ONE Portal Server 3.0 product refer to what were formerly known as the iPlanet™ Portal Server 3.0, Service Pack 3a, iPlanet™ Portal Server 3.0, Service Pack 4 products, and iPlanet™ Portal Server 3.0, Service Pack 5 products. Also, all instances of the Sun™ ONE Identity Server 5.1 product refer to what was formerly known as the iPlanet™ Directory Server Access Management Edition 5.1 product.

Overview of Data Migration

Several features in Sun ONE Portal Server 6.2 product require format changes in the data store of Sun ONE Portal Server 3.0 because the Sun ONE Portal Server 6.2 software uses new access layer and APIs provided by Sun ONE Identity Server 6.1 release. The Sun ONE Portal Server 3.0 Data Migration Tool Suite provided with Sun ONE Portal Server 6.2 release enables you to migrate your LDAP data, templates, JavaServer Pages™ (JSP™), resource bundles, certificates (with the exception of gateway certificates), authentication module data, and properties files fromSun ONE Portal Server 3.0 to Sun ONE Portal Server 6.2 or to Sun ONE Identity Server as necessary. The Sun ONE Portal Server 3.0 Data Migration Tool Suite does not migrate gateway certificates.

These are the high-level steps to migrate your data from Sun ONE Portal Server 3.0 to Sun ONE Portal Server 6.2. (Subsequent chapters provide step-by-step instructions for performing the actual migration.)

Perform a full installation of Sun ONE Portal Server 6.2 including the Sun ONE Portal Server 3.0 Data Migration Tool Suite.



Note	The Sun ONE Portal Server 6.2 product supports migration of a Sun ONE Portal Server 3.0 installation to a Sun ONE Portal Server 6.2 installation deployed on a the Sun™ ONE Web Server (which uses the Java™ 2 SDK (J2SDK™), Standard Edition 1.4.1_05 for its Java™ run-time environment) as well as Sun™ ONE Application Server, IBM Websphere application server, and BEA Weblogic application server.

Install the Sun ONE Portal Server 3.0 Data Migration Tool Suite on a system that has an existing version of Sun ONE Portal Server 3.0 already installed.

If you are migrating from a Sun ONE Portal Server 3.0 system to a separateSun ONE Portal Server 6.2 system, you need two installations of the Sun ONE Portal Server 3.0 Data Migration Tool Suite, one for each system.

If you are performing a single-system migration, you can install Sun ONE Portal Server 6.2 on a Sun ONE Portal Server 3.0 system.

Install the Sun™ ONE Compass Server migration tools if you need to migrate a Sun ONE Compass Server. Sun ONE Compass Server migration tools are separate from the Sun ONE Portal Server 3.0 Data Migration Tool Suite. See Chapter 8, "Migrating Sun™ ONE Compass Server" for details on migrating Sun™ ONE Compass Server 3.01C, Service Pack 1 or later to Sun ONE Portal Server 6.2.

Run the export tool on the Sun ONE Portal Server 3.0 system. This script stores the existingSun ONE Portal Server 3.0 data to the file system. This data collection is an automated process.

Move the exported data from the Sun ONE Portal Server 3.0 system to the Sun ONE Portal Server 6.2 system if you are using two separate machines.

Run the conversion tool on the Sun ONE Portal Server 6.2 system. This script modifies the Sun ONE Portal Server 3.0 data exported using the export tool so that the data is usable by Sun ONE Portal Server 6.2. This process might require manual intervention since there is no way to know all possible customizations and their desired effect by the portal server that you have envisioned.

Run the import tool on theSun ONE Portal Server 6.2 system. This script imports the data which was exported and converted using the export and conversion tools. This process is automated requiring little to no intervention.



Note	You can add functionality to the core tools by writing your own custom migration module and installing it into the migration tool suite. The migration tools will detect the modules and update user menu options as needed. See Appendix B, "Sun ONE Portal Server 3.0 Data Migration Module Author's Guide" for more information on migration modules.

Figure 1-1 provides an overview of the migration process. It shows that the export tools take data from iPlanet Directory Server 4.1x and templates, JSPs, and resource bundles from Sun ONE Portal Server 3.0 and store them as a flat file representation of theSun ONE Portal Server 3.0 system. The conversion tools convert the flat file representation of Sun ONE Portal Server 3.0 into a flat file representation of Sun ONE Portal Server 6.2 customizations. The import tools then import LDAP data into Sun ONE Identity Server, and the templates, JSPs, and resource bundles into Sun ONE Portal Server 6.2.

Throughout the migration process, the tools produce a report listing actions taken or not taken, along with warnings and errors. You can use this report to troubleshoot the migration.

The Migration Process

This section describes how the migration process works and outlines what you need to know before beginning the migration process

How the Migration Process Works

You migrate a system by using three command-line scripts, or tools: the export tool, the conversion tool, and the import tool. This section describes how these tools work. See Appendix A, "Tool Design" for the syntax of these scripts.

Export Tool

Retrieves and stores to the export directory all component, domain, role, and user data used by the Sun ONE Portal Server 3.0 system.

Adds all templates and JSPs from the /etc/opt/SUNWips/desktop directories on the Sun ONE Portal Server 3.0 system to the template export tar file in the export directory.

Adds new or modified authentication templates from the /etc/opt/SUNWips/auth directory on the Sun ONE Portal Server 3.0 system to the template export tar file in the export directory.

Copies resource bundles from the /BaseDir/SUNWips/locale directory on the Sun ONE Portal Server 3.0 system to the template export tar file in the export directory.

Adds contents of the web server document root from the /BaseDir/SUNWips/public_html directory, except certain files specific to the Sun ONE Portal Server 3.0 installation, to the template export tar file in the export directory.

Saves web server certificates to the export directory. The migration tools do not migrate gateway certificates.

Runs commands as required by external modules.

Conversion Tool

Converts Sun ONE Portal Server 3.0 components to Sun ONE Identity Server services.

Converts Sun ONE Portal Server 3.0 domains to Sun ONE Identity Server organizations.

Converts Sun ONE Portal Server 3.0 roles to Sun ONE Identity Server suborganizations. You have the option to choose the default of suborganizations or flat role structure when migrating Sun ONE Portal Server 3.0 roles.

Converts Sun ONE Portal Server 3.0 users to Sun ONE Identity Server users.

Converts Desktop, provider, and channel customizations to display profile XML fragments.

Converts gateway rules to Rewriter rulesets.

Bundles any gateway rules not in Sun ONE Portal Server 6.2 into a custom ruleset.

Translates tags and URLs in Desktop templates.

Translates tags, URLs, and function calls deprecated by theSun ONE Portal Server 6.2 JSP implementation in JSP files.

Translates SRC values in HTML files from web server documents.

Removes the title and description from resource bundles.

Lists custom Desktop code in the migration report.

Lists custom provider definitions in the migration report to state that you need to recompile the code.

Copies certificate databases, with the exception of gateway certificates, to the import directory.

Converts other data using external modules.

Import Tool

Imports all converted service, organization, role, and user data into Sun ONE Identity Server.

Copies converted Desktop templates to the /etc/opt/SUNWps/desktop directory on the Sun ONE Portal Server 6.2 system.

Copies converted resource bundles to BaseDir/SUNWps/web-src/WEB-INF/classes on the Sun ONE Portal Server 6.2 system.

Copies certificate databases, with the exception of gateway certificates, to the proper location on theSun ONE Portal Server 6.2 system.

Imports other data using external modules.

Redeploys the web application at the completion of the import process.

What You Need to Know Before Beginning the Migration Process

All data to be migrated by the migration tools, including templates, JSPs, and resource bundles reside on a Sun ONE Portal Server 3.0 system. LDAP data may reside either on the Sun ONE Portal Server 3.0 system or on an external system.

All data to be migrated by these tools will be converted to work with Sun ONE Portal Server 6.2 on Sun ONE Identity Server.

Sun ONE Portal Server 6.2 provides only command-line migration tools. There is no graphical interface for these tools.

Sun ONE Portal Server 6.2 can install everything, including the migration tools. The installation will provide you with a menu so you can choose what you need.

You will need to perform additional manual steps for custom providers and templates prior to using them in Sun ONE Portal Server 6.2.

If the Sun ONE Portal Server 6.2 machine name is different from the Sun ONE Portal Server 3.0 machine name, certificates will need to be reissued.

Sun ONE Portal Server 6.2 now includes the Sun ONE Compass Server functionality as a core search engine. Therefore, do not install Sun ONE Compass Server on the Sun ONE Portal Server 6.2 node. Sun ONE Portal Server 6.2 refers to the functionality of Sun ONE Compass Server as Search or Search Engine.

There is a minimum free disk space requirement of 500 MB. This requirement is for the export and conversion tools.

Only migration from Sun ONE Portal Server 3.0 to Sun ONE Portal Server 6.2 as described in this guide is supported.

Sun ONE Portal Server 3.0 must be unavailable during migration. If the Sun ONE Portal Server 3.0 system is in production during migration, after you run the export tool any updates to the data will not be migrated.

For single-system migration, you must use different port numbers for the Sun ONE Portal Server 6.2 instance from the port numbers used for the Sun ONE Portal Server 3.0 instance.

The migration tools export symbolic links from the Sun ONE Portal Server 3.0 system and preserve them during the migration to the Sun ONE Portal Server 6.2 system. The tools do not, however, migrate the contents of the symlink target to the Sun ONE Portal Server 6.2 system. You must manually copy or move the contents of the symlink target to the Sun ONE Portal Server 6.2 system.

Migration Checklist

Will you migrate from one system to another? Or will you perform a single-system migration?

Are there customizations to the Desktop templates that you need to migrate?

Is there any custom provider code? If so, this will need to be compiled and added manually.

Are there customizations to the authentication modules that you need to migrate?

Is the name of the Sun ONE Portal Server 6.2 system the same as the name of the Sun ONE Portal Server 3.0 system from which you are migrating? If not, you need new certificates.

Do you have test systems set up for the migration that you can put into production after the migration is complete in order to avoid down time?

When will the migration begin?

When do you expect the migration to finish?

How many domains are you migrating?

How many users are you migrating?

How many roles are you migrating? What is this impact on your migrating given the new role concept in Sun ONE Identity Server?

How many customized providers do you need to migrate manually to the new provider APIs (PAPI)?

Do you have a multi-node environment that requires additional planning for migration?

Do you have an existing installation of Sun ONE Compass Server that requires migration?

What other manual steps do you need to perform for successful migration (outside of the automated steps via the migration tools available)?

Migration Tools Overview

This section describes how the individual migration tools work and the options you have for migrating data. The migration package is SUNWpsmig and you need to install it on both the Sun ONE Portal Server 3.0 and Sun ONE Portal Server 6.2 systems.

Export Tool

Prompts the user for a directory where the tool saves all exported data.

Verifies that adequate disk space is available.

Verifies that Sun ONE Portal Server 3.0 is installed on the system.

Creates the directories where the tool stores the exported Sun ONE Portal Server 3.0 data.

Uses Sun ONE Portal Server 3.0 package information and system configuration files to find variables to be used for exporting data.

Exports all variables.

Searches for modules.

Displays the menu for user selection if needed.

Export Tool Modules

The export tool uses modules to create the script menus. This modularity enables you to create new modules and add them to the menu. The export tool creates the executable files. The export tool also creates the export menu from the text returned from invoking each module with the --menu option.

Menu order is dependant on the first two digits of the module file name in ascending numerical order. 00 is the first possible menu item, 99 the last. In the case where two or more items share the same number, the menu for those items is in ascending alphabetical order based on filename.

The export tool does not add a menu item for those modules that return no text. These modules are considered “run-always.”

The export tool adds a menu item for All of the above at the end of the module menu.

The export tool adds a menu item for Exit as the final option

Run order is dependant on the first two digits of the module file name in ascending numerical order. The module whose file name begins with 00 is the first module executed. The module whose file name begins with 99 is the last module executed. In the case where two or more module file names share the same number, the export tool executes these modules in ascending alphabetical order.

The export tool runs any modules that do not return a menu item along with a single module user selection.

They exist under the installed migration directory /modules.

They end with the text “export.”

They are executable.

They have the digits 0-9 as the first two characters of module file name.

They return a single line of text or nothing when invoked with the --menu option.

LDAP Database Export Module

Alerts you to the fact that the LDAP database tool ldapsearch is required to export the LDAP database if ldapsearch does not exist on the system.

Saves the LDIF representation of the database.

Uses ipsadmin to export XML files for domains, roles, and components.

Flat File Export Module

Desktop templates

Resource bundles

Web server root documents

Modified and new authentication templates

Certificate Export Module

The web server certificate database, if it exists, to the export directory. The certificate export module does not copy gateway certificates.

Conversion Tool

Prompts for the location of the exported data and verifies that it contains the results of a successful export of Sun ONE Portal Server 3.0 data.

Prompts for theSun ONE Identity Server Internal LDAP Authentication password.

Prompts for an import directory where the tool saves all converted data.

Verifies that adequate disk space is available in the import directory.

Creates the directories to store the converted Sun ONE Portal Server 3.0 data.

Verifies that a proper installation of Sun ONE Portal Server 6.2 exists on the system.

Converts all variables.

Searches for modules.

Displays the menu for user selection if needed.

Conversion Tool Modules

The conversion tool uses modules to create the script menus. This modularity enables you to create new modules and add them to the menu. The conversion tool creates the executable files. The conversion tool also creates the export menu from the text returned from invoking each module with the --menu option.

The conversion tool does not add a menu item for those modules that return no text. These modules are considered “run-always.”

The conversion tool adds a menu item for All of the above at the end of the module menu.

The conversion tool adds a menu item for Exit as the final option.

Run order is dependant on the first two digits of the module file name in ascending numerical order. The module whose file name begins with 00 is the first module executed. The module whose file name begins with 99 is the last module executed. In the case where two or more module file names share the same number, the conversion tool executes these modules in ascending alphabetical order.

The conversion tool runs any modules that do not return a menu item along with a single module user selection.

They exist under the installed migration directory /modules.

They end with the text “convert.”

They are executable.

They have the digits 0-9 as the first two characters of module file name.

They return a single line of text or nothing when invoked with the --menu option.

LDAP Database Conversion Module

Converts all domain data from the Sun ONE Portal Server 3.0 system into organizations for Sun ONE Portal Server 6.2. The tool creates organization XML files for importing using the amadmin program.

Converts all role data from Sun ONE Portal Server 3.0 into suborganizations or roles for Sun ONE Portal Server 6.2. The tool creates organization XML files for importing using the amadmin program.

Converts all user data from the Sun ONE Portal Server 3.0 system into users for Sun ONE Portal Server 6.2. The tool creates an LDIF file for importing into the Sun ONE Identity Server instance.

Converts provider and channel entries from the exported LDAP database data into display profile fragments and stores them in the import directory.

Saves component entries in the appropriate service file.

Saves domain entries in the appropriate organization file.

Saves role entries in the appropriate role file.

Saves user entries in the appropriate user file.

Checks each provider and channel component for a Sun ONE Portal Server 6.2 equivalent.

Checks attributes of providers and channels to determine customization.

Checks each className for a Sun ONE Portal Server 6.2 equivalent and notes in the migration report each custom className.

Creates service definition files based on known component translations.

Places in the migration report a list of components that appear to be imported for a customer application.

Gateway Rules to Rewriter Rulesets Conversion Module


Note	Any special use of domains, roles, and users might require manual conversion.

Places any rules not defined as part of the default Sun ONE Portal Server 6.2 ruleset in a new “custom” ruleset.

Creates a file to reflect this new “custom” ruleset in the import directory.

Updates the rulesets for channels that use URLScraper or XMLprovider based on Rewriter migration. The module also notes in the migration report that any channels that use or extend these classes should have their rulesets updated.

Desktop Conversion Module

Extracts the flat file tar file into a temporary directory. All operations described here pull templates from this temporary directory and place changes in another temporary directory for archiving after all conversion is complete.

Copies all files from the temporary export directory to the temporary import directory, preserving ownership and permissions whenever possible.

Scans templates for invalid tags. The module notes these templates in the migration report. If the template is used by a provider that has a Sun ONE Portal Server 6.2 equivalent, the module notes this fact so that you can check for customization you may have made to the templates.

Converts Sun ONE Portal Server 3.0 tags to Sun ONE Portal Server 6.2 tags for all files in the desktop directory. The module notes modifications to templates in the migration report.

Changes file names from .html to .template for all files in the desktop directory.

Changes DesktopServlet URLs to the Desktop servlet name defined by the Sun ONE Portal Server 6.2 installation for all files in the desktop directory.

Changes links to static content in the URL defined by the Sun ONE Portal Server 6.2 installation for all files in the desktop directory.

Removes deprecated APIs from JSPs within the desktop directory. The module notes modifications to JSPs in the migration report.

Changes links to static content within .html files in the web server document directory.

Copies each resource bundle from the export directory to the import directory.

Creates a tar file from the temporary import directory and places it in the import directory.

Certificate Conversion Module

The certificate conversion module copies web server certificates from the export directory to the import directory. It does not copy gateway certificates.

Import Tool

Prompts for the directory containing all converted data.

Prompts for theSun ONE Identity Server Internal LDAP Authentication password.

Verifies that a proper installation of Sun ONE Portal Server 6.2 exists on the system.

Exports all variables.

Searches for modules.

Displays the menu for user selection if needed.

Deploys the data.

Import Tool Modules

The import tool uses modules to create the script menus. This modularity enables you to create new modules and add them to the menu. The import tool creates the executable files. The import tool also creates the export menu from the text returned from invoking each module with the --menu option.

The import tool does not add a menu item for those modules that return no text. These modules are considered “run-always.”

The import tool adds a menu item for All of the above at the end of the module menu.

The import tool adds a menu item for Exit as the final option.

Run order is dependant on the first two digits of the module file name in ascending numerical order. The module whose file name begins with 00 is the first module executed. The module whose file name begins with 99 is the last module executed. In the case where two or more module file names share the same number, the import tool executes these modules in ascending alphabetical order.

The import tool runs any modules that do not return a menu item along with a single module user selection.

They exist under the installed migration directory /modules.

They end with the text “import”

They are executable.

They have the digits 0-9 as the first two characters of the module file name.

They return a single line of text or nothing when invoked with the --menu option.

LDAP Database Import Module

Looks for a configuration file to find a Sun ONE Identity Server installation.

Alerts you to the fact that you must run the tool on the node running Sun ONE Identity Server if a Sun ONE Identity Server does not exist on the node. The files in the import directory can be used on any Sun ONE Identity Server node.

Uploads customizations into the Sun ONE Identity Server node.

Flat Files Import Module

The flat file import module extracts the following from the import tar file to the appropriate locations:

Desktop templates

Resource bundles

Web server root documents

Modified and new authentication templates

Certificate Import Module

Copies the web server certificate database, if it exists, to the appropriate location. It does not copy the gateway certificate database.



Note	The import directory must have read and write permissions. Without write permissions, the import tool will exit when trying to create the log files. Without read permissions, the import script will be unable to read all the directory contents and there will be errors throughout the import process. You need to be logged in as root when importing data from a local directory or ensure that the machine that is remotely mounted recognizes the user as root. If you are not concerned about security, you may open read permission recursively on the import directory by doing the following. chmod -R a+r ImportDir

Table 1-1 shows the destination of migrated data on the Sun ONE Portal Server 6.2 system. This two-column table lists the data types in the first column and the destination directory in Sun ONE Portal Server 6.2.

Table 1-1 Destination of Migrated Data on the Sun ONE Portal Server 6.2 System
Data Type	Destination Directory in Sun ONE Portal Server 6.2
Desktop data	/etc/opt/SUNWps/desktop
Resource bundles	BaseDir/SUNWps/web-src/WEB-INF/ classes
Sun ONE Portal Server 3.0 user documents from BaseDir/SUNWips/public_html/docs	BaseDir/SUNWps/web-src/docs
Static web data	BaseDir/SUNWam/public_html

Previous Contents Index Next
Sun Java System Portal Server 6 2004Q2 Migration Guide