5
Using the Oracle9iAS Migration Assistant

This chapter explains how to use the Oracle9iAS Migration Assistant. This chapter contains these sections:

• Understanding the Migration Assistant

• Using the Migration Assistant

• Verifying Migration Results

• Restarting the Oracle9iAS Migration Assistant

Understanding the Migration Assistant

This section details the overall functionality of the Assistant. The Migration Assistant is designed to:

• Provide options for Oracle HTTP Server, Oracle9iAS Containers for J2EE, and Web Cache) to migrate configuration settings and applications from the source Oracle home to the target Oracle home on the same computer.

• Create a log file of all migration activity.

• Migrate configuration settings and applications to an uncustomized installation of Release 2 (9.0.3).

• Make the migration process auditable. A flag is set in the target Oracle home, Release 2 (9.0.3), to indicate that the Assistant has performed a migration there. All migration activities are recorded in a log file. See "Restarting the Oracle9iAS Migration Assistant".

Before starting the Assistant, read the section for each migration option you plan to use.

• Migrating the Oracle HTTP Server

• Migrating Oracle9iAS Containers for J2EE (OC4J)

• Migrating Oracle9iAS Web Cache

Using the Migration Assistant

This section explains how to prepare for and complete a migration. It contains these topics:

Preparing to Migrate

Using the Oracle9iAS Migration Assistant (GUI Version)

Using the Oracle9iAS Migration Assistant (Command Line Version)

Preparing to Migrate

Perform the tasks in this section before you begin migrating to Release 2 (9.0.3). If you have a Release 1 (1.0.2.1.x) installation, you must first migrate to Oracle9iAS Release 1 (1.0.2.2.x).

See Also: Oracle9i Application Server Migration Guide in the Release 1 (1.0.2.2.x) Oracle9i Application Server documentation library

Before you begin the migration process:

1. Install Release 2 (9.0.3), and all associated patches. Patches are available for download on http://metalink.oracle.com on the Patches page (for queries, use the product family '9i Application Server').

   Note: If Release 2 (9.0.3) is installed on the same computer as the Release 2 (9.0.2) Infrastructure, you may also need to apply infrastructure patches to the Release 2 (9.0.2) installation.

   See Also: Oracle9i Application Server Installation Guide

2. Stop the Release 2 (9.0.3) instance, if necessary.

3. Stop the Oracle9iAS Release 1 (1.0.2.2.x) or Oracle9iAS Release 2 (9.0.2) instance.

4. Ensure that you have access rights to all directories in the target Oracle home.

Information Requirements

Before you start the Assistant, be prepared with the password for the SSL certificate key file for the Oracle HTTP Server, if a password other than the default 'welcome' password was assigned. See Table 2-4 for password requirements. This password is used to generate the wallet during SSL conversion. If you enter the password incorrectly 3 times, components containing the SSL-related information are set to non-migratable status (excluded from the migration).

SSL Configuration Requirements When Migrating from Release 1

If you want to use SSL with the Oracle HTTP Server in the Release 2 (9.0.3) environment, ensure that the following directives are configured (uncommented) in the httpd.conf file before you start the Assistant:

• SSLCertificateFile

• SSLCertificateKeyFile

SSLCertificateFile and SSLCertificateKeyFile are necessary for any SSL-enabled web site, and if the configuration being migrated is an SSL configuration, these will be configured in httpd.conf in the source installation.

You must also ensure that the trust points are specified by some directive in the Release 1 installation. See "Migration of SSL Settings from Oracle9iAS Release 1 (1.0.2.2.x)" for instructions on how to do this.

Using the Oracle9iAS Migration Assistant (GUI Version)

Note: The screen images in this section show the migration process on a UNIX system (different from Windows only in the separation character used in the directory paths).

1. Go to ORACLE_HOME_2/migration (UNIX), ORACLE_HOME_2\migration (Windows).

2. Start the Assistant with the command:

   MigAssistant.sh (UNIX)

   MigAssistant.bat (Windows)

   The Oracle Home screen appears (Figure 5-1).

   Figure 5-1 Oracle Home screen

   

   Text description of the illustration ohome3.gif

3. Complete the Source... field with the full path to ORACLE_HOME_1. You can:
   • Type the full path into the field.

   • Click Browse... to specify the path by navigating. When the Browse window appears, displaying top-level folders, click once on the Oracle home and click Open (double-clicking opens the folder).

