2
Using the Oracle9iAS Migration Assistant

This chapter describes the Oracle9iAS Migration Assistant, a tool that migrates Oracle HTTP Server, Oracle9iAS Containers for J2EE, and Web Cache from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2). The Assistant is available in GUI and command-line versions.

Note: Oracle only supports the use of the Assistant for migrations from Release 1 (1.0.2.2.x).

By automating much of the migration process, the Oracle9iAS Migration Assistant eliminates errors associated with migrating files manually and expedites what can otherwise be a very lengthy process. It also prepares applications for use immediately after migration, enabling you to use the new Oracle9iAS release soon after installation.

This chapter contains these sections:

• Understanding the Migration Assistant
  • The Oracle HTTP Server Migration Process

  • The Oracle9iAS Containers for J2EE (OC4J) Migration Process

  • The Oracle9iAS Web Cache Migration Process

• Installing the Migration Assistant

• Migrating Applications

• Restarting the Oracle9iAS Migration Assistant

Understanding the Migration Assistant

This section details the overall functionality of the Assistant, and the specialized functionality for each of the migration options. The Migration Assistant is designed to:

• Migrate the specified components from the Oracle9iAS Release 1 (1.0.2.2.x) Oracle home to the Oracle9iAS Release 2 (9.0.2) Oracle home on the same computer.

• Create a log file of all migration activity.

• Run against an installation of Oracle9iAS Release 2 (9.0.2) that has not been customized.

• Make the migration process auditable. A flag is set in the target Oracle home, Oracle9iAS Release 2 (9.0.2), 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 option you plan to use.

• The Oracle HTTP Server Migration Process

• The Oracle9iAS Containers for J2EE (OC4J) Migration Process

• The Oracle9iAS Web Cache Migration Process

• Using the Oracle9iAS Migration Assistant (GUI Version)

• Using the Oracle9iAS Migration Assistant (Command Line Version)

The Oracle HTTP Server Migration Process

This section describes the functionality of the Oracle HTTP Server migration option, and lists the elements migrated for each component. It contains the following topics:

• Oracle HTTP Server Migration Candidates

• The HTTP Server Directive Migration Process

• Backup and Auditing Measures for Oracle HTTP Server Migration

Oracle HTTP Server Migration Candidates

The Oracle HTTP Server migration option recognizes the following configuration files, programs, static documents, and modules as candidates for migration:

• The httpd.conf file. (This file must be selected, or no other files will be migrated.)

  Note: Any configuration file named in an Include directive except for oracle_apache.conf or jserv.conf can also be migrated. For example, if you had a user-defined configuration file myFile.conf and in httpd.conf the directive include "home/myDirectory/myFile.conf" then during migration processing, you can choose to migrate the directive and the file.

• cgi and fastcgi programs not found in the 9.0.2 instance. The default Oracle9iAS 1.0.2.2 instance contains

  ORACLE_HOME_1/Apache/Apache/cgi-bin/printenv
  ORACLE_HOME_1/Apache/Apache/cgi-bin/test-cgi
  ORACLE_HOME_1/Apache/Apache/fastcgi-bin/echo
  ORACLE_HOME_1/Apache/Apache/fastcgi-bin/echo2
  
  

  Any other cgi or fastcgi applications defined by ScriptAlias or Options ExecCGI directives in httpd.conf are migration candidates.

• New static documents or directories found in:

  ORACLE_HOME_1/Apache/Apache/htdocs

  with the exception of the following subdirectories:

  webapp

  onlineorders_html

  manual

  doc

  _pages

• Any new files or directories under the following directories:

  ORACLE_HOME_1/Apache/Apache/htdocs/WEB-INF (including subdirectories)

  ORACLE_HOME_1/Apache/Apache/htdocs/demo (including subdirectories)

  Note: index.html will be migrated only if its file size differs from that of the default. If the content differs, but the file size remains the same, you must migrate index.html manually.

• The .so (shared object) files for any modules not in the Oracle9iAS Release 1 (1.0.2.2.x) default set but specified in a LoadModule directive.

Default modules

Table 2-1 lists the default set of modules shipped in Oracle9iAS Release 1 (1.0.2.2.x).

Table 2-1 Default Modules

Module Name
access_module	dms_module	perl_module
action_module	env_module	proxy_module
agent_log_module	example_module	referer_log_module
alias_module	expires_module	rewrite_module
anon_auth_module	fastcgi_module	setenvif_module
asis_module	headers_module	speling_module
auth_module	imap_module	ssl_module
autoindex_module	includes_module	status_module
cern_meta_module	info_module	unique_id_module
cgi_module	mime_magic_module	userdir_module
dbm_auth_module	mime_module	usertrack_module
define_module	mmap_static_module	vhost_alias_module
digest_module	negotiation_module
dir_module	oprocmgr_module

