2
Migrating the Oracle HTTP Server

This chapter describes the functionality of the Migration Assistant in migrating the Oracle HTTP Server (OHS), and lists the elements migrated for each component. It contains the following topics:

• Oracle HTTP Server Migration Candidates

• HTTP Server Elements Not Migrated

• The Oracle HTTP Server Directive Migration Process

• Backup and Auditing Measures for Oracle HTTP Server Migration

Oracle HTTP Server Migration Candidates

This section describes the configuration files, programs, static documents, and modules that the Migration Assistant recognizes as candidates for migration in Oracle HTTP Server directories.

The httpd.conf File

The Assistant migrates the httpd.conf file.

On UNIX systems, its location is:

ORACLE_HOME_1/Apache/Apache/conf

On Windows systems its location is:

ORACLE_HOME_1\Apache\Apache\conf

This file must be selected, and the Migration Assistant must be able to parse it. If it is not selected or cannot be parsed, no other OHS files will be migrated.

User-defined Configuration Files

The Assistant migrates any user-defined configuration file named in an Include directive in httpd.conf (and, recursively, any user-defined configuration file named in an Include directive in the parent user-defined configuration file). The parent user-defined configuration file must be selected. If it is not selected, none of the child user-defined configuration files will be selected. Each user-defined configuration file found in ORACLE_HOME_1 is re-created in the corresponding location in ORACLE_HOME_2.

cgi and fastcgi Programs

The Assistant migrates non-default cgi and fastcgi programs found in the following directories only:

On UNIX systems, their location is:

ORACLE_HOME_1/Apache/Apache/cgi-bin

ORACLE_HOME_1/Apache/Apache/fcgi-bin

On Windows systems their location is:

ORACLE_HOME_1\Apache\Apache\fcgi-bin

ORACLE_HOME_1\Apache\Apache\cgi-bin

Static Documents and Directories

The Assistant migrates non-default static documents or directories that it finds in the default location for static documents.

On UNIX systems, the default location is:

ORACLE_HOME_1/Apache/Apache/htdocs

On Windows systems, the default location is:

ORACLE_HOME_1\Apache\Apache\htdocs

If you have placed customized files in default sub-directories of htdocs, you must migrate them manually.

When migrating from Release 1, the Assistant migrates any non-default files or directories in the subdirectories of htdocs.

On UNIX systems:

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

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

On Windows systems:

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

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

Note: index.html exists in the source and target Oracle homes. To determine whether customization has occurred, compare the file's contents to the default index.html. Migrating from 1.0.2.2: The Migration Assistant compares the file sizes to determine whether it should migrate the file. However, note that it is possible that file sizes could be the same, and the contents could differ between the source and target Oracle homes. In 1.0.2.2, the default size is 2183 bytes. Migrating from 9.0.2: The index.html file must be migrated manually.

The Assistant migrates static documents or directories that are defined by the DocumentRoot directive.

Shared Object (.so) and Dynamic Link Library (.dll) Files

The Assistant migrates the .so files on UNIX systems, or the .dll files on Windows systems, for any modules that are not in the Oracle9iAS Release 1 (1.0.2.2.x) or Oracle9iAS Release 2 (9.0.2) default set, but are 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 Oracle9iAS Release 1 (1.0.2.2.x) Modules

Module Name
access_module	dir_module	oprocmgr_module
action_module	dms_module	perl_module
agent_log_module	env_module	proxy_module
alias_module	example_module	referer_log_module
anon_auth_module	expires_module	rewrite_module
asis_module	fastcgi_module	setenvif_module
auth_module	headers_module	speling_module
autoindex_module	imap_module	ssl_module
cern_meta_module	includes_module	status_module
cgi_module	info_module	unique_id_module
config_log_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

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

Table 2-2 Default Oracle9iAS Release 2 (9.0.2) Modules

Module Name
access_module	dir_module	oc4j_module
action_module	dms_module	ossl_module
agent_log_module	env_module	perl_module
alias_module	example_module	proxy_module
anon_auth_module	expires_module	referer_log_module
asis_module	fastcgi_module	rewrite_module
auth_module	headers_module	setenvif_module
autoindex_module	imap_module	speling_module
cern_meta_module	includes_module	status_module
cgi_module	info_module	unique_id_module
config_log_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

Default Directives in Source and Target Versions of httpd.conf

The directives listed in Table 2-3 occur in the default versions of the httpd.conf files in the source and target instances.