4. Complete the Destination... field with the full path to ORACLE_HOME_2. You can:
   • Type the full path into the field.

   • Click Browse... to specify the path by navigating. When the Browse window appears, displaying top-level folders, click once on the Oracle home and click Open (double-clicking opens the folder).

   If OC4J was not found in the Source... path you specified, the J2EE Home screen appears (Figure 5-2).

   Note: The Migration Assistant looks for OC4J in: ORACLE_HOME_1/J2EE_containers/j2ee/home (UNIX) ORACLE_HOME_1/j2ee/home (UNIX) ORACLE_HOME_1\J2EE_containers\j2ee\home (Windows) ORACLE_HOME_1\j2ee\home (Windows) and presents the J2EE Home screen if it does not find it there.

   Figure 5-2 J2EE Home screen

   

   Text description of the illustration j2eehome.gif

5. If OC4J was installed in a location other than the Source... path, click the Migrate OC4J radio button and complete the J2EE home path (type it or navigate to it), then click Next.

6. If OC4J is not installed, or you do not intend to migrate it, click the Exclude OC4J radio button, then click Next.

   The Components screen appears (Figure 5-3). By default, all of the components are selected for migration.

   Figure 5-3 Components screen

   

   Text description of the illustration compone3.gif

7. To deselect a component for migration, click the checkbox to clear it.

8. Click Next.

   If OC4J was selected, the OC4J screen appears (Figure 5-4). By default, all applications are selected for migration. See "OC4J Migration Candidates" for information on how the configuration files and applications are identified for migration.

   Figure 5-4 OC4J screen

   

   Text description of the illustration oc4jfil3.gif

9. To deselect a file or application for migration, click the checkbox to clear it.

   Warning: If any migrated application uses datasource tags, you must select data-sources.xml for migration. If you do not, the migration will fail.

10. Click Next.

    If Oracle HTTP Server was selected, the Oracle HTTP Server screen appears (Figure 5-5). By default, all of the configuration files, CGI applications, and static documents found are selected for migration. See "Oracle HTTP Server Migration Candidates" for information on how the configuration files and applications are identified for migration.

    Figure 5-5 Oracle HTTP Server screen

    

    Text description of the illustration ohsfile3.gif

11. To deselect a file or application for migration, click the checkbox to clear it.

12. Click Next.

    If an SSL certificate file was found with a password other than the default 'welcome', the httpd.conf: Passwords screen appears (Figure 5-6).

    Figure 5-6 httpd.conf: Passwords screen

    

    Text description of the illustration password.gif

13. Complete the password field with the password for the certificate key file. The SSL wallet will be generated with this password.

    Note: The Assistant allows you three attempts to enter the correct password before setting the SSL-enabled component to non-migratable status. If this happens, you must migrate the component manually.

14. Click Next.

    The httpd.conf: Directives screen appears (Figure 5-7), which is populated with the directives you can choose to migrate. By default, all directives except for mod_proxy are selected for migration. See "The Oracle HTTP Server Directive Migration Process" for information on how the Assistant compiled this list of directives.

15. To deselect a directive, click the checkbox to clear it.

    Figure 5-7 httpd.conf: Directives screen

    

    Text description of the illustration directi3.gif

16. Click Next.

    The Summary screen appears (Figure 5-8), showing your choices of Oracle homes, configuration files, and applications.

    Figure 5-8 Summary screen

    

    Text description of the illustration summary3.gif

17. Review the choices.

18. If necessary, click Back to navigate to previous screens to make changes.

19. Click Next.

    The Warning screen appears (Figure 5-9).

    Figure 5-9 Warning screen

    

    Text description of the illustration warning3.gif

    Warning: If you click Next now, the Assistant will begin to apply the current migration selections. Once the migration begins, you can click Cancel to stop the Assistant. It will finish the migration in progress (Oracle HTTP Server, OC4J or Web Cache), and then stop. No other selected migrations will start. To undo a migration, you must manually restore the configuration files in the 9.0.3 instance from a backup. For a description of backups and file names, see: "Backup and Auditing Measures for Oracle HTTP Server Migration" "Backup and Auditing Measures for OC4J Migration" "Backup and Auditing Measures for Web Cache Migration"