Default Directives in httpd.conf

Table 2-2 lists the directives found in both versions of the httpd.conf file.

Table 2-2 httpd.conf Default Directives

Directive Name
AccessFileName	IfDefine	ScriptAlias
AddCharset	IfModule	ServerAdmin
AddEncoding	IndexOptions	ServerName
AddHandler	KeepAlive	ServerRoot
AddIcon	KeepAliveTimeout	ServerSignature
AddIconByEncoding	LanguagePriority	ServerType
AddIconByType	Listen	SetEnv
AddLanguage	LoadModule	SetHandler
Alias	Location	SSLEngine
Allow	LogFormat	SSLLog
AllowOverride	LogLevel	SSLLogLevel
BrowserMatch	MaxClients	SSLMutex
CustomLog	MaxKeepAliveRequests	SSLOptions
DefaultIcon	MaxRequestsPerChild	SSLPassPhraseDialog
DefaultType	MaxSpareServers	SSLRandomSeed
Deny	MIMEMagicFile	SSLSessionCache
Directory	MinSpareServers	SSLSessionCacheTimeout
DirectoryIndex	Options	StartServers
DocumentRoot	Order	Timeout
ErrorLog	PassEnv	TransferLog
ExtendedStatus	PerlHandler	TypesConfig
Files	PerlSendHeader	UseCanonicalName
Group	PidFile	User
HeaderName	Port	UserDir
HostnameLookups	ReadmeName

This is the default set of directives for Oracle HTTP Server migration. These directives occur in the default versions of the httpd.conf files in the 1.0.2.2 and 9.0.2 instances. The Assistant highlights the differences so that you can select them for migration. If the setting for a directive is the same in both files, no action is taken.

In the discussion of the migration process below, directives are described as primitive directives or container directives. Primitive directives occupy a single line; for example:

Timeout 300

KeepAlive on

Container directives occupy multiple lines, have a start directive and an end directive, and contain arguments (which are primitive directives). For example:

<Directory "/private2/myDirectory">
    Options FollowSymLinks MultiViews
    AllowOverride None
</Directory> 

The container directive above has start and end directives <Directory "/private2/myDirectory"> and </Directory. The arguments are the primitive directives Options FollowSymLinks MultiViews and AllowOverride None.

HTTP Server Elements Not Migrated

The Oracle HTTP Server migration option does not migrate:

JServ - JServ is included in Oracle9iAS Release 2 (9.0.2) only to support legacy use; the preferred servlet environment is Oracle9iAS Containers for J2EE (OC4J). If you used JServ in Release 1 and want to use OC4J in Release 2, see "Migrating JServ to OC4J". The manual process for migrating JServ is described there.

Configuration files related to the use of mod_plsql - Files such as oracle_apache.conf, plsql.conf, dads.conf and cache.conf and the Include directive in httpd.conf (for oracle_apache.conf) are excluded from the migration.

See Also: Chapter 4, "Migrating Portals Components", "Migrating Database Access Descriptors" for instructions on migrating the mod_plsql configuration and "mod_plsql Parameter Changes in Release 2"for a complete list of parameter changes.

The HTTP Server Directive Migration Process

To migrate directives, the Assistant:

1. Presents directives in the 1.0.2.2 httpd.conf file that are different from the default (uncustomized) file, httpd.conf.default, or that are new (not part of the default set of directives). The default file, httpd.conf.default, must be present or the program will not function.

   By default, all such directives are selected for migration via a checkbox and presented in a scrolling list. You can exclude a directive from the migration by clearing its checkbox.

   Note: An exception to this default selection of directives is the mod_proxy directive. All mod_proxy directives are unchecked by default. They will not be migrated unless they are explicitly selected in the httpd.conf: Directives screen (shown).

   Notes: Container directives are migrated as a whole; when you select a container directive for migration, you select all of the arguments (primitive directives) in it. For this reason, only the top level (that is, the start and end directives) of the container directive is presented as a migration selection. Path-related directives are presented with the destination path instead of the source path. For example, a directive from the Release 1 configuration such as ORACLE_HOME_1/Apache/Apache/myAlias will appear onscreen as ORACLE_HOME_2/Apache/Apache/myAlias

2. Writes selected directives to a difference file.

3. Merges the difference file with the 9.0.2 httpd.conf file as follows:
   • Default directives with changed settings replace the corresponding directive in the 9.0.2 httpd.conf file.

   • Non-default directives (that is, those not listed in Table 2-2) are written to the end of the 9.0.2 httpd.conf file.

4. Discards JServ directives.

Migration of SSL Settings

