Skip Headers

Oracle® HTTP Server Administrator's Guide
10g Release 1 (10.1)

Part Number B12255-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

7
Oracle HTTP Server Modules

This chapter describes the modules (mods) included in the Oracle HTTP Server. The modules extend the basic functionality of the Web server, and support integration between Oracle HTTP Server and other Oracle Database components.

Documentation from the Apache Software Foundation is referenced when applicable.


Note:

Readers using this guide in PDF or hard copy formats will be unable to access third-party documentation, which Oracle provides in HTML format only. To access the third-party documentation referenced in this guide, use the HTML version of this guide and click the hyperlinks.


List of Modules

Table 7-1 lists all the Oracle HTTP Server modules discussed in this chapter.

Table 7-1 Oracle HTTP Server Modules

Oracle HTTP Server Modules

mod_access

mod_actions

mod_alias

mod_asis

mod_auth

mod_auth_anon

mod_auth_db

mod_auth_dbm

mod_auth_digest

mod_autoindex

mod_cern_meta

mod_certheaders

mod_cgi

mod_define

mod_digest

mod_dir

mod_dms

mod_env

mod_example

mod_expires

mod_fastcgi

mod_headers

mod_imap

mod_include

mod_info

mod_isapi

mod_log_agent

mod_log_config

mod_log_referer

mod_mime

mod_mime_magic

mod_mmap_static

mod_negotiation

mod_onsint

mod_ossl

mod_perl

mod_plsql

mod_proxy

mod_rewrite

mod_setenvif

mod_so

mod_speling

mod_status

mod_unique_id

mod_userdir

mod_usertrack

mod_vhost_alias

 

mod_access

Controls access to the server based on characteristics of a request, such as hostname or IP address.

See Also:

Module mod_access in the Apache Server documentation.

mod_actions

Enables execution of CGI scripts based on file type or request method.

See Also:

Module mod_actions in the Apache Server documentation.

mod_alias

Enables manipulation of URLs in processing requests. It provides mapping between URLs and filesystem paths, and URL redirection capabilities.

See Also:

Module mod_alias in the Apache Server documentation.

mod_asis

Enables sending files that contain their own HTTP headers. It is not supported by Oracle.

See Also:

Module mod_asis" in the Apache Server documentation.

mod_auth

Enables user authentication with files based user lists.

See Also:

Module mod_auth in the Apache Server documentation.

mod_auth_anon

Enables anonymous user access to protected areas (similar to anonymous FTP, where the email addresses can be logged).

See Also:

Module mod_auth_anon in the Apache Server documentation.

mod_auth_db

Uses Berkeley DB files to provide user authentication.

This module is disabled in the Oracle HTTP Server and is not supported by Oracle.

mod_auth_dbm

Uses DBM files to provide user authentication.

This module is not supported by Oracle.

mod_auth_digest

Uses MD5 Digest Authentication to provide user authentication.

This module is not supported by Oracle.

mod_autoindex

Generates directory indexes automatically.

See Also:

Module mod_autoindex in the Apache Server documentation.

mod_cern_meta

Emulates CERN (Conseil Europeen pour le Recherche Nucleaire) HTTPD metafile semantics. Metafiles are additional HTTP headers that can be produced for each file the server accesses, in addition to the typical set.

This module is not supported by Oracle.

mod_certheaders

Enables reverse proxies that terminate SSL connections in front of Oracle HTTP Server to transfer information regarding SSL connection, such as SSL client certificate information, to Oracle HTTP Server, and applications running behind Oracle HTTP Server. This information is transferred from the reverse proxy to Oracle HTTP Server using HTTP headers. The information is transferred from the headers to the standard CGI environment variable, which mod_ossl or mod_ssl populates if the SSL connection is terminated by Oracle HTTP Server. It also enables certain requests to be treated as HTTPS requests even though they are received through HTTP.