20. Click Next to apply the migration choices you have made, or click Back to navigate to previous screens to make changes.

    The Migration Status screen appears with a progress bar showing the percentage of the migration completed (Figure 5-10).

    Figure 5-10 Migration Status screen

    

    Text description of the illustration status3.gif

21. Click Finish to close the Migration Assistant.

Using the Oracle9iAS Migration Assistant (Command Line Version)

1. Go to ORACLE_HOME_2/migration (UNIX), or ORACLE_HOME_2\migration (Windows).

2. Start the Assistant with the command:

   MigAssistantCmd.sh (UNIX)

   MigAssistantCmd.bat (Windows)

   The following prompt appears:

   Source Oracle home?

3. Enter the path to ORACLE_HOME_1.

   The following prompt appears:

   Target Oracle home?

4. Enter the path to ORACLE_HOME_2.

   A prompt resembling the following appears.

   Select components to migrate

   Migrate all components?[YES]n

5. Press Enter to accept the default in brackets, or type n and press Enter to answer No.

   The next prompt appears.

6. Repeat Step 5 for each prompt. The remaining prompts resemble the following:

   Migrate all files for PlugIn Oracle9iAS WebCache?[YES]n

   Migrate webcache.xml[YES]

   Migrate all files for PlugIn Oracle9iAS Containers for

   J2EE(OC4J)?[YES]n

   Migrate data-sources.xml[YES]

   Migrate principals.xml[YES]

   Migrate all files for PlugIn Oracle HTTP Server?[YES]n

   Migrate httpd.conf[YES]

   Questionaire

   PlugIn Oracle HTTP Server httpd.conf

   Please enter the password for ORACLE_HOME_

   1/conf/ssl.crt/server.crt[welcome]

7. Press Enter to accept the default password welcome, or type the password and press Enter.

   A summary of selections resembling the following appears:

   Press Enter to accept the default password welcome, or type the password and press Enter.

   A summary of selections resembling the following appears:

   Summary page

   PlugIn Oracle9iAS Web Cache
webcache.xml

   Plugin Oracle9iAS Containers for J2EE(OC4J)
data-sources.xml
principals.xml

   PlugIn Oracle HTTP Server
httpd.conf

   Start migration...

8. Press Enter to start the migration.

   Migration processing begins. Status messages resembling the following appear:

   Migrating plugin Oracle9iAS Web Cache

   Outcome Status code 0

   Status description SUCCESS

   Migrating plugin Oracle9iAS Containers for J2EE(OC4J)

   Outcome Status code 0

   Status description SUCCESS

   Migrating plugin Oracle9iAS HTTP Server

   Outcome Status code 0

   Status description SUCCESS

Verifying Migration Results

1. Review the log file, located in:

   ORACLE_HOME_2/migration/log/iASMigration.log (UNIX)

   ORACLE_HOME_2\migration\log\iASMigration.log (Windows)

   The log files summarize all migration activity and errors.

2. Migrate manually any configuration or applications not migrated by the Migration Assistant, for example:
   • Static documents or cgi or fastcgi applications noted in the log file (these are only logged, not migrated, if found in non-default locations).

   • cgi or fastcgi applications defined by means other than the ScriptAlias directive.

   • mod_osso.conf or mod_oc4j.conf

   • mod_plsql configuration files

   • Other configuration described in "HTTP Server Elements Not Migrated".

   • Web Cache elements not migrated. See "Completing the Web Cache Migration".

   • OC4J elements not migrated, specifically customization in files such as orion-web.xml, orion-ejb-jar.xml, orion-application.xml. See "OC4J Elements Not Migrated" and Appendix A, "Files Reference" for examples of files not migrated.

3. Ensure that all of the components in the target installation will start. Run the demos (available on the Oracle9iAS Welcome page) to verify this.

4. Perform tests for each migrated application or configuration setting to ensure it is working as it did in the previous release.

Restarting the Oracle9iAS Migration Assistant

If the migration is unsuccessful, you can run the Migration Assistant again. Follow these steps:

1. Delete the flag file firstRun from the Release 2 (9.0.3) Oracle home directory.

2. Restore all configuration files and directories to their pre-migration state. The log file contains the names of all files that were altered or copied.

3. Follow the instructions in:

   "Using the Oracle9iAS Migration Assistant (GUI Version)"

   or

   "Using the Oracle9iAS Migration Assistant (Command Line Version)" .