To accommodate the replacement of standard SSL with mod_ossl in Oracle9iAS Release 2 (9.0.2), the Assistant automatically creates a directive for mod_ossl, SSLWallet (as shown in Example 2-1), based on the Release 1 configuration (shown in Example 2-2). It then starts a program that generates an Oracle wallet. You can choose not to generate the wallet during migration by commenting out the SSL configuration in the Release 1 file before you start the migration Assistant.

See Also: Oracle9i Application Server Security Guide

To ensure that a valid wallet gets generated in the migration, you must specify the trust points (the signers of the certificates) in the Release 1 configuration. There are two ways to do this:

• Concatenate the signer certificates (the certificate chain) into the Release 1 server certificate file.

• Concatenate all of the signers into one file, and use the SSLCertificateChainFile directive in the Release 1 httpd.conf file.

You can also import other certificate authority certificates into the wallet, by specifying them with the SSLCACertificateFile and SSLCACertificatePath in the Release 1 httpd.conf file.

Note: The Release 1 default SSL certificate is signed by the certificate authority 'oracle demoCA', whose certificate is at ORACLE_HOME_1/Apache/Apache/conf/ssl.crt/demoCAcert.crt. Before migration, you must set the SSLCertificateChainFile directive to point to the default SSL certificate: SSLCertificateChainFile ORACLE_HOME_ 1/Apache/Apache/conf/ssl.crt/demoCAcert.crt

The migration Assistant manages SSL certificate key file and wallet passwords as follows:

Table 2-3 SSL Password Requirements

If Release 1 SSL Certificate Key File has...	Then during migration...
the default 'welcome' password	you are not prompted for a password.
a password other than 'welcome'	you are prompted to enter the correct password.
no password assigned	you are not prompted for a password, and the generated wallet password is set to 'welcome'.

The SSL directives in httpd.conf are shown below for Oracle9iAS Release 2 (9.0.2) (IfModule) and Release 1 (IfDefine):

Example 2-1 SSL Directive (Release 2)

<IfModule mod_ossl.c>
   <VirtualHost _default_:4443>
     SSLWallet wallet location
     SSLVerifyClient optional
     SSLProtocol all
   </VirtualHost>
</IfModule> 

Example 2-2 SSL Directive (Release 1)

<IfDefine SSL>
   <VirtualHost _default_:443>
     SSLCertficateFile certificate location
     SSLCertificateKeyFile key location

 SSLCertificateChainFile chain location

     SSLVerifyClient optional_no_ca
     SSLProtocol TLSv1
   </VirtualHost>
</IfDefine> 

Note the following changes:

• SSLVerifyClient is set to optional if it was set to optional_no_ca.

• SSLProtocol is set to all if it was set to TLSv1.

The following directives are invalid in mod_ossl, and replaced by SSLWallet:

• SSLCertificateFile

• SSLCertificateKeyFile

• SSLCertificateChainFile

• SSLCACertificatePath

• SSLCACertificateFile

• SSLRandomSeed

• SSLVerifyDepth

During migration, the Assistant extracts certificate-related directives and starts a program that generates a wallet. The wallet-related directives are written to the difference file. The value of SSLWallet is the value of SSLCertificateFile, or, if path-related:

ORACLE_HOME_2/Apache/Apache/conf/ssl.wlt/certificate name 

Backup and Auditing Measures for Oracle HTTP Server Migration

The Assistant performs the following functions to provide a way to audit the migration process:

• Creates a backup of the default 9.0.2 httpd.conf file named httpd.conf.migbak. Because it was written by a parser, this file is not identical in format to httpd.conf, but the content is exactly the same.

• Logs all migration activity and errors in

  ORACLE_HOME_2/migration/log/iASMigration.log 
  
  

The Oracle9iAS Containers for J2EE (OC4J) Migration Process

This section explains the functionality of the OC4J migration option. It contains the following topics:

• OC4J Migration Candidates

• The OC4J Configuration File Migration Process

• Backup and Auditing Measures for OC4J Migration

OC4J Migration Candidates

The OC4J migration option recognizes these configuration files and applications as candidates for migration:

• The principals.xml and data-sources.xml files.

• Applications defined in the server.xml file in the 1.0.2.2 instance, in .ear file format.

  Note: Applications must be in .ear file format and defined in the source server.xml file in order to be migrated. Applications are deployed to the 9.0.2 Oracle9iAS instance using DCM (Distributed Configuration Management). The assumption is that the application was not installed there previously (the 9.0.2 instance is supposed to be a new, unchanged Oracle9iAS installation), but if an application exists, it will be overwritten. The Assistant will not migrate applications in any format other than .ear (such as .war, exploded, etc.).

Standalone OC4J Instances and Migration