Perform the following steps to configure mod_certheaders:

  1. Configure Oracle HTTP Server to load mod_certheaders. To do this, add a LoadModule directive to httpd.conf file.
    • UNIX: LoadModule certheaders_module libexec/mod_certheaders.so
    • Windows: LoadModule certheaders_module modules/ApacheModuleCertHeaders.dll
  2. Specify which headers should be translated to CGI environment variables. This can be achieved by using the AddCertHeader directive. This directive takes a single argument, which is the CGI environment variable that should be populated from a HTTP header on incoming requests. For example, to populate the SSL_CLIENT_CERT CGI environment variable, add the following line to httpd.conf:
    AddCertHeader SSL_CLIENT_CERT
    
    

    The AddCertHeader directive can be a global setting if it is placed in the base virtual server section of httpd.conf. It can be specific to a single virtual host by placing it within a virtual host container, or it can be specific to a set of URIs by placing it within a <Directory> or <Location> container directive within httpd.conf. The combination of these directives are additive, so that for a given URI, all directives that are specific to that URI will be added to any that are specific to that request's virtual host, which will be added to any that is defined for that base virtual host.

    Table 7-2 lists all the supported CGI environment variables with their corresponding HTTP header names.

    Table 7-2 CGI Environment Variables with Corresponding Header Names
    CGI Variable Header Name CGI Variable Header Name

    SSL_PROTOCOL

    SSL-Protocol

    SSL_SESSION_ID

    SSL-Session_Id

    SSL_CIPHER

    SSL-Cipher

    SSL_CIPHER_EXPORT

    SSL-Cipher-Export

    SSL_CIPHER_ALGKEYSIZE

    SSL-Cipher-Algkeysize

    SSL_VERSION_LIBRARY

    SSL-Version-Library

    SSL_CLIENT_CERT

    SSL-Client-Cert

    SSL_VERSION_INTERFACE

    SSL-Version-Interface

    SSL_CLIENT_CERT_CHAIN_n

    SSL-Client-Cert-Chain-n

    SSL_CIPHER_USEKEYSIZE

    SSL-Cipher-Usekeysize

    SSL_CLIENT_VERIFY

    SSL-Client-Verify

    SSL_SERVER_CERT

    SSL-Server-Cert

    SSL_CLIENT_M_VERSION

    SSL-Client-M-Version

    SSL_SERVER_M_VERSION

    SSL-Server-M-Version

    SSL_CLIENT_M_SERIAL

    SSL-Client-M-Serial

    SSL_SERVER_M_SERIAL

    SSL-Server-M-Serial

    SSL_CLIENT_V_START

    SSL-Client-V-Start

    SSL_SERVER_V_END

    SSL-Server-V-End

    SSL_CLIENT_V_END

    SSL-Client-V-End

    SSL_SERVER_V_END

    SSL-Server-V-End

    SSL_CLIENT_S_DN

    SSL-Client-S-DN

    SSL_SERVER_S_DN

    SSL-Server-S-DN

    SSL_CLIENT_S_DN_C

    SSL-Client-S-DN-C

    SSL_SERVER_S_DN_C

    SSL-Server-S-DN-C

    SSL_CLIENT_S_DN_ST

    SSL-Client-S-DN-ST

    SSL_SERVER_S_DN_ST

    SSL-Server-S-DN-ST

    SSL_CLIENT_S_DN_L

    SSL-Client-S-DN-L

    SSL_SERVER_S_DN_L

    SSL-Server-S-DN-L

    SSL_CLIENT_S_DN_O

    SSL-Client-S-DN-O

    SSL_SERVER_S_DN_O

    SSL-Server-S-DN-O

    SSL_CLIENT_S_DN_OU

    SSL-Client-S-DN-OU

    SSL_SERVER_S_DN_OU

    SSL-Server-S-DN-OU

    SSL_CLIENT_S_DN_CN

    SSL-Client-S-DN-CN

    SSL_SERVER_S_DN_CN

    SSL-Server-S-DN-CN

    SSL_CLIENT_S_DN_T

    SSL-Client-S-DN-T

    SSL_SERVER_S_DN_T

    SSL-Server-S-DN-T

    SSL_CLIENT_S_DN_I

    SSL-Client-S-DN-I

    SSL_SERVER_S_DN_I

    SSL-Server-S-DN-I

    SSL_CLIENT_S_DN_G

    SSL-Client-S-DN-G

    SSL_SERVER_S_DN_G

    SSL-Server-S-DN-G

    SSL_CLIENT_S_DN_S

    SSL-Client-S-DN-S

    SSL_SERVER_S_DN_S

    SSL-Server-S-DN-S

    SSL_CLIENT_S_DN_D

    SSL-Client-S-DN-D

    SSL_SERVER_S_DN_D

    SSL-Server-S-DN-D

    SSL_CLIENT_S_DN_UID

    SSL-Client-S-DN-Uid

    SSL_SERVER_S_DN_UID

    SSL-Server-S-DN-Uid

    SSL_CLIENT_S_DN_Email

    SSL-Client-S-DN-Email

    SSL_SERVER_S_DN_Email

    SSL-Server-S-DN-Email

    SSL_CLIENT_I_DN

    SSL-Client-I-DN

    SSL_SERVER_I_DN

    SSL-Server-I-DN

    SSL_CLIENT_I_DN_C

    SSL-Client-I-DN-C

    SSL_SERVER_I_DN_C

    SSL-Server-I-DN-C

    SSL_CLIENT_I_DN_ST

    SSL-Client-I-DN-ST

    SSL_SERVER_I_DN_ST

    SSL-Server-I-DN-ST

    SSL_CLIENT_I_DN_L

    SSL-Client-I-DN-L

    SSL_SERVER_I_DN_L

    SSL-Server-I-DN-L

    SSL_CLIENT_I_DN_O

    SSL-Client-I-DN-O

    SSL_SERVER_I_DN_O

    SSL-Server-I-DN-O

    SSL_CLIENT_I_DN_OU

    SSL-Client-I-DN-OU

    SSL_SERVER_I_DN_OU

    SSL-Server-I-DN-OU

    SSL_CLIENT_I_DN_CN

    SSL-Client-I-DN-CN

    SSL_SERVER_I_DN_CN

    SSL-Server-I-DN-CN

    SSL_CLIENT_I_DN_T

    SSL-Client-I-DN-T

    SSL_SERVER_I_DN_T

    SSL-Server-I-DN-T

    SSL_CLIENT_I_DN_I

    SSL-Client-I-DN-I

    SSL_SERVER_I_DN_I

    SSL-Server-I-DN-I

    SSL_CLIENT_I_DN_G

    SSL-Client-I-DN-G

    SSL_SERVER_I_DN_G

    SSL-Server-I-DN-G

    SSL_CLIENT_I_DN_S

    SSL-Client-I-DN-S

    SSL_SERVER_I_DN_S

    SSL-Server-I-DN-S

    SSL_CLIENT_I_DN_D

    SSL-Client-I-DN-D

    SSL_SERVER_I_DN_D

    SSL-Server-I-DN-D

    SSL_CLIENT_I_DN_UID

    SSL-Client-I-DN-Uid

    SSL_SERVER_I_DN_UID

    SSL-Server-I-DN-Uid

    SSL_CLIENT_I_DN_Email

    SSL-Client-I-DN-Email

    SSL_SERVER_I_DN_Email

    SSL-Server-I-DN-Email

    SSL_CLIENT_A_SIG

    SSL-Client-A-Sig

    SSL_SERVER_A_SIG

    SSL-Server-A-Sig

    SSL_CLIENT_A_KEY

    SSL-Client-A-Key

    SSL_SERVER_A_KEY

    SSL-Server-A-Key

  3. mod_certheaders can be used to instruct Oracle HTTP Server to treat certain requests as if they were received through HTTPS even though they were received through HTTP. This is useful when Oracle HTTP Server is front-ended by a reverse proxy or load balancer, which acts as a termination point for SSL requests, and forwards the requests to Oracle HTTP Server through HTTPS.

    For load balancers, mod_certheaders must be explicitly configured to determine which requests should be treated as HTTPS requests. To do this, use the following directive:

    SimulateHttps on
    
    

    SimulateHttps can be embedded within a virtual host, such as:

    <VirtualHost localhost:7777>
        SimulateHttps on
        .
        .
        .
    </VirtualHost>
    
    

    This tells mod_certheaders to treat every request handled by this virtual host as HTTPS, or the directive can be placed within a <LocationMatch>, <Directory>, or <DirectoryMatch> directive container such as:

    <Location /foo/>
        SimulateHttps on
    </Location>
    
    

    This limits it to URLs starting with /foo/.

mod_cgi

Enables the server to run CGI scripts.

See Also:

Module mod_cgi in the Apache Server documentation.

mod_define

Enables the Define directive, which defines a variable that can be expanded on any configuration line. The Define directive has the status Extension, which means that it is not compiled into the server by default.

This module requires the Extended API (EAPI). Oracle HTTP Server always has EAPI-enabled.

This module is available on UNIX systems only.

mod_digest

Uses an older version of the MD5 Digest Authentication specification than that used in mod_auth_digest to provide user authentication. mod_digest probably only works with older browsers.

See Also:

Module mod_digest in the Apache Server documentation.

mod_dir

Enables the server to perform slash (/) redirects. Directories must contain a trailing slash. If a request for a URL without a trailing slash is received, mod_dir redirects the request to the same URL followed by a trailing slash. For example:

http://myserver/documents/mydirectory

is redirected to

http://myserver/documents/mydirectory/


See Also: Module mod_dir in the Apache Server documentation.

mod_dms

Enables you to monitor performance of site components with Oracle's Dynamic Monitoring Service (DMS).

See Also:

Oracle Application Server 10g Performance Guide

mod_env

Enables you to control the environment for CGI scripts and SSI (Server Side Includes) pages by passing, setting, and unsetting environment variables.

See Also:

Module mod_env in the Apache Server documentation.

mod_example

Provides examples and guidance on how to write modules using the Apache API. When implemented, it demonstrates module callbacks triggered by the server.

This module is not supported by Oracle.

mod_expires

Enables the server to generate Expires HTTP headers, which provide information to the client about document validity. Documents are served from the source if, based on the expiration criteria, the cached copy has expired.

See Also:

Module mod_expires in the Apache Server documentation.

mod_fastcgi

Supports the FastCGI protocol, which enables you to maintain a pool of running servers for CGI applications, thereby eliminating start-up and initialization overhead.

See Also:

Module mod_fastcgi in the Apache Server documentation.

mod_headers

Enables you to merge, replace, or remove HTTP response headers.

See Also:

Module mod_headers in the Apache Server documentation.

mod_imap

Enables server-side image map processing.

This module is not supported by Oracle.

mod_include

Provides a filter that processes documents for SSI (Server Side Includes) directives.

See Also:

Module mod_include in the Apache Server documentation.

mod_info

Summarizes the entire server configuration, including all installed modules and directive settings.

See Also:

Module mod_info in the Apache Server documentation.

mod_isapi

Enables serving of Internet Server extensions (such as .dll modules).

It is available on the Windows platform only, and is not supported by Oracle.

mod_log_agent

Enables logging of client user agents. It is deprecated; you should use mod_log_config instead of mod_log_agent.

This module is not supported by Oracle.

mod_log_config

Provides configurable, customizable logging of server activities. You can choose the log format, and select or exclude individual requests for logging, based on characteristics of the requests.

See Also:

Module mod_log_config in the Apache Server documentation.

mod_log_referer