Table 2-3 Default Directives

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

The Assistant highlights any differences between the directives in the source and target files 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 "myDirectory">

Options FollowSymLinks MultiViews

AllowOverride None

</Directory>

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

HTTP Server Elements Not Migrated

The following Oracle HTTP Server elements are not migrated:

• JServ - JServ is no longer supported; Release 1 (1.0.2.2) supported it for legacy use only. The current servlet container is Oracle9iAS Containers for J2EE (OC4J).

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

• Static documents in non-default locations of ORACLE_HOME_1 - The Migration Assistant will not migrate static documents that are in ORACLE_HOME_1 in locations other than ORACLE_HOME_1/Apache/Apache/htdocs (UNIX) or ORACLE_HOME_1\Apache\Apache\htdocs (Windows).

  If static documents are found in non-default locations of ORACLE_HOME_1, a message is written to the log file as a reminder to migrate them manually.

• cgi or fastcgi programs in non-default locations of ORACLE_HOME_1 - The Migration Assistant will not migrate cgi or fastcgi programs that are in ORACLE_HOME_1 in locations other than ORACLE_HOME_1/Apache/Apache/cgi-bin or fcgi-bin (UNIX) or ORACLE_HOME_1\Apache\Apache\cgi-bin or fcgi-bin (Windows).

  If cgi or fastcgi programs are found in non-default locations of ORACLE_HOME_1, a message is written to the log file as a reminder to migrate them manually.

• cgi or fastcgi applications not defined by the ScriptAlias directive - The Migration Assistant will not migrate cgi or fastcgi applications defined by means other than the ScriptAlias directive. You must migrate these manually.

• mod_osso.conf or mod_oc4j.conf - These configuration files are not migrated from Release 2 (9.0.2) to Release 2 (9.0.3).

A Note About Web Cache and Oracle HTTP Server

If you are migrating an Oracle HTTP Server that ran behind Web Cache in the previous release, you should look closely at the port configuration in both components to ensure that the desired port configuration is preserved in the migration. Specifically, the VirtualHost, Port, and Listen directives have corresponding Web Cache elements that need to specify the same ports.

See "Synchronizing Oracle9iAS Web Cache and Oracle HTTP Server Ports".

The Oracle HTTP Server Directive Migration Process

To migrate directives, the Assistant:

1. Presents directives in the source 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 (UNIX) ORACLE_HOME_1\Apache\Apache\myAlias (Windows) will appear on the screen as ORACLE_HOME_2/Apache/Apache/myAlias (UNIX) ORACLE_HOME_2\Apache\Apache\myAlias (Windows)

2. Writes selected directives to a difference file.

3. Merges the difference file with the Release 2 (9.0.3) httpd.conf file as follows:
   • Default directives with changed settings replace the corresponding directives in the Release 2 (9.0.3) httpd.conf file.

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

4. Discards JServ directives.

Migration of SSL Settings from Oracle9iAS Release 1 (1.0.2.2.x)

When you migrate from Release 1, the Assistant automatically creates a directive for mod_ossl, SSLWallet, based on the Release 1 configuration. It then starts a program called osslconvert 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 is 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 directives in the Release 1 httpd.conf file.

Note: The Release 1 default SSL certificate is signed by the certificate authority 'oracle demoCA'. Before migration, you must set the SSLCertificateChainFile directive to point to the default SSL certificate or the purchased certificate. The directive setting for the default certificate is: SSLCertificateChainFile ORACLE_HOME_1/Apache/Apache/conf/ssl.crt/demoCAcert.crt (UNIX) SSLCertificateChainFile ORACLE_HOME_1\Apache\Apache\conf\ssl.crt\demoCAcert.crt (Windows)

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

Table 2-4 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 (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 (UNIX)

ORACLE_HOME_2\Apache\Apache\conf\ssl.wlt\certificate name (Windows)

Wallet Generation for Default Virtual Host

The Assistant automatically generates the wallet for any virtual host that is SSL-enabled. The default httpd.conf file only defines one virtual host.

On UNIX systems, if you override the certificate that is associated with the virtual host named in the Release 1 httpd.conf file, the Assistant modifies the Release 2 httpd.conf file during migration so that it points to the newly generated wallet.

On Windows systems, if you override the certificate that is associated with the virtual host named in the Release 1 httpd.conf file, you can manually modify the Release 2 httpd.conf file after migration so that it points to the newly generated wallet.

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 target 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 (UNIX)

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