If you installed OC4J in a standalone configuration prior to installing Oracle9iAS Release 1 (1.0.2.2.x), be aware that the Migration Assistant only migrates the OC4J instance bundled with Oracle9iAS Release 1 (1.0.2.2.x).

For example, suppose that:

1. An OC4J instance was installed and configured, with applications deployed.

2. Subsequently, Oracle9iAS Release 1 (1.0.2.2.x) was installed, with its bundled OC4J instance. The applications are still deployed on the original instance.

3. The Migration Assistant is run.

   No applications are migrated, since they were not found on the Oracle9iAS Release 1 (1.0.2.2.x) OC4J instance.

The OC4J Configuration File Migration Process

The OC4J migration option does the following:

1. Copies selected principals.xml and data-sources.xml from ORACLE_HOME_1/j2ee to ORACLE_HOME_2/j2ee.

2. Reads application information from the server.xml file in ORACLE_HOME_1 and prompts you to select the applications to migrate.

3. Starts a default OC4J instance in ORACLE_HOME_2.

4. Re-deploys the migrated applications in ORACLE_HOME_2.

5. Stops the default OC4J instance (and all of Oracle9iAS, if it was running).

J2EE Compliance Requirements for OC4J Migration

In Oracle9iAS Release 2 (9.0.2), OC4J deployment enforces J2EE compliance rules. For this reason, the Oracle9iAS Migration Assistant may not migrate applications that are not 100% J2EE compliant. The Assistant simply reads the files and attempts to deploy them to Oracle9iAS Release 2 (9.0.2); if deployment fails, it could be because an application is not J2EE compliant.

If the Assistant cannot deploy an application for any reason, it logs the exception (which may not be explicitly described as a compliance issue).

While the development of J2EE applications is standardized and portable, the XML configuration files are not. You may have to configure multiple XML files before deploying an application to OC4J. The configuration needed depends on the services the application uses. For example, if the application uses a database, you must configure the DataSource object in the data-sources.xml file.

Validating EAR Files for J2EE Compliance

The dcmctl utility provides a J2EE compliance validation command. It takes one input, the name of an EAR file, and lists non-compliant characteristics of that file. The syntax is:

dcmctl validateEarFile -v -f name.ear

where name is the name of the EAR file. -v specifies the verbose option of dcmctl; this provides the most detailed output of commands.

You must configure proxy settings so that the validation routine can access DTDs on the Web, if necessary (for example, on the Sun Microsystems site). To do this, you define an environment variable called ORACLE_DCM_JVM_ARGS, which specifies a hostname and port for the proxy. For example, using tcsh, the command is

tcsh> setenv ORACLE_DCM_JVM_ARGS "-DhttpProxy.host=www-proxy.hostname.com 
-DhttpProxy.port=9999"

where hostname is the host name and 9999 is the port number. (The method of defining this environment variable is platform-dependent.)

Example 2-3 validateEarFile Command and Output for J2EE-Compliant Application

dcmctl validateEarFile -v -f simple.ear   


No J2EE XML/DTD validation errors were found

Example 2-4 validateEarFile Command and Output for non- J2EE-Compliant Application

dcmctl validateEarFile -v -f petstore.ear


Warning: J2EE/DTD validation errors were found



ADMN-906001   {0}   Base Exception:   
oracle.ias.sysmgmt.deployment.j2ee.exception.J2eeDeploymentException:Cannot 
get xml   document by parsing /var/tmp/jar50152.tmp: Invalid element 
'servlet' in content of 'web-app',   expected elements '[servlet-mapping, 
session-config, mime-mapping, welcome-file-list,   error-page, taglib, 
resource-ref, security-constraint, login-config, security-role, env-entry,   
ejb-ref]'.

It is a good idea to review all applications for overall J2EE compliance before migrating them, since there are cases in which an application is deployable, but delivers unpredictable or undesirable server behavior. For example, ensure that each application has a unique context root defined in application.xml.

Backup and Auditing Measures for OC4J Migration

The Assistant performs the following functions to provide a way to audit the migration process:

• Creates a backup of each configuration file. The copy has the same filename, and the extension .SAVED_COPY.

• Logs all migration activity and errors in

  ORACLE_HOME_2/migration/log/iASMigration.log 
  
  

The Oracle9iAS Web Cache Migration Process

This section explains the functionality of the Web Cache migration option. It contains the following topics:

• Web Cache Migration Candidates

• The Web Cache Migration Process

• Backup and Auditing Measures for Web Cache Migration

Web Cache Migration Candidates

The Web Cache migration option recognizes most of the elements in the webcache.xml file in ORACLE_HOME_1. They are listed in "The Web Cache Migration Process" below.

