Sun ONE logo     Previous     Contents     Index     Next     
Sun ONE Portal Server 6.0 Migration Guide



Chapter 1   Planning the Migration



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 and iPlanet™ Portal Server 3.0, Service Pack 4 products.


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

This chapter contains the following sections:

Overview of Data Migration

Several new features in Sun ONE Portal Server 6.0 require format changes in the data store of Sun ONE Portal Server 3.0 because of the new access layer and APIs that Sun ONE Portal Server 6.0 uses: iPlanet™ Directory Server Access Management Edition 5.1. The Sun ONE Portal Server 3.0 Data Migration Tool Suite provided with Sun ONE Portal Server 6.0 enables you to migrate your LDAP data, templates, JavaServer Pages™ (JSP™), resource bundles, certificates (with the exception of gateway certificates), custom authentication module data, and properties files from Sun ONE Portal Server 3.0 to Sun ONE Portal Server 6.0 or to iPlanet Directory Server Access Management Edition 5.1 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.0. (Subsequent chapters provide step-by-step instructions for performing the actual migration.)

  1. You need to perform a full installation of Sun ONE Portal Server 6.0 including the Sun ONE Portal Server 3.0 Data Migration Tool Suite.

  2. You need to 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 separate Sun ONE Portal Server 6.0 system, you need two installations of the Sun ONE Portal Server 3.0 Data Migration Tool Suite, one for each system.

  3. You can install Sun ONE Portal Server 6.0 on a Sun ONE Portal Server 3.0 system for single-system migration.

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

  5. If you have a multi-instance setup in Sun ONE Portal Server 3.0, see the Sun ONE Portal Server 6.0 Installation Guide for UNIX for information on multi-instance setup of Sun ONE Portal Server 6.0.

  6. You need to run the export tool on the Sun ONE Portal Server 3.0 system. This script stores the existing Sun ONE Portal Server 3.0 data to the file system. This data collection is an automated process.

  7. You need to move the exported data from the Sun ONE Portal Server 3.0 system to the Sun ONE Portal Server 6.0 system if you are using two separate machines.

  8. You need to run the conversion tool on the Sun ONE Portal Server 6.0 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.0. 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.

  9. You need to run the import tool on the Sun ONE Portal Server 6.0 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.

  10. You can add functionality to the core tools by writing your own custom migration module and installing it into the migration tool suite proper. 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 the Sun 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.0 customizations. The import tools then import LDAP data into iPlanet Directory Server Access Management Edition 5.1, and the templates, JSPs, and resource bundles into Sun ONE Portal Server 6.0.

Figure 1-1    Overview of Migration Process


This image shows a graphical representation of the migration process as described in the paragraph preceding the image.

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

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 to the export directory.

  • 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 iPlanet Directory Server Access Management Edition 5.1 services.

  • Converts Sun ONE Portal Server 3.0 domains to iPlanet Directory Server Access Management Edition 5.1 organizations.

  • Converts Sun ONE Portal Server 3.0 roles to iPlanet Directory Server Access Management Edition 5.1 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 iPlanet Directory Server Access Management Edition 5.1 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.0 into a custom ruleset.

  • Translates tags and URLs in Desktop templates.

  • Translates tags, URLs, and function calls deprecated by the Sun ONE Portal Server 6.0 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 iPlanet Directory Server Access Management Edition 5.1.

  • Copies converted authentication templates to the BaseDir/SUNWam/web-apps/services/WEB-INF/config/auth/default directory on the Sun ONE Portal Server 6.0 system.

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

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

  • Copies certificate databases, with the exception of gateway certificates, to the proper location on the Sun ONE Portal Server 6.0 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.0 on iPlanet Directory Server Access Management Edition 5.1.

  • Sun ONE Portal Server 6.0 provides only command-line migration tools. There is no graphical interface to these tools.

  • Sun ONE Portal Server 6.0 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.0.

  • If the Sun ONE Portal Server 6.0 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.0 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.0 node. Sun ONE Portal Server 6.0 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.0 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.0 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.0 system. The tools do not, however, migrate the contents of the symlink target to the Sun ONE Portal Server 6.0 system. You must manually copy or move the contents of the symlink target to the Sun ONE Portal Server 6.0 system.

Migration Checklist

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

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

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

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

  5. Is the name of the Sun ONE Portal Server 6.0 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.

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

  7. When will the migration begin?

  8. When do you expect the migration to finish?

  9. How many domains are you migrating?

  10. How many users are you migrating?

  11. How many roles are you migrating? What is this impact on your migrating given the new role concept in iPlanet Directory Server Access Management Edition 5.1?

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

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

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

  15. 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.0 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:

  • 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

The 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

The flat file export module creates a tar file that contains:

  • Desktop templates

  • Resource bundles

  • Web server root documents

  • Modified and new authentication templates

Certificate Export Module

The certificate export module copies:

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

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

  • 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

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.0. 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.0. 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.0. The tool creates an LDIF file for importing into the iPlanet Directory Server Access Management Edition 5.1 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.0 equivalent.

    A list of all providers and channels is available in the Sun ONE Portal Server 3.0 attribute iwtDesktop-allProviders. The values have the format providerName|className.

    A provider is the first providerName for a unique className.A channel is the second and later to use a unique className.

  • Checks attributes of providers and channels to determine customization.

  • Checks each className for a Sun ONE Portal Server 6.0 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.

    Included in this report are components that have not been identified as a provider, channel, or authentication module in addition to iwtGateway, iwtDesktop, iwtNetlet, and iwtNetfile components.


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


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.0 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.0 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.0 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.0 installation for all files in the desktop directory.

  • Changes links to static content in the URL defined by the Sun ONE Portal Server 6.0 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.

  • Verifies that a proper installation of Sun ONE Portal Server 6.0 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:

  • 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

The LDAP database import tool module:

  • Looks for a configuration file to find an iPlanet Directory Server Access Management Edition 5.1 installation.

  • Alerts you to the fact that you must run the tool on the node running iPlanet Directory Server Access Management Edition 5.1 if an iPlanet Directory Server Access Management Edition 5.1 does not exist on the node. The files in the import directory can be used on any iPlanet Directory Server Access Management Edition 5.1 node.

  • Uploads customizations into the iPlanet Directory Server Access Management Edition 5.1 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

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.


    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.0 system. This two-column table lists the data types in the first column and the destination directory in Sun ONE Portal Server 6.0.


Table 1-1    Destination of Migrated Data on the Sun ONE Portal Server 6.0 System  

Data Type

Destination Directory in Sun ONE Portal Server 6.0

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     
Copyright 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated September 25, 2002