Enables logging of documents that reference documents on the server. It is deprecated; you should use mod_log_config instead of mod_log_referer.

See Also:

Module mod_log_referer in the Apache Server documentation.

mod_mime

Enables the server to determine the type of a file from its filename, and associate files with handlers for processing.

See Also:

Module mod_mime in the Apache Server documentation.

mod_mime_magic

Enables the server to determine the MIME type of a file by examining a few bytes of its content. It is used in cases when mod_mime cannot determine a file type. Make sure that mod_mime appears before mod_mime_magic in the configuration file, so that mod_mime processes the files first.

See Also:

Module mod_mime_magic in the Apache Server documentation.

mod_mmap_static

Maps a list of files into memory, useful for frequently requested files that are not changed often.

This module is not supported by Oracle.

mod_negotiation

Enables the server for content negotiation (selection of documents based on the client's capabilities).

See Also:

Module mod_negotiation in the Apache Server documentation.

mod_onsint

This module provides integration support with Oracle Notification Service (ONS) and OPMN (Oracle Process Manager and Notification Server).

Benefits of mod_onsint

mod_onsint provides the following functionality:

Implementation Differences for mod_onsint

Due to the difference in architecture of Oracle HTTP Server on UNIX and Windows, the implementation of mod_onsint varies slightly on these platforms.

On UNIX, mod_onsint spawns a process at module initialization time. This process is responsible for watching the parent process as well as sending and receiving ONS messages. Callback functions from other modules interested in ONS notifications are made in this process. For this information to be shared with other Oracle HTTP Server child processes, the use of an interprocess communication method such as a memory mapped file must be used. If a failure of a parent process is detected on UNIX, a signal is sent to all the other child processes, causing them to shut down.

On Windows, Oracle HTTP Server consists of only two processes, the parent and a multi-threaded child that handles all of the HTTP requests. In this model, mod_onsint runs as a thread within the child process. This thread watches the parent process as well as sending and receiving ONS messages. Callback functions from other modules interested in ONS notifications are made in the child process. If a failure of the parent process is detected, the mod_onsint terminates the child process, effectively shutting down Oracle HTTP Server.

See Also:

"Oracle HTTP Server Processing Model"

There is no configuration of mod_onsint needed to provide functionality equivalent to that provided with Oracle HTTP Server in Oracle9i Application Server, Release 2 (9.0.2), other than the loading of the module. There is only an optional directive called OpmnHostPort that can be set. This directive enables you to specify a hostname and port that OPMN should use for pinging the Oracle HTTP Server instance that mod_onsint is running in. If OpmnHostPort is not specified, mod_onsint chooses an HTTP port automatically. However, in certain circumstances, you may want to choose a specific HTTP port and hostname that OPMN should use to ping the listener with.

OpmnHostPort takes a single argument which is a host:port string that specifies the values to pass to OPMN. For example, the following line would specify that OPMN should use the localhost interface and port 7778 to ping this listener:

OpmnHostPort localhost: 7778

This directive must be in the global section of the httpd.conf file. It cannot be embedded into any virtual host of location container. After installation, an OpmnHostPort directive is located in dms.conf. It points OPMN to the Oracle HTTP Server "diagnostic port", which is a special localhost only virtual host.

You cannot combine directives using the one-argument syntax with directives using the two-argument syntax. If you use the two-argument syntax, the default for groups without a group-specific secret key is 'disabled'.

mod_ossl

This Oracle module enables strong cryptography for Oracle HTTP Server. It is a plug-in to Oracle HTTP Server that enables the server to use SSL. It is very similar to the OpenSSL module, mod_ssl. However, in contrast to the OpenSSL module, mod_ossl is based on the Oracle implementation of SSL, which supports SSL, version 3, and is based on Certicom and RSA Security technology.

See Also:

mod_perl

This module embeds the Perl interpreter into the Oracle HTTP Server. This eliminates start-up overhead and enables you to write modules in Perl.


Note:

The demonstration script for this module that is shipped with Oracle Database should be disabled in production environments. It is included only to verify that the installation was successful.


See Also:

mod_perl Guide

Database Usage Notes

This section provides information for mod_perl users working with databases. It explains how to test a local database connection and set character forms.

Using Perl to Access the Database

The following section contains information about using Perl to access the database. Perl scripts access databases using the DBI/DBD driver for Oracle. The DBI/DBD driver is part of Oracle Database. It calls Oracle Callable Interface (OCI) to access the databases.

DBI must be enabled in httpd.conf for DBI to function. To do this, perform the following steps:

  1. Edit httpd.conf using a text editor.
  2. Search for "PerlModule Apache: :DBI".
  3. Uncomment the line "PerlModule Apache: :DBI".
  4. Restart Oracle HTTP Server using the following commands:

Files must be copied to ORACLE_HOME/Apache/Apache/cgi-bin

Example 7-1 Using Perl to Access the Database

#!<ORACLE_HOME>perl/bin/perl -w 
  use DBI; 
  my $dataSource = "host=<hostname.domain>;sid=<orclsid>;port=1521"; 
  my $userName = "scott"; 
  my $password = "tiger"; 
  my $dbhandle = DBI->connect("dbi:Oracle:$dataSource", $userName, $password) 
    or die "Can't connect to the Oracle Database: $DBI::errstr\n"; 
  print "Content-type: text/plain\n\n"; 
  print "Database connection successful.\n"; 
  ### Now disconnect from the database 
  $dbhandle->disconnect 
    or warn "Database disconnect failed; $DBI::errstr\n"; 
  exit;

You can access the DBI scripts from the following locations:

http://<hostname.domain>:<port>/cgi-bin/<scriptname>
http://<hostname.domain>:<port>/perl/<scriptname>

If the script specifies "use Apache::DBI" instead of "use DBI", then it will only be able to run from http://<hostname.domain>:<port>/perl/<scriptname>.

Testing Database Connection

The following is a sample Perl script for testing the database connection of a local seed database. To use the script to test another database connection, you must replace scott/tiger with the user name and password for the target database.

Example 7-2 Sample Perl Script For Testing Connection for Local Seed Database

##### Perl script start ###### 
use DBI;
print "Content-type: text/plain\n\n"; 
$dbh = DBI->connect("dbi:Oracle:", "scott/tiger", "") || die $DBI::errstr;
 $stmt = $dbh->prepare("select * from emp order by empno")|| die $DBI::errstr; 
$rc = $stmt->execute() || die $DBI::errstr; 
while (($empno, $name) = $stmt->fetchrow()) { print "$empno $name\n"; } 
warn $DBI::errstr if $DBI::err; 
die "fetch error: " . $DBI::errstr if $DBI::err; 
$stmt->finish() || die "can't close cursor"; 
$dbh->disconnect() || die "cant't log off Oracle"; 
##### Perl script End ###### 

Using SQL NCHAR Datatypes

SQL NCHAR datatypes have been refined in Oracle9i, and are now called reliable Unicode datatypes. SQL NCHAR datatypes such as NCHAR, NVARCHAR2 and NCLOB allow you to store any Unicode characters regardless of the database character set. The character set for those datatypes is specified by the national character set, which is either AL16UTF-16 or UTF8.

See Also:

Oracle9i documentation for more about SQL NCHAR datatypes.

This release of DBD::Oracle supports SQL NCHAR datatypes and provides driver extension functions to specify the character form for data binding. The following script shows an example to access SQL NCHAR data:

Example 7-3 Sample Script to Access SQLNCHAR Data

# declare to use the constants for character forms
use DBD::Oracle qw(:ora_forms);
# connect to the database and get the database handle
$dbh = DBI->connect( ... );
# prepare the statement and get the statement handle
$sth = $dbh->prepare( 'SELECT * FROM TABLE_N WHERE NCOL1 = :nchar1' );
# bind the parameter of a NCHAR type
$sth->bind_param( ':nchar1', $param_1 );
# set the character form to NCHAR
$sth->func( { ':nchar1' => ORA_NCHAR } , 'set_form' );
$sth->execute;

As shown in Example 7-3, the set_form function is provided as a private function that you can invoke with the standard DBI func() method. It takes an anonymous hash that specifies which placeholder should be associated with which character form. The valid values of character form are either ORA_IMPLICIT or ORA_NCHAR. Setting the character form to ORA_IMPLICIT causes the application's bound data to be converted to the database character set, and ORA_NCHAR to the national character set. The default form is ORA_IMPLICIT.

Another function is provided to specify the default character set form as follows:

# specify the default form to be NCHAR
$dbh->func( ORA_NCHAR, 'set_default_form' );

After this call is made, the form of all parameters is ORA_NCHAR, unless otherwise specified with set_form calls. Note that unlike the set_form function, this is a function on the database handle, so every statement from the database handle with its default form specified has the form of your choice by default.

set_form

This function sets the character form for parameter(s). Valid forms are either ORA_IMPLICIT (default) or ORA_NCHAR. The constants are available as: ora_forms in DBD::Oracle.

Example 7-4 Sample for set_form

# a declaration example for the constants ORA_IMPLICIT and ORA_NCHAR
use DBD::Oracle qw(:ora_forms);
# set the character form for the placeholder :nchar1 to NCHAR
$sth->func( { ':nchar1' => ORA_NCHAR } , 'set_form' );
# set the character form using the positional index
$sth->func( { 2 => ORA_NCHAR } , 'set_form' );
# set the character form for multiple placeholders at once
$sth->func( { 1 => ORA_NCHAR, 2 => ORA_NCHAR } , 'set_form' );

set_default_form

This function sets the default character form for a database handle.

Example 7-5 Default Character Form for a Database Handle

$dbh->func( ORA_NCHAR , 'set_default_form' );

mod_plsql

This Oracle module connects the Oracle HTTP Server to an Oracle database, enabling you to create Web applications using Oracle stored procedures.

In order to access a Web-enabled PL/SQL application, configure a PL/SQL Database Access Descriptor (DAD) for mod_plsql. A DAD is a set of values that specifies how mod_plsql connects to a database server to fulfill an HTTP request. Besides the connect details, a DAD contains important configuration parameters for various operations in the database and for mod_plsql in general. Any Web-enabled PL/SQL application which makes use of the PL/SQL Web ToolKit needs to create a DAD to invoke the application.

Creating a DAD

Perform the following steps to create a DAD:

  1. Edit the DAD configuration file ORACLE_HOME/Apache/modplsql/conf/dads.conf.
  2. Add a DAD where the DAD has the following format:
    1. The Oracle HTTP Server <Location> directive which defines a virtual path used to access the PL/SQL Web Application. This directive begins enclosing a group of directives that apply to the named Location.

      For example, the directive <Location /myapp> defines a virtual path called "/myapp" that will be used to invoke a PL/SQL Web Application through a URL like http://host:port/myapp/.


      Note:

      Older versions of mod_plsql were always mounted on a virtual path with a prefix of '/pls'. This restriction is removed in newer versions but might still be a restriction imposed by some of the older PL/SQL applications.


    2. The Oracle HTTP Server "SetHandler" directive which directs Oracle HTTP Server to enable mod_plsql to handle the request for the virtual path defined by the named Location
      SetHandler pls_handler
      
      
    3. Additional Oracle HTTP Server directives that are allowed in the context of a <Location> directive. Typically, the following directives are used:
      Order deny,allow
      Allow from all
      AllowOverride None
      
      
    4. One or more mod_plsql specific directives. For example:
      PlsqlDatabaseUsername        scott
      PlsqlDatabasePassword        tiger
      PlsqlDatabaseConnectString   orcl
      PlsqlAuthenticationMode      Basic
      
      
    5. An Oracle HTTP Server </Location> directive which closes the group of directives for the named Location, and defines a single DAD.
  3. Save the edits.
  4. Obfuscate the DAD password by running the "dadTool.pl" script located in ORACLE_HOME/Apache/modplsql/conf.

    See Also:

    "PlsqlDatabasePassword" for instructions on performing the obfuscation.

  5. Restart the Oracle HTTP Server for the configuration to take effect.

You can create additional DADs by defining other uniquely named Locations in dads.conf.

This section contains the following topics:

Configuration Files

Configuration Parameters

Configuration Files

mod_plsql configuration reside in the following three configuration files:

plsql.conf

This file contains the LoadModule directive to load mod_plsql into Oracle HTTP Server, any global setting for mod_plsql, and include directives for dads.conf and cache.conf. This file is included by the Oracle HTTP Server configuration file ORACLE_HOME/Apache/Apache/conf/oracle_apache.conf on UNIX or ORACLE_HOME\Apache\Apache\conf\oracle_apache.conf on Windows, which itself gets included in the primary Oracle HTTP Server configuration file httpd.conf.

See Also:

"oracle_apache.conf"

dads.conf

This file contains the configuration parameters for the PL/SQL database access descriptor (DAD). A DAD is a set of values that specifies how mod_plsql connects to a database server to fulfill a HTTP request.

cache.conf

This file contains the configuration settings for the file system caching functionality implemented in mod_plsql. This configuration file is relevant only if PL/SQL applications use the OWA_CACHE package to cache dynamically generated content in the file system.

See Also:

Oracle HTTP Server mod_plsql User's Guide for details on caching functionality in mod_plsql.

Configuration Parameters

Table 7-3 contains a list of mod_plsql configuration parameters. They are discussed in detail in later sections.

While specifying a value for a configuration parameter, follow Oracle HTTP Server conventions for specifying values. For instance, if a value has white spaces in it, enclose the value with double quotes. For example: PlsqlNLSLanguage "TRADITIONAL CHINESE_TAIWAN.UTF8"

Also, multi-line directives enables you to specify the same directive multiple times in a DAD.

Table 7-3 mod_plsql Configuration Files and Parameters  
Configuration File Parameters

plsql.conf

PlsqlDMSEnable

PlsqlLogEnable

PlsqlLogDirectory

PlsqlIdleSessionCleanupInterval

dads.conf

PlsqlAfterProcedure

PlsqlAlwaysDescribeProcedure

PlsqlAuthenticationMode

PlsqlBeforeProcedure

PlsqlBindBucketLengths

PlsqlBindBucketWidths

PlsqlCGIEnvironmentList

PlsqlCompatibilityMode

PlsqlDatabaseConnectString

PlsqlDatabasePassword

PlsqlDatabaseUserName

PlsqlDefaultPage

PlsqlDocumentPath

PlsqlDocumentPath

PlsqlDocumentProcedure

PlsqlDocumentTablename

PlsqlErrorStyle

PlsqlExclusionList

PlsqlFetchBufferSize

PlsqlInfoLogging

PlsqlMaxRequestsPerSession

PlsqlNLSLanguage

PlsqlPathAlias

PlsqlPathAliasProcedure

PlsqlSessionCookieName

PlsqlSesssionStateManagement

PlsqlTransferMode

PlsqlUploadAsLongRaw

cache.conf

PlsqlCacheCleanupTime

PlsqlCacheDirectory

PlsqlCacheEnable

PlsqlCacheMaxAge

PlsqlCacheMaxSize

PlsqlCacheTotalSize

plsql.conf

This file contains the LoadModule directive to load mod_plsql into the Oracle HTTP Server, global settings for mod_plsql, and include directives for dads.conf and cache.conf.


Note:

Refer to plsql.README located in ORACLE_HOME/Apache/modplsql/conf for detailed description of plsql.conf.


The following section discusses the following parameters that can be specified in plsql.conf:

PlsqlDMSEnable

Enables Dynamic Monitoring Service (DMS) for mod_plsql.

Category Value

Syntax

PlsqlDMSEnable On/Off

Default

On

Example

PlsqlDMSEnable On

PlsqlLogEnable

Enables debug level logging for mod_plsql.

Debug level logging is meant to be used for debugging purposes only. When logging is enabled, log files are generated at:

as configured by PlsqlLogDirectory. This parameter should be set to "Off" unless recommended by Oracle support to debug problems with mod_plsql.

To view more details about the internal processing of mod_plsql, set this directive to "On". This causes mod_plsql to start logging for every request that is processed. The log files are generated as specified by the PlsqlLogDirectory directive.

Category Value

Syntax

PlsqlLogEnable On/Off

Default

Off

Example

PlsqlLogEnable Off

PlsqlLogDirectory

Specifies the directory where debug level logs are written out.

Set the directory name of the location where log files should be generated when logging is enabled. To avoid possible confusion about the location of this directory, an absolute path is recommended.

On UNIX, this directory must have write permissions by the owner of the child httpd processes.

Category Value

Syntax

PlsqlLogDirectory directory

Default

None

Example

PlsqlLogDirectory ORACLE_HOME/Apache/modplsql/logs

PlsqlIdleSessionCleanupInterval

Specifies the time (in minutes) in which the idle database sessions should be closed and cleaned by mod_plsql.

This directive is used in conjunction with connection pooling of database connections and sessions in mod_plsql. When a session is not used for the specified amount of time, it is closed, and freed. This is done so that unused sessions can be cleaned, and the memory is freed on the database side.

Setting this time to a low number helps in faster cleanup of unused database sessions. Be aware that if this number is too low, then this may adversely affect the performance benefits of connection pooling in mod_plsql.

If the number of open database sessions is not a concern, you can increase the value of this parameter for best performance. In such a case, if the site is accessed frequently enough that the idle session cleanup interval is never reached for a session, then the DAD configuration parameter PlsqlMaxRequestsPerSession can be modified so that it is guaranteed that a pooled database session gets recycled on a regular basis.

For most installations, the default parameter value should suffice.

Category Value

Syntax

PlsqlIdleSessionCleanupInterval number

Default

15 (minutes)

Example

PlsqlIdleSessionCleanupInterval 15

dads.conf

This file contains the configuration parameters for the PL/SQL Database Access Descriptor (DAD).

DAD Parameters

This section describes all the DAD level parameters that can be specified in the dads.conf file. Besides these directives, you can also specify additional Oracle HTTP Server directives that can be specified in the context of a <Location> directive, such as:

Order deny,allow
AllowOverride None

The following parameters are discussed in detail in the subsequent sections:

PlsqlAfterProcedure

Specifies the procedure to be invoked after calling the requested procedure. This enables you to put a hook point after the requested procedure is called. This is useful in doing SQL*Traces/SQL Profiles while debugging a problem with the requested procedure. This is also useful when you want to ensure that a specific call be made after running every procedure.

Category Value

Syntax

PlsqlAfterProcedure string

Default

None

Example

PlsqlAfterProcedure portal.mypkg.myafterproc

Notes:

PlsqlAlwaysDescribeProcedure

Specifies whether mod_plsql should describe a procedure before trying to execute it. If this is set to "On", then mod_plsql will always describe a procedure before invoking it. Otherwise, mod_plsql will only describe a procedure when its internal heuristics have interpreted a parameter type incorrectly.

Category Value

Syntax

PlsqlAlwaysDescribeProcedure On/Off

Default

Off

Example

PlsqlAlwaysDescribeProcedure Off

Notes:

PlsqlAuthenticationMode

Specifies the authentication mode to use for allow access through this DAD.

Category Value

Syntax

PlsqlAuthenticationMode Basic/SingleSignOn/GlobalOwa/CustomOwa/PerPackageOwa

Default

Basic

Example

PlsqlAuthenticationMode Basic

Notes:

PlsqlBeforeProcedure

Specifies the procedure to be invoked before calling the requested procedure. This enables you to put a hook point before the requested procedure is called. This is useful in doing SQL*Traces/SQL Profiles while debugging a problem with the requested procedure. This is also useful when you want to ensure that a specific call be made before running every procedure.

Category Value

Syntax

PlsqlBeforeProcedure string

Default

None

Example

PlsqlBeforeProcedure portal.mypkg.mybeforeproc

Notes:

PlsqlBindBucketLengths

Specifies the rounding size to use while binding the number of elements in a collection bind. While executing PL/SQL statements, the Oracle database maintains a cache of PL/SQL statements in the shared SQL area, and attempts to reuse the cached statement if the same statement is executed again. Oracle's matching criteria requires that the statement texts be identical, and that the bind variable data types match. Unfortunately, the type match for strings is sensitive to the exact byte size specified, and for collection bindings is also sensitive to the number of elements in the collection. Since mod_plsql binds statements dynamically, the odds of hitting the shared cache are low, and it may fill up with near-duplicates and lead to contention for the latch on the shared area. This parameter reduces that effect by bucketing bind lengths to the nearest level.

All numbers specified should be in ascending order. After the last specified size, subsequent bucket sizes will be assumed to be twice the last one.

Category Value

Syntax

PlsqlBindBucketLengths number multiline

Default

4,20,100,400

Example

PlsqlBindBucketLengths 4

PlsqlBindBucketLengths 25

PlsqlBindBucketLengths 125

Notes:

PlsqlBindBucketWidths

Specifies the rounding size to use while binding the number of elements in a collection bind. While executing PL/SQL statements, the Oracle database maintains a cache of PL/SQL statements in the shared SQL area, and attempts to reuse the cached statement if the same statement is executed again. Oracle's matching criteria requires that the statement texts be identical, and that the bind variable data types match. Unfortunately, the type match for strings is sensitive to the exact byte size specified, and for collection bindings is also sensitive to the number of elements in the collection. Since mod_plsql binds statements dynamically, the odds of hitting the shared cache are low, and it may fill up with near-duplicates and lead to contention for the latch on the shared area. This parameter reduces that effect by bucketing bind widths to the nearest level.

All numbers specified should be in ascending order. After the last specified size, subsequent bucket sizes will be assumed to be twice the last one.

The last bucket width must be equal to or less than 4000. This is due to the restriction imposed by OCI where array bind widths cannot be greater than 4000.

Category Value

Syntax

PlsqlBindBucketWidths number multiline

Default

32,128,1450,2048,4000

Example

PlsqlBindBucketWidths 40

PlsqlBindBucketWidths 400

PlsqlBindBucketWidths 2000

Notes:

PlsqlCGIEnvironmentList

Specifies overrides and/or additions of CGI environment variables to the default set of environment variables passed down to a PL/SQL procedure. This is a multi-line directive of name-value pairs to be added, overridden or removed. You can only specify one environment variable for each directive.

You can add CGI environment variables from the Oracle HTTP Server environment by specifying the variable name. To remove a CGI environment variable, set it equal to nothing. To add your own name-value pair, use the syntax myname=myvalue.

Category Value

Syntax

PlsqlCGIEnvironmentList string multiline

Default

None

Example

  • To add a new environment variable from the Oracle HTTP Server environment:

    PlsqlCGIEnvironmentList DOCUMENT_ROOT

  • To remove an environment variable:

    PlsqlCGIEnvironmentList MYENVAR2=

  • To override from the Oracle HTTP Server environment:

    PlsqlCGIEnvironmentList REQUEST_PROTOCOL=HTTPS

  • To add your own environment variable:

    PlsqlCGIEnvironmentList MY_VARNAME=MY_VALUE

Notes:

PlsqlCompatibilityMode

Specifies the compatibility mode for running mod_plsql. This parameter is supported only for Oracle Application Server releases, and is used when you are using mod_plsql with an older version of Oracle Application Server Portal. In such situations, if you are running mod_plsql against a pre-9.0.2 version of Oracle Application Server Portal, this should be set to 1.

Category Value

Syntax

PlsqlCompatibilityMode BitFlag

Default

0

Example

PlsqlCompatibilityMode 1

Notes:

PlsqlDatabaseConnectString

Specifies the connection to an Oracle database.

Category Value

Syntax

PlsqlDatabaseConnectString

stringServiceNameFormat/SIDFormat/TNSFormat/NetServiceNameFormat, where string can be one of the following based on the second argument:

  • ServiceNameFormat: HOST:PORT:SERVICE_NAME format where HOST is the hostname running the database, PORT is the port number the TNS listener is listening on, SERVICE_NAME is the database service name.
  • SIDFormat: HOST:PORT:SID format where HOST is the hostname running the database, PORT is the port number the TNS listener is listening on, SID is the database SID.
  • TNSFormat: A valid TNS alias which resolves using Net8 utilities like tnsping and SQL*Plus.
  • NetServiceNameFormat: A valid net service name which resolves to a connect descriptor. A connect descriptor is a specially formatted description of the destination for a network connection. A connect descriptor contains destination service and network route information.

If the format argument is not specified, then mod_plsql assumes that `string' is either in the HOST:PORT:SID format, or resolvable by Net8. The differentiation between the two is made by the presence of the colon in the specified string.

It is recommended that newer DADs do not use the SIDFormat syntax. This exists only for backward compatibility reasons. Use the new two argument format for newly created DADs.

Default

None

Example

  • PlsqlDatabaseConnectString myhost.com:1521:myhost.iasdb.inst ServiceNameFormat
  • PlsqlDatabaseConnectString myhost.com:1521:iasdb SIDFormat
  • PlsqlDatabaseConnectString myhost_tns TNSFormat
  • PlsqlDatabaseConnectString cn=oracle,cn=iasdb NetServiceNameFormat
  • PlsqlDatabaseConnectString (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(Host=myhost.com)(Port= 1521))(CONNECT_DATA=(SID=iasdb))) TNSFormat
  • PlsqlDatabaseConnectString myhost_tns
  • PlsqlDatabaseConnectString myhost.com:1521:iasdb

Notes:

PlsqlDatabasePassword

Specifies the password to use to log in to the database.

Category Value

Syntax

PlsqlDatabasePassword string

Default

None

Example

PlsqlDatabasePassword tiger

After making manual configuration changes to DAD passwords, it is recommended that the DAD passwords are obfuscated by running the "dadTool.pl" script located in ORACLE_HOME/Apache/modplsql/conf.

Following are the steps to obfuscate DAD passwords:

  1. If necessary, switch user to the Oracle software owner user, typically oracle using the following command:
    $su - oracle
    
    
  2. Set the ORACLE_HOME environment variable to specify the path to the Oracle home directory for the current release and set the PATH environment variable to include the directory containing the Perl executable and the location of the dadTool.pl script.

    On Bourne, Bash, or Korn Shell:

    ORACLE_HOME=new_ORACLE_HOME_path;export ORACLE_HOME
    PATH=ORACLE_HOME/Apache/modplsql/conf:ORACLE_HOME/perl/bin:PATH;export PATH
    
    

    On C or tcsh Shell:

    setenv ORACLE_HOME new_ORACLE_HOME_PATH
    setenv PATH ORACLE_HOME/Apache/modplsql/conf:ORACLE_HOME/perl/bin:PATH
    
    

    On Windows:

    set PATH=ORACLE_HOME\Apache\modplsql\conf;ORACLE_
    HOME\perl\5.6.1\bin\MSWin32-x86;%PATH%
    
    
    
    
    Note: The preceding command for Windows should be issued in one line.
  3. Set the appropriate shared library path environment variable for your platform.
    • On UNIX platforms, include the ORACLE_HOME/lib directory in your shared library path. Table 7-4 shows the appropriate environment variable for each platform.

      Table 7-4 Platform Type and Corresponding Shared Library Path Environment Variable
      Platform Environment Variable

      AIX

      LIBPATH

      HP-UX

      SHLIB_PATH

      Linux, Solaris, and Tru64 UNIX

      LD_LIBRARY_PATH

      For example, to set the SHLIB_PATH environment in the Bourne shell on HP-UX systems, enter the following command:

      $SHLIB_PATH=$ORACLE_HOME/lib:$SHLIB_PATH;export SHLIB_PATH
      
      
    • On Windows, include $ORACLE_HOME/bin in your PATH, for example:
      set PATH=%ORACLE_HOME%\bin;%PATH%
      
      
  4. Change directory to the mod_plsql configuration directory for the current release of Oracle HTTP Server:
    cd $ORACLE_HOME/Apache/modplsql/conf
    
    
  5. Invoke the following Perl script to obfuscate DAD password:
    perl dadTool.pl -o 
    
    

Notes:

PlsqlDatabaseUserName

Specifies the username to use to logon to the database.

Category Value

Syntax

PlsqlDatabaseUsername string

Default

None

Example

PlsqlDatabaseUsername scott

Notes:

PlsqlDefaultPage

Specifies the default procedure to call if none is specified in the URL.

Category Value

Syntax

PlsqlDefaultPage string

Default

None

Example

PlsqlDefaultPage myschema.mypackage.home

Notes:

PlsqlDocumentPath

Specifies a virtual path in the URL that initiates document download form the document table. For example, if this parameter is set to docs, then the following URLs will start the document downloading process for URLs of the format:

/pls/dad/docs
/pls/plsqlapp/docs



Category Value
Syntax PlsqlDocumentPath string
Default docs
Example PlsqlDocumentPath docs

Notes:

PlsqlDocumentProcedure

Specifies the procedure to call when a document download is initiated. This procedure is called to process the download.

Category Value

Syntax

PlsqlDocumentProcedure string

Default

None

Example

PlsqlDocumentProcedure portal.wwdoc_process.process_download

Notes:

PlsqlDocumentTablename

Specifies the table in the database to which all documents are uploaded.

Category Value

Syntax

PlsqlDocumentTablename string

Default

None

Example

PlsqlDocumentTablename myschema.document_table

Notes:

PlsqlErrorStyle

Specifies the Error Reporting Mode for mod_plsql errors. This parameter accepts the following values:

In older versions of the product, this parameter was called error_style.

PlsqlExclusionList

Specifies a pattern for excluding certain procedures, packages, or schema names from being directly executed from a browser. This is a multi-line directive in which each pattern occupies one line. The pattern is case-insensitive and can accept simple wildcards such as *, ? and [a-z]. The default patterns excluded from direct URL access are: sys.*, dbms_*, utl_*, owa_*, owa.*, htp.*, htf.*.

Setting this directive to "#NONE#" will disable all protection. This is not recommended for a live site, however, it is sometimes used for debugging purposes.

If this parameter is overridden, the defaults are no longer in effect. In that case, you must explicitly add the default list to the list of excluded patterns.

Category Value

Syntax

PlsqlExclusionList string multiline/#NONE#

Default

dbms_*

utl_*

owa_*

owa.*

htp.*

htf.*

Example

PlsqlExclusionList sys.*

PlsqlExclusionList dbms_*

PlsqlExclusionList utl_*

PlsqlExclusionList owa_*

PlsqlExclusionList owa.*

PlsqlExclusionList htp.*

PlsqlExclusionList htf.*

PlsqlExclusionList myschema.private.*

The preceding configuration excludes access to URLs containing sys.*, dbms_*, utl_*, owa_*, owa.*, htp.*, htf.*, myschema.private.*

Notes:

PlsqlFetchBufferSize

Specifies the number of rows of content to fetch from the database for each trip, using either owa_util.get_page or owa_util.get_page_raw.

By default, mod_plsql attempts to fetch 200 response lines of output where each line is of 255 bytes. In situations where the response bytes are single-bytes, the response buffer is populated to the maximum and can pack 255*200=51000 bytes for each round trip. However, for responses containing multi-byte data, the byte packing for each row could be less than ideal resulting in lesser bytes getting transferred for each round trip. If your application generates large pages frequently and the response does not fit in one round trip, then consider setting this parameter higher. However, the memory usage for mod_plsql will increase.

Category Value

Syntax

PlsqlFetchBufferSize number

Default

200

Example

PlsqlFetchBufferSize 256

Notes:

PlsqlInfoLogging

Specifies what mode mod_plsql should use to do extra performance logging.

The mode is:

InfoDebug: This logs more information to the Apache's error_log. This is used in conjunction with Apache's "info" logging level. If the Apache's logging level is not at least set to this high, this setting will be ignored.

Category Value

Syntax

PlsqlInfoLogging InfoDebug

Default

Empty

Example

PlsqlInfoLogging InfoDebug

This logging setting is useful for debugging problems in your PL/SQL application.

PlsqlMaxRequestsPerSession

Specifies the maximum number of requests a pooled database connection should service before it is closed and re-opened.

Category Value

Syntax

PlsqlMaxRequestsPerSession number

Default

1000

Example

PlsqlMaxRequestsPerSession 1000

Notes:

PlsqlNLSLanguage

Specifies the NLS_LANG variable for this DAD. This parameter overrides the NLS_LANG environment variable. When this parameter is set, the PL/SQL Gateway uses the specified NLS_LANG to connect to the database. Once connected, an alter session command is issued to switch to the specified language and territory. If the middle tier character set matches that of the database, then no alter session call is issued by mod_plsql.

Category Value

Syntax

PlsqlNLSLanguage string

Default

None

Example

PlsqlNLSLanguage America_America.UTF8

Notes:

PlsqlPathAlias

Specifies a virtual path alias to map to a procedure call. This is application specific.

Category Value

Syntax

PlsqlPathAlias string

Default

None

Example

PlsqlPathAlias url

Notes:

PlsqlPathAliasProcedure

Specifies the procedure to call when the virtual path in the URL matches the path alias as configured by PlsqlPathAlias.

Category Value

Syntax

PlsqlPathAliasProcedure string

Default

None

Example

PlsqlPathAliasProcedure portal.wwpth_api_alias.process_download

Notes:

PlsqlSessionCookieName

Specifies the cookie name whenPlsqlAuthenticationMode is set to SingleSignOn. This parameter is supported only for Oracle Application Server releases, and is used by the Oracle Application Server Portal and Oracle Application Server Single Sign-On.

Category Value

Syntax

PlsqlSessionCookieName cookie_name

Default

Same as DAD name

Example

PlsqlSessionCookieName mycookie

Notes:

PlsqlSesssionStateManagement

Specifies how package and session state should be cleaned up at the end of each mod_plsql request.

Notes:

mod_plsql does not support stateful mode of operation. To equip PL/SQL applications with stateful behavior, save state in cookies and/or in the database.

PlsqlTransferMode

Specifies the transfer mode for data from the database back to mod_plsql. Most applications use the default value of CHAR.

Category Value

Syntax

PlsqlTransferMode CHAR/RAW

Default

CHAR

Example

PlsqlTransferMode CHAR

Notes:

PlsqlUploadAsLongRaw

Specifies the extensions to be uploaded as LONGRAW data type, as opposed to using the default BLOB data type. The default can be overridden by specifying multi-line directives of file extensions for field. A value of '*' in this field causes all documents to be uploaded as LONGRAW.

Category Value

Syntax

PlsqlUploadAsLongRaw string multiline

Default

None

Example

PlsqlUploadAsLongRaw jpg, PlsqlUploadAsLongRaw gif

Notes:

cache.conf

cache.conf file contains the cache settings for mod_plsql. This file contains parameters which specify the characteristics of the mod_plsql cache system.

See Also:

This file is relevant only if the PL/SQL Application uses the OWA_CACHE packages to cache content in the file system. Extremely few customer applications make use of the OWA_CACHE packages.

The following parameters are specified in cache.conf file:

PlsqlCacheCleanupTime

Specifies the time to start the cleanup of the cache storage.

This setting defines the exact day and time in which cleanup should occur. The frequency can be set as daily, weekly, and monthly.

PlsqlCacheDirectory

Specifies the directory where cache files are written out by mod_plsql. This directory must exist or else Oracle HTTP Server will not start.

On UNIX, this directory must have write permissions by the owner of the child httpd processes.

Category Value

Syntax

PlsqlCacheDirectory <directory>

Default

none

Example

PlsqlCacheDirectory ORACLE_HOME/Apache/modplsql/cache

In older versions, this parameter was called "cache_dir" and resides in the "[PLSQL Cache]" section of ORACLE_HOME/Apache/modplsql/cfg/cache.cfg.

PlsqlCacheEnable

Enables mod_plsql caching.

Category Value

Syntax

PlsqlCacheEnable On/Off

Default

Off

Example

PlsqlCacheEnable On

Notes:

PlsqlCacheMaxAge

Specifies the maximum time, in days, a cache file can be allowed to reside in a file system cache, after which the cached file will be removed for cache maintenance.

This setting is to ensure that the cache system does not contain old content. This setting removes old cache files and makes space for new ones.

Category Value

Syntax

PlsqlCacheMaxAge <number>

Default

30 (30 days)

Example

PlsqlCacheMaxAge 30

PlsqlCacheMaxSize

Specifies the maximum possible size of a cache file.

This setting is to prevent the case in which one file can fill up the entire cache. In general, it is recommended that this be set to about 1-3 percent of the total cache size.

Category Value

Syntax

PlsqlCacheMaxSize <number>

Default

1048576 (1 MB)

Example

PlsqlCacheMaxSize 1048576

In older versions, this parameter was called "max_size" and resided in the "[PLSQL Cache]" section of ORACLE_HOME/Apache/modplsql/cfg/cache/cfg.

PlsqlCacheTotalSize

Specifies the total size of the cache directory.

This setting limits the amount of space the cache is allowed to use. Both PLSQL cache and Session Cookie cache share this cache space. Note that this setting is not a hard limit. It might exceed the limit temporarily during normal processing. This is normal behavior.

The cleanup algorithm uses this setting to determine how much to reduce the cache files. Therefore, the real space limit is the physical storage's available size.

This parameter takes bytes as values;

In older versions, this parameter was called "total_size" and resided in the "[PLSQL Cache]" section of ORACLE_HOME/Apache/modplsql/cfg/cache/cfg.

mod_proxy

This module provides proxy capability for FTP, CONNECT (for SSL), HTTP/0.9, HTTP/1.0, and HTTP/1.1.

See Also:

mod_rewrite

Oracle HTTP Server provides mod_rewrite as a tool for URL manipulation. A rewriting engine based on a regular-expression parser is used by mod_rewrite to rewrite requested URLs. The granularity of URL manipulations can be affected by the formats of server variables, environment variables, HTTP headers, and time stamps.

This module operates on the full URLs (including the path-info part) both in per-server context (httpd.conf) and per-directory context (.htaccess) and can generate query-string parts on result.

The following topics are discussed in the subsequent sections:

mod_rewrite Rules Processing

Apache processes HTTP in phases. A hook for each of these phases is provided by the Apache API. mod_rewrite uses two of these hooks- the URL-to-filename translation hook which is used after the HTTP request has been read but before any authorization starts, and the Fixup hook which is triggered after the authorization phases and after the per-directory configuration files (.htaccess) have been read, but before the content handler is activated.

mod_rewrite reads the configured rulesets from its configuration structure. Server level rulesets are best configured at startup, while directory level rulesets are configured during the directory access of the kernel.

mod_rewrite loops through the ruleset rule by rule (RewriteRule directive) and when a particular rule matches, it loops through corresponding conditions (RewriteCond directives). First the URL is matched against the Pattern of each rule. When it fails, mod_rewrite looks for corresponding rule conditions. If none are present, it just substitutes the URL with a new value which is constructed from the string Substitution and goes on with its rule-looping. But if conditions exist, it starts an inner loop for processing them in the order that they are listed.

For conditions, a string TestString is created by expanding variables, back-references map lookups, and then CondPattern is matched against the expanded TestString. If the pattern does not match, the complete set of conditions and the corresponding rule fails. If the pattern matches, then the next condition is processed until no more conditions are available. If all conditions match, processing is continued with substituting the URL using Substitution.

When request seeks a URL with more than one slash (/), for example, http://yourserver//oldpath/rqstdrsrc, the "//oldpath" may bypass RewriteCond and RewriteRule directives if they are not correctly written.

For example, consider the following rule:

RewriteRule ^/oldpath(.*) /newpath$1 [R]

Requesting http://yourserver/oldpath/files will redirect and return the page http://yourserver/newpath/files as expected.

However, requesting http://yourserver//oldpath/files will bypass this particular rule, potentially serving a page that you were not expecting it to. You can work around the problem by making sure that rules will capture more than one slash (/). To fix the earlier example, you should use this replacement:

RewriteRule ^/+somepath(.*) /otherpath$1 [R]

mod_rewrite Directives

This section discusses the following mod_rewrite directives:

RewriteEngine

Enables or disables the runtime rewriting engine. If it is set to "Off", this module does no runtime processing at all. Use this directive to disable the module instead of commenting out all the RewriteRule directives.

Rewrite configurations are not inherited by default. This means that you need to have ReWriteEngine On directive for each virtual host in which you want to use it.

RewriteOptions

By specifying RewriteOptions 'inherit', you can force the configuration of the parent by the children. In virtual-server context this means that the maps, conditions and rules of the main server are inherited. In directory context this means that conditions and rules of the .htaccess configuration of the parent directory are inherited.

RewriteLog

Sets the name of the file to which the server logs any rewriting action that it performs. If the name does not begin with a slash (/), then it is assumed to be relative to the Server Root. To disable logging, either remove or comment out the RewriteLog directive or use RewriteLogLevel 0. Avoid setting the filename to /dev/null to prevent logging. This can slow down the server with no advantage.

RewriteLogLevel

Sets the verbosity level of the rewriting log file. The default level 0 means no logging, while 9 or more means that practically all actions are logged.

RewriteBase

Explicitly sets the base URL for pre-directory rewrites. Rewrite rule can be used in per-directory configuration (.htaccess) files. When a substitution occurs for a new URL, the base URL should be added into the server processing. To be able to do this, the module needs to know what the corresponding URL-prefix or URL-base is. By default, this prefix is the corresponding file path itself. However, at most Web sites, URLs are not directly related to physical filename paths. In such cases, you have to use the RewriteBase directives to specify the correct URL-prefix.

If the URLs of your Web server are not directly related to physical file paths, you have to use RewriteBase in every .htaccess files where you want to use RewriteRule directives.

Example 7-6 RewriteBase Directive

Assume the following per-directory configuration file:

## /abc/def/.htaccess - - per-dir config file for directory /abc/def
 # /abc/def is the physical path of /xyz,
RewriteEngine On
RewriteBase /xyz
RewriteRule ^oldstuff\.html$ newstuff.html

In Example 7-6, a request to /xyz/oldstuff.html gets correctly rewritten to the physical file /abc/def/newstff.html.

Rewrite Rules Hints

Table 7-5 provide hints for using rewrite rules.

Table 7-5 Rewrite Rules Hints
Value Definition

.

Any single character

[char]

Any character listed within a square bracket

b*

Any character b any number of times

.*

Any character any number of times

For example, if you want to redirect requests from /demo1, /demo2, and /demo3 to /alldemos, write the rewrite rule as one of the following:

RewriteRule /demo. /alldemos [R]

or

RewriteRule /demo [123] /alldemos [R]

If you intend that /DemoA, /DemoB, and /DemoC to be redirected to /alldemos, add NC (no case) to the preceding rewrite rules, such as:

RewriteRule /demo [123] /alldemos [R, NC]

This rewrite rule will not work to redirect from /demonstration1 to /demos, because "." works form one character only. To enable redirection of all URLs beginning with "demo", irrespective of subsequent characters, use the rewrite rule as follows:

RewriteRule ^/demo* /alldemos [R, NC]

In the preceding example, ^ means the beginning, * means any character after demo.

If there was a request for /demo1/not_just_index.html, all the preceding rewrite rules would have redirected the request the request to /alldemos/index.html, that may not be what you want. It is quite possible that you may want to redirect to the corresponding files in /alldemos, as listed in Table 7-6.

Table 7-6 Request Redirection
Request for Redirected to

/demo1/happy.html

/alldemos/happy.html

/demo1/go.jpg

/alldemos/go.jpg

/demos1/lucky.jpg

/alldemos/lucky.jpg

Then you have to use substitution in your rewrite rule as follows:

RewriteRule ^/demos1(.*)$ //alldemos/$1 [R NC]

The explanation for this rule is:

Take the value of the expression, such as happy.html, go.jpg, and lucky.jpg, that appears after demo1 as variables ($1) and substitute it after /alldemos/.

See Also:

Module mod_rewrite in the Apache Server documentation.

Redirection Examples

For redirecting requests from the DocumentRoot to a directory called newroot, set the following mod_rewrite directives:

RewriteEngine On
RewriteRule ^/(.*)$ /newroot/$1 [R]

For directing requested for files from one directory (olddir) to another (newdir), set the following directives:

RewriteEngine On
RewriteRule ^/olddir(.*)$ /newdir/$1 [R] 

In each of these cases, you should ensure that the requested resources are indeed available in the redirected location. The mod_rewrite module does not ensure the existence of the requested resource in the new location.

For disabling all requests using the HTTP TRACE method, set the following mod_rewrite directives:

RewriteEngine On
RewriteCond %{REQUEST_METHOD} ^TRACE
RewriteRule .* - [F]

mod_setenvif

This module enables you to set environment variables based on characteristics of a request.

See Also:

Module mod_setenvif in the Apache Server documentation.

mod_so

This module loads executable code and modules into the server at start-up time.

See Also:

Module mod_so in the Apache Server documentation.

mod_speling

This module attempts to correct misspelled or miscapitalized URLs.

See Also:

Module mod_speling in the Apache Server documentation.

mod_status

This module displays an HTML page of server activity and performance.

See Also:

Module mod_status in the Apache Server documentation.

mod_unique_id

This module creates a unique ID for each request.

See Also:

Module mod_unique_id in the Apache Server documentation.

This module is available on UNIX systems only.

mod_userdir

This module maps requests to user-specific directories.

See Also:

Module mod_userdir in the Apache Server documentation.

mod_usertrack

This module tracks user activity by creating a log.

See Also:

Module mod_usertrack in the Apache Server documentation.

mod_vhost_alias

This module enables dynamically configured mass virtual hosting.

See Also:

Module mod_vhost_alias in the Apache Server documentation.