The Assistant does not migrate:

• The internal.xml file. You must manually migrate network timeouts, keepalive values, and osrecv values from the CALYPSONETINFO element of the internal.xml file to the webcache.xml file in ORACLE_HOME_2.

• The MULTIVERSIONHEADERRULE, if the header used for disambiguation is the Host header. Web Cache in Oracle9iAS Release 2 (9.0.2) supports multiple sites. See the Web Cache documentation for site-to-server mapping.

Migration of Session Definitions

A session defnition consists of a session name, a cookie, a URL parameter, and a default value. The migration Assistant migrates session definitions as follows:

• If the session name, cookie, URL parameter, and default value, are the same in Release 2 as in Release 1, then the session definition is not migrated.

• If the session name is the same, but the cookie, URL parameter, or default value is different, then the migration Assistant migrates the session as it is, changes the name of the Release 2 session, and updates its references.

  Warning: Any application that was using the WEBCACHETAG element with reference to the original Release 2 Web Cache session definition must be modified to use the re-named session definitions.

The Web Cache Migration Process

The Web Cache migration option does the following:

1. Copies the following elements of the webcache.xml file from ORACLE_HOME_1 to ORACLE_HOME_2:
   • SECURITY

     SECURESUBNET (Sub-element of SECURITY; trusted subnets).

     Note: The Migration Assistant does not migrate any passwords. The administrator and invalidation passwords have default values when Release 2 is installed; see the Web Cache documentation for the default passwords.

   • WATCHDOG

   • REQUESTBACKLOGTIMELIMIT (an attribute of the SITE element)

     Copied to the first SITE element of the webcache.xml in ORACLE_HOME_2.

   • ERRORPAGES

     Copied from the ORACLE_HOME_1 webcache.xml file to the ORACLE_HOME_2 webcache.xml file under the first SITE element.

   • MULTIVERSIONCOOKIESRULE

     Copied from the webcache.xml file in ORACLE_HOME_1 and merged with the data in the same sections of the GLOBALCACHINGRULES element in the webcache.xml file in ORACLE_HOME_2.) This can result in duplicate or redundant multi-version cookies rules. See "Completing the Web Cache Migration" for instructions on resolving this.

   • SESSIONCACHINGRULE

     Copied from the ORACLE_HOME_1 webcache.xml file to the ORACLE_HOME_2 webcache.xml file, in the GLOBALCACHINGRULES section. This can result in duplicate or redundant session caching rules. See "Completing the Web Cache Migration" for instructions on resolving this.

   • EXPIRATIONRULE

     Copied from the webcache.xml file in ORACLE_HOME_1 and merged with the data in the same sections of the GLOBALCACHINGRULES element in the webcache.xml file in ORACLE_HOME_2.) This can result in duplicate or redundant expiration rules. See "Completing the Web Cache Migration" for instructions on resolving this.

   • CACHEABILITY

     Copied from the ORACLE_HOME_1 webcache.xml file to the ORACLE_HOME_2 webcache.xml file, in the GLOBALCACHINGRULES section. This can result in duplicate or redundant cacheability rules. See "Completing the Web Cache Migration" for instructions on resolving this.

     Note: Since the migrated CACHEABILITY rules are defined in the GLOBALCACHINGRULES section, they apply to all of the SITES defined in the ORACLE_HOME_2 webcache.xml file. If you define another SITE element later in ORACLE_HOME_2, you must also define cacheability rules for it. The rules defined in the GLOBALCACHINGRULES section will apply to the new SITE also.

   • HOST

     All of the application web servers from the ORACLE_HOME_1 webcache.xml file are migrated to the ORACLE_HOME_2 webcache.xml file. Host IDs are generated for each of these hosts.

   • EVENTLOG

   • ACCESSLOG (except for the LOGDIR attribute)

   • RESOURCELIMITS

Backup and Auditing Measures for Web Cache Migration

The Assistant performs the following functions to provide a way to audit the migration process:

1. Creates a backup copy of the webcache.xml file from ORACLE_HOME_2. The backup file is named webcache.xml.backup.

2. Logs all migration activity and errors in

   ORACLE_HOME_2/migration/log/iASMigration.log 
   
   

Installing the Migration Assistant

This section provides information about hardware and software requirements for installation of Oracle9iAS Migration Assistant. The topics include:

• Hardware Requirements

• Software Requirements

• Starting Oracle Universal Installer

Hardware Requirements

In addition to the hardware requirements for Oracle9i Application Server as described in the Oracle9i Application Server Installation Guide, the Oracle9iAS Migration Assistant requires 512 MB memory.

Software Requirements

The Oracle9iAS Migration Assistant requires the following software:

