Skip Headers

Oracle® Application Server 10g Upgrading from Release 1 (1.0.2.2.x) to 10g (9.0.4)
10g (9.0.4)
Part No. B13674-02
  Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index

Previous Next  

2 Upgrading the Oracle HTTP Server

This chapter contains step-by-step instructions for upgrading the Oracle HTTP Server. It contains the following sections:

2.1 Oracle HTTP Server Upgrade Items

An upgrade item is an aspect of configuration that is acted upon during upgrade: a file, executable, or a setting that you must add, change, or delete/replace in the 10g (9.0.4) installation. Oracle HTTP Server upgrade items are described in Table 2-1.

Table 2-1 Oracle HTTP Server Upgrade Items

Upgrade Item Location in Release 1 (1.0.2.2.x) Oracle home Location in 10g (9.0.4) Oracle home Notes
httpd.conf Apache/Apache/conf Apache/Apache/conf httpd.conf is the main configuration file for OHS. If this file is not located in its default location, <source_MT_OH>/Apache/Apache/conf in Oracle9iAS Release 1 (1.0.2.2.x) and you want it to be in a non-default location in 9.0.4, you must also modify the opmn.xml file (OPMN's configuration file) to reflect the non-default location.
User-defined configuration files

User-defined configuration files are the files defined recursively by Include directives in httpd.conf. Since mod_jserv and the JServ servlet engine have been replaced by mod_oc4j and OC4J, upgrading JServ is not discussed here.

The upgrade of component configuration files defined in or referenced by Include directives in oracle_apache.conf is not discussed in this chapter.

User-defined modules

User-defined modules are modules other than those listed in the default set of modules in "Modules Shipped in Release 1 (1.0.2.2)".
mod_ssl

This module was replaced with mod_ossl in Oracle9iAS Release 2 (9.0.2). Therefore, to upgrade to Oracle Application Server 10g (9.0.4), you must replace the SSL certificates with Oracle wallets. If you use SSL connections, you should upgrade SSL certificates to Oracle wallets.

For instructions on how to create Oracle wallets, see:

Oracle Application Server 10g Security Guide

cgi/fastcgi programs

You must locate all programs referenced in the configuration files and copy them to the corresponding locations in the 10g (9.0.4) Oracle home.
Static documents

You must locate all static documents and copy them to the corresponding locations in the 10g (9.0.4) Oracle home.

Modules Shipped in Release 1 (1.0.2.2)

2.2 Components Related to the Oracle HTTP Server

This section discusses the Oracle HTTP Server relationship to other components and describes the configuration tasks necessary to make the components work together.

2.2.1 Oracle Process Manager and Notification Server

The Oracle HTTP Server is managed by the Oracle Process Manager and Notification Server (OPMN) server. You must place the entry shown below in bold text in the opmn.xml file:

<ias-component id="HTTP_Server" status="enabled" id-matching="false">
 <process-type id="HTTP_Server" module-id="OHS"> 
    <process-set id="HTTP_Server" restart-on-death="true" numprocs="1">
      <module-data>
       <category id="start-parameters">
          <data id="config-file" value="/myconfs/httpd.conf"/>  
          <data id="start-mode" value="ssl-enabled"/>
        </category>
...

The "config-file" module-data directive in the first line of the OPMN entry specifies the location of the httpd.conf file. If is not in the default location after upgrade, enter its full path as the value for the "config-file" directive. If the Oracle HTTP Server uses an SSL connection, set the "start-mode" module-data directive value to "ssl-enabled".

2.2.2 Oracle Application Server Web Cache

If Oracle Application Server Web Cache is configured as the first listener, ensure that the Oracle HTTP Server directives listed in Table 2-2 have the same values as the corresponding OracleAS Web Cache elements. In particular, note that the Oracle HTTP Server Port directive specifies the port number of a front-end load balancer or reverse proxy. Thus, if Oracle Application Server Web Cache is used, then the Oracle HTTP Server Port directive should have the value of the port on which OracleAS Web Cache is listening.

Table 2-2 Oracle HTTP Server and Oracle Application Server Web Cache Port Settings

Oracle HTTP Server Directive Oracle Application Server Web Cache Element
VirtualHost Site definitions
Listen Origin server ports
VirtualHost, Listen Site-to-server mappings
Port Listen

2.3 Oracle HTTP Server Upgrade Tasks

This section provides instructions for upgrading each item identified in Section 2.1, "Oracle HTTP Server Upgrade Items". It is divided into the following subsections:

2.3.1 Upgrading the httpd.conf File

Since the file is quite large, it is useful to begin with an exhaustive listing of the changes to the file since installation, and a general idea of the customizations represented. Use a file comparison utility to compare:

<source_MT_OH>/Apache/Apache/conf/httpd.conf

to

<source_MT_OH>/Apache/Apache/conf/httpd.conf.default

The results of the comparison will identify all changes made to the file since installation. These changes to the file represent two types of customizations:

  • Changes made to default directive settings throughout the file (which were initially set by the installer). To upgrade these, you must modify the directives throughout <destination_MT_OH>/Apache/Apache/conf/httpd.conf to reflect the same settings. Table 2-3 shows the changes to default settings.

  • Directives added (typically, appended to the end of the file). To upgrade these, you must copy them to the end of the <destination_MT_OH>/Apache/Apache/conf/httpd.conf file, replacing any path values to reflect the new Oracle home location.

Table 2-3 Changes to Default Oracle HTTP Server Directives and Settings

Upgrade Item Release 1 (1.0.2.2.x) Setting 10g (9.0.4) Setting Status Remarks
oprocmgr (process manager for JServ) LoadModule oprocmgr_module libexec/liboprocmgr.so None Removed OPMN is the process manager for OC4J; JServ no longer used
SSL <IfDefine SSL>LoadModule ssl_module libexec/mod_ssl.so</IfDefine> LoadModule ossl_module libexec/mod_ossl.so Changed mod_ossl replaced mod_ssl. In 10g (9.0.4), mod_ossl is always loaded.
SSL Configuration

Relocated and changed
Dynamic Monitoring Service (DMS) LoadModule dms_module libexec/mod_dms.so Not applicable Relocated In 10g (9.0.4), DMS has its own configuration file, dms.conf. The LoadModule directive for mod_dms has been moved to that file.
mod_rewrite LoadModule rewrite_module libexec/mod_rewrite.so Same Relocated To avoid the conflict of mod_osso and mod_oc4j to process the request, this module's location has to be moved to the end.
MaxSpareServers directive 10 20 Value changed On UNIX systems, the maximum number of child processes that are not handling a request.

This directive has no effect on Windows systems.

ErrorLog


If this directive specifies a new location for the log file, ensure that the specified directory structure is present. If it is not, Oracle HTTP Server will not start.
CustomLog


If this directive specifies a new location for the log file, ensure that the specified directory structure is present. If it is not, Oracle HTTP Server will not start.
<Directory/> Options directive in this container does not have MultiViews set Options directive in this container has MultiViews set

Alias /javacachedocs This directive not present
Added
Alias /perl/ Not in an <IfModule> container <IfModule mod_perl.c>

   Alias /perl/

</IfModule>

Changed
Alias /soapdocs/ This directive is used This directive is not used Removed
<Location /server-status>

</Location>



The Allow directive in this <Location> container has changed.
SetEnv Perl

Relocated
DirectoryMatch for WEB_INF directory
<DirectoryMatch /WEB_INF/> Added
IfModule mod_fastcgi.c>

...

...

  SSLOptions

  +StdEnvVars

...

...

</IfModule>

<IfDefine SSL>

...

  SSLOptions

...

</IfDefine>

<IfModule mod_ossl.c>

...

  SSLOptions

...

</IfModule>

Changed
PassEnv directives No PassEnv directives used PassEnv ORACLE_HOME

PassEnv LIBRARY_PATH

PassEnv NLS_LANG

PassEnv TNS_ADMIN

Added

2.3.2 Upgrading Port and Listen Directives

In a production environment, you will not want port assignments to change as part of the upgrade. The installer assigns a new set of ports for the Port and Listen directives. When you upgrade, you want to retain the ports from the previous installation, discarding those assigned during installation of 10g (9.0.4).

Beginning with 10g (9.0.4), the installer no longer assigns port 80 for http requests and port 443 for https requests, since it is common to use a load balancer such as OracleAS Web Cache in front of the Oracle HTTP Server. So, in practice, Oracle HTTP Server rarely listens on ports 80 and 443.

Configure the port directives as required by your environment, with the following points in mind:

  • If you choose to install OracleAS Web Cache, the Oracle HTTP Server Port directive and the OracleAS Web Cache Listen element will be different. Port is the port that OracleAS Web Cache listens on, and Listen is the port Oracle HTTP Server listens on. By default, the values differ by 1.

  • If you have port-based virtual hosts, you might want to put Listen near the virtual host section in the httpd.conf file. The port value for the virtual host should differ from the Listen port value by 1 if OracleAS Web Cache is installed.

2.3.3 Upgrading Module-Specific Directives

In 10g (9.0.4), a new convention for module-specific directives is observed in the httpd.conf file: they are placed inside of an <IfModule> container. Directives related to mod_dms, mod_ossl, and mod_oc4j now observe this convention.

For example, in Release 1 (1.0.2.2.x), module-specific directives may appear as name-value pairs, such as:

AA aa 
BB bb

In 10g (9.0.4), you should configure these directives in the following manner:

<IfModule mod_mymod.c>
   AA aa
   BB bb
</IfModule>

In addition, extract all configuration related to DMS from the httpd.conf file in Release 1 (1.0.2.2.x) into the dms.conf file in the 10g (9.0.4) installation. Do the same for all SSL-related configuration, placing it into ssl.conf. Remove all mod_oprocmgr configuration and the mod_jserv.conf file, since these are deprecated.

2.3.4 Upgrading User-defined Configuration Files

If user-defined configuration files are part of your system, follow these steps to upgrade them.

  1. Find these files by searching <source_MT_OH>/Apache/Apache/conf/httpd.conf recursively for Include directives.

  2. Copy the files from <source_MT_OH> to <destination_MT_OH>. If the files are not located in <source_MT_OH>, save a backup copy of the files and make the necessary changes (Steps 3 and 4) in-place, in the original files.

  3. Edit the files to reflect the new Oracle home path.

  4. Restructure the files, if necessary.

2.3.5 Upgrading User-Defined Dynamic Module Libraries

If you have added dynamic module libraries to your system (on UNIX, these files have an .so extension; on Windows, a .dll extension), follow these steps to upgrade them.

  1. Find these files by searching <source_MT_OH>/Apache/Apache/conf/httpd.conf recursively for LoadModule directives.

  2. Copy the files from <source_MT_OH> to <destination_MT_OH>. (If the files are not located in <source_MT_OH>, and <destination_MT_OH> is on the same computer, no action is necessary.)

2.3.6 Upgrading CGI and FastCGI Programs

CGI scripts can be enabled in two ways: ScriptAlias or ScriptAliasMatch directives enable a URL inside the directory specified by the DocumentRoot directive to be mapped onto a valid directory name, identifying that directory as one containing executable scripts. The other way is to use the ExecCGI option, specified in an Options directive.

To upgrade the CGI scripts, identify them using the directory or file references in the directives in <source_MT_OH>/Apache/Apache/conf/httpd.conf (and other configuration files, if applicable) and copy them to <destination_MT_OH>. (If the files are not located in <source_MT_OH>, and <destination_MT_OH> is on the same computer, no action is necessary.)

2.3.7 Upgrading Static Documents

The DocumentRoot directive specifies the location of static documents and their related directories. The base server and each virtual host can define a document root; you must copy all static documents in each location in <source_MT_OH> to the corresponding location in <destination_MT_OH>.

2.3.8 Upgrading SSL Certificates

Upgrading from Release 1 (1.0.2.2.x) to 10g (9.0.4) introduces a significant change in the security configuration of the Oracle HTTP Server: mod_ossl replaces mod_ssl, which requires that SSL certificates be replaced with Oracle wallets.

If you have not replaced the SSL certificate since installation, and did not add new SSL certificates, then you do not need to perform these steps. However, if you replaced the installer-created SSL certificate with a certificate of your own, use the osslconvert utility to generate the Oracle wallet.

Issue these commands:

  1. Issue these commands:

    export ORACLE_HOME=<destination_MT_OH>

    export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH

  2. Execute the osslconvert utility with this command:

    run <destination_MT_OH>/Apache/Apache/bin/osslconvert -cert <source_MT_OH certificate file> -key <source_MT_OH private key file>

    where:

    • <source_MT_OH certificate file> is the path and filename of the certificate file in the Release 1 (1.0.2.2.x) Oracle home.

    • <source_MT_OH private key file> is the path and filename of the private key file in the Release 1 (1.0.2.2.x) Oracle home.

    The utility takes other parameters, described below:

    • -chain <source_MT_OH certificate chain file>

    • -capath <source_MT_OH certificate authority path>

    • -cafile  <source_MT_OH certificate authority file>

    • -wallet <destination_MT_OH wallet full path>

    • -certpass <password for source_MT_OH certificate>

    • -wltpass <password for destination_MT_OH wallet>

    • -ssowallet <yes | no>

    • -validate <yes | no>

2.3.8.1 Modifying SSL-Related Directives

Upgrading from Release 1 (1.0.2.2.x) to 10g (9.0.4) introduces a significant change in the security configuration of the Oracle HTTP Server: mod_ossl replaces mod_ssl, so SSL-related directives must be changed.

The mod_ossl module does not use the directives listed below. The Oracle HTTP Server will not start if they are used. The following directives are replaced by SSLWallet in 10g (9.0.4):

  • SSLCertificateFile

  • SSLCertificateKeyFile

  • SSLCertificateChainFile

  • SSLCACertificatePath

  • SSLCACertificateFile

  • SSLRandomSeed

  • SSLVerifyDepth

Example 2-1 shows the SSL directives used in Release 1 (1.0.2.2.x), and Example 2-2 shows the directives used in 10g (9.0.4).

Example 2-1 SSL Directives in Release 1 (1.0.2.2.x)

<IfDefine SSL>
   <VirtualHost _default_:443>
     SSLCertficateFile certificate location
     SSLCertificateKeyFile key location
     SSLCertificateChainFile chain location
     SSLVerifyClient optional_no_ca
     SSLProtocol TLSv1
   </VirtualHost>
</IfDefine>

Example 2-2 SSL Directives in 10g (9.0.4)

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

Two directive settings may require change:

  • SSLVerifyClient no longer takes optional_no_ca as a valid value. If it is set, change the setting to optional.

  • If Set SSLProtocol was set to TLSv1, change it to all.


Tip:

Refer to the Oracle9i Application Server Security Guide in the Release 2 (9.0.2) documentation library, Chapter 4, "Configuring HTTP Server Security", particularly the section titled "Using Secure Sockets Layer (SSL) to Authenticate Users". All SSL configuration directives are described in detail there. Chapter 5, "using Oracle Wallet Manager", explains how to create and manage Oracle wallets.

2.4 Validating the Oracle HTTP Server Upgrade

After you complete the upgrade tasks, ensure that the upgraded version of the Oracle HTTP Server is working as expected. Steps 1 through 5 below validate that the server will start in SSL mode, and is correctly configured to be managed by Oracle Process Manager and Notification Server (OPMN). You must devise and perform specific tests for applications and configuration elements that are unique to your site.

Example 2-3 shows a portion of the <destination_MT_OH>/opmn/conf/opmn.xml file, the configuration file for OPMN.

Example 2-3 Oracle HTTP Server Entries in OPMN Configuration File

<ias-component id="HTTP_Server" status="enabled" id-matching="false">
  <process-type id="HTTP_Server" module-id="OHS">
   <process-set id="HTTP_Server" restart-on-death="true" numprocs="1">
       <module-data>
     <category id="start-parameters">
          <data id="config-file" value="/myconfs/httpd.conf"/>
      <data id="start-mode" value="ssl-enabled"/>
 </category>
...

  1. If the Oracle HTTP Server configuration file is not in the default location <destination_MT_OH>/Apache/Apache/conf/httpd.conf after upgrade, you must specify the location to OPMN. Edit the line as shown below to include the location and filename (replacing httpd.conf with the filename, if it is different):

    <data id="config-file" value="/<path to file>/httpd.conf"/>

  2. If an SSL connection is used, set the start mode to SSL, as shown:

    <data id="start-mode" value="ssl-enabled"/>

  3. If OPMN is not running, start it with this command:

    opmnctl start

  4. Use OPMN to start the Oracle HTTP Server by issuing this command:

    opmnctl startproc ias-component=HTTP_Server

  5. Test the SSL connection by accessing http:// and https:// URLs.

  6. Invoke CGI and FastCGI programs and verify that they function as expected.

  7. Perform a test for each application configured in your site.