Sun Java System Portal Server 6 2004Q2 Migration Guide |
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.
This chapter contains the following sections:
Overview of Data MigrationSeveral 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.
- 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.
Figure 1-1 Overview of Migration Process
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 ProcessThis 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
The export tool performs the following tasks:
- 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
The conversion tool performs the following tasks:
- 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
The import tool performs the following tasks:
- 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
Use the following information to help plan 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 OverviewThis 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
The 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
The export tool runs the modules based on user selection.
- 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.
Files are considered export modules when they meet the following criteria:
LDAP Database Export Module
The LDAP database export module:
Flat File Export Module
The flat file export module creates a tar file that contains:
Certificate Export Module
The certificate export module copies:
Conversion Tool
The 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.
- 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 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.
The conversion tool runs the modules based on user selection.
- 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.
Files are considered conversion modules when they meet the following criteria:
LDAP Database Conversion Module
The 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
The gateway rules to Rewriter rulesets conversion module:
- 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
The 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
The 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.
- 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 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.
The import tool runs the modules based on user selection.
- 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.
Files are considered import modules when they meet the following criteria:
LDAP Database Import Module
The LDAP database import tool 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:
Certificate Import Module
The certificate import module:
- Copies the web server certificate database, if it exists, to the appropriate location. It does not copy the gateway certificate database.
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.