• Oracle9iAS Release 2 (9.0.2) Middle Tier

• Oracle Universal Installer version 2.1.0.9 or higher

• JDK 1.3.1

Operating System Requirements

The following tables contains the software requirements for Oracle9iAS.

• Table 2-4 lists the software requirements for AIX-Based Systems.

• Table 2-5 lists the software requirements for HP 9000 Series HP-UX.

• Table 2-6 lists the software requirements for Linux Intel.

• Table 2-7 lists the software requirements for Tru64.

For the latest information, refer to OracleMetaLink:

http://metalink.oracle.com

Note: Download the operating system patches for AIX-Based Systems, Tru64 UNIX, HP 9000 Series HP-UX, and Linux Intel from the vendor web sites.

Note: The current JDK 1.3.1 production version is required. For Linux, this JDK is included on the Oracle9iAS CD-ROM

Table 2-4 Software Requirements for AIX-Based Systems  

Item	Requirement
Operating System	AIX 4.3.3 (64-bit only)
Software	JDK1.3.1 SR-3 or higher Motif 1.2
Operating System patches for AIX 4.3.3	ML10 or higher Common Locale Support package (bos.loc.com) VAC5.0 runtime or higher
Clusterware Patches	PSSP 3.2 IY04109 IY04149 IY04767 HACMP/ES 4.4 IY03478 IY04109 IY06749 IY20220 IY17439 IY15677 IY14572 IY13935
Window Manager	Use any supported IBM AIX window manager that supports Motif, such as dtwm, twm, and olwm.

Table 2-5 Software Requirements for HP 9000 Series HP-UX  

Item	Requirement
Operating System	HP-UX 11.0 (64-bit)
Software	JDK 1.3.1 Motif 2.1
Operating System Patches	You must install any prerequisite patches for JDK. These patches are available from the HP website. NOTE: Several of the patches listed below have dependency patches that must be installed as well. When you navigate to the download web page for an individual patch, click the dependency link and make sure you install the dependency patches if required.
HP-UX 11.0 Patches	Dec 2000 Patch Bundle PHSS_23377 PHCO_23770 PHKL_23226 PHCO_23092 PHCO_23792 PHCO_23963 PHCO_24148 PHKL_18543 PHKL_23226 PHKL_23409 PHKL_24826 PHKL_24943 PHKL_24971 PHNE_21731 PHNE_23456 PHNE_23833 PHSS_23440 PHSS_17535 PHSS_23546 PHSS_23800 PHKL_25188 PHSS_23823
HP-UX 11i Patches	December 2001 Quality Pack (Gold Patch Set) plus PHCO_25452 PHKL_24569 PHKL_25389 PHKL_25729 PHKL_25842 PHKL_27092
Clusterware	MC/ServiceGuard 11.09 OPS Edition PHCO_23919
Required Executables	The following executables must be present in the /usr/ccs/bin directory: make, ar, ld, nm, and cc.

Table 2-6 Software Requirements for Linux Intel

Item	Requirement
Operating System	SuSE SLES7 or Red Hat Advanced Server 2.1 Distribution
Software	JDK 1.3.1 XFree86 Development 3.3.3.1 or later Open Motif 2.1.30 For SuSE SLES7 the following is also required: kernel 2.4.7 glibc 2.2.2-55 For Red Hat Advanced Server 2.1 the following is also required: kernel 2.4.9 glibc 2.2.4-25

Table 2-7 Software Requirements for Tru64 UNIX

Item	Requirement
Operating System	Tru64 UNIX 5.1 or 5.1a
Software	JDK 1.3.1 Motif 1.2
Operating System Patches for Tru64 UNIX 5.1	5.1 patchkit 3 or higher
Operating System Patches for Tru64 UNIX 5.1a	5.1a patchkit 1 or higher
Clusterware	TruClusters 5.1a (CFS aware)
Operating System Packages	The OSFLIBA, OSFPGMR, and OSFCMPLRS subsets. These subsets are part of the Tru64 UNIX operating system distribution.
Window Manager	X Windows must be installed on the system from where the Installer is run. Use any HP-supported X Windows server with support for Motif, such as dtwm, twm, and mwm. Character mode installations are not supported for Oracle9iAS Release 2 (9.0.2) The X environments, Basic X-environments (OSF11), and X Servers (OSFSER) are required to run graphical products.
Required Executables	The following executables must be present in the /usr/ccs/bin directory: make, ar, ld, and nm.

Starting Oracle Universal Installer

Follow these steps to launch Oracle Universal Installer, which installs the Oracle9iAS Migration Assistant:

1. Stop all Oracle processes and services (for example, the Oracle database) running on the computer.

2. Insert the Supplemental CD into the CD-ROM drive.

