Oracle9i Application Server Migrating from Oracle9iAS Release 1 (1.0.2.2.x) to Release 2 (9.0.2) Release 2 (9.0.2) for Sun SPARC Solaris Part Number A96157-03 |
|
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.
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
Installing the Migration Assistant
Restarting the Oracle9iAS 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:
Before starting the Assistant, read the section for each option you plan to use.
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:
The Oracle HTTP Server migration option recognizes the following configuration files, programs, static documents, and modules as candidates for migration:
httpd.conf
file. (This file must be selected, or no other files will be migrated.)
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.
ORACLE_HOME_1/Apache/Apache/htdocs
with the exception of the following subdirectories:
webapp
onlineorders_html
manual
doc
_pages
ORACLE_HOME_1/Apache/Apache/htdocs/WEB-INF
(including subdirectories)
ORACLE_HOME_1/Apache/Apache/htdocs/demo
(including subdirectories)
Note:
|
Table 2-1 lists the default set of modules shipped in Oracle9iAS Release 1 (1.0.2.2.x).
Table 2-2 lists the directives found in both versions of the httpd.conf
file.
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
.
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. |
To migrate directives, the Assistant:
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). |
httpd.conf
file as follows:
httpd.conf
file.
httpd.conf
file.
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.
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:
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.
The migration Assistant manages SSL certificate key file and wallet passwords as follows:
The SSL directives in httpd.conf
are shown below for Oracle9iAS Release 2 (9.0.2) (IfModule) and Release 1 (IfDefine):
<IfModule mod_ossl.c> <VirtualHost _default_:4443> SSLWallet wallet location SSLVerifyClient optional SSLProtocol all </VirtualHost> </IfModule>
<IfDefine SSL> <VirtualHost _default_:443> SSLCertficateFile certificate locationSSLCertificateKeyFile
key locationSSLVerifyClient optional_no_ca SSLProtocol TLSv1 </VirtualHost> </IfDefine>SSLCertificateChainFile
chain location
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
The Assistant performs the following functions to provide a way to audit the migration process:
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.
ORACLE_HOME_2/migration/log/iASMigration.log
This section explains the functionality of the OC4J migration option. It contains the following topics:
The OC4J migration option recognizes these configuration files and applications as candidates for migration:
principals.xml
and data-sources.xml
files.
server.xml
file in the 1.0.2.2 instance, in .ear file format.
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:
No applications are migrated, since they were not found on the Oracle9iAS Release 1 (1.0.2.2.x) OC4J instance.
The OC4J migration option does the following:
principals.xml
and data-sources.xml
from ORACLE_HOME_1/J2EE to ORACLE_HOME_2/J2EE.
server.xml
file in ORACLE_HOME_1 and prompts you to select the applications to migrate.
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.
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.)
dcmctl validateEarFile -v -f simple.earNo J2EE XML/DTD validation errors were found
dcmctl validateEarFile -v -f petstore.earWarning: J2EE/DTD validation errors were foundADMN-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
.
The Assistant performs the following functions to provide a way to audit the migration process:
.SAVED_COPY
.
ORACLE_HOME_2/migration/log/iASMigration.log
This section explains the functionality of the Web Cache migration option. It contains the following topics:
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:
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.
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:
Any application that was using WEBCACHETAG with reference to the original Release 2 Web Cache session definition must be modified to use the re-named session definitions.
Warning:
The Web Cache migration option does the following:
webcache.xml
file from ORACLE_HOME_1 to ORACLE_HOME_2:
SECURESUBNET (Sub-element of SECURITY; trusted subnets).
Copied to the first SITE element of the webcache.xml
in ORACLE_HOME_2
.
Copied from the ORACLE_HOME_1 webcache.xml
file to the ORACLE_HOME_2 webcache.xml
file under the first SITE element.
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.
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.
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.
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.
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.
The Assistant performs the following functions to provide a way to audit the migration process:
webcache.xml
file from ORACLE_HOME_2. The backup file is named webcache.xml.backup
.
ORACLE_HOME_2/migration/log/iASMigration.log
This section provides information about hardware and software requirements for installation of Oracle9iAS Migration Assistant. The topics include:
The following table, Table 2-4, "Oracle9iAS Migration Assistant Hardware Requirements" contains the minimum hardware requirements for the Oracle9iAS Migration Assistant.
Table 2-4 Oracle9iAS Migration Assistant Hardware Requirements
Hardware Items | Minimum Requirements |
---|---|
CPUFoot 1 |
A SPARC Processor |
Memory |
128 MB |
Monitor |
256 color viewing capability |
1
Oracle recommends a multiple CPU computer. |
The Oracle9iAS Migration Assistant requires the following software:
Table 2-5 lists the Solaris Operating System patches you will need to download before installing Oracle9iAS Migration Assistant. The patches can be downloaded from:
http://sunsolve.sun.com
Operating System | Version |
---|---|
Solaris 2.6 |
|
Solaris 7 (2.7) |
|
Solaris 8 (2.8) |
Follow these steps to launch Oracle Universal Installer, which installs the Oracle9iAS Migration Assistant:
The Oracle Product Installation CD-ROM is in RockRidge format. If you are using the Solaris Volume Management software (installed by default with Sun SPARC Solaris), then the CD-ROM is mounted automatically to cdrom/9ias_supplemental
when you insert it in the disk drive.
If you are not using the Solaris Volume Management software, then you must mount the CD-ROM manually. 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.
prompt> mkdir mount_point
prompt> mount options device_name mount_point
prompt> exit
The following example mounts the CD-ROM manually on /cdrom,
without using the Solaris Volume Management software. Execute the following commands as root user.
prompt> mkdir /cdrom
prompt> mount -r -F hsfs device_n
ame /cdrom
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.
Note:
oracle
user.
prompt> mount_point/9ias_supplemental/runInstaller
The Welcome screen appears (Figure 2-1).
The File Locations screen appears (Figure 2-2).
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.
Note:
The Summary screen appears (Figure 2-3).
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.
The Install screen appears (Figure 2-4).
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).
This screen indicates the results of the installation process.
This section provides guidelines for preparing for a migration, and step-by-step instructions for starting and operating the Assistant.
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. |
Before you start the Assistant, be prepared with the following (as required for the components you plan to migrate):
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
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.
MigAssistant.sh
The Oracle Home screen appears (Figure 2-6).
If OC4J was not found in the Source... path you specified, the J2EE Home screen appears (Figure 2-7).
The Components screen appears (Figure 2-8). By default, all of the components are selected for migration.
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.
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.
If an SSL certificate file was found with a password other than the default 'welcome', the httpd.conf: Passwords screen appears (Figure 2-11).
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.
The Summary screen appears (Figure 2-13), showing your choices of Oracle homes, configuration files, and applications.
The Warning screen appears (Figure 2-14).
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.2 instance from a backup. For a description of backups and file names, see:
|
The Migration Status screen appears with a progress bar showing the percentage of the migration completed (Figure 2-15).
MigAssistantCmd.sh e
The following prompt appears:
Source Oracle home?
The following prompt appears:
Target Oracle home?
A prompt resembling the following appears.
Select compnents to migrate Migrate all components?[YES]n
The next prompt appears.
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]
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...
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
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:
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.
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:
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:
firstRun
from the Release 2 Oracle home directory.
"Using the Oracle9iAS Migration Assistant (GUI Version)"
or
"Using the Oracle9iAS Migration Assistant (Command Line Version)" .
|
Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|