3. Mount the Supplemental CD-ROM.

   Note: The Oracle Product Installation CD-ROM is in RockRidge format. To manually mount or unmount the CD-ROM, you must have root privileges. Be sure to unmount the CD-ROM before removing it from the drive.

4. To manually mount the Supplemental CD-ROM, perform the following steps:

5. Insert the Supplemental CD into the CD-ROM drive.

6. Log in as the root user.

7. Create the CD-ROM mount point directory.

   prompt> mkdir mount_point
   
   

8. Mount the CD-ROM drive on the mount point directory and exit the root account:

   prompt> mount options device_name mount_point
   
   prompt> exit
   

   See Also: For more information on mounting CD-ROMs for AIX-Based Systems, Tru64 UNIX, HP 9000 Series HP-UX, and Linux Intel, refer to the Oracle9i Application Server Installation Guide.

   1. Log out as the root user.

      Note: This is an important step. If you are still the root user when you start Oracle Universal Installer, then only the root user will have permissions to manage Oracle9iAS Migration Assistant.

   2. Run Oracle Universal Installer from the CD-ROM.

   3. Log in as the oracle user.

   4. Start the Installer by entering:

      prompt> mount_point/9ias_supplemental/runInstaller
      
      

   The Welcome screen appears (Figure 2-1).

Figure 2-1 Oracle Universal Installer Welcome screen

Text description of the illustration ouiwelcm.gif

1. Click Next.

   The File Locations screen appears (Figure 2-2).

Figure 2-2 Oracle Universal Installer File Locations screen

Text description of the illustration ouifiles.gif

Note: The Source and Destination locations must be on the same computer.

Complete the Source... field with the location of the products.jar file on the Supplemental CD. You can type the path, or click Browse... to navigate to it.

Complete the Destination... field with the Oracle home in which you want to install the Oracle9iAS Migration Assistant. The Name drop-down box contains a list of all middle-tier Oracle homes on the computer.

Note: You can only install the Assistant into an existing Oracle9iAS Release 2 (9.0.2) Oracle home in a middle tier type of installation. You cannot install it into an infrastructure installation.

Click Next.

The Summary screen appears (Figure 2-3).

Figure 2-3 Oracle Universal Installer Summary screen

Text description of the illustration ouisummy.gif

This screen summarizes the choices on the File Locations screen: the path to products.jar and the destination Oracle home, as well as the installation type, language, and space requirements.

If you need to change the source or destination path, click Previous and enter or select the path you want. Otherwise, continue with Step 6.

Click Next.

The Install screen appears (Figure 2-4).

Figure 2-4 Oracle Universal Installer Install screen

Text description of the illustration ouiinstl.gif

This screen shows the progress of the installation of the Assistant to the selected Oracle home. The text above the progress bar indicates the installation actions as they occur. When the process completes, the End of Installation screen appears (Figure 2-5).

Figure 2-5 Oracle Universal Installer End of Installation screen

Text description of the illustration ouiendof.gif

This screen indicates the results of the installation process.

Click Exit.

Migrating Applications

This section provides guidelines for preparing for a migration, and step-by-step instructions for starting and operating the Assistant.

Preparing to Migrate

This section outlines prerequisite steps for migrating.

Note: You do not need to start Oracle9iAS before using the Migration Assistant. The Assistant will start an OC4J instance to deploy the OC4J applications, and then stop it when it is finished.

Information Requirements

Before you start the Assistant, be prepared with the following (as required for the components you plan to migrate):

• 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-3 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. They are excluded from the migration.

• Familiarity with the Oracle HTTP Server directives and their purpose, as related to your configuration.

SSL Configuration Requirements

If you want to use SSL with the Oracle HTTP Server in the Oracle9iAS Release 2 (9.0.2) 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 Release 1 installation.

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

Using the Oracle9iAS Migration Assistant (GUI Version)

1. If necessary, change to the directory in which the Assistant is installed.

2. Start the Assistant with the command:

   $ MigAssistant.sh36
   
   

   The Oracle Home screen appears (Figure 2-6).

Figure 2-6 Oracle Home screen

Text description of the illustration ohome.gif

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.

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.

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

Figure 2-7 J2EE Home screen

Text description of the illustration j2eehome.gif

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

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 2-8). By default, all of the components are selected for migration.

Figure 2-8 Components screen

Text description of the illustration componen.gif

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

Click Next.

If OC4J was selected, the OC4J screen appears (Figure 2-9). 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 2-9 OC4J screen

Text description of the illustration oc4jfile.gif

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

Click Next.

If Oracle HTTP Server was selected, the Oracle HTTP Server screen appears (Figure 2-10). By default, all of the configuration files and CGI applications 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 2-10 Oracle HTTP Server screen

Text description of the illustration ohsfiles.gif

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

Click Next.

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

Figure 2-11 httpd.conf: Passwords screen

Text description of the illustration password.gif

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.

Click Next.

The httpd.conf: Directives screen appears (Figure 2-12), 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 HTTP Server Directive Migration Process" for information on how the Assistant compiled this list of directives.

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

Figure 2-12 httpd.conf: Directives screen

Text description of the illustration directiv.gif

Click Next.

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

Figure 2-13 Summary screen

Text description of the illustration summary.gif

Review the choices.

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

Click Next.

The Warning screen appears (Figure 2-14).

Figure 2-14 Warning screen

Text description of the illustration warning.gif

Warning: If you click Next, then 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.2 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"

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 2-15).

Figure 2-15 Migration Status screen

Text description of the illustration status.gif

Click Finish to close the Migration Assistant.

Review the log files.

Perform tests for each application you migrated.

Using the Oracle9iAS Migration Assistant (Command Line Version)

1. Start the Assistant with the command:

   MigAssistantCmd.sh
   
   

   The following prompt appears:

   Source Oracle home?
   
   

2. Enter the path to ORACLE_HOME_1.

   The following prompt appears:

   Target Oracle home?
   
   

3. Enter the path to ORACLE_HOME_2.

   A prompt resembling the following appears.

   Select compnents to migrate Migrate all components?[YES]n 
   
   

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

   The next prompt appears.

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

   Migrate all subComponents of PlugIn  Oracle9iAS Web Cache?[YES]n 
   
   Migrate webcache.xml[YES] 
   
   Migrate all subComponents of PlugIn Oracle9iAS Containers for 
   J2EE(OC4J)?[YES]n 
   
   Migrate data-sources.xml[YES] 
   
   Migrate principals.xml[YES] 
   
   Migrate all subComponents of PlugIn  Oracle HTTP Server?[YES]n 
   
   Migrate httpd.conf[YES] 
   
   Migrate Globals.java[YES] 
   
   Migrate Globals.class[YES] 
   
   Migrate Globals$__jsp_StaticText.class[YES] 
   
   Migrate globals.ser[YES] 
   
   Migrate _index.java[YES] 
   
   Migrate _index.class[YES] 
   
   Migrate _index$__jsp_StaticText.class[YES]
   
   Questionaire PlugIn Oracle HTTP Server httpd.conf 
   Please enter the password for ORACLE_HOME_
   1/conf/ssl.crt/server.crt:[welcome]
   
   

6. 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  
   news.ear  
   petstore.ear  
   atm.ear PlugIn 
   Oracle HTTP Server  
   Globals.java  
   Globals.class  
   Globals$__jsp_StaticText.class  
   globals.ser  _index.java  _index.class  _index$__jsp_StaticText.class
   Start migration...
   
   

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

8. Review the log files.

9. Perform tests for each application you migrated.

Completing the Web Cache Migration

To complete the Web Cache migration, you may need to perform the following tasks. Use the administrator user interface to review and, if necessary, change the configuration as follows:

Note: If, because of a port conflict, the Web Cache administration process does not start, you must specify the correct administration port in the MULTIPORT element of the webcache.xml file, and restart Web Cache.

• Create the site-to-server mappings.

• To use the same Operations Port or Listening Port wallets as in Release 1, obtain the wallet information from Release 1 and modify the wallet information in Release 2, using the Administration user interface.

• Review post-installation user changes.

  The migration Assistant can be invoked any time after the Oracle9iAS Release 2 (9.0.2) installation. If changes were made to the webcache.xml file, they are preserved. There may be redundant cacheability rules. You must review the file to resolve these. The rules themselves, and the order in which they appear, determine the caching behaviors executed by Web Cache.

• Resolve any port conflicts introduced by the migration.

  Port numbers are not migrated from the webcache.xml file. Compare the Release 1 and Release 2 webcache.xml files to ensure that there are no port conflicts after the migration Assistant has executed.

  Web Cache does not migrate administration, listen, statistics, and invalidation port numbers. To use the Release 1 port numbers in Release 2, perform the following steps:

  1. Determine the Web Cache port numbers used in Release 1.

  2. Use the Administration user interface to change the port numbers in Release 2.

• Review session caching rules and resolve any duplications.

• Review expiration rules and resolve any duplications.

• Review multi-version cookies rules and resolve any duplications.

Restarting the Oracle9iAS Migration Assistant

You must restore the Oracle9iAS Release 2 (9.0.2) instance to its pre-migration condition before you restart the migration Assistant. Follow these steps:

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

2. Restore all configuration files and directories to their pre-migration state. (Use the log file to determine which files 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)" .